Using the Jigsaw Block in your Data Pack

Before Jumping In
Before continuing, you'll want to be familiar with the following:

• Structure Block variants, how to use them, and how to save structures to .nbt files in your world folder
• Data packs and how to make them
• Basics of custom world generation
  

---

The Basics
The Jigsaw Block (minecraft:jigsaw) is a unique internal block used in random structure generation. Its purpose is to define (within structure pieces) the locations where other structure pieces connect to them, as well as which pieces connect there. The term 'structure pieces' refers to individual .nbt files.

Several of the vanilla structures generate in a method essentially governed by source code, however three particular structures (Village, Bastion Remnant, and Pillager Outpost) generate as pieces joined together by Jigsaw Blocks.

These blocks can be used to create custom structures from custom pieces as well via data packs; world generation files included in the same pack can be used to control where and how often any structures generate.

---

Orientation
The Jigsaw Block has several orientation block states, and how it's oriented makes a big difference. In order to cause another structure piece to generate beside the piece you're working on, you'll need opposing Jigsaw Blocks at the appropriate edges of the pieces.

For example, you have a structure piece that you'd like to have another piece generate beside, attached to its north face. You'd need to:

• Place a north-oriented Jigsaw Block somewhere on the north face of your first structure piece

• Place a south-oriented Jigsaw block on the appropriate face of the other structure piece

• Fill in the correct data in the Jigsaw Blocks' GUIs (explained below)

The structure pieces generate such that those two Jigsaw Blocks touch each other, and so the X/Y coordinates you'd pick for the Jigsaw blocks on the north/south face determine their relative alignment.

Up-oriented and down-oriented Jigsaw Blocks don't work this way. Their purpose is to generate structure pieces that are contained entirely within the original structure piece. An example of this is villager generation in villages. In vanilla villages, villagers don't 'spawn' upon generation - there are a bunch of Jigsaw Blocks in the ground, oriented upward; these generate tiny structure pieces that just have a matching down-oriented Jigsaw Block with a Villager standing on top amidst a couple of Structure Voids.

---

Jigsaw GUI
The Jigsaw GUI allows you to define its properties. These are as follows:

•Target pool
By default, this is set to minecraft:empty (i.e. nothing). This would be left as minecraft:empty if you don't want a new structure piece to generate attached to this Jigsaw Block (this type of Jigsaw use is explained below).

'Template Pools' can be defined in which you specify a list of any number of structure pieces and their random-selection weight; assigning a Template Pool in the Target pool field will cause your Jigsaw Block to try to generate a structure selected randomly (with weight) from it. You can of course use a pool that contains only one structure piece to guarantee its selection.

•Name
By default, this is set to minecraft:empty (i.e. nothing). The Name is used so that Jigsaw Blocks in other structure pieces can find this Jigsaw Block (explained below) - it's used as an identifier.

This would be left as minecraft:empty if other structure pieces shouldn't find this Jigsaw Block (this type of Jigsaw use is explained below).

•Target name
By default, this is set to minecraft:empty (i.e. nothing). This would be left as minecraft:empty if you don't want a new structure piece to generate attached to this Jigsaw Block (this type of Jigsaw use is explained below).

The Target name works together with the Target pool to find the correct part of an acceptable structure piece to generate attached to your Jigsaw. The Jigsaw Block randomly (with weight) selects a structure piece from its Target pool, then randomly selects an appropriately-facing Jigsaw Block in the chosen structure piece whose Name is set the same as your Jigsaw's Target name, and generates the chosen structure piece such that the two Jigsaw Blocks face and touch each other.

•Turns into
By default, this is set to minecraft:air. When the structure piece generates, the Jigsaw Block transforms into another block of your choice to remove itself and complete the structure.

•Joint type (up/down-oriented Jigsaw Blocks only)
By default, this is set to Rollable. When Rollable, the structure piece that generates attached to this Jigsaw Block can generate randomly rotated 0°/90°/180º/270°, around the Y-axis, anchored on the target Jigsaw Block. When set to Aligned, there is no rotation (0°).

---

Usage Example

