Features & carvers

The worldgen decoration layer: the shared value-provider building blocks, configured features (the shapes) and placed features (where/how often they appear), and configured carvers that cut caves and canyons. Primary syntax targets 1.21+ (singular worldgen/configured_feature/, worldgen/placed_feature/, worldgen/configured_carver/ folders).

Shared building blocks

Several small value types appear across features, carvers, and structures. The dossier factors them out once; every schema below refers back to them. Wherever a field is typed as "vertical anchor", "height provider", "int provider", "float provider", or "block state provider", plug in one of the objects defined here.

Vertical anchor

A single Y position relative to the world. Use exactly one key.

vertical anchor — the three forms

{ "absolute": 0 }
{ "above_bottom": 8 }
{ "below_top": 10 }

Height provider

Returns a Y using vertical anchors. Used for ore height ranges, carver origins, and structure start heights.

height provider — two forms

{ "type": "uniform", "min_inclusive": { "absolute": 0 }, "max_inclusive": { "absolute": 256 } }
{ "type": "trapezoid", "min_inclusive": { "above_bottom": 5 }, "max_inclusive": { "below_top": 10 }, "plateau": 20 }

Int provider & float provider

An int provider returns an integer for numeric parameters (vein size, patch tries, radii). A float provider mirrors it with constant / uniform / clamped_normal / trapezoid types and is used for carver radii.

int provider — two forms

{ "type": "uniform", "min_inclusive": 0, "max_inclusive": 7 }
{ "type": "clamped_normal", "mean": 8.0, "deviation": 3.0, "min_inclusive": 1, "max_inclusive": 16 }

Block state provider

Decides which block state to place at each position inside a feature (trunks, foliage, patches, disks). Wherever a feature field is typed "block state provider", use one of these.

The noise field is a noise-parameters object (firstOctave + amplitudes[]), not an empty object — e.g. { "firstOctave": -3, "amplitudes": [1.0] }.

worldgen/placed_feature examples reuse these — weighted logs, then randomized crop age

{
  "type": "weighted_state_provider",
  "entries": [
    { "data": { "Name": "minecraft:oak_log", "Properties": { "axis": "y" } }, "weight": 3 },
    { "data": { "Name": "minecraft:birch_log", "Properties": { "axis": "y" } }, "weight": 1 }
  ]
}

{
  "type": "randomized_int_state_provider",
  "property": "age",
  "values": { "type": "uniform", "min_inclusive": 0, "max_inclusive": 7 },
  "source": { "type": "simple_state_provider", "state": { "Name": "minecraft:wheat" } }
}

Configured features

A configured feature at data/<namespace>/worldgen/configured_feature/ is a feature type bundled with its config. It never generates by itself — a placed feature references it and supplies the placement rules, or a biome references it. Root shape:

worldgen/configured_feature — root schema shape

{
  "type": "minecraft:<feature_id>",
  "config": { /* type-specific */ }
}

/place feature <configured_feature_id> [pos] places one directly for testing — it resolves against the configured_feature registry, not the placed-feature registry, and ignores placement modifiers.

Common feature types

tree

The most involved feature. It composes a trunk placer, a foliage placer, block state providers for logs/leaves/dirt, a minimum-size guard, and optional decorators. Schema shape (angle-bracket placeholders indicate where the building-block objects go):

worldgen/configured_feature — tree config shape

{
  "type": "minecraft:tree",
  "config": {
    "trunk_provider":   { /* block state provider — the log */ },
    "foliage_provider": { /* block state provider — the leaves */ },
    "trunk_placer":     { "type": "...", "base_height": 4, "height_rand_a": 2, "height_rand_b": 0 },
    "foliage_placer":   { "type": "...", "radius": <int provider>, "offset": <int provider> },
    "minimum_size":     { "type": "two_layers_feature_size", "limit": 1, "lower_size": 0, "upper_size": 1 },
    "dirt_provider":    { /* block state provider — block placed under trunk */ },
    "root_placer":      { /* optional */ },
    "decorators":       [ /* required, may be empty — tree decorators */ ],
    "ignore_vines":     false,
    "force_dirt":       false
  }
}

Trunk placers (all share numeric base_height, height_rand_a, height_rand_b):

