Iris/AGENTS.md

# Iris Agent Guide

Iris is a world generation engine for Minecraft servers and mod loaders. It generates terrain, biomes, caves, structures, objects, and entities from editable JSON packs, with an in-game studio authoring workflow. The same engine runs as a Bukkit-family plugin and as a Fabric, Forge, or NeoForge server mod. Read this file before making any change; the workspace-level `../AGENTS.md` also applies when working inside the VolmitSoftware workspace.

## Documentation Policy (mandatory)

- `docs/` is the authoritative reference for every feature of this plugin/mod. Files are flat (no subfolders) and numbered `NN - Title.md`, ordered for someone new to Iris; API docs always keep the highest numbers.
- ANY change that alters a feature, command, permission, setting, pack JSON contract, studio/editor workflow, pregen behavior, structure/object system, integration, localization, client HUD/protocol, or public API surface MUST update the matching numbered doc in the same workstream. A behavior change with stale docs is an incomplete change — do not finish work without the doc update.
- Docs state actual runtime behavior, not intended behavior. If a change fixes a documented quirk, update or remove that quirk entry. If a change introduces surprising behavior, document it plainly.
- Docs are purely factual reference material: no marketing language, no emojis, no filler. Each file opens with a 1–4 sentence summary.
- Cross-references use exact filenames (for example `see "04 - Commands & Permissions.md"`). When adding or renumbering files, fix every cross-reference.
- Hosted external docs are not authority; this `docs/` tree is.
- Maintainer-only checklists use high numbers before the API series and are titled `Maintainer — …`.

## Doc Index

| File | Covers |
|------|--------|
| `00 - Overview.md` | What Iris is, feature map, doc index, project layout |
| `01 - Installation & Platforms.md` | Plugin/mod install, data dirs, first boot, platforms, native worldgen matrix |
| `02 - Getting Started.md` | First world, teleport, basic pregen, first studio |
| `03 - Configuration.md` | `settings.json` keys, defaults, hotload |
| `04 - Commands & Permissions.md` | Full `/iris` tree, Bukkit vs modded, permissions |
| `05 - Concepts & Pack Layout.md` | Pack roots, keys, folders, snippets, world snapshot vs studio |
| `06 - Worlds & Lifecycle.md` | create/load/unload/remove, main world, Folia, pack copy |
| `07 - Pregeneration.md` | pregen ops, cache, mantle, HUD |
| `08 - Localization.md` | locales, overrides, client lang |
| `09 - PlaceholderAPI.md` | `%iris_…%` keys and migration |
| `10 - Studio & VSCode Schemas.md` | Studio workflow, schemas, hotload |
| `11 - Dimensions.md` | Dimension JSON, modes, height, imports |
| `12 - Regions.md` | Regions and region-level content |
| `13 - Biomes.md` | Biome JSON, layers, custom biomes, spawns |
| `14 - Generators & Noise.md` | Generators, styles, expressions, images |
| `15 - Caves & Carving.md` | Cave profiles, field modules, carving |
| `16 - Surfaces, Decorators & Deposits.md` | Decorators, deposits, palettes |
| `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md` | Procedural decoration systems |
| `18 - Structures Overview.md` | Objects vs jigsaw vs native structures |
| `19 - Objects.md` | Creating and importing `.iob` objects |
| `20 - Object Placement.md` | Placing objects in biomes and regions |
| `21 - Jigsaw Structures.md` | Iris multi-piece structures |
| `22 - Native Structures & Datapacks.md` | Vanilla/datapack structures on Iris |
| `23 - Loot, Entities, Spawners, Markers.md` | Pack entities and loot |
| `24 - Pack Mods & Snippets.md` | Injectors/replacers and snippets |
| `25 - Pack Management.md` | Download, validate, cleanup, package, update-world |
| `26 - Example - Minimal Dimension.md` | Minimal pack walkthrough |
| `27 - Example - Configuring Overworld.md` | Editing the shipping overworld |
| `28 - Integrations.md` | WorldEdit, Multiverse, Mythic, item plugins, tree feller |
| `29 - Client HUD & Protocol.md` | Client mod HUD and protocol |
| `30 - Platform Differences.md` | Bukkit vs Fabric/Forge/NeoForge matrix |
| `31 - Operator Runbooks & Smoke Tests.md` | Manual verification |
| `32 - Determinism & Goldenhash.md` | Cross-platform parity gate |
| `33 - Performance Tuning.md` | Threads, mantle, SIMD, pregen caps |
| `85 - Maintainer - MC Version Bump.md` | Version bump procedure |
| `86 - Maintainer - Release Checklist.md` | Release steps |
| `87 - Maintainer - Release Readiness.md` | Living readiness tracker |
| `90 - API - Getting Started.md` | Bukkit public API setup |
| `91 - API - Terrain.md` | Terrain query service |
| `92 - API - World Events.md` | Engine and pregen events |
| `93 - API - Tree Feller.md` | Tree feller service |
| `94 - API - Modded.md` | Modded public API |

Docs `00`–`33` serve operators and pack authors in reading order; `85`–`87` are maintainer; `90`–`94` serve plugin and mod developers.

## Build and Platforms

- Java 25 required. Independent Gradle build from `Iris/`: `./gradlew build`, `./gradlew test`.
- Artifacts: Bukkit-family plugin jar; Fabric, Forge, and NeoForge mod jars under `dist/` when built.
- Modules: `core` (engine), `spi` (platform SPI), `adapters/bukkit/plugin` (plugin + Bukkit API), `adapters/modded-common` + loader adapters, `probe` (offline tooling).
- Default pack downloads at first boot from the IrisDimensions overworld release; packs live under the platform data directory `packs/<key>/`.

## Content Model (brief)

- **Pack** — directory of JSON and `.iob` resources under `packs/<key>/` with at least `dimensions/*.json`.
- **Dimension** — root config for a world type (height, modes, regions, imports).
- **Region / Biome / Generator** — spatial and terrain authoring units.
- **Object / Structure** — placed content (`.iob`, Iris jigsaw, native/datapack structures).
- **Studio** — transient authoring world with live pack hotload and VSCode schemas.