View source for Minecraft:Jigsaw structure

{{Infobox structure
| defaultimagesize = 150px
| image = Jigsaw Block.png
| biome = None
| blocks = 
* {{BlockLink|Jigsaw Block}}
|canspawn=No
}}
'''Jigsaw structures''' are [[Minecraft:structure]]s that generate using [[Minecraft:jigsaw block]]s.

They are used to generate {{EnvLink|pillager outpost|pillager outposts}}, {{EnvLink|village|villages}}, {{EnvLink|bastion remnant|bastion remnants}}, {{EnvLink|ancient city|ancient cities}}, {{EnvLink|trail ruins}}, and {{EnvLink|trial chambers}}.
The jigsaw structure generation can be customized using [[Minecraft:data pack]]s {{in|java}} or [[Minecraft:add-on]]s {{in|bedrock}}.

== Generation ==
The generation places a number of pieces. A piece is usually a [[Minecraft:structure template]], but can also be a [[Minecraft:placed feature]]. The pieces are organized into [[Minecraft:template pool]]s. During generation pieces are randomly selected from a given template pool.

When a structure is generated starting from a given chunk, it generates in a number of steps, detailed below. 

=== Step 1: Starting piece ===
A jigsaw structure defines a {{nbt|string}}{{nbt|compound|start_pool}}. A piece is selected from this pool and placed at the starting position. Rotation and the starting template are chosen randomly, based on the chunk coordinates and the world seed. If the selected piece is a {{cd|minecraft:empty_pool_element}}, the structure fails to generate.{{only|je|short=1}}<ref group="note" name="fail">When the structure fails to generate, it can't be located using {{cmd|/locate}} and other structures from the same [[Minecraft:structure set]] can take its place.</ref> The starting position is the 0, 0 chunk coordinate of the starting chunk. If the {{nbt|string|project_start_to_heightmap}}{{only|je|short=1}}/{{nbt|string|heightmap_projection}}{{only|be|short=1}} is set, the start height is based on the specified [[Minecraft:heightmap]], offset by the values result of {{nbt|int}}{{nbt|compound|start_height}}. Otherwise, {{nbt|int}}{{nbt|compound|start_height}} is used to determine the start height.

If the structure defines a {{nbt|string|start_jigsaw_name}}, then a jigsaw block with that name is randomly selected and then placed at the starting position. If no matching jigsaw block is found, the structure fails to generate.<ref group="note" name="fail" /> If the structure has {{nbt|string|start_jigsaw_name}} unset, the north west corner of the (unrotated) piece is placed at the starting position.

If the final starting piece position is not at least {{nbt|int|dimension_padding.bottom}} blocks away from the lower build limit and {{nbt|int|dimension_padding.top}} blocks away from the upper build limit, the structure fails to generate.<ref group="note" name="fail" />

Finally, the starting piece is put into a generation queue.

=== Step 2: Connecting pieces ===
The generation queue is processed sequentially. A piece is removed from the queue when it is processed. Of the processed (parent) piece all jigsaw blocks are then used to generate a connecting piece. The jigsaw blocks are handled in order from high to low selection priority set in each jigsaw block and a random order of jigsaw blocks with equal selection priority. 

