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, pools, 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 where no other biome matches
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
pool-generation: false            # Optional. Default: false
pools:                             # Optional. Fluid pool placement in caves
  - block: 'water'
    max-altitude: -100
    noise-scale: 0.008
    noise-threshold: 0.7
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

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.

Pools

Each entry places a fluid pool (e.g. underground lakes) using its own noise field:

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.

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, no above-ground air, and no pool generation. Every block starts solid and caves are carved out; the biome itself supplies both the “rock” (fill block) and cave wall/floor/ceiling blocks.

Full Field Reference

biomes:                          # Required
  - 'cave_shallow'
  - 'cave_sand'
  - 'cave_red_sand'
  - 'cave_gravel'
  - 'cave_dirt'
  - 'cave_deep'
default-biome: 'cave_shallow'  # Optional
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
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
pool-generation: true
pools:
  - 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

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

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