Minecraft:Jigsaw structure

Template:Infobox structure Jigsaw structures are Minecraft:structures that generate using Minecraft:jigsaw blocks.

They are used to generate Template:EnvLink, Template:EnvLink, Template:EnvLink, Template:EnvLink, Template:EnvLink, and Template:EnvLink. The jigsaw structure generation can be customized using Minecraft:data packs Template:In or Minecraft:add-ons Template:In.

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 pools. 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 Template:NbtTemplate:Nbt. 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 Template:Cd, the structure fails to generate.Template:Only<ref group="note" name="fail">When the structure fails to generate, it can't be located using Template:Cmd 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 Template:NbtTemplate:Only/Template:NbtTemplate:Only is set, the start height is based on the specified Minecraft:heightmap, offset by the values result of Template:NbtTemplate:Nbt. Otherwise, Template:NbtTemplate:Nbt is used to determine the start height.

If the structure defines a Template:Nbt, 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 Template:Nbt 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 Template:Nbt blocks away from the lower build limit and Template:Nbt 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 referenced in Template:Nbt 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:

1. All the pieces from the template pool — in random order according to their weight.
2. All the pieces from the fallback pool specified in the template pool — in random order according to their weight.

If the maximum depth (defined by Template:NbtTemplate:Only/Template:NbtTemplate:Only) is reached, point 1 is skipped.

Connecting piece try

From the tried piece a random jigsaw block is selected, that

1. is facing outside of the bounds of the connecting piece
2. has a "name" that matches the "target name" of the parent jigsaw block,
3. 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:

1. 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 Template:Nbt is set to Template:Cd, 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 Template:NbtTemplate:Nbt).</ref>, otherwise the outer bounding box is determined as:
   • Horizontal side-length Template:CdTemplate:Nbt or Template:Nbt.Template:NbtTemplate:Cd
   • Vertical side-length Template:CdTemplate:Nbt or Template:Nbt.Template:NbtTemplate:Cd
   • 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 Template:Nbt or Template:NbtTemplate:NbtTemplate:Only blocks away from the lower build limit and Template:Nbt or Template:NbtTemplate:NbtTemplate:Only blocks away from the upper build limit.
2. Not intersect with any other piece (except those that it is placed inside of)
3. 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 Template:Cd processor Template:In). For pieces set to terrain matching each column of blocks is adjusted in height match the terrain (using the Template:Cd processor Template:In).

Notes: <references group="note"/>

Pool aliases

Pool aliases are used to redirect the alias "target pool" referenced in Minecraft:jigsaw blocks to a (different) Minecraft:template pools. 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 Template:Nbt are rewired to Template:Nbt.

• Template:Nbt: a pool alias
  • Template:Nbt: Template:Cd
  • Template:Nbt: ID — alias to be redirected
  • Template:Nbt: Template:Json ref — target for redirection

random

A target selected from Template:Nbt per structure. All references to Template:Nbt are rewired that target.

• Template:Nbt: a pool alias
  • Template:Nbt: Template:Cd
  • Template:Nbt: ID
  • Template:Nbt: list of possible rewiring targets
    • Template:Nbt: a rewiring target
      • Template:Nbt: The chance of this target to be selected
      • Template:Nbt: Template:Json ref — target for redirection if selected

random_group

A alias group is selected from Template:Nbt per structure. All pool aliases in that group are used.

• Template:Nbt: a pool alias
  • Template:Nbt: Template:Cd
  • Template:Nbt list of possible rewiring groups. One group is selected per structure generation.
    • Template:Nbt: a group
      • Template:Nbt: The chance of this group to be selected
      • Template:Nbt: list of pool aliases to be used if the group is selected
        • Template:Nbt: any pool alias

Data values

ID

Template:El: Template:ID table

Config

Template:El:

<section begin="config"/>

