World Builder Configuration

Configure terrain generation presets — flat, procedural surface, cave, and sky island worlds.

A world builder preset is the terrain-generation recipe a world is built from. There are four builder types, each with its own preset file format: FlatWorld (a flat test world), Default (full procedural surface generation), Cave (an underground-only dimension), and SkyIsland (floating islands in a void). A mod can ship any number of named presets per type — the base game ships one preset per type, all named genesis (or super-flat-world for FlatWorld).

This is paired with a World Type Configuration, which controls physics (gravity, day length) separately from terrain.

File Location

Presets are not referenced from your mod’s manifest — they’re loaded by type and name directly from fixed folders:

mods/<YourMod>/world-builders/default/<preset-name>.yaml
mods/<YourMod>/world-builders/flat-world/<preset-name>.yaml
mods/<YourMod>/world-builders/cave/<preset-name>.yaml
mods/<YourMod>/world-builders/sky-island/<preset-name>.yaml

Each file is a single object at the document root (no wrapping list) — its exact shape depends on the builder type, covered in its own section below.

Selecting a Preset

A world’s builder type and preset are chosen when the world is created and stored in that world’s save data as default-world-preset-type (FlatWorld/Default/Cave/SkyIsland) and default-world-preset (the file name, without .yaml). The in-game “Create World” menu only lets a player choose the type; which preset file loads for a given type is currently fixed to genesis (super-flat-world for FlatWorld) rather than mod-selectable through the UI — a mod adding its own preset makes it available for a save file to reference, but a player can’t yet pick it from the new-world screen.

Default World Builder

Full procedural surface generation — the standard overworld. Biomes, terrain layers, caves, ore/structure placement, and static object spawning are all driven by the biomes defined in Biome Terrain Generation; this file only selects which defined biomes are in play and configures world-wide generation systems (caves, fluid bodies, underground features, sky islands).

Full Field Reference

biomes:                          # Required. At least one must resolve or the whole preset fails to load
  - 'plains'
  - 'forest'
default-biome: 'plains' # Optional. Used only if the preset lists no usable biomes
cave-generation: true            # Optional. Default: true
generate-caves-above-ground: false  # Optional. Default: false
cave-layers:                     # Optional. Which block layers caves carve into
  - 1
cave-generator:                   # Optional. See Cave Generator below
  noise-scale: 0.01
  smooth-steps: 4
  expansion-steps: 1
  final-polish: true
  min-region-size: 20
fluid-bodies:                      # Optional. Fluid body placement in caves — see Fluid Bodies
  - block: 'water'
    min-altitude: -3000
    max-altitude: -100
    noise-scale: 0.008
    noise-threshold: 0.7
aoe-zone-bodies:                   # Optional. Persistent AoE zone volumes as terrain — see AoE Zone Bodies
  - zone: 'updraft'
    min-altitude: 40
    max-altitude: 220
    spacing: 96
    spawn-chance: 0.5
rivers:                            # Optional. Surface rivers — see Rivers
  - spacing: 900
    spawn-chance: 0.6
    min-length: 300
    max-length: 700
    max-relief: 20
    min-depth: 2
    max-depth: 6
    bank-height: 3
    bank-taper: 10
    bed-block: sand
    water-block: water
global-underground-features:      # Optional. Feature names (see Underground Feature Configuration)
  - 'glow_cave'
sky-island-features:               # Optional. Feature names (see Sky Island Feature Configuration)
  - meadow_islands
singular-landmarks:                # Optional. The one-per-world landmarks this world places
  - border_seal_lair

Every name field on this page follows the standard rule: a bare name resolves to your own mod, and you only write a OtherMod: prefix for cross-mod references. See Naming & namespacing.

Changed. This used to be inconsistent: biomes, default-biome and the flat preset’s own biome key were looked up verbatim, so a bare name never matched anything and every preset had to spell out Mod:name; sky-island-features was hardcoded to fall back to Creation:, so a third-party mod could not reference its own features without a prefix. Both now namespace to the preset’s own mod. Presets that already write explicit prefixes are unaffected — an explicit prefix is still used as-is.

Cave Generator

A preset’s caves are carved by a cellular automaton seeded from simplex noise. cave-generator says which algorithm and tunes it:

