API Worldgen Biomes

Biomes and biome sources

Lua API / World generation / Biomes and biome sources

Keyed biome declarations define stable biome identity, presentation, surfaces, decorators, weather, and spawn lists. Biome sources decide where keyed biomes appear.

betamoon.worldgen.biomes:add(definition)

Returns a stable biome reference. A supplied key normalizes to namespace:biome/path; get and getRequired perform keyed lookup. name remains the display name and is separate from identity.

local moonGrove = betamoon.worldgen.biomes:add {
    key = "mymod:moon_grove",
    name = "Moon Grove",
    basedOn = betamoon.mc.world.biomes.forest,
    tags = { "mymod:forest", "mymod:moon" },
    surface = moonSoil,
    weather = { rain = true }
}

assert(moonGrove:getKey() == "mymod:biome/moon_grove")

Field definitions

Field	Default / behavior
key	Recommended stable key. Omit only for the legacy climate-range facade below.
name	Required display name.
basedOn	Optional vanilla biome name to copy before applying overrides.
color, foliageColor	Optional integer colors.
tags	Up to 64 case-insensitive tags. A leading # is optional in the declaration.
surface	Surface reference/key, or the legacy { top, filler, rule } table.
surfaceRule	Surface reference/key alias, useful beside legacy surface.top and surface.filler.
decorator.placements	Placement references/keys and/or inline placement definitions. See below.
decorators	Compact alias for decorator.placements.
weather	Omitted inherits initial weather.
spawns	Vanilla spawn-list overrides; BetaMoon entities use their own spawning definition.

Tags are accepted by placements through biomes.includeTags and excludeTags. String selectors in include and exclude may use a biome display name, a full keyed ID, or #tag. BetaMoon natural entity spawn definitions accept the same three string forms in their biomes list.

Biome lookup

get and getRequired accept a keyed biome ID. They also accept a biome display name and can return native biome references. find, first, and one filter references by optional name, owner, and vanilla fields. find returns a result list, first returns the first match or nil, and one raises an error when more than one biome matches.

Biome reference and overrides

getKey() returns a BetaMoon biome's stable key. A native biome reference returns its display name because native Beta 1.7.3 biomes do not have BetaMoon keys. Live reference fields include key, name, displayName, owner, isVanilla, isBetaMoon, exists, color, foliageColor, surface, weather, range, trees, and spawns.

local layer = moonGrove:override {
    displayName = "Moonlit Grove",
    weather = { rain = false, snow = true }
}

-- Restore the next lower layer or the original declaration.
layer:remove()

biome:override(definition) can change the display name, colors, top or filler blocks, weather, spawn lists, and—where available—climate ranges and tree settings. Changing identity, tags, surface rules, decorators, or biome-source membership requires a restart. Generation settings affect future chunks; colors and weather may be visible immediately.

Biome decorators

For a keyed biome, add tree features through decorator.placements. The legacy trees selector does not generate trees for a keyed biome, even when its decorator list is empty.

An inline entry has the same fields as worldgen.placements:add, except key and stage may be omitted. BetaMoon derives a stable key from the biome and list position, defaults the stage to surface_features, and forces the biome filter to that biome. A referenced placement becomes a decorator template: its feature, sampling, conditions, ordering, and salt are copied into a biome-scoped placement, and the template itself is not generated globally. This lets one authored placement be attached to more than one biome without duplicate global generation.

local groveTrees = betamoon.worldgen.placements:add {
    key = "mymod:grove_trees",
    feature = silverwood,
    attempts = { perChunk = 3, extraChance = 0.25 },
    position = { height = { type = "surface" } },
    conditions = { ground = { 2, 3 }, requireSky = true }
}

local moonGrove = betamoon.worldgen.biomes:add {
    key = "mymod:moon_grove",
    name = "Moon Grove",
    surface = moonSoil,
    tags = { "mymod:forest" },
    decorator = {
        placements = {
            groveTrees,
            { feature = blueFlowerPatch, attempts = 2 }
        }
    }
}

Inserting or removing an earlier inline decorator can change the generated positions of later entries. Append entries where possible, or use explicitly keyed placements when results must remain stable. As with ordinary placements, explicit before and after edges take precedence.

Biome sources

betamoon.worldgen.biomeSources:add(definition) returns a reference; get returns nil when absent and getRequired raises an error. Set active = true to select a source. When several active sources exist, the highest source priority wins; equal winning priorities are rejected instead of depending on script load order.

Fixed source

betamoon.worldgen.biomeSources:add {
    key = "mymod:moon_everywhere",
    type = "fixed",
    biome = moonGrove,
    active = true
}

A fixed source selects one registered keyed biome for all climate values.

Common source field definitions

Field	Default / behavior
key	Required stable biome-source key.
type	Required fixed or vanilla_climate.
active	false; only active sources participate in selection.
priority	0; the highest active source priority wins.
biome	Required keyed biome reference/key for fixed.
entries	Required list of 1–256 climate entries for vanilla_climate.

A returned source reference provides getKey(). biomeSources:get(key) returns a reference or nil, and getRequired(key) raises an error when the source is absent.

Vanilla-climate source

betamoon.worldgen.biomeSources:add {
    key = "mymod:moon_climate",
    type = "vanilla_climate",
    active = true,
    entries = {
        {
            biome = moonGrove,
            temperature = { min = 0.35, max = 0.75 },
            humidity = { min = 0.55, max = 1 },
            priority = 10
        }
    }
}

Climate-entry field definitions

Field	Default / behavior
biome	Required keyed biome reference/key.
temperature	Required inclusive { min = a, max = b } or { a, b } range within 0–1.
humidity	Required inclusive range within 0–1.
priority	0; resolves overlapping entries.

entries accepts 1–256 records. Equal entry priorities use canonical biome-key order, so output remains deterministic. Unmatched climate ranges retain vanilla selection. The World content debug export writes worldgen_biome_sources.txt with the selected source and climate-range coverage. It also writes worldgen_surfaces.txt; biomes.txt includes keyed identity, tags, surface, and decorator counts.

Changing an active biome source can change weather, colors, spawn filtering, and decoration over existing terrain after reopening the world. It does not rewrite already generated blocks.

Unkeyed biome declarations

An unkeyed biome declaration supports range, trees, top/filler blocks, and vanilla spawn lists. Each range accepts { min = a, max = b } or { a, b }, with 0 ≤ min ≤ max ≤ 1. A keyed declaration can also include range, but use biomeSources to control where keyed biomes appear.

betamoon.worldgen.biomes:add {
    name = "Gravel Desert",
    basedOn = betamoon.mc.world.biomes.desert,
    surface = { top = 13 },
    range = {
        temperature = { min = 0.95, max = 1 },
        humidity = { min = 0, max = 0.2 }
    },
    trees = { type = betamoon.worldgen.treeModes.none }
}

weather.rain and weather.snow

Snow wins if both boolean flags are true. A supplied table with neither true creates dry weather. An omitted weather table inherits the initial biome weather.

Vanilla spawn lists

Each supplied group is a list of { entity = ..., weight = ... }. An empty list clears that group. Entity must resolve to a living entity; prefer a named entity constant. Weight is a positive integer.

Groups are monsters (monster alias), creatures (creature, animal, or animals aliases), and water (watercreature or watercreatures aliases).

spawns = {
    monsters = {},
    creatures = { { entity = betamoon.mc.entities.sheep, weight = 8 } }
}

Examples: Biome adapted from a vanilla default, keyed biome from scratch, and complete modular worldgen pack.