==== Connecting piece selection ====
The jigsaw block is referencing a "target pool". The "target pool" is used as an alias by the [[#Pool aliases|pool aliases]] referenced in {{nbt|list|pool_aliases}} to determine which [[Minecraft:template pool]] to use. If no pool alias is used then the "target pool" directly references the template pool to use.

The connecting piece is determined using that template pool in following order:
# All the pieces from the template pool &mdash; in random order according to their weight.
# All the pieces from the fallback pool specified in the template pool &mdash; in random order according to their weight.

If the maximum depth (defined by {{nbt|int|size}}{{only|je|short=1}}/{{nbt|int|max_depth}}{{only|be|short=1}}) is reached, point 1 is skipped.

==== Connecting piece try ====
From the tried piece a random jigsaw block is selected, that
# is facing outside of the bounds of the connecting piece
# has a "name" that matches the "target name" of the parent jigsaw block,
# has an orientation that is compatible with the parent jigsaw orientation (pieces can be rotated horizontally only).

The piece is placed in the world such that the jigsaw blocks connect to each other. If the currently handled piece or the newly selected piece is set to terrain matching, the piece is moved vertically to align with the terrain.

==== Piece placement condition ====
The placement is then checked for validity. A piece has to:
# Not exceed the outer bounding box. If it is placed within another piece, then the bounding box of that piece is the outer bounding box<ref group="note" name="expansion_hack">When {{nbt|bool|use_expansion_hack}} is set to {{cd|true}}, the bounding box of the pieces is extended to the height of the highest possible child piece (except when parent piece is generated by the {{nbt|string}}{{nbt|compound|start_pool}}).</ref>, otherwise the outer bounding box is determined as:
#* Horizontal side-length {{cd|2 * }}{{nbt|int|max_distance_from_center}} or {{nbt|compound|max_distance_from_center}}.{{nbt|int|horizontal}}{{cd| + 1}}
#* Vertical side-length {{cd|2 * }}{{nbt|int|max_distance_from_center}} or {{nbt|compound|max_distance_from_center}}.{{nbt|int|vertical}}{{cd| + 1}}
#* Centered in the center by XZ and lowest Y block of first piece.
#* It then gets truncated on the top or bottom such that it is at least {{nbt|int|dimension_padding}} or {{nbt|compound|dimension_padding.}}{{nbt|int|bottom}}{{only|je|short=1}} blocks away from the lower build limit and {{nbt|int|dimension_padding}} or {{nbt|compound|dimension_padding.}}{{nbt|int|top}}{{only|je|short=1}} blocks away from the upper build limit. 
# Not intersect with any other piece (except those that it is placed inside of)
# If parent is inside of grandparent, then not be outside of grandparent

If the piece can't be placed, then the placement is retried with the next piece (see [[#Connecting piece selection]]). If all pieces can't be placed than no piece is placed for this jigsaw block.

If the piece can be placed, then the newly placed piece is added to the generation queue according to the placement priority specified in the parent jigsaw block, but behind elements of equal placement priority already in the queue. The generation continues with the next jigsaw block of the parent piece.

=== Step 3: Processing ===
Finally, each piece is processed, changing or removing blocks from the template.

The processing is done using the [[Minecraft:processor list]] specified for each piece in the template pool. Additionally, jigsaw blocks are replaced with the specified "Turns into" final state (using the {{cd|minecraft:jigsaw_replacement}} processor {{in|je}}). For pieces set to terrain matching each column of blocks is adjusted in height match the terrain (using the {{cd|minecraft:gravity}} processor {{in|je}}).

'''Notes:'''
<references group="note"/>

== Pool aliases ==
'''Pool aliases''' are used to redirect the alias "target pool" referenced in [[Minecraft:jigsaw block]]s to a (different) [[Minecraft:template pool]]s. The redirections are determined before the generation starts, so in a single structure all references to a specific alias template pool are rewired to the same target template pool. Any alias that is not redirected by a pool alias is used directly as reference to a template pool.

=== direct ===
All references to {{nbt|string|alias}} are rewired to {{nbt|string|target}}.
<div class="treeview">
* {{nbt|compound}}: a pool alias
** {{nbt|string|type}}: {{cd|direct}}
** {{nbt|string|alias}}: [[Minecraft:Resource location|ID]] &mdash; alias to be redirected
** {{nbt|string|target}}: {{json ref|template pool}} &mdash; target for redirection
</div>

=== random ===
A target selected from {{nbt|list|targets}} per structure. All references to {{nbt|string|alias}} are rewired that target.
<div class="treeview">
* {{nbt|compound}}: a pool alias
** {{nbt|string|type}}: {{cd|random}}
** {{nbt|string|alias}}: [[Minecraft:Resource location|ID]]
** {{nbt|list|targets}}: list of possible rewiring targets
*** {{nbt|compound}}: a rewiring target
**** {{nbt|int|weight}}: The chance of this target to be selected
**** {{nbt|string|data}}: {{json ref|template pool}} &mdash; target for redirection if selected
</div>

=== random_group ===
A alias group is selected from {{nbt|list|groups}} per structure. All pool aliases in that group are used.

<div class="treeview">
* {{nbt|compound}}: a pool alias
** {{nbt|string|type}}: {{cd|random_group}}
** {{nbt|list|groups}} list of possible rewiring groups. One group is selected per structure generation.
*** {{nbt|compound}}: a group
**** {{nbt|int|weight}}: The chance of this group to be selected
**** {{nbt|list|data}}: list of pool aliases to be used if the group is selected
***** {{nbt|compound}}: any pool alias
</div>

== Data values ==
=== ID ===
{{el|je}}:
{{ID table
|firstcolumnname=Structure type
|displayname=Jigsaw
|spritename=jigsaw
|spritetype=block
|nameid=jigsaw
|foot=1}}

=== Config ===
{{el|java}}:
<section begin="config"/><div class="treeview">
*{{nbt|compound}} Structure configuration
**{{nbt|string|type}}: {{cd|jigsaw}}
** {{Nbt inherit/structure}}
**{{nbt|string}}{{nbt|compound|start_pool}}: {{json ref|template pool|Template pool|inline=1}} &mdash; The template pool the structure starts from.
**{{nbt|int|size}}: Value between 0 and 20 (inclusive) &mdash; The depth of jigsaw structures to generate. 
**{{nbt|int}}{{nbt|compound|start_height}}: If <code>project_start_to_heightmap</code> is unset, the structure will start at the value provided. Otherwise, the value acts as an offset from the [[Minecraft:heightmap]].
*** {{Nbt inherit/height provider}}
**{{nbt|string|project_start_to_heightmap}}: (optional) The [[Minecraft:heightmap]] the start height should project to. Can be <code>WORLD_SURFACE_WG</code>, <code>WORLD_SURFACE</code>, <code>OCEAN_FLOOR_WG</code>, <code>OCEAN_FLOOR</code>, <code>MOTION_BLOCKING</code>, or <code>MOTION_BLOCKING_NO_LEAVES</code>.
**{{nbt|string|start_jigsaw_name}}: (optional) The name of the jigsaw block the structure start attaches to.
**{{nbt|int}}{{nbt|compound|max_distance_from_center}}: Defines the maximum distance of any piece from the structure start. When defined as a single number, defines both horizontal and vertical distance and is limited to the limits of {{nbt|int|horizontal}} (see below).
***{{nbt|int|horizontal}}: Value between 1 and 128 (inclusive) when {{nbt|string|terrain_adaptation}} is "none", otherwise from 1 to 116 (inclusive). &mdash; The maximum horizontal [[Minecraft:Chebyshev distance]] from the jigsaw pieces to the structure start.
***{{nbt|int|vertical}}: Optional value between 1 and 4064 (defaults to 4064) &mdash; The maximum vertical distance of any piece to the structure start.
**{{nbt|bool|use_expansion_hack}}: Allows the structure's vertical limit to be expanded if necessary. Used in villages to prevent cut-off when terrain height varies.
**{{nbt|list|pool_aliases}}: (optional) used to rewire jigsaw pool connections by redirecting pool references on individual structure instances.
*** {{nbt|compound}}: [[Minecraft:Jigsaw_structure#Pool aliases|pool alias]]
**{{nbt|int}}{{nbt|compound|dimension_padding}}: (optional, defaults to {{cd|0}}). Padding on the top and bottom world limit. {{nbt|int}}: shorthand to set the same value for {{nbt|int|bottom}} and {{nbt|int|top}}.
*** {{nbt|int|bottom}}: (optional, defaults to {{cd|0}}), non-negative. Amount of blocks at the bottom build limit that are excluded from the outer bounding box of the structure.
*** {{nbt|int|top}}: (optional, defaults to {{cd|0}}), non-negative. Amount of blocks at the top build limit that are excluded from the outer bounding box of the structure.
**{{nbt|string|liquid_settings}}: (optional, defaults to {{cd|apply_waterlogging}}). How blocks with {{cd|waterlogged}} block state should generate when they overlap with existing water. {{cd|apply_waterlogging}}: [[Minecraft:Waterlogging|waterlog]] block placed inside water, {{cd|ignore_waterlogging}}: keep the {{cd|waterlogged}} block state as is.
</div><section end="config"/>

{{el|bedrock}}:
<div class="treeview">
*{{nbt|compound}} Structure configuration
**{{nbt|string|format_version}}: {{more info}}
**{{nbt|compound|minecraft:jigsaw}}
*** {{nbt|compound|description}}
**** {{nbt|string|identifier}}: The identifier used for {{cmd|locate}} and {{cmd|place}}
*** {{nbt|compound|biome_filter}}: Biomes that this structure is allowed to generate in. {{more info|how is this defined?}} 
*** {{nbt|string|step}}: The step where the structure generates. {{more info|is this the same options as java edition?}}
*** {{nbt|string|terrain_adaptation}}: (Optional, defaults to {{cd|none}}) The type of terrain adaptation used for the structure. {{cd|none}} for no adaptation, {{cd|beard_thin}} is used by [[Minecraft:Pillager Outpost|pillager outposts]] and [[Minecraft:Village|villages]], {{cd|beard_box}} is used by [[Minecraft:Ancient City|ancient cities]], {{cd|bury}} is used by [[Minecraft:Stronghold|strongholds]], and {{cd|encapsulate}} is used by [[Minecraft:Trial Chambers]].
***{{nbt|string|start_pool}}: {{json ref|template pool|Template pool}} &mdash; The template pool the structure starts from.
***{{nbt|int|max_depth}}: Value between 0 and 20 (inclusive) &mdash; The depth of jigsaw structures to generate. 
***{{nbt|int}}{{nbt|compound|start_height}}: If <code>heightmap_projection</code> is unset, the structure will start at the value provided. Otherwise, the value acts as an offset from the [[Minecraft:heightmap]]. {{more info|only constant and uniform work here, and additionally a from_sea vertical anchor}}
**** {{Nbt inherit/height provider}}
***{{nbt|string|heightmap_projection}}: (optional) The [[Minecraft:heightmap]] the start height should project to. Can be <code>world_surface</code> or <code>sea_floor</code>.
***{{nbt|string|start_jigsaw_name}}: (optional) The name of the jigsaw block the structure start attaches to.
***{{nbt|int|max_distance_from_center}}: The maximum 3D [[Minecraft:Chebyshev distance]] from the jigsaw pieces to the structure start. Value between 1 and 128 (inclusive) {{verify|does the reduction to 116 max when using terrain adaptation also exist in bedrock?}}.
***{{nbt|list|pool_aliases}}: (optional) used to rewire jigsaw pool connections by redirecting pool references on individual structure instances.
**** {{nbt|compound}}: [[Minecraft:Jigsaw_structure#Pool aliases|pool alias]]
***{{nbt|int|dimension_padding}}: (optional, defaults to {{cd|0}}). Padding on the top and bottom world limit.
***{{Nbt|string|liquid_settings}}: (optional, defaults to <code>apply_waterlogging</code>). How water interacts with the structure when it is generated. Can be <code>apply_waterlogging</code> or <code>ignore_waterlogging</code>.
</div>

== History ==
=== ''Java Edition'' ===
{{HistoryTable
|{{HistoryLine|java}}
|{{HistoryLine||1.14|dev=18w46a|Added [[Minecraft:jigsaw block]]s.}}
|{{HistoryLine|||dev=18w47a|Added jigsaw structures in the form of [[Minecraft:pillager outpost]].}}
|{{HistoryLine||1.16.2|dev=20w28a|Jigsaw structures can now be customized in [[Minecraft:data pack]]s, using {{cd|configured_structure_features}} of type {{cd|village}}, {{cd|pillager_outpost}}, and {{cd|bastion_remnant}}. They have a maximum radius of 80 blocks.}}
|{{HistoryLine||1.19|dev=Deep Dark Experimental Snapshot 1|Jigsaw structures with radius 128{{verify|might be a bit smaller than that}} can now be generated using the {{cd|configured_structure_features}} type {{cd|ancient_city}}.}}
|{{HistoryLine|||dev=22w11a|Merged the {{cd|structure}} types {{cd|village}}, {{cd|pillager_outpost}} and {{cd|bastion_remnant}} into a single type {{BlockSprite|jigsaw|text='''jigsaw'''}} .
|Added {{nbt|int}}{{nbt|compound|start_height}}, {{nbt|string|project_start_to_heightmap}} and {{nbt|boolean|use_expansion_hack}}.}}
|{{HistoryLine|||dev=22w12a|Added {{nbt|int|max_distance_from_center}}.}}
|{{HistoryLine|||dev=22w13a|Replaced {{nbt|boolean|adapt_noise}} with {{nbt|string|terrain_adaptation}}.}}
|{{HistoryLine|||dev=22w17a|Added {{nbt|string|start_jigsaw_name}}.}}
|{{HistoryLine||1.20.3|dev=23w42a|Added {{nbt|list|pool_aliases}}.}}
|{{HistoryLine||1.21|dev=24w19a|Added {{nbt|int|dimension_padding}}.}}
|{{HistoryLine|||dev=24w20a|{{nbt|int}}{{nbt|compound|dimension_padding}} can now also be specified separately for {{nbt|int|bottom}} and {{nbt|int|top}} padding.}}
|{{HistoryLine|||dev=pre1|Added {{nbt|string|liquid_settings}}.}}
|{{HistoryLine||1.21.9|dev=25w31a|{{nbt|int}}{{nbt|compound|max_distance_from_center}} can now also be specified separately for {{nbt|int|horizontal}} and {{nbt|int|vertical}} distance.}}
}}

=== ''Bedrock Edition'' ===
{{HistoryTable
|{{HistoryLine|bedrock}}
|{{HistoryLine||1.10.0|dev=beta 1.10.0.3|Added [[Minecraft:jigsaw block]]s.}}
|{{HistoryLine||1.21.50|exp=Data-Driven Jigsaw Structures|dev=Preview 1.21.50.26|Jigsaw structures can now be customized in [[Minecraft:add-on]]s, using files json.}}
|{{HistoryLine||1.21.80|exp=Data-Driven Jigsaw Structures|dev=Preview 1.21.80.22|Added {{nbt|int|start_height}}, {{nbt|int|dimension_padding}}, {{nbt|int|max_distance_from_center}} and {{nbt|list|pool_aliases}}.}}
|{{HistoryLine||1.21.90|exp=Data-Driven Jigsaw Structures|dev=Preview 1.21.90.21|Added {{nbt|string|liquid_settings}}}}
|{{HistoryLine||1.21.100|exp=Data-Driven Jigsaw Structures|dev=Preview 1.21.100.20|{{nbt|int}}{{nbt|compound|max_distance_from_center}} now parses horizontal and vertical values separately in an object while supporting horizontal only with parsing as a constant, the vertical value is now optional and defaults to having no limit.}}
|{{HistoryLine||1.21.120|dev=Preview 1.21.120.23|Jigsaw structures can now be customized without using any experiments.}}
}}

== Navigation ==
{{Navbox generated structures}}

[[Minecraft:de:Verbundblock-Konstruktion]]
[[Minecraft:fr:Structure en puzzle]]
[[Minecraft:pt:Estrutura de bloco-quebra-cabeça]]