Minecraft Blogs / Tutorial

Using the Jigsaw Block in your Data Pack

  • 345 views, 1 today
  • 6
  • 3
  • 9
Baroque Obama avatar Baroque Obama
Level 54 : Grandmaster Architect
Before Jumping In
Before continuing, you'll want to be familiar with the following:

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.

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.

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.

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.

Create an account or sign in to comment.

03/04/2021 3:07 pm
Level 7 : Apprentice Explorer
RubencioGd avatar
I still have a problem with this:

I made some structures and template pools in order to generate random structures.
The problem is that when the first structure spawns naturally, the jigsaw in that structure just disappears and don't execute.
But if you execute them manually, they work.
03/04/2021 4:08 pm
Level 54 : Grandmaster Architect
Baroque Obama
Baroque Obama avatar
Most likely this is a positioning and orientation issue.

If you're placing a Jigsaw so that the next piece should spawn directly beside this one, then the Jigsaws must be located along the edges (where joining will happen), pointed outward - this will result in a Jigsaw in each piece touching each other and pointing at each other (which is what's needed).

If you're instead placing a Jigsaw so that the next piece spawns within this one, then you'll need to use opposing upward/downward oriented Jigsaws in the pieces, and the second piece must "fit" entirely within the first.
02/20/2021 8:58 pm
Level 54 : Grandmaster Architect
Baroque Obama
Baroque Obama avatar
Also, in keeping with the spirit of this article, I can't fail to point out that you can do this by including a Jigsaw in the throne structure (likely upward-facing, as the entire gemstone should be contained within the throne structure), and a template pool with some gemstone structures (each just a gemstone on top of a downward-facing Jigsaw), weighted as you like in the pool :)
02/21/2021 3:16 pm
Level 1 : New Miner
Andrew_Graph avatar
just saw this, ignore my other remark. We came up with the same idea xD
02/20/2021 8:42 pm
Level 1 : New Miner
Andrew_Graph avatar
Heyo, If you could help me with my objective, I'd appreciate it. It might even give you some ideas for future content.

I've been trying to make a single-pool structure that varies slightly. It's basically an abandoned stone throne with a single gem on top that will randomly be a gold, diamond, or emerald block, however my attempts at randomizing this stone have failed. I've tried using the structure block's metadata to call a function that replaces the block with a random block, however I cannot find a way to reference the function. I've tried namespace:structureName/functionName, but that didn't work. The other thing I tried was functionName with copies of the function in namespace:structureName/functionName and minecraft:structureName/functionName. I'm not sure what else to try, but there's my situation. I was wondering if Jigsaw blocks might be able to help with this issue. I wanted to avoid making 3 separate structures (1 for each random gem).
Don't hesitate to explain in great detail if you have a solution! Thanks in advance.
02/20/2021 8:50 pmhistory
Level 54 : Grandmaster Architect
Baroque Obama
Baroque Obama avatar
I suggest taking one of two possible approaches here.

Option 1: Multiple copies of your structure
You could have (for example) 3 .nbt structure files, each with an identical throne, but a different gemstone adorning it. Then in the starting template pool referred to in your structure feature, you could have each of these 3 structure files as an element, and weight them any way you like. This would be the easier of the two methods I'm suggesting.

Option 2: Use a single structure with an armor stand, a tick function, and predicates
You could opt for a single throne structure file. In this case, you could summon an armor stand with a tag for reference at the location the gemsone should be, and include it in the saved .nbt file. In your tick function, you could have any nearby armor stands with this tag randomly setblock one of the gemstones, then kill itself. The randomness would be best achieved through custom predicates. This is the more complicated of the two approaches, and I don't recommend this one.
02/20/2021 8:53 pm
Level 1 : New Miner
Andrew_Graph avatar
Alrighty! Thanks for the quick reply.
02/20/2021 8:55 pm
Level 54 : Grandmaster Architect
Baroque Obama
Baroque Obama avatar
No worries! If you run into trouble, just DM me and I'll see what I can do :)
02/21/2021 3:15 pm
Level 1 : New Miner
Andrew_Graph avatar
I propose a slight modification to your first option. What if I could use a jigsaw block in-place where the gem is supposed to be and have the throne without a gem be the starting pool, then the jigsaw block gets replaced with one of 3 different .nbt files (one for each gem). Think that could work?
Planet Minecraft Logo


© 2010 - 2021