--- name: minecraft-world-generation description: "Create custom world generation content for Minecraft 1.21.x including custom biomes, dimensions, noise settings, surface rules, placed/configured features, carvers, structure sets, and biome modifiers. Covers both the datapack-only approach (JSON worldgen files) and the mod-code approach (NeoForge BiomeModifiers, Fabric BiomeModification API, code-driven worldgen registration with DeferredRegister). Includes compact JSON patterns and validator-backed reference checks for biome, dimension, placed_feature, configured_feature, structure, structure_set, and biome_modifier files. Targets Minecraft 1.21.x with official Mojang mappings. Use when the user asks about Minecraft worldgen, custom biomes, datapack JSON for dimensions or features, or mod-based biome modification with NeoForge or Fabric." --- # Minecraft World Generation Skill ## Two Approaches to Custom Worldgen | Approach | Best When | Platform | |----------|-----------|----------| | **Datapack JSON** | Overriding/extending vanilla worldgen | Vanilla, any server | | **Mod + Datagen** | Registering new biomes/dimensions, code-driven | NeoForge / Fabric | | **Biome Modifier (NeoForge)** | Adding features/spawns to existing biomes | NeoForge | | **BiomeModification API (Fabric)** | Adding features/spawns to existing biomes | Fabric | ### Routing Boundaries - `Use when`: the task is biome/dimension/feature/structure worldgen design or registration. - `Do not use when`: the task is general non-worldgen datapack work (recipes, advancements, predicates, function orchestration) (`minecraft-datapack`). - `Do not use when`: the task is non-worldgen mod systems (items, entities, GUI, gameplay logic) (`minecraft-modding`). --- ## Directory Layout (Datapack / Mod Resources) ``` data// ├── worldgen/ │ ├── biome/ │ │ └── my_biome.json │ ├── configured_feature/ │ │ └── my_ore.json │ ├── placed_feature/ │ │ └── my_ore_placed.json │ ├── noise_settings/ │ │ └── my_dimension_noise.json │ ├── density_function/ │ │ └── my_density.json (advanced) │ ├── structure/ │ │ └── my_structure.json │ ├── structure_set/ │ │ └── my_structures.json │ ├── processor_list/ │ │ └── my_processors.json │ ├── template_pool/ │ │ └── my_pool.json │ └── carver/ │ └── my_carver.json ├── dimension/ │ └── my_dimension.json ├── dimension_type/ │ └── my_type.json ├── tags/ │ └── worldgen/ │ └── biome/ │ └── is_forest.json └── neoforge/ └── biome_modifier/ (NeoForge mod only) └── add_ores.json ``` --- ## Custom Biome JSON The biome and dimension examples below match the 1.21.10-and-earlier worldgen shape. Minecraft 1.21.11 moves many visual/environment fields into Environment Attributes and Timelines, so for 1.21.11+ projects first verify the current vanilla registry JSON or generate from a known-good tool before copying old `effects` fields into new packs. ### `data//worldgen/biome/my_biome.json` ```json { "has_precipitation": true, "temperature": 0.7, "temperature_modifier": "none", "downfall": 0.8, "effects": { "sky_color": 7907327, "fog_color": 12638463, "water_color": 4159204, "water_fog_color": 329011, "grass_color_modifier": "none", "ambient_sound": "minecraft:ambient.cave", "mood_sound": { "sound": "minecraft:ambient.cave", "tick_delay": 6000, "block_search_extent": 8, "offset": 2.0 } }, "spawners": { "monster": [ { "type": "minecraft:zombie", "weight": 95, "minCount": 4, "maxCount": 4 }, { "type": "minecraft:skeleton", "weight": 100, "minCount": 4, "maxCount": 4 } ], "creature": [ { "type": "minecraft:sheep", "weight": 12, "minCount": 4, "maxCount": 4 } ], "ambient": [], "axolotls": [], "underground_water_creature": [], "water_creature": [], "water_ambient": [], "misc": [] }, "spawn_costs": {}, "carvers": { "air": ["minecraft:cave", "minecraft:cave_extra_underground", "minecraft:canyon"] }, "features": [ [], [], ["minecraft:lake_lava_underground", "minecraft:lake_lava_surface"], ["minecraft:amethyst_geode", "minecraft:monster_room"], [], [], [ "minecraft:ore_dirt", "minecraft:ore_gravel", "minecraft:ore_granite_upper", "minecraft:ore_coal_upper", "minecraft:ore_coal_lower", ":my_ore_placed" ], [], ["minecraft:spring_lava"], [], ["minecraft:freeze_top_layer"] ] } ``` > The `features` array has exactly 11 slots (indices 0–10), one per `GenerationStep.Decoration`: > > | Index | Step | Put here | > |-------|------|---------| > | 0 | `RAW_GENERATION` | (rarely used) | > | 1 | `LAKES` | Surface water/lava lakes | > | 2 | `LOCAL_MODIFICATIONS` | Underground lava lakes, geodes | > | 3 | `UNDERGROUND_STRUCTURES` | Amethyst geodes, dungeons | > | 4 | `SURFACE_STRUCTURES` | Glaciers, blue ice patches | > | 5 | `STRONGHOLDS` | (unused in biome JSON) | > | 6 | `UNDERGROUND_ORES` | **All ores go here** | > | 7 | `UNDERGROUND_DECORATION` | Fossils, infested stone | > | 8 | `FLUID_SPRINGS` | `spring_water`, `spring_lava` | > | 9 | `VEGETAL_DECORATION` | Trees, grass, flowers | > | 10 | `TOP_LAYER_MODIFICATION` | `freeze_top_layer` | > > Custom ores added via placed features must be placed at index **6**. --- ## Configured Feature ### `data//worldgen/configured_feature/my_ore.json` ```json { "type": "minecraft:ore", "config": { "targets": [ { "target": { "predicate_type": "minecraft:tag_match", "tag": "minecraft:stone_ore_replaceables" }, "state": { "Name": "minecraft:emerald_ore" } } ], "size": 4, "discard_chance_on_air_exposure": 0.0 } } ``` ### Other feature types | Type | Use | |------|-----| | `minecraft:ore` | Ore veins | | `minecraft:tree` | Tree placement | | `minecraft:random_patch` | Grass, flowers, mushrooms | | `minecraft:block_pile` | Hay bales, pumpkins | | `minecraft:lake` | Water/lava lakes | | `minecraft:disk` | Sand/gravel/clay disks | | `minecraft:no_bonemeal_flower` | Wither roses, etc. | | `minecraft:simple_block` | Single block placement | | `minecraft:fill_layer` | Fill an entire layer | | `minecraft:geode` | Amethyst geodes | | `minecraft:decorated` | Wraps another feature with placement | --- ## Placed Feature ### `data//worldgen/placed_feature/my_ore_placed.json` ```json { "feature": ":my_ore", "placement": [ { "type": "minecraft:count", "count": 8 }, { "type": "minecraft:in_square" }, { "type": "minecraft:height_range", "height": { "type": "minecraft:trapezoid", "min_inclusive": { "above_bottom": 0 }, "max_inclusive": { "absolute": 64 } } }, { "type": "minecraft:biome" } ] } ``` ### Common placement modifiers | Type | Effect | |------|--------| | `minecraft:count` | Number of attempts | | `minecraft:count_on_every_layer` | Per layer | | `minecraft:in_square` | Randomize X/Z within chunk | | `minecraft:biome` | Only place if biome has this feature | | `minecraft:height_range` | Y-level range | | `minecraft:surface_relative_threshold_filter` | Filter by surface depth | | `minecraft:noise_based_count` | Count varies with noise | | `minecraft:rarity_filter` | 1-in-N chance | | `minecraft:environment_scan` | Scans up/down for a condition | --- ## Dimension Type The following dimension type is the 1.21.10-and-earlier shape. For 1.21.11+ dimension work, prefer starting from the current vanilla dimension type and environment attribute registries, then validate in a fresh test world before shipping. Do not assume older `effects`, `fixed_time`, or bed/anchor booleans still model every environment behavior on newer runtimes. ### `data//dimension_type/my_type.json` ```json { "ultrawarm": false, "natural": true, "coordinate_scale": 1.0, "has_skylight": true, "has_ceiling": false, "ambient_light": 0.0, "fixed_time": false, "monster_spawn_light_level": { "type": "minecraft:uniform", "min_inclusive": 0, "max_inclusive": 7 }, "monster_spawn_block_light_limit": 0, "piglin_safe": false, "bed_works": true, "respawn_anchor_works": false, "has_raids": true, "logical_height": 384, "height": 384, "min_y": -64, "infiniburn": "#minecraft:infiniburn_overworld", "effects": "minecraft:overworld" } ``` --- ## Custom Dimension ### `data//dimension/my_dimension.json` ```json { "type": ":my_type", "generator": { "type": "minecraft:noise", "biome_source": { "type": "minecraft:fixed", "biome": ":my_biome" }, "settings": "minecraft:overworld" } } ``` ### Multi-biome dimension with `minecraft:multi_noise` source ```json { "type": ":my_type", "generator": { "type": "minecraft:noise", "biome_source": { "type": "minecraft:multi_noise", "biomes": [ { "parameters": { "temperature": [ -1.0, -0.45 ], "humidity": [ -1.0, -0.35 ], "continentalness": [ -1.2, -1.05 ], "erosion": [ -0.78, 0.0 ], "weirdness": [ 0.0, 0.0 ], "depth": [ 0.0, 0.0 ], "offset": 0.0 }, "biome": ":my_biome" } ] }, "settings": "minecraft:overworld" } } ``` --- ## NeoForge: Biome Modifier Biome Modifiers let you add features, spawns, or carvers to existing biomes without replacing the biome JSON. ### JSON biome modifier (`data//neoforge/biome_modifier/add_ores.json`) ```json { "type": "neoforge:add_features", "biomes": "#minecraft:is_overworld", "features": ":my_ore_placed", "step": "underground_ores" } ``` ### Other NeoForge biome modifier types ```json { "type": "neoforge:add_spawns", "biomes": "#minecraft:is_forest", "spawners": [{ "type": "minecraft:wolf", "weight": 5, "minCount": 2, "maxCount": 4 }] } { "type": "neoforge:remove_features", "biomes": "#minecraft:is_plains", "features": "minecraft:ore_coal_upper", "steps": ["underground_ores"] } { "type": "neoforge:remove_spawns", "biomes": "#minecraft:is_ocean", "entity_types": "#minecraft:skeletons" } ``` --- ## Fabric: BiomeModification API (Code) ```java import net.fabricmc.fabric.api.biome.v1.BiomeModifications; import net.fabricmc.fabric.api.biome.v1.BiomeSelectors; import net.minecraft.world.level.levelgen.GenerationStep; public class MyModWorldgen { public static void init() { // Add a placed feature to all overworld biomes BiomeModifications.addFeature( BiomeSelectors.foundInOverworld(), GenerationStep.Decoration.UNDERGROUND_ORES, ResourceKey.create( Registries.PLACED_FEATURE, ResourceLocation.fromNamespaceAndPath(MyMod.MOD_ID, "my_ore_placed") ) ); // Add mob spawns BiomeModifications.addSpawn( BiomeSelectors.tag(BiomeTags.IS_FOREST), MobCategory.CREATURE, EntityType.WOLF, 5, 2, 4 ); } } ``` --- ## Mod-Registered Worldgen (NeoForge + Fabric via Datagen) ### Register worldgen keys in code ```java // In a dedicated worldgen registry class public class ModWorldgen { public static final ResourceKey MY_BIOME = ResourceKey.create( Registries.BIOME, ResourceLocation.fromNamespaceAndPath(MyMod.MOD_ID, "my_biome") ); public static final ResourceKey MY_ORE_PLACED = ResourceKey.create( Registries.PLACED_FEATURE, ResourceLocation.fromNamespaceAndPath(MyMod.MOD_ID, "my_ore_placed") ); } ``` ### Datagen: NeoForge (`DatapackBuiltinEntriesProvider`) ```java public class ModWorldgenProvider extends DatapackBuiltinEntriesProvider { private static final RegistrySetBuilder BUILDER = new RegistrySetBuilder() .add(Registries.CONFIGURED_FEATURE, ModWorldgenProvider::bootstrapConfigured) .add(Registries.PLACED_FEATURE, ModWorldgenProvider::bootstrapPlaced); public ModWorldgenProvider(PackOutput output, CompletableFuture registries) { super(output, registries, BUILDER, Set.of(MyMod.MOD_ID)); } private static void bootstrapConfigured(BootstrapContext> ctx) { ctx.register( ModWorldgen.MY_ORE_CONFIGURED, new ConfiguredFeature<>(Feature.ORE, new OreConfiguration( OreConfiguration.target( new TagMatchTest(BlockTags.STONE_ORE_REPLACEABLES), ModBlocks.MY_ORE.get().defaultBlockState() ), 9 // vein size )) ); } private static void bootstrapPlaced(BootstrapContext ctx) { HolderGetter> configured = ctx.lookup(Registries.CONFIGURED_FEATURE); ctx.register( ModWorldgen.MY_ORE_PLACED, new PlacedFeature( configured.getOrThrow(ModWorldgen.MY_ORE_CONFIGURED), List.of( HeightRangePlacement.triangle( VerticalAnchor.absolute(-64), VerticalAnchor.absolute(32) ), CountPlacement.of(8), InSquarePlacement.spread(), BiomeFilter.biome() ) ) ); } } ``` Register in your `GatherDataEvent` handler: ```java @SubscribeEvent public static void onGatherData(GatherDataEvent event) { DataGenerator gen = event.getGenerator(); PackOutput output = gen.getPackOutput(); gen.addProvider(event.includeServer(), new ModWorldgenProvider(output, event.getLookupProvider())); } ``` ### Datagen: Fabric (`FabricDynamicRegistryProvider`) ```java public class ModWorldgenProvider extends FabricDynamicRegistryProvider { public ModWorldgenProvider(FabricDataOutput output, CompletableFuture registries) { super(output, registries); } @Override protected void configure(HolderLookup.Provider registries, Entries entries) { entries.addAll(registries.lookupOrThrow(Registries.CONFIGURED_FEATURE)); entries.addAll(registries.lookupOrThrow(Registries.PLACED_FEATURE)); } @Override public String getName() { return "Worldgen"; } } ``` --- ## Custom Structure ### `data//worldgen/structure/my_structure.json` ```json { "type": "minecraft:jigsaw", "biomes": "#:my_biome_tag", "step": "surface_structures", "terrain_adaptation": "beard_thin", "start_pool": ":my_pool/start", "size": 6, "max_distance_from_center": 80, "use_expansion_hack": false, "spawn_overrides": {} } ``` ### Template pool for jigsaw structures ```json { "fallback": "minecraft:empty", "elements": [ { "weight": 1, "element": { "element_type": "minecraft:single_pool_element", "location": ":my_structure/start", "projection": "rigid", "processors": "minecraft:empty" } } ] } ``` --- ## Structure Set ### `data//worldgen/structure_set/my_structures.json` ```json { "structures": [ { "structure": ":my_structure", "weight": 1 } ], "placement": { "type": "minecraft:random_spread", "spacing": 32, "separation": 8, "salt": 12345678 } } ``` --- ## Development Workflow 1. Create or edit worldgen JSON files in `data//worldgen/` (or equivalent mod resources path). 2. Run the bundled validator to catch JSON and cross-reference errors before loading: ```bash ./scripts/validate-worldgen-json.sh --root /path/to/datapack-or-mod-resources # Strict mode treats warnings as failures: ./scripts/validate-worldgen-json.sh --root /path/to/datapack-or-mod-resources --strict ``` 3. Fix any reported errors and re-validate until clean. The validator checks: - JSON validity for `worldgen/**` and `neoforge/biome_modifier/**` - Cross-reference integrity for `placed_feature -> configured_feature` - Cross-reference integrity for `structure_set -> structure` and biome/biome_modifier feature targets 4. In-game biome and structure testing: ```mcfunction /locate structure :my_structure /locate biome :my_biome /placefeature :my_ore_placed ``` 5. For dimension testing, use `/execute in` (dimension must exist at world load, not added via `/reload`): ```mcfunction execute in :my_dimension run tp @s 0 100 0 ``` 6. Check `latest.log` for worldgen errors (missing biome references, malformed noise settings). 7. Note: `/reload` refreshes datapack JSON but does **not** re-generate already-generated chunks. Test new worldgen in a fresh world or newly generated chunks. For existing test worlds, use a disposable copy and a purpose-built chunk reset/regeneration workflow; `/fill` only replaces blocks and is not a substitute for world generation. --- ## References - Minecraft Wiki — World generation: https://minecraft.wiki/w/Custom_world_generation - Minecraft Wiki — Biome: https://minecraft.wiki/w/Biome/JSON_format - Minecraft Wiki — Features: https://minecraft.wiki/w/World_generation/Configured_feature - NeoForge Biome Modifiers: https://docs.neoforged.net/docs/worldgen/biomemodifier/ - Fabric BiomeModifications: https://wiki.fabricmc.net/tutorial:biomemodification - misode's data pack generator (worldgen UI): https://misode.github.io/worldgen/