Foliage placers (all take radius + offset int providers, plus extras):

Minimum size controls trunk width vs. height so the tree fits before it is placed:

Decorators (tree decorators — the required decorators[] array):

ore

Blob of ore blocks that replace matching targets. size is the vein size (int 0–64); discard_chance_on_air_exposure (float 0–1) is the per-block chance to skip a block adjacent to air (the "eaten by caves" look). Each targets[] entry is { target: <rule test>, state: <block state> }, where the rule test uses the same predicate grammar as processor rule tests (always_true, block_match, blockstate_match, tag_match, random_block_match, random_blockstate_match).

data/example/worldgen/configured_feature/ore_iron.json

{
  "type": "minecraft:ore",
  "config": {
    "size": 9,
    "discard_chance_on_air_exposure": 0.0,
    "targets": [
      { "target": { "predicate_type": "minecraft:tag_match", "tag": "minecraft:stone_ore_replaceables" },
        "state": { "Name": "minecraft:iron_ore" } },
      { "target": { "predicate_type": "minecraft:tag_match", "tag": "minecraft:deepslate_ore_replaceables" },
        "state": { "Name": "minecraft:deepslate_iron_ore" } }
    ]
  }
}

random_patch, disk, lake & geode

random_patch (and flower / no_bonemeal_flower) scatters a sub-feature. Note its feature field is a placed feature reference (or inline placed feature), not a configured one.

data/example/worldgen/configured_feature/flower_patch.json

{
  "type": "minecraft:random_patch",
  "config": {
    "tries": 96,
    "xz_spread": 7,
    "y_spread": 3,
    "feature": "example:placed_single_flower"
  }
}

disk — a flat blob (clay/sand/gravel patches):

lake — takes fluid (block state provider) and barrier (block state provider). A minimal example:

data/example/worldgen/configured_feature/lava_lake.json

{
  "type": "minecraft:lake",
  "config": {
    "fluid":   { "type": "simple_state_provider", "state": { "Name": "minecraft:lava" } },
    "barrier": { "type": "simple_state_provider", "state": { "Name": "minecraft:stone" } }
  }
}

geode — the amethyst-geode generator. Its config is large: blocks (filling, inner_layer, alternate_inner_layer, middle_layer, outer_layer providers), layers (thickness floats), crack (generate_crack_chance, base_crack_size, crack_point_offset), inner_placements, plus int providers outer_wall_distance / distribution_points / point_offset, and min_gen_offset, max_gen_offset, invalid_blocks_threshold, use_potential_placements_chance.

Two more terrain features worth their fields:

Placed features

A placed feature at data/<namespace>/worldgen/placed_feature/ wraps a configured feature with an ordered list of placement modifiers that decide where and how often it appears. Each modifier transforms a stream of candidate positions.

worldgen/placed_feature — root schema shape

{
  "feature": "namespace:configured_feature_or_inline",
  "placement": [ /* modifiers applied in order */ ]
}

Every placement modifier

heightmap enum (used by heightmap and surface_relative_threshold_filter): WORLD_SURFACE_WG, WORLD_SURFACE, OCEAN_FLOOR_WG, OCEAN_FLOOR, MOTION_BLOCKING, MOTION_BLOCKING_NO_LEAVES.

Examples

data/example/worldgen/placed_feature/patch_flowers.json

{
  "feature": "example:flower_patch",
  "placement": [
    { "type": "minecraft:rarity_filter", "chance": 2 },
    { "type": "minecraft:in_square" },
    { "type": "minecraft:heightmap", "heightmap": "MOTION_BLOCKING" },
    { "type": "minecraft:biome" }
  ]
}

data/example/worldgen/placed_feature/ore_iron_upper.json (vanilla-style ore distribution)

{
  "feature": "example:ore_iron",
  "placement": [
    { "type": "minecraft:count", "count": 90 },
    { "type": "minecraft:in_square" },
    { "type": "minecraft:height_range",
      "height": { "type": "trapezoid", "min_inclusive": { "absolute": 80 }, "max_inclusive": { "absolute": 384 } } },
    { "type": "minecraft:biome" }
  ]
}

Feature stacking