cave-generator:
  type: cellular_automata     # Required. The only type a preset's caves accept
  noise-scale: 0.01
  smooth-steps: 4

Renamed, and now carries a type. This block was cave-grid-options, and an underground feature had a block by the same name that drove a different algorithm — a plain per-block noise threshold with no automaton — while accepting this same key set. So smooth-steps and friends looked valid there and did nothing. Both blocks are now cave-generator with an explicit type, and each type accepts only the keys its algorithm reads: cellular_automata here, simplex_threshold on a feature.

region-size-chunks is gone. It was accepted and documented here as sizing a cached grid, and was read by no code at all. It is now rejected as an unknown key.

Fluid Bodies

Each entry seeds a fluid body (e.g. underground lakes, lava pools) into carved cave floors using its own noise field. A cell qualifies when it is open air with a solid block directly below it (a floor), sits inside the entry’s [min-altitude, max-altitude] world-Y band, and clears its noise threshold; the seeded fluid then spreads via flood-fill to fill the cavity after the chunk loads.

Entries are tried in declaration order and the first whose band and noise both match a cell wins, so list deeper/rarer fluids first to build a depth gradient (e.g. lava in a deep band, water in a shallower one).

The same fluid-bodies block is accepted by both the Default and Cave world builders. In the Cave builder there is no surface, so a cell’s depth is simply its world-Y.

Renamed from pools. This block, and its pool-generation on/off switch, were previously named pools / pool-generation. The switch is gone — an empty or omitted fluid-bodies list places nothing — and a min-altitude bound was added. Old presets using pools:/pool-generation: now fail to load on the unknown key; rename the block to fluid-bodies:.

Note: older copies of the shipped genesis.yaml also set cave-room-generation, cave-room-generation-x-scale/-y-scale, cave-room-chance, cave-tunnel-generation, cave-tunnel-generation-x-scale/-y-scale, and cave-tunnel-chance. These were leftover from a since-replaced cave generation approach and are not read by any code — they have been removed from the shipped preset. Don’t add them to a new preset; use cave-generator instead.

Rivers

Each entry is a family of rivers cut into the surface. Placement is seed-deterministic, like every other world-generation pass: along every spacing-block column a roll against spawn-chance decides whether a river starts there, and everything about its shape follows from that anchor and the terrain it crosses. Nothing is written to the save, so a reloaded world reproduces the same rivers exactly.

A river is level, and it is level in pieces. Standing water in this engine finds one height and stays there, so a river is a chain of basins, each at its own surface level, separated by a single uncut column of ground. Each basin runs as far along the terrain as it can before the ground varies by more than max-relief, at which point the next one starts a step lower or higher. Flat country therefore gives one long unbroken river; a slope gives a staircase. The column between two basins is cut down to a sill one block proud of the higher one, so the water reads as continuous rather than walled off.

max-relief is the dial that matters. A basin takes its surface level from the lowest ground it crosses, so the cut into its highest point is as deep as the ground varies — which means the same number controls both how far a river runs unbroken and how deep its banks get. Measured against the shipped Genesis terrain:

Two guards shape where rivers can go, and neither is tunable. A basin whose surface would meet a biome’s own water table is dropped, and a column the sea already owns ends a course — a river joined to an ocean would flood that ocean up to the river’s level along every connected coast. And spacing is held to at least a whole course’s footprint (max-length plus both bank ramps), with a warning, because two overlapping courses would leave one river’s water against the other’s sill.

current

Water in this engine does not flow (see the note below), so a river that should carry you does it with persistent AoE zones tiled down its length, exactly as aoe-zone-bodies places them. Two zones are named rather than one because the push direction lives on the zone definition, as its force vector, and a river running the other way needs the opposite vector.

If either zone is missing, unknown, or not persistent, the whole current is dropped with a warning and the river is left still — a worldgen zone that expires would vanish a moment after its chunk loaded, which reads as a bug rather than as a missing feature.

Water does not flow. The fluid simulation conserves volume and has no source blocks, so no body of water in the game runs, and no waterfall persists. A river’s motion is its current zones, its descent between basins, and its animated water — not the simulation. Whether the engine should ever gain source/flow semantics is an open design question, not an oversight.

AoE Zone Bodies

