Jigsaw Structures

A jigsaw structure is built from individual `.mcstructure` files stored in your behavior pack's `structures` folder. Inside those saved structures, you place `minecraft:jigsaw` blocks at the exact edges where another piece should attach, such as the end of a corridor or a doorway.

When the world generates (or when you run `/place`), the game places a starting template. It then scans that template for jigsaw blocks, looks up the template pool each block points to, picks a weighted random child structure, and aligns their matching jigsaw faces. This process repeats recursively for as many steps as your depth setting allows. Once assembly is complete, every `minecraft:jigsaw` block replaces itself with the final block you defined in its interface.

Before writing any JSON, you have to build your pieces in a test world and place the jigsaw blocks where they connect. Give yourself the block using `/give @s jigsaw` and interact with it to open its configuration screen. Every field on this screen directly controls how the world generator stitches your pieces together.

Pay close attention to the facing direction of the jigsaw block when you place it. Two pieces will only snap together if their jigsaw blocks face directly into each other and sit on the outside boundary of their respective structure bounding boxes. Once your piece is ready, save it to disk using a `minecraft:structure_block`.

Data-driven jigsaw structures in Bedrock are split across four subdirectories inside `BP/worldgen/`. Each folder represents one layer of the generation pipeline, moving from how the individual blocks age, to how pieces are grouped, to how the overall structure spawns in biomes.

Your `BP/worldgen/template_pools/` files group your `.mcstructure` files into weighted lists and link directly to the `Target Pool` strings you typed into your jigsaw blocks. `BP/worldgen/processors/` (or processor lists) hold rules for randomizing blocks on placement, such as turning a percentage of stone bricks into mossy or cracked variants so repeated rooms do not look identical.

Higher up, `BP/worldgen/structures/` defines the actual jigsaw structure identifier, its starting pool, the biome filter, the generation step (such as surface structures or underground structures), and the maximum recursion depth. Finally, `BP/worldgen/structure_sets/` controls global spacing and separation on the world grid so your structures do not spawn right on top of each other.

While you can test your structure using commands without a structure set, natural world generation requires a file in `BP/worldgen/structure_sets/`. This file divides the world into regions measured in chunks and attempts to place one structure per region.

Inside the placement configuration, `spacing` is the average distance in chunks between two generation attempts, while `separation` is the minimum chunk distance between them. `separation` must always be strictly less than `spacing`. The `salt` is a unique positive integer used to randomize the placement seed so your custom structure does not generate at the exact same coordinates as vanilla villages or temples.

{
  "format_version": "1.21.20",
  "minecraft:structure_set": {
    "description": {
      "identifier": "wiki:crypt_set"
    },
    "placement": {
      "type": "minecraft:random_spread",
      "salt": 48291044,
      "spacing": 24,
      "separation": 8
    },
    "structures": [
      {
        "structure": "wiki:crypt",
        "weight": 1
      }
    ]
  }
}

As the jigsaw assembler branches out, it checks every candidate piece against the bounding boxes of pieces that have already been placed. If a room from your template pool would overlap an existing hallway, the generator discards that choice and tries the next weighted option in the pool.

If none of the main rooms fit—or if the generator reaches the maximum recursion depth defined in your structure file—you do not want hallways left wide open to cave walls or solid stone. Template pools allow you to specify a fallback pool (often called a terminator pool). This fallback pool should contain 1-block-thick cap pieces, such as a sealed wall or a rubble collapse, whose bounding boxes are thin enough that they never collide with neighboring rooms.

Waiting to fly around a newly generated world to see if your structure spawns is slow and unreliable. Bedrock includes the `/place` command specifically for testing jigsaw assembly in real time.

You can test an entire jigsaw assembly from its starting pool right where you stand, or you can test a fully registered structure definition. If you pass a depth number (from 1 to 7) to `/place jigsaw`, you can watch how the structure terminates at shallow depths versus deep ones.

/place structure wiki:crypt ~ ~ ~
/place jigsaw wiki:crypt_start_pool wiki:anchor 5 ~ ~ ~

The `/place` command and jigsaw block mechanics are available in Bedrock 1.21.0+. Data-driven `BP/worldgen/` JSON files for custom jigsaw structures require Bedrock 1.21.20+ and are gated behind the experimental worldgen toggle (Data-Driven Jigsaw Structures / Creator Features depending on your minor 1.21 release).

Read out of the game itself, so the ids match the version you are building for.