Iris/docs/18 - Structures Overview.md

# 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

1. Describe the intended result in one sentence: one repeated build, an assembled graph, or a registered Minecraft structure.
2. Choose the matching row in **Which system** below. Do not begin by converting assets between systems.
3. Complete that guide's smallest worked example in a disposable Studio or test world.
4. Validate the pack, place or locate one instance, then generate a natural instance in new chunks.
5. 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>`.