Structures & jigsaw

The full custom-structure pipeline: the structure definition, the structure set that places it, the template pool and processor list that assemble its pieces, and the .nbt builds plus the structure-block / jigsaw-block workflow behind them. Primary syntax targets 1.21+ (singular worldgen/structure/ and structure/ folders).

Structure definition

The structure definition JSON at data/<namespace>/worldgen/structure/ is distinct from the .nbt build files (see below). It declares which biomes the structure may generate in, its generation step, mob-spawn overrides, terrain adaptation, and — for jigsaw structures — the starting template pool and expansion limits.

worldgen/structure — jigsaw root schema shape

{
  "type": "minecraft:jigsaw",
  "biomes": "#minecraft:has_structure/village_plains",
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "spawn_overrides": {},
  "start_pool": "example:village/town_centers",
  "size": 6,
  "start_height": { "absolute": 0 },
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "max_distance_from_center": 80,
  "use_expansion_hack": false
}

Structure types

One data-driven type plus fifteen hardcoded types. Most custom work uses jigsaw.

Hardcoded types accept the common fields below plus a few type-specific ones — e.g. mineshaft has mineshaft_type + probability; ocean_ruin has biome_temperature, large_probability, cluster_probability; ruined_portal has a setups[] list; shipwreck has is_beached; nether_fossil has height.

Common fields (all structure types)

spawn_overrides is an object keyed by mob category (monster, creature, ambient, water_creature, water_ambient, misc, underground_water_creature, axolotls). Each entry sets a bounding_box (piece or full) and a spawns list:

spawn_overrides — one category

{
  "monster": {
    "bounding_box": "piece",
    "spawns": [ { "type": "minecraft:pillager", "weight": 1, "minCount": 1, "maxCount": 2 } ]
  }
}

terrain_adaptation decides how the world is reshaped to receive the structure. It is optional and defaults to none. It is a field of the base structure type, not of jigsaw — nether_fossil and stronghold use it without being jigsaw structures at all.

The four active values are two families of two. The beard family is for structures that sit on the surface and need ground beneath them; the bury family is for structures that sit inside rock and need to stay enclosed. Within each family, the second value is the heavier variant.

So of the 52 vanilla structure definitions, 29 declare the field and 23 rely on the none default. The distribution is lopsided on purpose: beard_thin is the ordinary case, and the other three values are each used by exactly the one or two structures whose shape demands them.

Two things follow from the fact that the adaptation reshapes terrain rather than the structure:

• It works on noise terrain. The reshaping happens while the world's terrain is being generated. A dimension whose generator does not produce terrain that way has nothing for the adaptation to bend.
• It is charged against your size budget, which is the practical constraint and is covered immediately below.

The adaptation is charged against the size budget. Exceed the remaining allowance and the pack does not fail to validate — it fails to load, with Horizontal structure size including terrain adaptation must not exceed 128, which is why a structure can pass every static check and still leave the game refusing the whole pack. The three blending adaptations cost 12, so the usable ceiling under them is 116.

Vanilla sits on that ceiling deliberately rather than near it. Reading terrain_adaptation beside max_distance_from_center across all 52 vanilla structure definitions, the only two that reach it are the two largest, and both stop at exactly 116:

Jigsaw-specific fields

start_height × project_start_to_heightmap interaction:

• Projected (heightmap set): start_height is a relative Y from the surface. 0 = one block into the ground; positive raises, negative buries. Use absolute anchors.
• Not projected (heightmap omitted): start_height is the literal spawn Y regardless of terrain. May use absolute / above_bottom / below_top (Nether structures use below_top to sit under the roof).

pool_aliases entries take one of three shapes:

pool_aliases — direct, random, random_group

{ "type": "minecraft:direct", "alias": "example:target", "target": "example:pool_a" }

{ "type": "minecraft:random", "alias": "example:target",
  "targets": [ { "data": "example:pool_a", "weight": 1 }, { "data": "example:pool_b", "weight": 2 } ] }

