mirrors/Iris
1
0
Fork 0
mirror of https://github.com/VolmitSoftware/Iris.git synced 2026-08-27 04:37:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

d

Browse Source
This commit is contained in:
Brian Neumann-Fopiano
2026-08-12 13:52:16 -04:00
parent 12b97b7994
commit 365205ad0a
82 changed files with 7978 additions and 5625 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/18 - Structures Overview.md
+155 -70
View File
@@ -1,89 +1,174 @@
# 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.
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.
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.
## The short version
| 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` |
Ask what the thing you want actually is.
## Tutorial: choose and prove one structure path
- **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.
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.
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.
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.
## 1. Objects
## The three systems
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.
**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[]`.
Reach for an object when the geometry is fixed and you mostly care about *where* and *how it sits*.
**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.
Example — scatter one boulder through a biome, seated one block into the ground:
**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
```json
{
"objects": [
{
"place": ["clutter/boulder1", "clutter/boulder2"],
"chance": 0.08,
"density": 2,
"mode": "CENTER_HEIGHT",
"translate": { "y": -1 }
}
]
}
```
## Shared rules
Building and saving the `.iob` is `19 - Objects.md`. Every placement field is `20 - Object Placement.md`.
**Command shape.** Director optional parameters are always `key=value` (`/iris structure verify overworld radius=200`, never a bare trailing number).
Objects attach to biomes and regions only. A dimension has no `objects[]`.
**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`.
## 2. Iris jigsaw structures
**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.
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.
**Only new chunks change.** Placement and structure-control edits affect chunks generated after the config existed.
Two layout modes:
**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`.
- `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.
**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>`.
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:
```text
/iris jigsaw create dimension=<pack> key=forts/border mode=planar width=15 height=15 depth=15
```
```json
{
"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:
```json
{
"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.