Iris/docs/18 - Structures Overview.md

18 - Structures Overview

Iris puts built content into the world three different ways: single .iob objects stamped by chance, Iris jigsaw structures assembled from many pieces, and native structures generated by Minecraft's own machinery. They share pack folders and some JSON, but they are separate systems with different authoring tools and different failure modes. This page picks one; the linked guides do the work.

The short version

Ask what the thing you want actually is.

• One build, repeated. A rock, a tree, a ruined tower, a bandit camp — always the same geometry, scattered around. That is an object.
• A build that is different every time. A village that grows its own road network, a stronghold with rooms and corridors, a fort whose towers vary. That is an Iris jigsaw structure.
• Something Minecraft already knows how to build. A vanilla village, a datapack's town from Terralith or Towns and Towers, an ocean monument with its real guardians and loot. That is a native structure, and your job is to control it, not rebuild it.

Do not convert between systems as a first move. Objects are not "small jigsaws", and a native structure re-imported as objects loses its processors, entities, and spawners.

1. Objects

An object is one .iob file and one entry in a biome's or region's objects[] array. The engine rolls a chance per chunk, then attempts that many stamps at random columns. Objects have by far the richest terrain-fitting tools — stilts, terrain vacuuming, surface painting, cave floor and ceiling anchors, snow, block find-and-replace, loot, and entity markers.

Reach for an object when the geometry is fixed and you mostly care about where and how it sits.

Example — scatter one boulder through a biome, seated one block into the ground:

{
  "objects": [
    {
      "place": ["clutter/boulder1", "clutter/boulder2"],
      "chance": 0.08,
      "density": 2,
      "mode": "CENTER_HEIGHT",
      "translate": { "y": -1 }
    }
  ]
}

Building and saving the .iob is 19 - Objects.md. Every placement field is 20 - Object Placement.md.

Objects attach to biomes and regions only. A dimension has no objects[].

2. Iris jigsaw structures

A jigsaw structure is a set of pieces — each piece is itself an object — that the assembler snaps together through matching connectors until it runs out of depth, space, or candidate pieces. Villages, forts, and strongholds are the shape of the problem. You author the pieces and the graph in Jigsaw Studio, and the saved resources run on every platform through the shared core assembler.

Two layout modes:

• PLANAR_JIGSAW constrains pieces to a grid, which is what you want for roads, halls, and courtyards. Iris classifies every piece by which of its north/east/south/west sides carry connectors, giving six rotation-independent archetypes: blank, end, straight, corner, tee, and cross. Each archetype gets its own workcell with its own width, height, depth, and enabled flag — they do not have to match each other and they do not have to be square.
• SPATIAL_JIGSAW is freeform in all three axes, for towers, shafts, stacked rooms, and stronghold-style sprawl. It uses one shared workcell.

Separately from the mode, a structure declares a compatibility contract. IRIS_EXTENDED (the default) gets the full Iris feature set. VANILLA_PORTABLE restricts the project so /iris jigsaw export can emit it as a real Minecraft 26.2 datapack — the exporter is strict and rejects the project outright rather than quietly dropping anything it cannot represent.

Example — create a planar project and place the finished structure from a region:

/iris jigsaw create dimension=<pack> key=forts/border mode=planar width=15 height=15 depth=15

{
  "structures": [
    {
      "structures": ["forts/border"],
      "distribution": "RANDOM_SPREAD",
      "spacing": 48,
      "separation": 16
    }
  ]
}

The whole workflow is 21 - Jigsaw Structures.md.

/iris jigsaw is Bukkit-only and player-only. Fabric, Forge, and NeoForge generate saved jigsaw structures perfectly well — they just have no authoring commands, so author on a Bukkit server and ship the pack.

3. Native structures

Native means anything in Minecraft's live structure registry: vanilla, a datapack, or a mod. Minecraft builds it, so you get full fidelity — processors, entities, spawners, and real loot tables — and Iris's job is to decide whether it generates, where, and how it meets Iris terrain.

Four things you can do:

• Leave it generating natively and fix how it sits, with importedStructures.adjustments (y shift, stilts, encasing, Y bands).
• Turn a structure or a whole family off, with importedStructures.disabled (prefix and family matching) or importedStructures.disabledExact (one key, leaving its variants alone).
• Ingest a datapack into one dimension with datapackImports, so its structures generate in that Iris world.
• Take positioning away from Minecraft entirely: list registered keys in a placement's nativeStructures and let Iris choose the start points on its own grid. Add nativeSuppression: "REPLACE_SOURCE" on a dimension-level placement to stop the original from also generating on its own.

Example — stop vanilla villages generating on their own, then place the plains variant yourself on an Iris grid, in the dimension file:

{
  "importedStructures": {
    "disabled": ["minecraft:village"]
  },
  "structures": [
    {
      "nativeStructures": [{ "structure": "minecraft:village_plains" }],
      "nativeSuppression": "REPLACE_SOURCE",
      "distribution": "RANDOM_SPREAD",
      "spacing": 40,
      "separation": 12
    }
  ]
}

Ingest, adjustment, disabling, and conversion back into editable Iris resources are all in 22 - Native Structures & Datapacks.md.

Quick reference

