Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VolmitSoftware/Iris/llms.txt

Use this file to discover all available pages before exploring further.

Jigsaw structures are Iris’s most powerful feature for creating complex, procedural structures that grow organically. Unlike static objects, jigsaw structures connect multiple pieces together using a connector-based system.

​
Overview

The jigsaw system consists of three main components:
  • Jigsaw Structures: The top-level definition that specifies starting pieces and configuration
  • Jigsaw Pools: Collections of pieces that can be randomly selected
  • Jigsaw Pieces: Individual building blocks with connectors that link to other pieces

​
Creating a Jigsaw Structure

Jigsaw structures are defined in the jigsaw-structures/ folder.

​
Basic Structure Configuration

{
  "pieces": [
    "my-village/starting-piece"
  ],
  "maxDepth": 9,
  "terminate": true
}

​
Configuration Options

​
Starting Pieces

pieces (required) Array of starting pieces. Iris randomly selects one piece to begin structure generation, then connects additional pieces using the pools defined in connectors. 
"pieces": [
  "village/town-center",
  "village/fountain-plaza"
]

​
Max Depth

maxDepth (default: 9) The maximum number of pieces that can extend from the center piece. Higher values create larger structures but may impact performance. 
"maxDepth": 12
Depth affects parallax layer growth which can slow generation. Values above 15 may cause noticeable performance impact.

​
Termination

terminate (default: true) Automatically caps off connector endpoints with terminal pieces (pieces with only one connector). 
"terminate": true,
"terminatePool": "village/end-pieces"
terminatePool Specify a custom pool for terminating pieces instead of searching all valid pools.

​
Y Position Control

overrideYRange Override the default heightmap placement with a specific Y range. 
"overrideYRange": {
  "min": 60,
  "max": 80,
  "style": {
    "type": "PERLIN"
  }
}
lockY (default: -1) Force all pieces to generate at a specific Y coordinate. 
"lockY": 64

​
Rotation

disableInitialRotation (default: false) Prevents the starting piece from rotating randomly. 
"disableInitialRotation": true

​
Parallax Optimization

useMaxPieceSizeForParallaxRadius (default: false) Uses maximum piece dimensions instead of average for parallax calculations. Enable this if you see structure cut-offs or broken terrain. 
"useMaxPieceSizeForParallaxRadius": true
Keep this disabled unless you experience visual issues. It’s more conservative but less performant.

​
Force Placement

forcePlace (default: false) Forces the entire structure to place, overriding collision detection. 
"forcePlace": false

​
Structure Key

structureKey Minecraft structure key for treasure map integration. 
"structureKey": "minecraft:village"

​
Using Datapack Structures

datapackStructures Use vanilla Minecraft datapack structures instead of Iris pieces. When defined, all other settings are ignored. 
{
  "datapackStructures": [
    "minecraft:village/plains/town_centers/plains_meeting_point_1",
    "minecraft:village/plains/town_centers/plains_meeting_point_2"
  ]
}

​
Jigsaw Pools

Pools are collections of pieces stored in jigsaw-pools/. 
{
  "pieces": [
    "village/houses/small-house-1",
    "village/houses/small-house-2",
    "village/houses/large-house-1"
  ]
}
Connectors reference pools to determine which pieces can attach.

​
Jigsaw Pieces

Pieces are the building blocks, stored in jigsaw-pieces/.

​
Basic Piece

{
  "object": "village/path-straight",
  "connectors": [
    {
      "name": "road",
      "targetName": "road",
      "position": { "x": 0, "y": 0, "z": 5 },
      "direction": "NORTH_NEGATIVE_Z",
      "pools": ["village/paths"]
    },
    {
      "name": "road",
      "targetName": "road",
      "position": { "x": 0, "y": 0, "z": -5 },
      "direction": "SOUTH_POSITIVE_Z",
      "pools": ["village/paths"]
    }
  ]
}

​
Connector Properties

