Iris/docs/05 - Concepts & Pack Layout.md

# 05 - Concepts & Pack Layout

An Iris pack is a directory of JSON, binary objects, and optional assets under the platform packs root (`packs/<key>/` on Bukkit-family; `config/irisworldgen/packs/<key>/` on Fabric/Forge/NeoForge). `IrisData` is the pack loader: it registers one `ResourceLoader` per registrant type, resolves keys to files, caches loads, and expands snippet references during JSON parse. Production worlds use a copied pack snapshot under the world folder; studio worlds load the live pack directory with hotload.

See also: `00 - Overview.md`, `01 - Installation & Platforms.md`, `10 - Studio & VSCode Schemas.md`, `11 - Dimensions.md`, `24 - Pack Mods & Snippets.md`, `25 - Pack Management.md`.

## Content model

| Concept | Role |
|---------|------|
| Pack | Directory under the packs root; pack folder name is the pack key |
| Dimension | Root world type under `dimensions/`; at least one is required |
| Region | Spatial zone listing biomes and region content |
| Biome | Terrain layers, surface, decorations, objects, structures, spawns |
| Generator | Height / noise generator definitions |
| Object | Placed block models (`.iob`) |
| Structure | Iris multi-piece / native structure graphs under `structures/` |
| Jigsaw pool / piece | Pool and piece JSON for Iris jigsaw assembly |
| Entity / spawner / marker / loot | Entity definitions, spawn rules, markers, loot tables |
| Mod schema | Inactive injector/replacer documents under `mods/`; loaded for schema/tooling but not applied by the engine |
| Expression / block / image | Expressions, custom blocks, PNG sampling maps |
| Snippet | Reusable JSON fragments under `snippet/<type>/` |
| Studio | Transient authoring world bound to the live pack with file hotload |
| World pack snapshot | Frozen copy at `<world>/iris/pack` used by non-studio worlds |

## Pack roots

| Context | Path |
|---------|------|
| Authoring / download target | Platform data dir `packs/<packKey>/` |
| Production world (non-studio) | World dimension root `iris/pack/` (see `06 - Worlds & Lifecycle.md`) |
| Studio world | Same as authoring pack path; no world copy unless benchmark |
| Prefetch cache | Platform `prefetch/` (loader key indexes) |
| Schemas (studio) | Pack-local `.iris/schema/` |

Pack folder names listed by Iris must be visible directories (not hidden names starting with `.`). Symbolic-link pack trees are rejected for download/replace and validation safety checks.

## Registrant folders

Every pack type that `IrisData` registers maps to a folder name returned by the registrant’s `getFolderName()`. Nested subfolders under a type root are allowed; the load key is the path relative to that root without the file extension.

| Folder | Type | Files | Required |
|--------|------|-------|----------|
| `dimensions/` | Dimension | `*.json` | **Yes** — pack is not loadable without at least one |
| `regions/` | Region | `*.json` | Optional |
| `biomes/` | Biome | `*.json` | Optional |
| `generators/` | Generator | `*.json` | Optional |
| `objects/` | Object | `*.iob` | Optional |
| `matter/` | Matter object | matter binary (loader-specific) | Optional; loader only, no runtime consumer |
| `structures/` | Structure | `*.json` | Optional |
| `jigsaw-pools/` | Jigsaw pool | `*.json` | Optional |
| `jigsaw-pieces/` | Jigsaw piece | `*.json` | Optional |
| `entities/` | Entity | `*.json` | Optional |
| `spawners/` | Spawner | `*.json` | Optional |
| `markers/` | Marker | `*.json` | Optional |
| `loot/` | Loot table | `*.json` | Optional |
| `mods/` | Pack mod schema | `*.json` | Optional; no runtime application path |
| `blocks/` | Block data | `*.json` | Optional |
| `expressions/` | Expression | `*.json` | Optional |
| `images/` | Image | `*.png` | Optional |
| `snippet/` | Snippet library | `snippet/<type>/**.json` | Optional (not a registrant loader) |

Live overworld also contains authoring-only or empty trees that loaders do not register as types (for example empty `caves/`, `ravines/`, `jigsaw-structures/`, plus pack-local `README.md`, workspace files, and `Schema.json`). Those names are not keys in `IrisData`.

## Key rules