Goal	Use	Guide
Scatter a fixed build across a biome — trees, rocks, ruins, clutter	Object + objects[]	20 - Object Placement.md
Put pack loot in an object's chests	Placement loot / vanillaLoot	20 - Object Placement.md
Spawn mobs from a placed build	Placement markers[] plus a markers/ resource	20 - Object Placement.md
Multi-room build that should differ every time	Iris jigsaw structure	21 - Jigsaw Structures.md
Village-style roads, halls, corners, tees, and caps	PLANAR_JIGSAW through /iris jigsaw	21 - Jigsaw Structures.md
Towers, shafts, stacked rooms, stronghold sprawl	SPATIAL_JIGSAW through /iris jigsaw	21 - Jigsaw Structures.md
One authored graph that must also ship as a vanilla 26.2 datapack	compatibility: VANILLA_PORTABLE, then /iris jigsaw export	21 - Jigsaw Structures.md
A vanilla structure sits badly in Iris terrain	importedStructures.adjustments	22 - Native Structures & Datapacks.md
Remove vanilla villages or another whole family	importedStructures.disabled	22 - Native Structures & Datapacks.md
Remove one key without touching its variants	importedStructures.disabledExact	22 - Native Structures & Datapacks.md
Make a datapack's structures generate natively	datapackImports plus ingest	22 - Native Structures & Datapacks.md
Keep a datapack's buildings but choose the locations	Disable the namespace, then a nativeStructures placement	22 - Native Structures & Datapacks.md
Replace a vanilla structure with Iris-positioned starts	Dimension placement with nativeSuppression: REPLACE_SOURCE	22 - Native Structures & Datapacks.md
Edit one registered vanilla or datapack jigsaw	/iris jigsaw convert, then edit the Iris copy	22 - Native Structures & Datapacks.md
Bulk-import registered structures and templates	/iris structure import, then inspect the copies	22 - Native Structures & Datapacks.md
Edit an existing Iris graph you do not own	/iris jigsaw adopt inspect, then apply the reviewed plan	21 - Jigsaw Structures.md
Builds shipped as vanilla .nbt	Ship them in a datapack, or import them as objects	22 - Native Structures & Datapacks.md

The systems compose, and shipping packs use all three: objects for decoration, jigsaws for authored multi-piece content, and native placements with suppression for the vanilla keys they want to reposition.

How the pieces connect

build in world ──wand──> object (.iob) ──┬── objects[] on a biome/region ──> scattered by chance
                                         │
                                         └── jigsaw piece ──> pool ──> structure ──┐
                                                                                   │
registered structure (vanilla / datapack / mod)                                    │
        │                                                                          │
        ├── generates natively, shaped by importedStructures                       │
        └── listed in a placement's nativeStructures ──────────┐                   │
                                                               ▼                   ▼
                                              structures[] on a dimension / region / biome

An Iris structure and a native structure both arrive through the same structures[] array — the difference is whether the entry names Iris assembly resources (structures) or registry keys (nativeStructures).

Rules that apply to all three

Keys are relative paths. Every pack resource is keyed by its path under its own folder, without the extension: objects/trees/oak/big1.iob is the object trees/oak/big1, and jigsaw-pools/fort/starts.json is the pool fort/starts.

Only new chunks change. Editing a placement or a structure control never rewrites terrain that already generated. Every check you run has to happen in chunks generated after the edit.

Worlds carry their own copy of the pack. On world create the pack is copied to <world>/iris/pack, and that copy is what the world loads from then on. Editing packs/<pack> changes nothing in an existing world until you run /iris developer update-world world=<world> pack=<dimension> confirm=true and the world is loaded again. Studio worlds are the exception: they read the live pack and hotload JSON and .iob edits into newly generated chunks about once a second.

Placement scope is explicit. structures[] can sit on a dimension, a region, or a biome. Scope is sampled at the center of the start chunk. Cave-biome entries only participate when the placement's resolved anchor is CAVE_FLOOR, CAVE_CEILING, CAVE_CENTER, or CAVE_ANY, and an optional caveBiomes allowlist is rechecked at the anchor Iris actually picked. See 15 - Caves & Carving.md.

Objects never write into native structure pieces. If any block of an object placement would land inside a live native structure volume, the whole placement is dropped — forcePlace: true does not override this. Pieces of an Iris structure are exempt, because they route through the internal structure path.

Command shape. On Bukkit, Director optional parameters are always key=value — /iris structure verify overworld radius=200, never a bare trailing number. The modded loaders use brigadier literals instead.

Validate before shipping. /iris pack validate pack=<pack> on Bukkit (the argument is required there; pass pack= with an empty value to cover every pack). On a modded loader use /iris pack validate <pack>, or omit the pack to validate all of them. It compiles the jigsaw graph, checks native-replacement placements, and runs object surface-support, loot, spawner, and block-property checks.

Proving a structure path works

1. Say in one sentence what you want: one repeated build, an assembled graph, or a registered Minecraft structure.
2. Pick the matching system above and do that guide's smallest worked example in a disposable Studio or test world. Do not start by converting assets between systems.
3. Validate the pack.
4. Place or locate one instance directly. On Bukkit that is /iris object paste <key> for objects and /iris structure place <dimension> <structure> for structures.
5. Then generate a natural instance in fresh chunks, and check again after a restart.

Steps 4 and 5 are both required. A direct place proves geometry and nothing else — it does not prove spacing, biome eligibility, height gates, or native registry scope. Only natural generation does that.

Add terrain adaptation, loot, markers, and suppression after the plain case generates. Debugging a stack of five features at once is how a broken key looks like a broken engine.