"Feature stacking" covers four related ways features layer during generation. Understanding all four is what lets you build composite terrain (a disk with plants on it, ore clusters, cave-wall growth) reliably.

1. The placement pipeline is a stack

A placed feature is an ordered list of placement modifiers, and that list is the stack: a stream of candidate positions flows through it top-to-bottom, and each modifier adds, drops, moves, or duplicates positions. Order matters — each modifier sees the stream as the previous one left it (e.g. heightmap before random_offset gives different results than the reverse).

2. Literal stacking — the count modifier

count duplicates each position N times (stacking copies onto one candidate). Two consequences:

• count is capped 0–256. To exceed it, stack multiple count modifiers — each multiplies the stream, so two count:100s ≈ 10 000 attempts.
• count_on_every_layer stacks one position per exposed vertical layer — the mechanism behind cave-wall vegetation and glow lichen climbing a cliff.
• Pair with in_square or every duplicate lands on the same X/Z (see the placement gotchas above).

3. Vertical stacking — features that place other features

Several configured-feature types reference other placed features, letting you nest feature logic:

• random_selector, simple_random_selector, random_boolean_selector — choose among sub-features by weight/chance.
• random_patch, vegetation_patch, waterlogged_vegetation_patch — their feature field is a placed feature, run many times over a patch (tries, xz_spread, y_spread). This is the "patch" pattern kanokarob's video calls Minecraft's most powerful feature.

So one biome entry can fan out: a random_selector → several random_patches → each placing a simple_block.

4. Decoration-step layering

A biome's features is a list of 11 lists, one per GenerationStep.Decoration (raw_generation → … → underground_ores → … → top_layer_modification). Two rules fall out:

• Across steps: a feature in an earlier step sees the world before later steps run — ores go in before vegetation so grass sits on the finished surface.
• Within a step: features generate in list order, so index 0 lays down before index 1 — how you stack a sand disk and then a plant on top of it.

Carvers

A configured carver at data/<namespace>/worldgen/configured_carver/ cuts caves and canyons after base terrain but before most decoration. There is no separate "placed carver" — a carver is attached to a biome via the biome's carvers field (e.g. { "air": [ "example:big_caves" ] }). Root:

worldgen/configured_carver — root schema shape

{ "type": "minecraft:cave | minecraft:nether_cave | minecraft:canyon", "config": { ... } }

Config fields

Universal fields (all three carver types):

cave / nether_cave extras: yScale (float provider), horizontal_radius_multiplier (float provider), vertical_radius_multiplier (float provider), floor_level (float provider). nether_cave behaves like cave with wider tunnels and no water carving.

canyon extras: vertical_rotation (float provider) plus a shape object — distance_factor, thickness, horizontal_radius_factor (float providers), vertical_radius_default_factor, vertical_radius_center_factor (floats), width_smoothness (int).

data/example/worldgen/configured_carver/big_caves.json

{
  "type": "minecraft:cave",
  "config": {
    "probability": 0.15,
    "y": { "type": "uniform", "min_inclusive": { "above_bottom": 8 }, "max_inclusive": { "absolute": 180 } },
    "yScale": { "type": "uniform", "min_inclusive": 0.1, "max_inclusive": 0.9 },
    "lava_level": { "above_bottom": 8 },
    "replaceable": "#minecraft:overworld_carver_replaceables",
    "horizontal_radius_multiplier": { "type": "uniform", "min_inclusive": 0.7, "max_inclusive": 1.4 },
    "vertical_radius_multiplier": { "type": "uniform", "min_inclusive": 0.8, "max_inclusive": 1.3 },
    "floor_level": { "type": "uniform", "min_inclusive": -1.0, "max_inclusive": -0.4 }
  }
}

Sources

• Configured feature — Minecraft Wiki
• Tree definition — Minecraft Wiki
• Int provider — Minecraft Wiki
• Height provider — Minecraft Wiki
• Placed feature — Minecraft Wiki
• Block state provider — Minecraft Wiki
• Configured carver — Minecraft Wiki
• /place command — Minecraft Wiki
• Data pack version — Minecraft Wiki
• Misode worldgen generators
• kanokarob — "This is Minecraft's Most Powerful Feature" (the feature/patch system)