- **Load key** is the path under the type folder without extension. Example: `biomes/temperate/plains.json` → key `temperate/plains`.
- Exact `name + extension` wins over dotted variants (`plains.json` beats `plains.disabled.json` when both match the base name rule).
- Ambiguous same-base-name matches log a warning and pick the sorted first file.
- Literal key `"null"` is refused.
- Cross-references between resources use these load keys (region biome lists, structure placements, spawner entity ids, and similar).
- Pack dimension selectors for world create accept `pack`, `pack:dimensionKey`, or `default` (resolves to `settings.generator.defaultWorldType`, default `overworld`). See `04 - Commands & Permissions.md` and `06 - Worlds & Lifecycle.md`.
- Download destination pack keys must match `[a-z0-9_-]+` and are taken from the single dimension load key in the archive.

## Dimensions required

`PackValidator` fails a pack as not loadable when:

1. The pack folder is missing or not a directory.
2. `dimensions/` is missing.
3. `dimensions/` has no `*.json` files.

A downloaded archive is also rejected unless it contains exactly one loadable dimension (install key becomes that dimension’s load key). Presence of a pack on disk is defined as a safe pack directory with at least one non-symlink `dimensions/*.json` file.

## Snippets

Types annotated with `@Snippet("<type>")` may be written inline as JSON objects **or** as a string reference to a snippet file.

| Rule | Behavior |
|------|----------|
| Path form | `"snippet/<type>/<name>"` (optional shorter forms are normalized onto `snippet/<type>/`) |
| On-disk file | `snippet/<type>/<name>.json` under the pack root |
| Nested snippet keys | Subfolders under `snippet/<type>/` are allowed; listed keys keep the `snippet/` prefix |
| Schema | Studio schema builder exposes `snippet/<type>/…` enums and pattern matches under `.iris/schema/snippet/` |
| Shipping example | Overworld uses `snippet/decorator/*` and `snippet/style/*` |

Snippet parse failures log errors and yield `null` for that field; full pack validation treats broken graphs as blocking or warning depending on the validator.

## Studio pack vs world pack snapshot

| Mode | Pack path used by engine | Hotload | Copy on create |
|------|--------------------------|---------|----------------|
| Studio (`studio=true`) | Live `packs/<key>/` (or studio project path) | Yes — polls pack for `.json`/`.iob` changes (~1s latch), excludes `.iris` | No pack install into world (unless benchmark) |
| Production create | Installs full pack tree into `<world>/iris/pack` | No | Atomic copy via `StudioSVC.installIntoWorld` |
| Benchmark | Installs into world pack path | Studio flag still drives transient cleanup rules | Yes when `benchmark` |

Hotload opens a new `IrisData` runtime from the same folder, reloads the dimension key, rebuilds engine runtime under a lifecycle lock, retires the previous data, and refreshes workspace/datapacks. Production engines load only the world snapshot; editing `packs/` does not affect existing non-studio worlds until the snapshot is replaced (see `25 - Pack Management.md` `update-world`).

## Minimal pack layout

```text
packs/myworld/
  dimensions/
    myworld.json
  regions/
    main.json
  biomes/
    plains.json
  generators/
    plain.json
```

A pack with only `dimensions/*.json` is structurally valid for presence and basic validation; generation quality depends on the dimension’s referenced regions/biomes/generators. For a walkthrough see `26 - Example - Minimal Dimension.md`.

## Live overworld folder map (shipping pack)

Adapter run configurations use these additional paths (`…/packs/overworld/`):

| Path | Contents (summary) |
|------|--------------------|
| `dimensions/overworld.json` | Root dimension |
| `regions/*.json` | Climate / biome zones |
| `biomes/**` | Nested biome sets (temperate, hot, frozen, ocean, …) |
| `generators/**` | Terrain generators |
| `objects/**` | `.iob` trees, structures, clutter, vanilla imports |
| `structures/*.json` | Structure graphs (including minecraft_* graphs) |
| `jigsaw-pieces/**`, `jigsaw-pools/**` | Jigsaw assembly data |
| `entities/standard/**`, `spawners/**`, `loot/**` | Entities, spawners, loot |
| `images/*.png` | Noise / map images |
| `snippet/decorator/**`, `snippet/style/**` | Shared snippets |

Related feature docs: `12 - Regions.md`, `13 - Biomes.md`, `14 - Generators & Noise.md`, `18 - Structures Overview.md`, `19 - Objects.md`, `21 - Jigsaw Structures.md`, `23 - Loot, Entities, Spawners, Markers.md`.