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

Docvks

Browse Source
This commit is contained in:
Brian Neumann-Fopiano
2026-08-10 15:47:26 -04:00
parent 506787f51a
commit ebfe278b3b
37 changed files with 2064 additions and 357 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/18 - Structures Overview.md
+28 -5
View File
@@ -2,7 +2,7 @@
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.
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 |
|---|---|
@@ -11,13 +11,23 @@ Command listings assume the Bukkit/Paper plugin. Fabric/Forge/NeoForge expose a
| `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: 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.
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.
@@ -29,15 +39,20 @@ Generated by Minecraft's machinery with full native fidelity (processors, entiti
| 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` |
| 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 |
| 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.
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
@@ -46,10 +61,16 @@ build in world ──wand──> object (.iob) ──objects[] placement──>
│
└──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 structure import──> objects + pieces + pools + structure (editable Iris copies)
└──/iris jigsaw convert or /iris structure import──> editable Iris copies
```
## Shared rules
@@ -62,4 +83,6 @@ registered structure (vanilla / datapack / mod)
**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>`.