name (required) Identifier for organization. Multiple connectors can share the same name. targetName (default: "*") Target specific connector names in other pieces. Use "*" to match any connector. 
"targetName": "entrance"
position (required) Relative coordinates within the piece where the connector is located. 
"position": { "x": 5, "y": 0, "z": 0 }
direction (required) The direction the connector faces. Pieces attach in this direction. Options:
  • UP_POSITIVE_Y
  • DOWN_NEGATIVE_Y
  • NORTH_NEGATIVE_Z
  • SOUTH_POSITIVE_Z
  • EAST_POSITIVE_X
  • WEST_NEGATIVE_X
pools (required) Array of pools to pull pieces from for this connector. 
"pools": [
  "village/decorations",
  "village/paths"
]
rotateConnector (default: false) Allows the placed piece to rotate on the connector. 
"rotateConnector": true
innerConnector (default: false) Allows pieces to collide with the parent piece’s bounding box. Useful for decorations like lamp posts on roads. 
"innerConnector": true
lockY (default: false) Prevents the connector’s Y position from adjusting. 
"lockY": true

​
Entity Spawning

spawnEntity Spawn entities at connector positions. 
"spawnEntity": "villager-farmer",
"entityPosition": { "x": 0, "y": 1, "z": 0 },
"entityCount": 3,
"keepEntity": true
keepEntity (default: false) Prevents spawned entities from despawning.

​
Placement Options

placementOptions Configure object placement behavior. Only define this when needed as it impacts performance. 
"placementOptions": {
  "mode": "FAST_MAX_HEIGHT"
}
See IrisObjectPlacement.java:58 for available modes.

​
Advanced Examples

​
Village with Roads

Structure: 
{
  "pieces": ["village/plaza"],
  "maxDepth": 8,
  "terminate": true,
  "terminatePool": "village/road-ends"
}
Starting Piece (plaza): 
{
  "object": "village/plaza-fountain",
  "connectors": [
    {
      "name": "road",
      "targetName": "road",
      "position": { "x": 10, "y": 0, "z": 0 },
      "direction": "EAST_POSITIVE_X",
      "pools": ["village/roads"]
    },
    {
      "name": "road",
      "targetName": "road",
      "position": { "x": -10, "y": 0, "z": 0 },
      "direction": "WEST_NEGATIVE_X",
      "pools": ["village/roads"]
    }
  ]
}
Road Piece: 
{
  "object": "village/path-5x5",
  "connectors": [
    {
      "name": "road",
      "targetName": "road",
      "position": { "x": 5, "y": 0, "z": 0 },
      "direction": "EAST_POSITIVE_X",
      "pools": ["village/roads"],
      "rotateConnector": true
    },
    {
      "name": "building",
      "targetName": "entrance",
      "position": { "x": 0, "y": 0, "z": 3 },
      "direction": "NORTH_NEGATIVE_Z",
      "pools": ["village/buildings"],
      "innerConnector": true
    }
  ]
}

​
Dungeon System

{
  "pieces": ["dungeon/entrance"],
  "maxDepth": 15,
  "lockY": 20,
  "terminate": true,
  "disableInitialRotation": true
}

​
Performance Tips

  1. Keep maxDepth reasonable: Values over 12 can significantly slow generation
  2. Limit piece complexity: Fewer connectors per piece = faster generation
  3. Use placement options sparingly: Only set placementOptions when absolutely necessary
  4. Optimize pool sizes: Smaller pools (3-5 pieces) perform better than large ones
  5. Disable parallax optimization: Keep useMaxPieceSizeForParallaxRadius off unless needed

​
Troubleshooting

​
Structure pieces are cut off

Enable useMaxPieceSizeForParallaxRadius: 
"useMaxPieceSizeForParallaxRadius": true

​
Structures won’t connect properly

  • Verify connector positions match object dimensions
  • Check that connector directions are opposite (NORTH connects to SOUTH)
  • Ensure targetName matches between connectors or use "*"

​
Structures float or sink into terrain

  • Use overrideYRange for consistent placement
  • Adjust placementOptions.mode
  • Consider using lockY for underground structures

​
Performance issues

  • Reduce maxDepth
  • Simplify connector networks
  • Remove unnecessary placementOptions
  • Use smaller pool sizes

Build docs developers (and LLMs) love

Get started for freeTalk to us