Each entry places a persistent AoE zone volume into the world as terrain — an updraft column, a traversal current, a rest pocket. Placement is a sparse, seed-deterministic grid: along every spacing-block column, a per-column roll against spawn-chance decides whether a zone is placed, and its Y is chosen deterministically within [min-altitude, max-altitude]. Because placement is a pure function of the world seed, the same world always generates the same zones — nothing is written to the save, and a reloaded world reproduces them exactly.

The named zone must be an AoE zone marked persistent: true (see Persistent zones); a non-persistent zone would expire the instant it generated, so it is rejected with a warning. This is currently a Default world builder feature only (the Cave, Sky Island, and Flat builders place none).

The zone’s own shape and force (from its aoe-zone-config entry) define what the placed volume does and how big it is — e.g. a tall rectangle with an upward force for a column of rising air. min/max altitude and spacing/spawn-chance only control where and how often it appears.

Flat World Builder

A minimal flat world, mainly useful for testing. No structures, ores, or static object spawning (trees, etc.) occur — generate-static-objects always returns nothing.

Full Field Reference

default-biome: 'plains'  # Required
surface-altitude: 5                # Optional, but omitting it logs a warning (spawn point may be wrong)
altitude-bands:                            # Required
  - min-altitude: 5
    max-altitude: 5
    block: 'grass'
  - min-altitude: 3
    max-altitude: 4
    block: 'dirt'
  - min-altitude: 1
    max-altitude: 2
    block: 'stone'
background-block: 'stone'      # Optional
background-bands:                       # Optional
  - min-altitude: 1
    max-altitude: 4
    block: 'stone_wall'
standalone-background-bands:            # Optional
  - min-altitude: 8
    max-altitude: 10
    block: 'stone_wall'
fluid-bands:                            # Optional
  - min-altitude: -3
    max-altitude: -1
    block: 'water'
    layer: 1

Layer Entries

Every layer list (altitude-bands, background-bands, standalone-background-bands, fluid-bands) uses the same {min-altitude, max-altitude, block} shape:

• max-altitude must be greater than or equal to min-altitude (both are world-Y bounds, inclusive).
• World-Y 0 is always skipped (the zero-crossing boundary) — a range that spans it logs a warning but otherwise proceeds normally around the gap.
• A single malformed entry (missing min-altitude/max-altitude/block) stops processing the rest of that list, so double-check each entry if blocks seem to be missing from one of these layer sets.

Cave World Builder

An underground-only dimension: there is no surface and no above-ground air. Every block starts solid and caves are carved out; the biome itself supplies both the “rock” (fill block) and cave wall/floor/ceiling blocks. Carved caverns can be flooded with fluid bodies (water, lava, etc.) — see Fluid Bodies.

Full Field Reference

biomes:                          # Required
  - 'cave_shallow'
  - 'cave_sand'
  - 'cave_red_sand'
  - 'cave_gravel'
  - 'cave_dirt'
  - 'cave_deep'
default-biome: 'cave_shallow'  # Optional
world-ceiling-y: 0             # Optional — depth 0.0 reference (top of the caves)
world-floor-y: -3000           # Optional — depth 1.0 reference (world floor)
cave-generator:                          # Optional, same fields as the default builder
  noise-scale: 0.007
  smooth-steps: 5
  expansion-steps: 2
  final-polish: true
  min-region-size: 25
fluid-bodies:                             # Optional — floods carved cave floors, see Fluid Bodies
  - block: 'water'
    min-altitude: -3000
    max-altitude: -200
    noise-scale: 0.008
    noise-threshold: 0.7
global-underground-features:              # Optional — the shipped genesis preset omits this
  - 'glow_cave'

Cave biome selection uses two domain-warped noise axes (depth and lateral position) rather than the surface builder’s altitude/temperature/precipitation model — this is handled entirely by the engine and isn’t configurable from the preset file.

Lighting note: a cave dimension has no sky, so the only light comes from glowing blocks. The shipped genesis preset sets no global-underground-features, so the only illumination is whatever the biomes bring themselves — currently just CAVE_DEEP, whose fill block is glow_rock. The upper/mid biomes (CAVE_SHALLOW, CAVE_SAND, etc.) have no light source and are dark until the player brings one. If you want lit pockets throughout (as the overworld gets), add glow_cave to global-underground-features.

Sky Island World Builder

A floating-islands dimension: the entire world defaults to empty air, and landmasses only appear where a sky island feature is active.

