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 blends the structure into surrounding terrain, and the adaptation counts against max_distance_from_center:

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: rigid (piece stays flat, ignores terrain — houses, start piece) or terrain_matching (each column drops to follow terrain — village roads).

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):

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: 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 — the file is written under the world's generated/<namespace>/structure(s)/. Merge it into the data pack.
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.

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.

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)