{ "type": "minecraft:random_group",
  "groups": [ { "data": [ /* list of direct/random aliases */ ], "weight": 1 } ] }

data/example/worldgen/structure/tall_tower.json (single-piece surface structure)

{
  "type": "minecraft:jigsaw",
  "biomes": "#minecraft:has_structure/mineshaft",
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_pool": "example:tall_tower",
  "size": 1,
  "start_height": { "absolute": 0 },
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "max_distance_from_center": 80,
  "use_expansion_hack": false,
  "spawn_overrides": {}
}

Structure set

A structure set at data/<namespace>/worldgen/structure_set/ controls where and how often a group of structure definitions is attempted. Biome validity is not here — that lives on each structure. Vanilla groups same-frequency structures (all village biome variants) into one set.

worldgen/structure_set — root schema shape

{
  "structures": [ { "structure": "example:tall_tower", "weight": 1 } ],
  "placement": { "type": "minecraft:random_spread", "salt": 1234567, "spacing": 32, "separation": 8 }
}

Fields

structures[] — each { "structure": <id>, "weight": <positive int> }. On a successful attempt, one is chosen by weight among those whose biome/conditions pass.

placement common fields:

random_spread extras: spacing (0–4096 chunks, average grid cell), separation (0–4096, minimum gap, must be < spacing), spread_type (linear default, or triangular).

