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 run saved Iris jigsaws through the shared assembler but do not expose the Bukkit-only Jigsaw Studio command tree.

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`

Tutorial: choose and prove one structure path

Describe the intended result in one sentence: one repeated build, an assembled graph, or a registered Minecraft structure.
Choose the matching row in Which system below. Do not begin by converting assets between systems.
Complete that guide's smallest worked example in a disposable Studio or test world.
Validate the pack, place or locate one instance, then generate a natural instance in new chunks.
Restart and repeat the locate/generation check before adding terrain adaptation, loot, markers, or suppression.

The proof requires both direct inspection and natural placement. /iris structure place proves geometry only; it does not prove spacing, biome eligibility, height gates, or native registry scope.

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 and strongholds. PLANAR_JIGSAW classifies north/east/south/west connectors into six rotation-independent archetypes: blank, end, straight, corner, T-junction, and cross. Each planar archetype has its own width, height, depth, enabled state, and variants; the dimensions do not need to match the other workcells or form a square. SPATIAL_JIGSAW accepts freeform horizontal and vertical connectors in one shared workcell. Bukkit Jigsaw Studio provides automatic capture, a permanent seed-1337 generated preview, dynamic graph evaluation, coherent theme sets, chance and piece rules, mandatory terminal caps, a control-chest GUI, and bound stick tools.

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
Planar village roads, halls, corners, tees, and caps with independent archetype sizes	`PLANAR_JIGSAW` through `/iris jigsaw`
Freeform rooms, stairs, shafts, towers, or strongholds	`SPATIAL_JIGSAW` through `/iris jigsaw`
One authored graph that must also ship as a vanilla 26.2 datapack	`VANILLA_PORTABLE` Iris jigsaw, then strict `/iris jigsaw export`
Move/stilt/encase vanilla structures for Iris terrain	`importedStructures.adjustments`
Remove vanilla villages or other families	`importedStructures.disabled`
Remove one native key without removing its variants	`importedStructures.disabledExact`
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 one registered vanilla/datapack jigsaw	`/iris jigsaw convert`, then edit the owned Iris copy
Bulk-import registered structures or convert non-jigsaw templates	`/iris structure import`, then inspect the Iris copies
Edit an existing unowned Iris graph	`/iris jigsaw adopt inspect`, then apply the reviewed in-place or clone plan
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. Vanilla export is a strict subset: Iris channels, structure edits/loot, fixed piece rotation, custom blocks, and tile/block-entity NBT are rejected rather than silently dropped.

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

/iris jigsaw create ──> transaction-owned objects + pieces + pools + structure
        │
        ├──six planar workcells / one spatial workcell──> variant load + marker capture + automatic atomic save
        ├──seed-1337 preview + dynamic evaluation──> generated read-only assembly
        └──VANILLA_PORTABLE export──> Minecraft 26.2 datapack

registered structure (vanilla / datapack / mod)
        │  generates natively, controlled by importedStructures (disabled / adjustments)
        ├──nativeStructures placement──> vanilla machinery at Iris-chosen points
        └──/iris jigsaw convert or /iris structure import──> 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.

Placement scope is explicit. Iris jigsaws can be attached at dimension, region, surface-biome, or cave-biome scope. Scope is sampled at the start chunk center; cave-biome placements participate only when their resolved anchor is CAVE_FLOOR, CAVE_CEILING, CAVE_CENTER, or CAVE_ANY, and an optional placement caveBiomes list is rechecked at the actual anchor. See 15 - Caves & Carving.md.

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>.

7.7 KiB Raw Blame History