Worldgen overview
A map of Minecraft's data-driven world generator: the pipeline from dimension to placed feature, which folder each piece lives in, the 11 generation steps, and how to test it in-game.
Worldgen JSON is an unstable, "experimental" datapack API. Unlike recipes, loot tables, and advancements, its schema is explicitly allowed to change between versions with no backward-compatibility guarantee — and it does, frequently. Fields are renamed, added, and removed at the snapshot level. Everything on these pages is pinned to the 1.21 / pack_format 48 baseline. Known divergences in the large 26.x rework:
- Most
dimension_typegameplay flags migrated into anattributesobject (26.x / 25w42a+). surface_rulerenamed tomaterial_rule(26.3-snap1).initial_density_without_jaggednessreplaced bypreliminary_surface_level(1.21.9 / 25w31a).weird_scaled_samplerdensity function removed (26.2-snap5, replaced byinterval_select).
Always regenerate and validate worldgen files against your exact target version.
The worldgen pipeline
Everything is one graph. A dimension instance ties a dimension type (physics/behavior) to a generator (how terrain and biomes are produced). The generator wires into noise settings, which reference density functions and custom noises for the actual math; the biome source selects biome files, which in turn list the features, carvers, and structures placed during generation.
| Stage | What it decides | Lives in |
|---|---|---|
| dimension | Ties a dimension type to a generator; registers a reachable dimension. | data/<ns>/dimension/ |
| dimension_type | Physics & behavior: light, height, coordinate scale, spawning, portals/beds. | data/<ns>/dimension_type/ |
| generator | noise / flat / debug — the terrain strategy. | (inside the dimension file) |
| biome_source | Where each biome goes: multi_noise, fixed, checkerboard, the_end. | (inside the generator) |
| noise_settings | Default block/fluid, vertical envelope, aquifers, ore veins, the noise router, surface rule. | data/<ns>/worldgen/noise_settings/ |
| density_function | JSON-encoded math of (x,y,z) that feeds the noise router slots (terrain shape, aquifers, veins). | data/<ns>/worldgen/density_function/ |
| noise | Perlin/octave noise (firstOctave + amplitudes) referenced by density functions. | data/<ns>/worldgen/noise/ |
| biome | Climate, client effects, mob spawns, carvers, and the 11 feature steps. | data/<ns>/worldgen/biome/ |
| features / carvers / structures | The trees, ores, caves, ravines, villages, and other placed content. | data/<ns>/worldgen/... |
A single missing or mistyped ID anywhere in this graph makes the chunk fail to load — often a silent void or a crash on entering the dimension.
The vanilla minecraft:overworld, minecraft:the_nether, and minecraft:the_end dimensions live in data/minecraft/dimension/ and can be overridden by placing a file at the same path in your datapack.
Folder map
All folder names are singular in 1.21+. Each registry has one file per ID:
| Registry | Path |
|---|---|
| Dimension instance | data/<ns>/dimension/<id>.json |
| Dimension type | data/<ns>/dimension_type/<id>.json |
| Biome | data/<ns>/worldgen/biome/<id>.json |
| Noise settings | data/<ns>/worldgen/noise_settings/<id>.json |
| Density function | data/<ns>/worldgen/density_function/<id>.json |
| Custom noise | data/<ns>/worldgen/noise/<id>.json |
| Configured / placed features, carvers, structures, structure sets | data/<ns>/worldgen/configured_feature/, placed_feature/, configured_carver/, structure/, structure_set/, template_pool/, processor_list/ |
The 11 generation steps
Each biome's features field is an array of 11 sub-arrays — one per generation step, indices 0 through 10 inclusive. Every biome in a chunk contributes its placed features to the matching step, and all biomes' step 0 run before any biome's step 1, and so on. The order is fixed:
| # | Step | Typical content |
|---|---|---|
| 0 | RAW_GENERATION | Earliest terrain-shaping placements (e.g. small end islands). |
| 1 | LAKES | Water/lava lakes. |
| 2 | LOCAL_MODIFICATIONS | Geodes, dripstone clusters, icebergs. |
| 3 | UNDERGROUND_STRUCTURES | Mineshafts, dungeons, fossils. (Never generates in flat.) |
| 4 | SURFACE_STRUCTURES | Desert wells and similar. (Never generates in flat.) |
| 5 | STRONGHOLDS | Stronghold placement. |
| 6 | UNDERGROUND_ORES | Ore blobs, dirt/gravel/granite disks. |
| 7 | UNDERGROUND_DECORATION | Glow lichen, sculk veins, cave decorations. |
| 8 | FLUID_SPRINGS | Water/lava springs. |
| 9 | VEGETAL_DECORATION | Trees, grass, flowers, mushrooms, kelp. |
| 10 | TOP_LAYER_MODIFICATION | Snow/ice freeze-over pass. |
Carvers (caves and ravines) run in a separate pass between raw terrain and features — they are listed in the biome's carvers field, not among the 11 feature steps.
Testing with /place
The /place command 1.19+ forces worldgen content to generate at a location so you can inspect it without hunting for the right biome or seed. Its four subcommands:
| Subcommand | Places |
|---|---|
/place feature <id> [pos] | A configured feature (tree, ore blob, etc.). |
/place structure <id> [pos] | A whole structure (village, temple, …). |
/place jigsaw <pool> <target> <max_depth> [pos] | A jigsaw assembly from a template pool. |
/place template <id> [pos] [rotation] [mirror] [integrity] [seed] | A structure template (NBT structure file). |
To exercise a custom dimension, jump in with /execute in <ns>:<id> run tp @s ~ ~ ~ — a new dimension does not auto-generate a portal to reach it. Combine with /reload after editing worldgen files, but note that already-generated chunks keep their old terrain; travel to fresh chunks (or use a new world) to see structural changes.
Stability & version discipline
Version discipline is the single biggest hazard in worldgen. The public wiki now documents 26.x snapshots that diverge sharply from 1.21. When copying wiki snippets, cross-check against a 1.21 vanilla extract before shipping.
Author by forking vanilla. The vanilla worldgen JSON (extractable from github.com/misode/mcmeta, tagged per version) is the ground truth; hand-writing a full noise router or surface rule is impractical. Copy a vanilla file and change one slot at a time. Use misode.github.io generators for schema-correct editing — but confirm its version selector matches your target.
Keep dimension_type.min_y/height and the referenced noise_settings.noise.min_y/height identical (both multiples of 16, with min_y + height ≤ 2032). A mismatch produces missing or duplicated terrain.
Where to go next
- Dimensions & dimension types — the
dimension/anddimension_type/files: generators, biome sources, and the physics field table. - Biomes, noise & density — biome schema, noise settings, density functions, surface rules, and custom noise.
- Features & carvers — configured/placed features and cave carvers placed during the 11 steps.
- Structures — structures, structure sets, jigsaw pools, and processors.