Minecraft Blogs / Tutorial

Using the Jigsaw Block in your Data Pack

  • 3,416 views, 11 today
  • 8
  • 3
  • 19
Baroque Obama avatar Baroque Obama
Level 62 : High 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.

04/15/2022 11:08 am
Level 30 : Artisan Professor
NikoKun avatar
I'm curious.. Do you think there's any way to use jigsaw/structures to generate an endless maze dimension? If it is, I haven't quite been able to figure it out yet, although there does seem to be some new jigsaw features in the upcoming update, which I'm hoping might make it more possible.. I'm just not sure.
04/15/2022 11:59 am
Level 62 : High Grandmaster Architect
Baroque Obama
Baroque Obama avatar
Sure thing, just make sure to insert one or more clever Command blocks in your structure(s), so that the commands (and functions) of your choice are called when a structure generates. This is accomplished by including a block of Redstone inside a structure as well, right beside the Command block, to activate it immediately when it generates. (See my Sky Realms pack for a concrete example of this in action).

Many of my data packs include one or more functions that are primarily setblock commands and the like, made for generating specific things in specific places; such a function could be called by a Command block inside your structure upon generation.

What you're asking is totally doable and not really tough, but there are a few moving parts to it :). No plug-ins needed, this can be done in Vanilla.

I think the key takeaway is that Jigsaw blocks aren't required in any way to accomplish your goal, and would only unnecessarily introduce randomness in the placement of things. One can accomplish perfect placement with much more customizable randomness and better results without them here, using the method above with Structure block.

There's a fair bit to it though... feel free to PM me if you'd like more help or more specifics :).
04/15/2022 3:39 pm
Level 30 : Artisan Professor
NikoKun avatar
Oh wow, fascinating! I hadn't considered having something within my structures auto-activate to spawn the next one, tho I've done something similar for an endlessly generating straight rail track, a while back. lol

Course for using a commandblock, other than individual setblock commands, I'm not sure how those would help spawn full structures this way, but I assume they can at least help cleanup leftover blocks and do finishing touches.
Also, since Structure blocks can be activated by redstone (I didn't realize that till now), I'll look more into how that works.. However, I'm still clueless as to how I could achieve randomness that way, without jigsaw blocks. If it's not too much to ask, that's the part I think I need clarification on the most. ^^;
04/15/2022 3:51 pm
Level 62 : High Grandmaster Architect
Baroque Obama
Baroque Obama avatar
Well, the Command block calls functions you've written and included in your data pack. The function(s) called can use commands with conditions: like ones that check to make sure the next piece still needs to be generated (and do so), or do nothing otherwise.

Randomness is also achieved through clever use of commands in the function(s), and functions filled with SetBlock and filling a bunch of relative positions with specific blocks can be used for building.

The Sky Realms pack does literally all of that lol
04/20/2022 10:53 pm
Level 30 : Artisan Professor
NikoKun avatar
Sweet, thanks for the tips! I've been looking through your Sky Realms datapack a bit, and that's certainly an interesting way to go about it.. Using the scoreboard for randomization, huh? Doing it that way still seems a little beyond me.. heh

Although, I've been tinkering around with the latest snapshot, and datapack version 10's new features; which do allow for spawning jigsaw structures into the world as part of the world generation. And that actually seems to be capable of doing exactly what I want, for now! I've already managed to get it spawning a pretty convincing looking Backrooms, and with almost no cutt-off areas or unused spaces, infinitely in a custom dimension! And with just 4 basic structures too. :D Gonna add some more variations and things to find, maybe play around with the structure weights.. If I can add enough to it, it might be worth sharing as a datapack! ;)

Can't wait for the official 1.19 update!
04/20/2022 11:45 pm
Level 62 : High Grandmaster Architect
Baroque Obama
Baroque Obama avatar
That's pretty exciting :). Glad to hear it's working out for you!

I haven't looked much beyond 1.17 yet because the PC I have right now is old/poopy enough that I can't play MC till I get an upgrade.... but once I get a new one, it soulds like I'll be updating this blog haha
01/30/2022 9:46 am
Level 63 : High Grandmaster Blacksmith
GentlemanRevvnar avatar
Do you know if there is any method to force the jigsaw block to generate a structure remotely?

For example having a setup that using commandblocks would automatically generate a structure once per day (in game time sense). I'm not talking about structure block, but jigsaw block, where random generation would be possible.

Do you know if there is any plugin that allows that? I can't seem to find any
01/30/2022 1:16 pmhistory
Level 62 : High Grandmaster Architect
Baroque Obama
Baroque Obama avatar
That' a tough one, because of the difference with structure blocks.

I never use plugins or mods, I only ever play/build/test with vanilla myself.
01/14/2022 8:15 am
Level 39 : Artisan Miner
Magnilum avatar
I don't understand why when try to execute the jigsaw manually in 1.18, it does't work. But using the same data pack with the same structures in 1.16.5, it works perfectly, I can generate manually.

An idea ? Or it's a bug from the 1.18 ?
01/14/2022 8:50 amhistory
Level 62 : High Grandmaster Architect
Baroque Obama
Baroque Obama avatar
Because my computer died several months ago and I'm stuck with something that won't run MC, I haven't tested 1.18 or really even looked into what changed in it yet. Your question is definitely something I'm gonna look into once I can :)
Planet Minecraft


© 2010 - 2022