Before Jumping InBefore continuing, you'll want to be familiar with the following:
The BasicsThe
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.
OrientationThe 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 GUIThe Jigsaw GUI allows you to define its properties. These are as follows:
•Target poolBy 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.
•NameBy 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 nameBy 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 intoBy 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 ExampleLet'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.
LimitationsWith 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.
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.
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.
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.
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.