API Worldgen Surfaces

Surfaces

Lua API / World generation / Surfaces

Surfaces are reusable top-to-bottom layer stacks applied while new overworld terrain is being formed. Attach a surface reference to a keyed biome; each eligible column samples its layer depths deterministically.

betamoon.worldgen.surfaces:add(definition)

Compiles a surface and returns a reference. Surface keys normalize to namespace:surface/path; get returns nil when absent and getRequired raises an error.

local moonSoil = betamoon.worldgen.surfaces:add {
    key = "mymod:moon_soil",
    replace = { 1, 2, 3, 12, 13 },
    layers = {
        { block = moonGrass, depth = 1 },
        { block = moonDirt, depth = { min = 2, max = 4 } }
    },
    underwaterBlock = moonSand,
    seaLevel = 64
}

Field definitions

Field	Default / behavior
key	Required stable key.
layers	Required list of 1–16 { block = ..., depth = ... } entries. Depth is an integer or 1–32 range; combined maximum depth is 64.
replace	Stone, dirt, grass, sand, and gravel. A block or list of existing base blocks that may be replaced.
underwaterBlock	Optional replacement for the first layer when its surface is below seaLevel.
seaLevel	64, from 0 through 127.

All blocks written by a surface currently use metadata zero.

The stack begins at the highest replaceable block below air in each terrain section and consumes downward:

air
layer 1: sampled depth (uses underwaterBlock when surfaceY < seaLevel)
layer 2: sampled depth
...
unchanged terrain

Every target must belong to replace. Encountering a nonreplaceable block stops the remaining layer stack at that point; BetaMoon does not tunnel through it. underwaterBlock depends only on the detected surface Y being below seaLevel. It does not test whether water is actually present, so choose the level and biome assignment accordingly.

Layer depths are sampled from the world seed, chunk, column, and surface key. Applying a surface does not invoke Lua per block or load neighboring chunks.

Lookup and references

A returned reference provides getKey(). betamoon.worldgen.surfaces:get(key) returns a reference or nil, while getRequired(key) raises an error when the key is absent. Surface keys normalize to namespace:surface/path.