Full Field Reference

sky-island-features:
  - meadow_islands
default-biome: meadow_island

A sky-island-features name without a colon is namespaced to your own mod, like every other reference — so write your own feature names bare (meadow_islands, not YourMod:meadow_islands). Use an explicit Mod:name prefix only to reference another mod’s feature. (This changed: the lookup was once hardcoded to fall back to Creation:, which forced even a mod’s own features to carry a prefix here.)

Spawn note: the first feature in sky-island-features determines where the player spawns — the engine looks for a landing spot in the middle of that feature’s min-altitude/max-altitude band. In the shipped preset, listing meadow_islands (altitude 80–160) first is what spawns the player on the meadow islands rather than the higher stone_islands (altitude 200–280). If you want players to start in a different band, list that feature first.

Warning: default-biome must name a biome actually registered in the biome manager. An empty/placeholder biome produces biome ID 0, which the client doesn’t have mapped, showing as “no biome” in-game.

Complete Examples

Based on the real shipped presets.

Default (world-builders/default/genesis.yaml):

biomes:
  - 'tropical_ocean'
  - 'plains'
  - 'mesa'
  - 'forest'
  - 'cherry_forest'
  - 'desert'
  - 'snow_tundra'
default-biome: 'cherry_forest'
cave-generation: true
generate-caves-above-ground: false
cave-layers:
  - 1
cave-generator:
  type: cellular_automata
  noise-scale: 0.01
  smooth-steps: 4
  expansion-steps: 1
  final-polish: true
  min-region-size: 20
fluid-bodies:
  - block: 'water'
    max-altitude: -100
    noise-scale: 0.008
    noise-threshold: 0.7

global-underground-features:
  - 'glow_cave'

sky-island-features:
  - meadow_islands
  - stone_islands

Flat (world-builders/flat-world/super-flat-world.yaml):

default-biome: 'plains'
surface-altitude: 5
altitude-bands:
  - min-altitude: 5
    max-altitude: 5
    block: 'grass'
  - min-altitude: 3
    max-altitude: 4
    block: 'dirt'
  - min-altitude: 1
    max-altitude: 2
    block: 'stone'

Cave (world-builders/cave/genesis.yaml):

biomes:
  - 'cave_shallow'
  - 'cave_sand'
  - 'cave_red_sand'
  - 'cave_gravel'
  - 'cave_dirt'
  - 'cave_deep'
default-biome: 'cave_shallow'
cave-generator:
  type: cellular_automata
  noise-scale: 0.007
  smooth-steps: 5
  expansion-steps: 2
  final-polish: true
  min-region-size: 25
fluid-bodies:
  - block: 'water'
    min-altitude: -3000
    max-altitude: -200
    noise-scale: 0.008
    noise-threshold: 0.7

Sky Island (world-builders/sky-island/genesis.yaml):

sky-island-features:
  - meadow_islands
default-biome: meadow_island

Difficulty Gradient

A spawn-anchored difficulty gradient makes a world start safe and get more dangerous as the player travels outward and digs down. It has two halves that work together, anchored at world origin x=0 (the spawn scan starts at x≈1, so x=0 is effectively the spawn point):

1. Safe start — on the world-builder preset. The difficulty-gradient block forces a safe biome near the origin:

difficulty-gradient:
  safe-biome: heartlands   # forced within safe-radius of x=0
  safe-radius: 500         # blocks; 0 (or no block) disables

Within safe-radius blocks of x=0, get_biome_at returns safe-biome regardless of the normal climate (surface) or depth/lateral (cave) selection, so the player always spawns somewhere benign. Beyond the radius, normal selection resumes. Works on both the Default and Cave builders.

2. Escalation — per mob, in mob config. Two spawn-rules fields gate a mob by where it may spawn relative to the gradient:

• min-distance-from-spawn — the mob only spawns at least this many blocks from x=0 (danger rises as you move outward).
• min-depth-factor — the mob only spawns where the normalized within-world depth (0.0 at the top, 1.0 at world-floor-y) is at least this (danger rises as you dig).

Give your early mobs no gate (they spawn everywhere, including the safe start) and your dangerous mobs a min-distance-from-spawn and/or min-depth-factor, and threat climbs with distance and depth while the spawn region stays survivable.

Last updated Sep 29, 2026