mirror of
https://github.com/VolmitSoftware/Iris.git
synced 2026-08-27 12:41:43 +00:00
d
This commit is contained in:
Brian Neumann-Fopiano
+115
-117
@@ -1,239 +1,237 @@
|
||||
# 19 - Objects
|
||||
|
||||
An Iris object is a sparse voxel volume (block states plus block-entity data) stored as `.iob` under a pack's `objects/` folder. This guide covers creating, importing, and editing objects. Generation wiring is `20 - Object Placement.md`; jigsaw pieces are `21 - Jigsaw Structures.md`.
|
||||
An Iris object is a sparse voxel volume — block states plus block-entity data — stored as a `.iob` file under a pack's `objects/` folder. You build it in a world, select it with a wand, and save it into the pack; nothing about the object itself says where it generates. Wiring it into generation is `20 - Object Placement.md`; using objects as jigsaw pieces is `21 - Jigsaw Structures.md`.
|
||||
|
||||
## Tutorial outcome
|
||||
## Capture and save an object
|
||||
|
||||
Build a small object in Studio, select its exact bounds, save it under a stable key, paste it once for geometry verification, and then wire it into generation in `20 - Object Placement.md`. Use a disposable object key until the bounds and origin are correct; overwriting an object has no automatic backup and does not rewrite copies already placed in chunks.
|
||||
|
||||
The object tutorial is complete when `/iris object analyze <key>` reports the expected dimensions and block count, `/iris object paste <key> edit=true` aligns correctly at the target, and a save/reopen cycle preserves block states and block-entity data.
|
||||
|
||||
Prerequisites: a writable pack, operator access on a Bukkit-family server, and a finished test build. A Studio world is the shortest path:
|
||||
Prerequisites: a writable pack, operator access on a Bukkit-family server, and something built to capture. A Studio world is the shortest path because it hotloads pack edits and starts you in creative.
|
||||
|
||||
```text
|
||||
/iris studio open <pack> seed=1337
|
||||
/iris object wand
|
||||
```
|
||||
|
||||
1. Left-click one selection corner and right-click the opposite corner. Run `/iris object x+y` if the rough selection should tighten around the build while keeping its base.
|
||||
2. Save a stable path with `/iris object save tutorial/lookout overwrite=true`. Outside an Iris world, use `/iris object save dimension=<pack> tutorial/lookout overwrite=true`.
|
||||
3. Confirm that `objects/tutorial/lookout.iob` exists and run `/iris object analyze tutorial/lookout`.
|
||||
4. Run `/iris object paste tutorial/lookout edit=true`; inspect alignment and block-entity data, make any edits, and save the same key with `overwrite=true`.
|
||||
5. Close and reopen Studio, paste the object again, then complete the natural-placement tutorial in `20 - Object Placement.md`.
|
||||
1. **Select.** Left-click one corner of the build, right-click the opposite corner. The selection lives on the wand item, and particles outline the box out to 256 blocks from you.
|
||||
2. **Tighten.** Run `/iris object x+y`. It walks the selection upward until the slab is empty air, backs off one, then pulls the four side faces in until each touches a block. Use `/iris object x&y` instead if the selection also needs to find its own floor. The saved volume is exactly the selection box, so any air you leave in it moves the object's origin.
|
||||
3. **Save into the pack.** `/iris object save tutorial/lookout`. Inside an Iris world the target pack resolves automatically; anywhere else pass `dimension=<pack>`. Add `overwrite=true` to replace an existing file — there is no backup. If the build contains chests, signs, banners, or spawners you care about, add `legacy=false` (section 3).
|
||||
Success looks like: a chat line naming the pack and the object, and a new file at `<data>/packs/<dimension load key>/objects/tutorial/lookout.iob`.
|
||||
4. **Verify it loads.** `/iris object analyze tutorial/lookout` reads the file back and reports width x height x depth, total block count, and the ten most common materials. If those numbers match what you selected, the file is good.
|
||||
5. **Verify it pastes.** `/iris object paste tutorial/lookout edit=true` stamps a copy where you are looking and hands you a wand already fitted to it. Walk the copy: check the orientation, check that chests still have contents and signs still have text, fix anything wrong in place, then re-save the same key with `overwrite=true`. `/iris object undo` removes the pasted copy.
|
||||
6. **Prove it survives a reload.** Close and reopen Studio, then paste again. Block states and block-entity data must come back identical; if a chest is empty now, the object was captured through a path that drops tile data (section 6).
|
||||
|
||||
If the save cannot resolve a pack, pass `dimension=<pack>`. If the paste is offset, inspect air padding inside the selection because the object origin is the bounding-box center. If a converted schematic has empty chests, signs, or spawners, use the live paste-and-wand route in section 3.2.
|
||||
The object is finished when `analyze` reports the dimensions you expect, a fresh paste lines up on the target block, and a save/reopen cycle changes nothing. Then continue with `20 - Object Placement.md`.
|
||||
|
||||
Use a throwaway key like `scratch/test1` until the bounds and origin are right. Overwriting an object does not rewrite copies already generated into existing chunks.
|
||||
|
||||
## 1. What an object is
|
||||
|
||||
An object stores bounding box (`w × h × d`), a sparse block map, and a sparse tile-data map. Origin is always the **center** of the bounding box (`w/2, h/2, d/2`, integer division) — derived from dimensions, never stored, recomputed on load.
|
||||
An object stores a bounding box (`w x h x d`), a sparse map of block states, and a sparse map of tile data. The origin is always the **center** of the bounding box — `w/2, h/2, d/2` with integer division. It is derived from the dimensions, never written to the file, and recomputed every load.
|
||||
|
||||
Stored:
|
||||
|
||||
- Every block except plain `minecraft:air`. `cave_air` and `void_air` **are** stored (use them to author carve-outs that clear terrain when placed).
|
||||
- Full block-entity NBT for tiles: chest inventories, sign text, spawners, furnaces, banners, decorated pots. A chest with a vanilla loot table keeps the table key and loot seed.
|
||||
- Every block in the selection except plain `minecraft:air`.
|
||||
- Block-entity data, at one of two fidelities. `/iris object save` defaults to `legacy=true`, which writes a reduced record for the block types it has a handler for: a sign keeps its front four lines and color and **loses its back side**, a spawner keeps only the entity type it spawns, a banner keeps its patterns and base color, and a container with a vanilla loot table keeps the table key and loot seed. Anything without a matching handler — including a hand-filled chest, a furnace with contents, a decorated pot — falls through to the full block-entity NBT. Pass `legacy=false` to serialize everything in full. Object studio click-to-save always writes full NBT.
|
||||
|
||||
Not stored:
|
||||
|
||||
- **Entities** (armor stands, item frames, paintings, mobs) — dropped on save. Runtime entity spawns use placement markers (`20 - Object Placement.md`).
|
||||
- **Entities.** Armor stands, item frames, paintings, and mobs are dropped on save. Runtime entity spawns come from placement markers instead (`20 - Object Placement.md`).
|
||||
- **Biomes.**
|
||||
- Jigsaw blocks, structure blocks, and structure voids — stripped when the `.iob` is **read**. Iris jigsaw connectors are JSON metadata, not blocks (`21 - Jigsaw Structures.md`).
|
||||
- **Jigsaw blocks, structure blocks, and structure voids.** These are filtered out when the `.iob` is *read*, not when it is written, so they can sit in a file and still never reach the world. Only the block is dropped; a tile-data entry saved at that position still loads. Iris jigsaw connectors are JSON metadata, not blocks (`21 - Jigsaw Structures.md`).
|
||||
|
||||
**Air is not one thing.** `minecraft:air` is skipped at capture. `cave_air` and `void_air` are both captured — but at placement time Iris skips `air` and `cave_air` blocks and only writes `void_air`. So `void_air` is the block to use when you want an object to carve terrain away, and `cave_air` inside an object is dead weight in every mode except the internal `STRUCTURE_PIECE` path.
|
||||
|
||||
### Format limits
|
||||
|
||||
`.iob` V2 uses short-typed centered coordinates (±32,767 per axis) and a short-counted palette capped at 32,767 distinct block states. Pre-V2 files still load via a legacy reader. No explicit size cap on save; practical limits are memory and wand scan budget (~30 ms/tick).
|
||||
`.iob` V2 writes an `Iris V2 IOB;` header, then short-typed centered coordinates and a short-counted palette. That gives a working range of +/- 32,767 blocks per axis from the center and 32,767 distinct block states per object. Neither limit is checked on save — exceed either and the shorts wrap silently, so the file writes and then reads back wrong. Files written before V2 still load through a legacy reader, tried automatically when the V2 header is missing. Nothing caps the block count; the practical limits are memory and the wand's scan budget, which processes 30 ms of blocks per tick by default (`-Diris.ms_per_tick`).
|
||||
|
||||
### Where objects live
|
||||
### Where objects live and how they are named
|
||||
|
||||
```
|
||||
plugins/Iris/packs/<pack>/objects/**/*.iob
|
||||
<platform data folder>/packs/<pack>/objects/**/*.iob
|
||||
```
|
||||
|
||||
Object key = path relative to `objects/`, `/`-separated, no extension:
|
||||
On a Bukkit-family server that is `plugins/Iris/packs/<pack>/objects/`. The object key is the path under `objects/`, slash-separated, without the extension:
|
||||
|
||||
```
|
||||
objects/light.iob -> "light"
|
||||
objects/trees/oak/big_oak_1.iob -> "trees/oak/big_oak_1"
|
||||
```
|
||||
|
||||
Keys resolve within the current pack. Outside an Iris world, lookups scan every visible pack — bare keys shared across packs are ambiguous; use distinctive subfolder paths.
|
||||
Keys resolve within the current pack first. Outside an Iris world, lookups fall back to scanning every visible pack and take the **first** one that resolves the key, with no warning that others also matched. That matters most for `/iris object shrink`, which resolves this way and then overwrites whatever it found. Give objects distinctive subfolder paths.
|
||||
|
||||
## 2. Making objects in-game
|
||||
## 2. Building and selecting in-game
|
||||
|
||||
### 2.1 Build surfaces
|
||||
### Build surfaces
|
||||
|
||||
- **Pack studio** — world generated from your pack: `/iris studio open <dimension> [seed=1337]`. Close with `/iris studio close`.
|
||||
- **Object studio** — flat gallery with every object in the pack on a grid and click-to-save editing (2.6): `/iris object studio [dimension=<dim>] [seed=1337]`. Omitting `dimension` aggregates objects from every visible pack.
|
||||
- **Pack studio** — a world generated from your pack, so you can build against real terrain: `/iris studio open <dimension> [seed=1337]`, closed with `/iris studio close`.
|
||||
- **Object studio** — a flat gallery laying out every object in the pack on a grid, with click-to-save editing (section 5): `/iris object studio [dimension=<dim>] [seed=1337]`. Omit `dimension` and it aggregates the objects of every visible pack.
|
||||
|
||||
You can also build in any flat world. `/iris object save` resolves `dimension` automatically inside an Iris world; outside one, pass `dimension=<pack>`.
|
||||
Any flat world works too. `/iris object save` only resolves the target pack automatically inside an Iris world; elsewhere pass `dimension=<pack>`.
|
||||
|
||||
### 2.2 The wand
|
||||
### The wand
|
||||
|
||||
```
|
||||
/iris object wand
|
||||
```
|
||||
|
||||
Blaze Rod named "Wand of Iris". Selection corners live on the item; dropping or replacing the wand loses the selection. Two wands are two independent selections.
|
||||
`/iris object wand` gives a Blaze Rod named "Wand of Iris". The two corners are written into the item's lore, so dropping or replacing the wand loses the selection, and two wands are two independent selections.
|
||||
|
||||
| Action | Effect |
|
||||
|---|---|
|
||||
| **Left click** a block | Set corner 1 |
|
||||
| **Right click** a block | Set corner 2 |
|
||||
| Left-click a block | Sets corner 1 |
|
||||
| Right-click a block | Sets corner 2 |
|
||||
|
||||
Main hand only; clicks cancel so you do not break or place. Selection particles draw when corners are within 64 blocks of each other. Setting a corner in a different world clears the other corner.
|
||||
Main hand only. Both clicks are cancelled so you never break or place while selecting. Setting a corner in a different world clears the other corner rather than producing a cross-world box. Outline particles are drawn for the selection while you are in the same world, out to 256 blocks from you, thinning out with distance.
|
||||
|
||||
**WorldEdit interop.** With `worldEditWandCUI` true (default in settings), a WorldEdit selection is accepted anywhere Iris wants a selection. `/iris object we` converts the current WorldEdit selection into an Iris wand. `position2` does not work with a WorldEdit-only selection — run `/iris object we` first.
|
||||
**WorldEdit interop.** With the `worldEditWandCUI` setting on (the default), a live WorldEdit selection stands in for an Iris wand across the `/iris object` selection and save commands. `/iris object we` converts the current WorldEdit selection into a real Iris wand, and it works whether or not that setting is on. `position2` is the exception: it needs an actual Iris wand, so run `/iris object we` first if you have only a WorldEdit selection.
|
||||
|
||||
### 2.3 Adjusting the selection
|
||||
### Adjusting the selection
|
||||
|
||||
| Command | Alias | Effect |
|
||||
|---|---|---|
|
||||
| `/iris object position1 [here=true]` | `p1` | Corner to feet (`here=true`) or look-at block (`here=false`) |
|
||||
| `/iris object position2 [here=true]` | `p2` | Other corner |
|
||||
| `/iris object shift [amount=1]` | | Move whole selection opposite facing |
|
||||
| `/iris object contract [amount=1]` | `-` | Inset on the face you look at |
|
||||
| `/iris object expand [amount]` | modded only | Expand the face you look at |
|
||||
| `/iris object x&y` | | Expand up **and** down until clear, then contract sides inward |
|
||||
| `/iris object x+y` | | Expand up only, then contract sides |
|
||||
| `/iris object position1 [here=true]` | `p1` | Moves a corner to the block under your feet, or to the block you are looking at with `here=false` |
|
||||
| `/iris object position2 [here=true]` | `p2` | Same for the other corner; requires an Iris wand |
|
||||
| `/iris object shift [amount=1]` | | Slides the whole box one step per `amount` along the axis you are facing |
|
||||
| `/iris object contract [amount=1]` | `-` | Pulls the face you are facing inward by `amount` |
|
||||
| `/iris object expand [amount=1]` | modded only | Pushes that face outward; the Bukkit command tree has no `expand` |
|
||||
| `/iris object x&y` | | Finds the empty air above and below the selection to set its top and bottom, then pulls the four sides in until they touch blocks |
|
||||
| `/iris object x+y` | | Same, but only searches upward — the current bottom is kept |
|
||||
|
||||
`x&y` / `x+y` wrap a build tightly: rough-select the base, then run one of them.
|
||||
Rough-select the base of a build, then run `x+y` to wrap it tightly.
|
||||
|
||||
### 2.4 Saving
|
||||
## 3. Saving
|
||||
|
||||
```
|
||||
/iris object save [dimension=<pack>] <name> [overwrite=false] [legacy=true]
|
||||
```
|
||||
|
||||
- `name` is required and positional — path under `objects/`, `/` allowed for subfolders.
|
||||
- `dimension` resolves from the Iris world; pass `dimension=<pack>` otherwise.
|
||||
- Without `overwrite=true` (alias `force=true`), an existing file aborts. No backup on overwrite.
|
||||
- Saved volume is the **full selection box** — no shrinkwrap. Deliberate air padding shifts the center.
|
||||
- `name` is required and positional. It is the path under `objects/`, and `/` creates subfolders.
|
||||
- `dimension` resolves from the Iris world you are standing in; pass `dimension=<pack>` anywhere else.
|
||||
- Without `overwrite=true` (alias `force=true`) an existing file aborts the save. There is no backup.
|
||||
- `legacy` defaults to **true**, which writes reduced tile records for signs, spawners, banners, and loot containers (section 1). Pass `legacy=false` when full block-entity fidelity matters — most obviously for double-sided signs.
|
||||
- The saved volume is the **full selection box**. Nothing is shrinkwrapped, so deliberate air padding is preserved — and moves the center.
|
||||
|
||||
File path: `plugins/Iris/packs/<dimension load key>/objects/<name>.iob`.
|
||||
The file lands at `<data>/packs/<dimension load key>/objects/<name>.iob`.
|
||||
|
||||
**Footgun:** the target pack folder is the **dimension's load key**, not necessarily the pack folder the dimension came from. A pack in `packs/mypack/` with `dimensions/overworld.json` saves objects into `packs/overworld/` if that load key differs. Keep the dimension JSON filename equal to the pack folder name.
|
||||
|
||||
Example:
|
||||
**Footgun:** the target folder is the **dimension's load key**, not the folder the dimension came from. A pack in `packs/mypack/` whose dimension file is `dimensions/overworld.json` writes its objects into `packs/overworld/`. Keep the dimension JSON filename equal to the pack folder name and this never bites.
|
||||
|
||||
```
|
||||
/iris object wand
|
||||
# left-click one corner, right-click the other
|
||||
/iris object x+y
|
||||
/iris object save trees/birch/tall_birch_1
|
||||
# -> plugins/Iris/packs/<dimension load key>/objects/trees/birch/tall_birch_1.iob
|
||||
```
|
||||
|
||||
### 2.5 Pasting, previewing, editing
|
||||
## 4. Pasting, editing, and inspecting
|
||||
|
||||
```
|
||||
/iris object paste <object> [edit=false] [rotate=0] [scale=1]
|
||||
```
|
||||
|
||||
Pastes at the block you look at. `rotate` is Y degrees; `scale` rescales with tricubic interpolation (clamped for large objects). Pastes are undoable:
|
||||
The paste lands on the block you are looking at, with the object's bottom resting on it — small foliage (grass, snow layers, vines, torches, dead bushes, poppies, dandelions) is ignored by the raycast so you target the ground, not the plant. `rotate` is degrees around Y. `scale` resizes with tricubic interpolation and is clamped down for large objects, so a big object silently pastes at a smaller factor than you asked for.
|
||||
|
||||
```
|
||||
/iris object undo [amount=1] (alias: u — reverts pastes, not hand edits)
|
||||
/iris object undo [amount=1]
|
||||
```
|
||||
|
||||
**Edit existing:** `paste` with `edit=true` hands a wand fitted to the pasted bounds; modify, then re-save with `overwrite=true`.
|
||||
Alias `u`. It reverts pastes, not blocks you placed by hand.
|
||||
|
||||
`paste ... edit=true` additionally hands you a wand fitted to the pasted bounds, which is the normal way to edit an existing object: paste it, change it, re-save the same key with `overwrite=true`.
|
||||
|
||||
Inspection and maintenance:
|
||||
|
||||
- `/iris object analyze <object>` — dimensions, block count, top materials. Read-only.
|
||||
- `/iris object shrink <object>` — shrinkwraps and **overwrites in place**, no confirmation. Re-centers; deliberate off-center padding shifts.
|
||||
- `/iris object plausibilize <target> [dryrun=false] [reach=12]` — tree-specific: organic branch connections so leaves survive vanilla decay. `target` accepts a key, a `prefix/` ending in `/`, or a path.
|
||||
- `/iris object dust` (alias `d`) — "Dust of Revealing". Right-click a block in an Iris world to highlight the placement that owns it.
|
||||
- `/iris find object <object> [teleport=true]` (also `/iris goto object`) — teleports to the grid cell in object studio, or locates a generated instance in a normal Iris world.
|
||||
- `/iris object analyze <object>` — dimensions, block count, and the top ten materials with their most common block-data variant. Read-only, and the fastest check that a file loads at all.
|
||||
- `/iris object shrink <object>` — shrinkwraps to the tightest box and **overwrites the file in place with no confirmation**. It re-centers, so any deliberate off-center padding is lost.
|
||||
- `/iris object plausibilize <target> [dryrun=false] [reach=12]` — tree-specific. It grows organic branch connections through the canopy so leaves survive vanilla decay; leaf clusters farther than `reach` blocks from wood are pinned persistent instead, and `reach=0` grows without a limit. `target` accepts an object key, a folder prefix ending in `/`, or a filesystem path. `dryrun=true` reports and writes nothing.
|
||||
- `/iris object dust` (alias `d`) — gives Glowstone Dust named "Dust of Revealing". Right-click a block in an Iris world and Iris names the placement that owns it.
|
||||
- `/iris find object <object> [teleport=true]` — `/iris goto object` is the same command under an alias. You have to be standing in an Iris world. In an object studio it teleports to that object's grid cell; otherwise it spirals outward looking for a generated instance, giving up after 120 seconds. `teleport=false` prints the coordinates instead of moving you.
|
||||
|
||||
### 2.6 Object studio: click-to-save
|
||||
## 5. Object studio: click-to-save
|
||||
|
||||
Inside `/iris object studio`, left- or right-clicking a block in a grid cell writes that cell back to its `.iob`:
|
||||
Inside `/iris object studio`, left- or right-clicking a block in a grid cell writes that cell straight back to its `.iob`. It is the quickest loop for touching up a library of small objects.
|
||||
|
||||
- Saved volume is the cell's original bounding box (center preserved; no shrinkwrap).
|
||||
- Content hash per cell; no-op if unchanged ("no changes").
|
||||
- Aborts if any covering chunk is unloaded — walk closer and click again.
|
||||
- The saved volume is the cell's original bounding box, so the center is preserved and nothing is shrinkwrapped. Tile data is always written in full, unlike `/iris object save`.
|
||||
- Each cell carries a content hash; clicking a cell you did not change reports no changes and writes nothing. The hashes are in memory only, so the first click on any cell after a world load always writes.
|
||||
- The save aborts **silently** if any chunk covering the cell is unloaded. If a click seems to do nothing, walk closer and click again.
|
||||
|
||||
## 3. Importing `.schem` files
|
||||
## 6. Importing existing builds
|
||||
|
||||
### 3.1 `/iris object convert`
|
||||
### 6.1 `.schem` files: `/iris object convert`
|
||||
|
||||
```
|
||||
/iris object convert
|
||||
```
|
||||
1. Drop Sponge `.schem` files into `<data>/convert/` (created on first use).
|
||||
2. Run `/iris object convert`.
|
||||
3. Each `foo.schem` becomes `foo.iob` **in that same folder**, shrinkwrapped. Move it into a pack yourself — convert never writes into a pack.
|
||||
|
||||
1. Drop `.schem` files into `plugins/Iris/convert/` (created on first use).
|
||||
2. Run the command. Each `foo.schem` becomes `foo.iob` **in that folder**, shrinkwrapped.
|
||||
3. Move the `.iob` into a pack yourself — convert never writes into a pack.
|
||||
What survives and what does not:
|
||||
|
||||
Support and losses:
|
||||
- **Sponge Schematic v2 and v3 only.** Anything else — MCEdit `.schematic`, `.litematic`, Sponge v1 — is rejected. No WorldEdit or FAWE needed; Iris parses the NBT itself.
|
||||
- **Blocks only.** The converter reads the palette and block indices and nothing else, so **block entities, entities, and biomes are all lost**: chests come out empty, signs blank, spawners default.
|
||||
- The source `.schem` is **deleted** after a successful conversion. Keep a copy elsewhere.
|
||||
- Files outside that folder, or not ending in `.schem`, produce no output at all.
|
||||
|
||||
- **Sponge Schematic v2 and v3 only.** MCEdit `.schematic`, `.litematic`, and Sponge v1 are rejected. No WorldEdit/FAWE required — Iris parses NBT itself.
|
||||
- Block palette and indices only. **Block entities, entities, and biomes are not carried**: chests empty, signs blank, spawners default.
|
||||
- Source `.schem` is **deleted** after successful conversion.
|
||||
- Empty folder or wrong extension produces no output.
|
||||
### 6.2 Keeping block entities: paste, then wand
|
||||
|
||||
### 3.2 High-fidelity path: paste, then wand
|
||||
The converter cannot preserve tile data, so anything with chests, signs, or spawners has to go through the world:
|
||||
|
||||
For schematics with chests, signs, or spawners:
|
||||
|
||||
1. Open a build world (`/iris studio open <pack>` or flat world).
|
||||
2. `//schem load <name>` and `//paste` with WorldEdit/FAWE.
|
||||
3. Keep the WorldEdit selection (accepted directly) or `/iris object we`, or select with the wand.
|
||||
1. Open a build world — `/iris studio open <pack>` or any flat world.
|
||||
2. `//schem load <name>` and `//paste` with WorldEdit or FAWE.
|
||||
3. Keep the WorldEdit selection (Iris accepts it directly) or run `/iris object we`, or re-select with the Iris wand.
|
||||
4. Tighten with `/iris object x+y` or `contract`.
|
||||
5. `/iris object save <name> [overwrite=true]`.
|
||||
|
||||
Wand save reads live blocks with full block-entity NBT. This is the only import route that preserves block entities.
|
||||
The wand save reads live blocks, so it captures full block-entity NBT. This is the only import route that preserves it.
|
||||
|
||||
### 3.3 Vanilla `.nbt` templates
|
||||
### 6.3 Vanilla `.nbt` templates
|
||||
|
||||
- `/iris structure import <dimension>` — imports registered structures and templates into the pack as objects plus jigsaw graphs.
|
||||
- `/iris studio importvanilla <dimension> [variants=3] [structures=true]` — imports vanilla trees/features under `objects/vanilla/`, plus structure passes when `structures=true`.
|
||||
- `/iris structure import <dimension>` — imports registered structures and their templates into the pack as objects plus jigsaw graphs.
|
||||
- `/iris studio importvanilla <dimension> [variants=3] [structures=true]` (aliases `importv`, `iv`) — captures vanilla trees, mushrooms, and object features into `objects/vanilla/`, taking `variants` samples of each, and also imports vanilla and datapack structures and jigsaws when `structures=true`.
|
||||
|
||||
Details: `22 - Native Structures & Datapacks.md`.
|
||||
Details are in `22 - Native Structures & Datapacks.md`.
|
||||
|
||||
## 4. Practical details
|
||||
## 7. Practical details
|
||||
|
||||
**Center and anchoring.** Center is always bounding-box middle. Wand saves keep selection box (asymmetric padding survives); `convert` and `shrink` shrinkwrap and re-center. At placement, the object is centered on the column in X/Z and lifted so its bottom sits on the anchor; beyond that, placement `mode` applies (`20 - Object Placement.md`).
|
||||
**Center and anchoring.** The center is always the middle of the bounding box. Wand saves keep the selection box, so asymmetric padding survives and shifts the center; `convert` and `shrink` shrinkwrap and re-center. At generation the object is centered on its column in X and Z and lifted so its bottom sits on the anchor — everything past that is the placement's `mode` (`20 - Object Placement.md`).
|
||||
|
||||
**Rotation is runtime, never baked.** A `.iob` stores one orientation; rotation ranges live on the placement. `paste rotate=90` rotates a throwaway copy.
|
||||
**Rotation is never baked in.** A `.iob` stores exactly one orientation. Rotation ranges belong to the placement; `paste rotate=90` rotates a throwaway copy and does not touch the file.
|
||||
|
||||
**Loot: two mechanisms.** A chest saved with a vanilla loot table keeps that table inside the `.iob`. Pack loot tables attach at placement (`loot`, `vanillaLoot`, `overrideGlobalLoot`) — `20 - Object Placement.md`.
|
||||
**Two separate loot mechanisms.** A chest saved into the `.iob` with a vanilla loot table on it keeps that table. Pack loot tables are attached by the placement instead (`loot`, `vanillaLoot`, `overrideGlobalLoot`) — see `20 - Object Placement.md`.
|
||||
|
||||
**Stale caches.** Objects are cached per pack. Non-studio worlds may not pick up on-disk `.iob` edits until pack reload; studio worlds hotload within about a second (new chunks only).
|
||||
**Caches and hotload.** Objects are cached per pack. Studio worlds watch the pack folder for `.iob` and `.json` changes and hotload at most once a second, backing off to about four seconds while the world is busy generating or running maintenance. A hotload swaps the engine's whole pack runtime, so already-generated chunks are untouched and only later ones see the edit. Ordinary worlds never hotload; they serve the cached copy until the pack reloads.
|
||||
|
||||
## 5. Common failure modes
|
||||
## 8. Common failure modes
|
||||
|
||||
1. **"You need to hold your wand!"** — no wand selection and no WorldEdit selection.
|
||||
2. **"File already exists."** — pass `overwrite=true`.
|
||||
3. **Save says missing `dimension`** — not in a loaded Iris world; pass `dimension=<pack>`.
|
||||
4. **Objects saved into the wrong pack folder** — dimension load key ≠ pack folder name (2.4).
|
||||
5. **`convert` does nothing** — files not in `plugins/Iris/convert/` or not ending in `.schem`.
|
||||
6. **Converted objects lack tile data** — converter never reads block entities; use paste-then-wand.
|
||||
7. **Converter deleted the schematic** — by design after success; keep a copy elsewhere.
|
||||
8. **Selection lost** — corners live on the wand item; `paste edit=true` overwrites the held wand selection.
|
||||
9. **`position2` does nothing** — WorldEdit-only selection; run `/iris object we` first.
|
||||
10. **Entities vanished** — never stored in objects.
|
||||
11. **Jigsaw/structure-void blocks vanished** — stripped on read; connectors are JSON.
|
||||
1. **"You need to hold your wand!"** — no Iris wand selection and no WorldEdit selection.
|
||||
2. **"File already exists."** — pass `overwrite=true` (or `force=true`).
|
||||
3. **Save complains about a missing `dimension`** — you are not standing in a loaded Iris world; pass `dimension=<pack>`.
|
||||
4. **Objects landed in the wrong pack folder** — the dimension's load key is not the pack folder name (section 3).
|
||||
5. **`convert` did nothing** — the files are not in `<data>/convert/`, or do not end in `.schem`.
|
||||
6. **Converted objects have empty chests** — the converter never reads block entities. Use the paste-then-wand route (6.2).
|
||||
7. **The converter ate the schematic** — that is by design after a successful conversion.
|
||||
8. **The selection vanished** — corners live on the wand item, and `paste edit=true` overwrites the held wand's selection.
|
||||
9. **`position2` does nothing** — you have a WorldEdit-only selection. Run `/iris object we` first.
|
||||
10. **Entities are gone** — objects never store entities. Use placement markers.
|
||||
11. **Jigsaw or structure-void blocks are gone** — they are filtered out when the file is read. Connectors are JSON, not blocks.
|
||||
12. **A paste is offset from where you expected** — the origin is the bounding-box center, so air padding inside the selection moves it. Re-select tightly or run `shrink`.
|
||||
13. **A sign lost its back side, or a spawner lost its settings** — saved with the default `legacy=true`. Re-save with `legacy=false`.
|
||||
14. **`shrink` rewrote a file in a pack you were not thinking about** — outside an Iris world, a bare key resolves to the first visible pack that has it, silently (section 1).
|
||||
|
||||
## Command reference
|
||||
|
||||
All under `/iris object` (alias `/iris o`). Optional parameters must be `key=value`.
|
||||
All under `/iris object` (alias `/iris o`). On Bukkit, optional parameters are `key=value`; the modded loaders expose the same commands as brigadier literals instead (`/iris object save overwrite <name>`, `/iris object paste rotate <degrees> <key>`, `/iris object paste at <x> <y> <z> <key>`).
|
||||
|
||||
| Command | Aliases | Parameters |
|
||||
|---|---|---|
|
||||
| `studio` | | `dimension=<dim>` (optional), `seed=1337` |
|
||||
| `wand` | | |
|
||||
| `we` | | |
|
||||
| `we` | | Bukkit only |
|
||||
| `position1` / `position2` | `p1` / `p2` | `here=true` |
|
||||
| `x&y` / `x+y` | | |
|
||||
| `x&y` / `x+y` | `xay` / `xpy` | |
|
||||
| `shift` | | `amount=1` |
|
||||
| `contract` | `-` | `amount=1` |
|
||||
| `expand` | | `amount=1`, modded only |
|
||||
| `save` | | `dimension` (contextual), `<name>`, `overwrite=false` (alias `force`), `legacy=true` |
|
||||
| `paste` | | `<object>`, `edit=false`, `rotate=0`, `scale=1` |
|
||||
| `undo` | `u` | `amount=1` |
|
||||
| `analyze` | | `<object>` |
|
||||
| `shrink` | | `<object>` |
|
||||
| `plausibilize` | | `<target>`, `dryrun=false`, `reach=12` |
|
||||
| `convert` | | |
|
||||
| `convert` | | Bukkit only |
|
||||
| `dust` | `d` | |
|
||||
|
||||
Related: `/iris studio open <dimension> [seed=]`, `/iris studio close`, `/iris object studio`, `/iris find object <object> [teleport=true]`.
|
||||
Related: `/iris studio open <dimension> [seed=]`, `/iris studio close`, `/iris studio importvanilla <dimension> [variants=3] [structures=true]` (aliases `importv`, `iv`), `/iris find object <object> [teleport=true]` (alias `/iris goto object`), `/iris structure import <dimension>`.
|
||||
|
||||
Reference in New Issue
Block a user