Brian Neumann-Fopiano
4.7 KiB
18 - Structures Overview
Iris places built content through three systems: single .iob objects, multi-piece Iris jigsaw assemblies, and native (vanilla/datapack/mod) structures. They share pack folders and some placement JSON, but each system has different fidelity, terrain tools, and commands. This page chooses the system; the linked guides are the field and workflow references.
Command listings assume the Bukkit/Paper plugin. Fabric/Forge/NeoForge expose a reduced command surface.
| Guide | Covers |
|---|---|
19 - Objects.md |
.iob format, wand/studio authoring, .schem import, editing |
20 - Object Placement.md |
Biome/region objects[]: chance, density, modes, loot, surface support |
21 - Jigsaw Structures.md |
Iris multi-piece structures: pieces, pools, connectors, grids |
22 - Native Structures & Datapacks.md |
Vanilla/datapack structures, ingest, adjustments, nativeStructures |
The three systems
1. Objects (objects/*.iob + objects[] on a biome or region).
A single build stamped by chance and density: trees, rocks, ruins, camps. Object placements have the richest terrain-fitting tools (stilts, vacuum, paint, cave anchors, snow, edit, loot, markers). Dimensions do not carry objects[].
2. Iris jigsaw structures (structures/, jigsaw-pools/, jigsaw-pieces/ + structures[] placement).
Multi-piece assemblies in the style of villages: pieces connect through named connectors drawn from weighted pools, on a deterministic placement grid. Every piece is an Iris object, so the assembly is fully editable.
3. Native structures (vanilla, datapack, and mod structures controlled from the dimension file). Generated by Minecraft's machinery with full native fidelity (processors, entities, spawners, loot). Iris can disable them, adjust them, ingest datapacks, and place specific registered keys on Iris grids.
Which system
| Goal | Use |
|---|---|
| Scatter a build across a biome (trees, rocks, ruins, clutter) | Object + objects[] placement |
| Pack loot tables on chests | Object placement loot / vanillaLoot |
| Procedural multi-room structure you fully author | Iris jigsaw structure |
| Move/stilt/encase vanilla structures for Iris terrain | importedStructures.adjustments |
| Remove vanilla villages or other families | importedStructures.disabled |
| Datapack structures generating natively | datapackImports + ingest |
| Datapack structures only where you choose | Disable namespace + nativeStructures placement |
| Replace a vanilla structure with Iris-positioned native starts | Dimension placement with nativeSuppression: REPLACE_SOURCE |
| Edit vanilla/datapack blocks, pieces, or pools | /iris structure import, then edit Iris copies |
| Builds from vanilla structure blocks | Ship .nbt in a datapack, or import as objects — see 22 - Native Structures & Datapacks.md |
Systems compose. Shipping packs commonly use objects for decoration, Iris or imported jigsaws for multi-piece content, and native placements with suppression for selected vanilla keys.
How the pieces relate
build in world ──wand──> object (.iob) ──objects[] placement──> generates in biome/region
│
└──jigsaw-piece JSON──> pool ──> structure ──structures[] placement──> assembled in world
registered structure (vanilla / datapack / mod)
│ generates natively, controlled by importedStructures (disabled / adjustments)
├──nativeStructures placement──> vanilla machinery at Iris-chosen points
└──/iris structure import──> objects + pieces + pools + structure (editable Iris copies)
Shared rules
Command shape. Director optional parameters are always key=value (/iris structure verify overworld radius=200, never a bare trailing number).
Keys are relative paths. Pack resources are keyed by path under their folder without extension: objects/trees/oak/big1.iob → object trees/oak/big1; jigsaw-pools/fort/starts.json → pool fort/starts.
Worlds snapshot the pack. On world create, the pack is copied to <world>/iris/pack and that copy is authoritative. Editing plugins/Iris/packs/<pack> does not change an existing world until /iris developer update-world world=<world> pack=<dimension> confirm=true (all arguments keyed) and a restart. Studio worlds read the live pack and hotload JSON/object edits into newly generated chunks about once per second.
Only new chunks change. Placement and structure-control edits affect chunks generated after the config existed.
Validate before shipping. On Bukkit, /iris pack validate pack=<pack> runs full pack validation, including jigsaw-graph and structure placement checks. Modded uses /iris pack validate <pack>.