Let's say you'd like a structure that always has a fountain in the center with a random house connected to it on its north, south, east, and west edges, forming a '+' shaped mini-village. You have your fountain structure piece built, as well as 11 different house structure pieces that can be randomly drawn from to fill the 4 'house slots'.

You'll want your fountain piece to be the starting point for your structure, and so you'll make a Template Pool that contains only the fountain piece, as well as a Configured Structure Feature for the full structure that refers to that Template Pool in its 'start_pool' tag. Then, make sure to add this feature to the 'starts' list tag in the biome files the structure should generate in.

• The fountain itself would start with four Jigsaw Blocks - one at the north/south/east/west edges of the structure. All of them would have their Target pool set to a new Template Pool you create that lists all 11 houses.

• They would all have Name set to minecraft:empty, because Jigsaw Blocks in other structure pieces have no reason to generate your central fountain piece.

• You can arbitrarily set whichever Target name you'd like here (e.g. 'target:name' or 'custom:house'); the idea is that there will be Jigsaw Blocks in each house piece whose Name is set to the same value.

With respect to Turns into, note that typically Jigsaw Blocks are best placed in the ground so one can easily align them and make sure the generation is seamless; typically one has them turn into the appropriate block that should be at that location in the ground. If the Jigsaw Block is in the air, it's usually best to use Structure Void rather than air; that being said, there are circumstances in which one might want to use air - one should use minecraft:cave_air.

Each of the house pieces would have one Jigsaw Block at an edge - this Jigsaw block will align with one of the 4 in the fountain piece such that they face and touch each other. The Jigsaw Blocks in the house pieces would have their Target pool and Target name set to minecraft:empty, because no new structure pieces should be generated from these Jigsaws.

Each of these Jigsaw Blocks would have Name set to the same value as the Target name in the fountain's Jigsaws.

The result is that, when Minecraft decides that your structure will be generated at a certain location:

• The Start Pool is drawn from, in this case guaranteeing a fountain piece is generated on the spot (this is 'level 0' generation)

• The four Jigsaws in the fountain piece each check their Target pools for a piece, and try to find a Jigsaw Block in the chosen piece with a Name matching the fountain Jigsaw's Target name, then generate that piece attached as described above (this is 'level 1' generation)

• The four house pieces that were randomly chosen and generated are checked for Jigsaw Blocks that search a Target pool for a Target name, and it's found that there aren't any - end of generation (otherwise we'd have 'level 2' generation)

And we get our structure. With respect to 'levels' of generation, one can specify how many levels deep the generation tree branches out after the Start Pool structure is generated. This is done by adjusting the 'size' tag in your Configured Structure Feature; only integer values from 0 to 7 inclusive are allowed.

---

A much simpler example can be found in Underworld Labyrinth - this is a collection of 64 identically-sized square mazes that have exits on their north/south/east/west faces.

• The Start Pool is the only Template Pool, containing all 64 maze pieces

• Each piece has a north/south/east/west Jigsaw Block

• The Jigsaw Blocks all draw from the Start Pool

• The Jigsaw Blocks all have the same Name and Target name (which are the same as each other)

• The 'size' tag of the Configured Structure Feature is set to 2
  

The result is a diamond-shaped configuration of perfectly-aligned squares, with a total of 13 pieces, making a huge connected labyrinth.

---

Limitations
With no formal documentation, trial and error has been my primary information resource. Collaborative discussion with Rainbeau_Flambe has also been very productive. Some limitations have been encountered, which should be taken note of:

• Bastion Remnants always spawn their Start Pool piece with its base at Y=31. This limits what can be done with them to some extent, but this constant value can also be used for advantage (see Abyssal Villages). Structures also seem to have a hard-coded total size maximum that stops generation 64 blocks away from the starting piece, where further pieces won't generate beyond.

• minecraft:cave_air is always a much better choice than just air - when a piece generates underwater (e.g. a Bastion Remnant-type in Overworld), only Cave Air will actually replace the water

• Blocks that can be waterlogged will generate waterlogged if the piece generates underwater, even if fully surrounded by other blocks
  

---

If you have more to contribute, please reach out. The world needs as much information as possible about this wonderful block!

Press Square to testify.