concentric_rings extras (used for strongholds): distance (0–1023, ring spacing in 6-chunk units), count (1–4095 total placements), spread (0–1023, placements on the nearest ring), preferred_biomes (biome ids / #tags).

data/example/worldgen/structure_set/towers.json

{
  "structures": [
    { "structure": "example:tall_tower", "weight": 3 },
    { "structure": "example:short_tower", "weight": 1 }
  ],
  "placement": {
    "type": "minecraft:random_spread",
    "salt": 84920155,
    "spacing": 34,
    "separation": 8,
    "spread_type": "linear",
    "frequency": 0.6,
    "exclusion_zone": { "other_set": "minecraft:villages", "chunk_count": 8 }
  }
}

Template pool

A template pool at data/<namespace>/worldgen/template_pool/ is "a loot table for builds." A jigsaw's start_pool and each jigsaw block's Target Pool point at one of these. It weights the candidate pieces and supplies a fallback.

element_type (inside each element):

projection — the two values, and what terrain_matching actually does

projection is required on every pool element except empty_pool_element, and takes exactly two values.

terrain_matching is not a placement mode of its own. It is a shorthand: the game hardcodes a minecraft:gravity processor onto the template when it sees this projection, with heightmap at its default WORLD_SURFACE_WG and offset at -1. Everything the projection does, that processor does. (Despite the name, this processor has nothing to do with falling-block physics; it rewrites Y coordinates as the template is stamped.)

Two consequences follow directly from those two parameter values:

• offset: -1 means the piece is always sunk one block. That is correct for a road — the path surface finishes flush with ground level rather than sitting one block proud — and wrong for anything you wanted resting on the surface. The projection gives you no way to change it.
• WORLD_SURFACE_WG is the highest non-air block, which counts water. A terrain_matching piece crossing a pond therefore lands on the water surface, not the bed.

What vanilla actually uses it for

Measured across every template pool in the game: of the 183 terrain_matching elements, 182 are village streets and street terminators — every biome variant and every zombie variant. The single remaining use is pillager_outpost/feature_plates, the ground plates scattered around an outpost's base. It is, in vanilla, a roads-and-groundplates feature and nothing else.

data/example/worldgen/processor_list/drape_on_seabed.json

{
  "processors": [
    { "processor_type": "minecraft:gravity",
      "heightmap": "OCEAN_FLOOR_WG",
      "offset": 0 }
  ]
}

Using beard_thin and terrain_matching together

The natural assumption is that a structure with beard_thin gets flattened ground, and that terrain_matching pieces then settle onto it so walls and floors line up. Neither half of that holds, and vanilla's own data says so.

beard_thin supports; it does not level. It generates terrain under the pieces and clears terrain inside them. The structure itself is anchored at a single point — 25 of 28 vanilla jigsaw structures set project_start_to_heightmap, which drops the start piece to the surface — and every rigid piece after that hangs off that anchor rather than off its own local ground. On a slope, distant pieces end up above the terrain and the beard fills the gap beneath them. The column of dirt and stone under a hillside village house is not a bug; it is beard_thin doing exactly its job.

Whether a wall matches its floor depends on where the boundary falls. Within a single piece there is one projection for the whole template: under rigid the wall and floor keep their exact relationship and always agree; under terrain_matching every column is dropped onto the heightmap independently, so the floor drapes while the wall shears into disconnected columns. Between two pieces it is worse, because the two Y values come from different computations entirely — a rigid piece takes its Y from the jigsaw connection, a terrain_matching piece from heightmap plus the injected offset: -1. They agree only by coincidence, and the sink guarantees a systematic one-block step even when the ground is level.

Heightmaps a gravity processor can target

data/example/worldgen/template_pool/tall_tower.json

{
  "name": "example:tall_tower",
  "fallback": "minecraft:empty",
  "elements": [
    { "weight": 3, "element": {
        "element_type": "minecraft:single_pool_element",
        "location": "example:tower/body",
        "processors": "example:mossify",
        "projection": "rigid" } },
    { "weight": 1, "element": {
        "element_type": "minecraft:single_pool_element",
        "location": "example:tower/body_ruined",
        "processors": "minecraft:empty",
        "projection": "rigid" } }
  ]
}

Processor list

A processor list at data/<namespace>/worldgen/processor_list/ is an ordered set of block transformations applied as a template piece is stamped into the world (weathering, block swaps, gravity settling, loot injection). Pool elements reference it via processors. The root is a processors array-holder object:

worldgen/processor_list — root schema shape

{ "processors": [ { "processor_type": "minecraft:block_ignore", "blocks": [ { "Name": "minecraft:structure_void" } ] } ] }

Processor types

Rules & rule tests

Each entry in a rule processor's rules[]: input_predicate tests the block in the template; location_predicate tests the block already in the world at that spot; if both pass, output_state is written.

rule — one entry

{
  "input_predicate":       { "predicate_type": "minecraft:always_true" },
  "location_predicate":    { "predicate_type": "minecraft:block_match", "block": "minecraft:red_sand" },
  "position_predicate":    { "predicate_type": "minecraft:always_true" },
  "output_state":          { "Name": "minecraft:red_sandstone" },
  "block_entity_modifier": { "type": "minecraft:passthrough" }
}

Rule tests (predicate_type — shared with ore targets):

Joint type only means something on a vertical joint

Minecraft only ever applies a Y rotation to a template piece. That single fact decides where joint matters:

• Horizontal front (north/south/east/west) — exactly one Y rotation makes the child oppose the parent, so the rotation is already determined. rollable versus aligned changes nothing at all.
• Vertical front (up/down) — a Y rotation does not change an up or down face, so all four rotations are candidates and the joint type is what picks between them. aligned pins the piece by requiring the parent and child tops to match; rollable leaves it free, and the piece lands facing a random way.

The type is read from the parent connector — the end doing the placing — so that is where the fix goes.

Trial spawners and vaults: the block entities a structure has to configure

Both arrived with the trial chambers and both are inert until configured, so a structure that places one must also carry its NBT — either baked into the saved piece, which is how vanilla does it (see trial chambers as a system), or, when a processor rule is what places the block, through append_static.

minecraft:trial_spawner

Two independent behaviour blocks: normal_config and ominous_config (the latter used when the player carries Bad Omen). Since 1.21.2 each accepts either an inline config object or a string id referencing a data-driven trial_spawner file. That indirection pays off when the same config is needed in more than one processor list or structure; it saves nothing when several pool elements already share a single processor list, because that is one copy either way.

minecraft:vault

Three parents, not two, and the split tells you which parts are yours to write:

• config — authored. The only block a data pack should hand-write.
• server_data — runtime bookkeeping. Who has claimed it, what is still to come out.
• shared_data — synced to nearby clients. What players in range actually see.

"block_entity_modifier": {
  "type": "minecraft:append_static",
  "data": {
    "normal_config": {                        // snake_case - block entity
      "spawn_potentials": [ {
        "weight": 1,
        "data": {
          "entity": {                         // snake_case key ...
            "id": "minecraft:zombie",
            "CustomName": { "text": "Guard" } // ... CamelCase value: entity NBT
          }
        }
      } ]
    }
  }
}

The eleven processor types, and which you can actually write

The worldgen/structure_processor registry holds eleven entries at 26.2. Only some are things you would ever put in a processor list by hand:

Counts measured from vanilla’s own processor lists at 26.2; the registry contents from the game’s shipped registry dump.

"processors": [
  { "processor_type": "minecraft:jigsaw_replacement" },
  { "processor_type": "minecraft:rule", "rules": [ ... ] }
]

"processors": [
  { "processor_type": "minecraft:jigsaw_replacement" },
  { "processor_type": "minecraft:rule", "rules": [ ... ] }
]

Position predicates (the optional position_predicate): always_true, linear_pos (min_chance, max_chance, min_dist, max_dist), axis_aligned_linear_pos (adds axis).

block_entity_modifier types — there are exactly four: clear, passthrough (keep existing NBT), append_static (data compound merged in), append_loot (loot_table — sets a LootTable so the container fills on first open).

data/example/worldgen/processor_list/mossify.json

{
  "processors": [
    { "processor_type": "minecraft:block_age", "mossiness": 0.2 },
    { "processor_type": "minecraft:rule",
      "rules": [
        { "input_predicate": { "predicate_type": "minecraft:block_match", "block": "minecraft:sand" },
          "location_predicate": { "predicate_type": "minecraft:block_match", "block": "minecraft:red_sand" },
          "output_state": { "Name": "minecraft:red_sand" } }
      ] }
  ]
}

Structure NBT & jigsaw workflow

Keep the two "structure" things straight:

• data/<namespace>/structure/<name>.nbt — the build saved by a Structure Block (blocks + optional entities).
• data/<namespace>/worldgen/structure/<name>.json — the definition (above) that decides biomes, step, and spawns. A template pool element's location points at the .nbt build.

Structure Block workflow

1. /give @s structure_block. The placed block defaults to Load mode; click Load twice to reach Save mode.
2. Set a Structure Name (namespace:path, lowercase / no spaces), a Relative Position (e.g. 1 0 1), and a Structure Size (max 48×48×48; extends in +X/+Y/+Z).
3. Toggle Include Entities if display entities / mobs are inside (they must sit ≥ 0.01 blocks inside the box or they're dropped). Redstone state is not saved.
4. Press SAVE — vanilla writes the file to the world's generated/<namespace>/structures/ (plural). Copy it into the data pack at data/<namespace>/structure/ (singular). The two folders are named differently; see below.
5. Use Structure Void (/give @s structure_void) at the build's edges so natural terrain / foliage shows through instead of air. (Build with sponge as a placeholder, swap to voids last — voids have a tiny hitbox.)

Jigsaw blocks

/give @s jigsaw. Directional; the sideways interface shows:

Convention: pair a parent and child by swapping Name ↔ Target Name and namespacing both.

Building and testing a jigsaw structure

The sections above describe each field. This one is the order of work, and the handful of rules that decide whether a jigsaw structure comes out the same every time or wanders somewhere new on every seed. The rules below come from tracing the jigsaw blocks of shipping packs rather than from reading the schema, and the numbers are measured results.

The rule that reframes everything: jigsaw cannot close a loop

A new piece only ever attaches to a free connector. Two pieces that are already placed never join each other. So the generator can never “close” a ring — a curtain wall, a cloister, a moat. What you do instead is make the geometry close and let the last connector go unfilled: walk the chain all the way round, and the final placement lands on the footprint of the start piece, is rejected as overlapping, and the connector is simply never used. The wall is continuous anyway, because the piece it wanted to place is already standing there. The ring closes by arithmetic, not by joining.

Vanilla itself ships connectors that can never fire

A jigsaw names a target, and the piece drawn from its pool must contain a jigsaw whose Name matches it. When nothing in that pool answers, the connector simply never fires: no error, no log line, nothing in game. This is worth knowing because vanilla does it too. Measured across all 1,511 vanilla 26.3 templates and 245 template pools, resolving each pool through its elements and its fallback chain:

The middle two rows are the ones that trip up a validator, and neither is a fault. A feature_pool_element places a configured feature — a tree, usually — and a feature contains no jigsaw blocks, so its target can never be answered by anything and is simply inert; 24 of the 245 vanilla pools are feature-only. The four placeholders are the trial-chamber spawner pools (contents/melee, ranged, slow_ranged, small_melee), which have no files because pool_aliases supply them at generation time. Whether a checker trips over the 234 depends on how it walks a pool: one that follows only elements carrying a location skips feature elements naturally, while one that resolves every referenced pool id has to exclude them deliberately — the first sweep behind this table did not, and reported 259.

The remaining 25 are genuinely unanswered: 17 in trail_ruins, 7 in bastion_remnant, 1 in trial_chambers. Fifteen of them target hall from trail_ruins/buildings/grouped, a pool whose twenty pieces between them offer only room and empty.

Four rules that make a layout deterministic

1. One pool per step, one element per pool. A wall built from a single wall_segments pool drawn from repeatedly is not a perimeter; it is a random walk of unpredictable length, and it wanders off one side. Number the chain instead — segment_1, segment_2, … — each its own pool with exactly one element.
2. One connector name per join, used once on each side. A parent’s target names the child’s entry connector, and that connector carries exactly that name. Mirrored pairs such as a2b and b2a never connect.
3. Cap every face you do not want to grow. Give it a jigsaw targeting minecraft:empty in pool minecraft:empty. Any face left with a live connector is a face that will sprout.
4. Corners are in the chain, and they turn. The corner piece has its entry connector on one face and its exit on the perpendicular one. It ends one arm and starts the next; it is not decoration placed afterwards.

The order of work

1. Draw the chain before building pieces. Every join as parent connector → child pool → child entry connector. If you cannot write it as a list, the generator cannot follow it either.
2. Build and save the pieces with structure blocks, placing jigsaw blocks on the faces from the chain — see Structure NBT & jigsaw workflow. Check the joint type on every vertical connector: the structure block GUI saves them as rollable whether you meant it or not (joint type).
3. Write one pool per step, then the structure and its structure set. Choose projection per element, not per pool.
4. Simulate before you generate. Drop the pack into MCJIG and look at the boxes. A pool that sprawls, recurses or never places the piece you care about is obvious in seconds, and it costs no world.
5. Place it with /place structure in a flat test world, several times at different coordinates. A deterministic layout looks the same every time; if it does not, go back to rule 1.
6. Read the log after every /reload. A pool or processor list that fails to parse is never registered, and the structure silently places nothing — see silent failures.

Trial chambers as a system

Trial chambers are the most complete worked example in vanilla of a structure that has to ship configured block entities, randomised encounters and a reward loop together. Everything below is measured from the game's own data at 26.3.

The parts

Configuration lives in the pieces, not in processors

The only trial-chamber processor list ages copper bulbs. Spawners and vaults arrive configured because their block-entity data is saved into the structure pieces themselves — and the two block entities do it differently:

A spawner piece — references, not a copy

{
  "id": "minecraft:trial_spawner",
  "normal_config":  "minecraft:trial_chamber/melee/zombie/normal",
  "ominous_config": "minecraft:trial_chamber/melee/zombie/ominous"
}

A vault piece — its config written inline

{
  "id": "minecraft:vault",
  "config": {
    "key_item":   { "id": "minecraft:trial_key", "count": 1 },
    "loot_table": "minecraft:chests/trial_chambers/reward"
  }
}

The spawner style suits behaviour that is reused: each piece names a config file instead of carrying a copy, so changing how a spawner behaves is one file rather than every piece that places it. The vault needs only two fields, so inline costs nothing. The ominous vault is the same piece shape with minecraft:ominous_trial_key and chests/trial_chambers/reward_ominous. For every field these blocks accept, see trial spawners and vaults.

How a chamber decides its mobs

Spawner pieces do not pick a mob. They pull from placeholder pools such as trial_chambers/spawner/contents/melee, and the structure's pool_aliases resolve those placeholders once per generated structure:

That is why a chamber feels themed rather than shuffled: every ranged and slow-ranged spawner in one structure agrees on the skeleton variant, because a random_group picks a whole group of aliases together, while melee and small melee each roll on their own. Breeze spawners have no alias and are always breezes. The three alias shapes are described under jigsaw-specific fields; this is the clearest reason to use the group form — whenever two placeholders must stay consistent with each other.

That timing is measured in a generated world, not inferred from the files. Across 23 chambers generated in a 26.3 world, all 76 alias resolutions were internally consistent: not one chamber mixed two mobs for the same placeholder, and every chamber resolved its random_group exactly once, so ranged and slow_ranged always agreed with each other. melee and small_melee varied between chambers but never within one. Two honest limits on that: it is 23 chambers from a single world, and it observes the outcome rather than the engine’s code path.

What “ominous” changes

Measured across all 14 spawner types, the ominous config differs from the normal one in these fields:

The last two rows do not overlap: each ominous spawner either arms its mobs or changes their numbers, never both.

The reward loop

1. A cleared spawner ejects loot. Ominous configs name their tables, an ominous key among them. Normal configs leave loot_tables_to_eject to its default, which these files do not state; the vault expects a trial_key, and spawners/trial_chamber/key is the table that produces one.
2. The key opens a vault whose key_item matches it.
3. The vault rolls chests/trial_chambers/reward, which is itself a table of tables: one roll of reward_rare (weight 8) or reward_common (weight 2); one to three rolls of reward_common; and a 25% chance of reward_unique.

The /place command

Used for testing structure generation without waiting for natural spawns.

/place — the four subcommands

/place feature   <configured_feature_id> [<pos>]
/place structure <structure_id>          [<pos>]
/place jigsaw    <start_pool> <target_jigsaw_name> <max_depth> [<pos>]
/place template  <template_id> [<pos>] [<rotation>] [<mirror>] [<integrity>] [<seed>] [strict]

• place feature takes a configured feature id (placement modifiers are ignored).
• place structure runs the full structure definition (spawn overrides, terrain adaptation).
• place jigsaw expands a pool to max_depth steps from a named jigsaw.
• place template stamps a raw .nbt build: rotation ∈ none / clockwise_90 / counterclockwise_90 / 180, mirror ∈ none / front_back / left_right, integrity 0–1.

What each argument resolves against

The four subcommands look alike and point at three different places. This is the distinction that most often produces a confident, wrong "does not exist" — the word structure names two unrelated things that legitimately coexist in one pack.

Sources

• Jigsaw structure — Minecraft Wiki
• Structure set — Minecraft Wiki
• Template pool — Minecraft Wiki
• Processor list — Minecraft Wiki
• Tutorial: Custom structures — Minecraft Wiki
• /place command — Minecraft Wiki
• Data pack version — Minecraft Wiki
• PMC "Custom Structure Generation Documentation" (kanokarob / Datapack Hub)