• Template:Nbt Structure configuration
  • Template:Nbt: Template:Cd
  • Template:Nbt inherit/structure
  • Template:NbtTemplate:Nbt: Template:Json ref — The template pool the structure starts from.
  • Template:Nbt: Value between 0 and 20 (inclusive) — The depth of jigsaw structures to generate.
  • Template:NbtTemplate:Nbt: If project_start_to_heightmap is unset, the structure will start at the value provided. Otherwise, the value acts as an offset from the Minecraft:heightmap.
    • Template:Nbt inherit/height provider
  • Template:Nbt: (optional) The Minecraft:heightmap the start height should project to. Can be WORLD_SURFACE_WG, WORLD_SURFACE, OCEAN_FLOOR_WG, OCEAN_FLOOR, MOTION_BLOCKING, or MOTION_BLOCKING_NO_LEAVES.
  • Template:Nbt: (optional) The name of the jigsaw block the structure start attaches to.
  • Template:NbtTemplate:Nbt: 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 Template:Nbt (see below).
    • Template:Nbt: Value between 1 and 128 (inclusive) when Template:Nbt is "none", otherwise from 1 to 116 (inclusive). — The maximum horizontal Minecraft:Chebyshev distance from the jigsaw pieces to the structure start.
    • Template:Nbt: Optional value between 1 and 4064 (defaults to 4064) — The maximum vertical distance of any piece to the structure start.
  • Template:Nbt: Allows the structure's vertical limit to be expanded if necessary. Used in villages to prevent cut-off when terrain height varies.
  • Template:Nbt: (optional) used to rewire jigsaw pool connections by redirecting pool references on individual structure instances.
    • Template:Nbt: pool alias
  • Template:NbtTemplate:Nbt: (optional, defaults to Template:Cd). Padding on the top and bottom world limit. Template:Nbt: shorthand to set the same value for Template:Nbt and Template:Nbt.
    • Template:Nbt: (optional, defaults to Template:Cd), non-negative. Amount of blocks at the bottom build limit that are excluded from the outer bounding box of the structure.
    • Template:Nbt: (optional, defaults to Template:Cd), non-negative. Amount of blocks at the top build limit that are excluded from the outer bounding box of the structure.
  • Template:Nbt: (optional, defaults to Template:Cd). How blocks with Template:Cd block state should generate when they overlap with existing water. Template:Cd: waterlog block placed inside water, Template:Cd: keep the Template:Cd block state as is.

<section end="config"/>

Template:El:

• Template:Nbt Structure configuration
  • Template:Nbt: Template:More info
  • Template:Nbt
    • Template:Nbt
      • Template:Nbt: The identifier used for Template:Cmd and Template:Cmd
    • Template:Nbt: Biomes that this structure is allowed to generate in. Template:More info
    • Template:Nbt: The step where the structure generates. Template:More info
    • Template:Nbt: (Optional, defaults to Template:Cd) The type of terrain adaptation used for the structure. Template:Cd for no adaptation, Template:Cd is used by pillager outposts and villages, Template:Cd is used by ancient cities, Template:Cd is used by strongholds, and Template:Cd is used by Minecraft:Trial Chambers.
    • Template:Nbt: Template:Json ref — The template pool the structure starts from.
    • Template:Nbt: Value between 0 and 20 (inclusive) — The depth of jigsaw structures to generate.
    • Template:NbtTemplate:Nbt: If heightmap_projection is unset, the structure will start at the value provided. Otherwise, the value acts as an offset from the Minecraft:heightmap. Template:More info
      • Template:Nbt inherit/height provider
    • Template:Nbt: (optional) The Minecraft:heightmap the start height should project to. Can be world_surface or sea_floor.
    • Template:Nbt: (optional) The name of the jigsaw block the structure start attaches to.
    • Template:Nbt: The maximum 3D Minecraft:Chebyshev distance from the jigsaw pieces to the structure start. Value between 1 and 128 (inclusive) Template:Verify.
    • Template:Nbt: (optional) used to rewire jigsaw pool connections by redirecting pool references on individual structure instances.
      • Template:Nbt: pool alias
    • Template:Nbt: (optional, defaults to Template:Cd). Padding on the top and bottom world limit.
    • Template:Nbt: (optional, defaults to apply_waterlogging). How water interacts with the structure when it is generated. Can be apply_waterlogging or ignore_waterlogging.

History