d

docs/00 - Overview.md

@@ -1,40 +1,48 @@
 # 00 - Overview
 
-Iris is a world generation engine for Minecraft servers and mod loaders. It builds terrain, biomes, caves, structures, objects, and entities from editable JSON packs, exposes an in-game studio authoring workflow, and runs as a Bukkit-family plugin or as a Fabric, Forge, or NeoForge server mod. Cross-platform generation is designed and tested for deterministic parity when artifacts, pack bytes, seeds, and test areas are identical; verify release candidates with GoldenHash. This branch targets Minecraft 26.2; Java 25 is required everywhere.
+Iris is a world generation engine for Minecraft: it replaces the vanilla chunk generator with terrain, biomes, caves, structures, objects, and entities built from editable JSON packs. The same engine ships as a Bukkit-family plugin and as a Fabric, Forge, or NeoForge server mod, and generates identical chunks on all four when artifacts, pack bytes, seed, and area match. This page is the map of the documentation set: read it to find the page you actually need, then leave. This branch targets Minecraft 26.2 and requires Java 25 everywhere.
+
+## Who this documentation is for
+
+There are three audiences and the numbering reflects them. Pages `00`–`33` are for **server operators** installing Iris and **pack authors** writing dimensions, in roughly the order a newcomer needs them. Pages `85`–`87` are **maintainer** checklists for cutting a release. Pages `90`–`94` are for **Java developers** consuming the Iris API from their own plugin or mod.
+
+Reading the set front to back is a waste of time. Pick the outcome you want from the table below and follow only that row.
 
 ## Choose a learning path
 
-Do not read the documentation as one long reference. Start with the outcome you need and follow that path in order:
-
-| Outcome | Read and complete |
+| You want to | Read, in order |
 |---|---|
-| Install Iris and create a world | `01 - Installation & Platforms.md` → `02 - Getting Started.md` → `31 - Operator Runbooks & Smoke Tests.md` |
-| Build a pack from nothing | `05 - Concepts & Pack Layout.md` → `10 - Studio & VSCode Schemas.md` → `26 - Example - Minimal Dimension.md` |
-| Design terrain and biomes | `11 - Dimensions.md` → `12 - Regions.md` → `13 - Biomes.md` → `14 - Generators & Noise.md` |
-| Add caves and surface detail | `15 - Caves & Carving.md` → `16 - Surfaces, Decorators & Deposits.md` → `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md` |
-| Add a structure | `18 - Structures Overview.md`, then `19 - Objects.md` + `20 - Object Placement.md`, `21 - Jigsaw Structures.md`, or `22 - Native Structures & Datapacks.md` |
-| Prepare a production world | `25 - Pack Management.md` → `06 - Worlds & Lifecycle.md` → `07 - Pregeneration.md` → `31 - Operator Runbooks & Smoke Tests.md` |
-| Integrate another plugin or mod | `28 - Integrations.md` → `30 - Platform Differences.md`; Java consumers start at `90 - API - Getting Started.md` |
+| Get Iris running and make one world | `01 - Installation & Platforms.md` → `02 - Getting Started.md` → `31 - Operator Runbooks.md` |
+| Write a pack from scratch | `05 - Concepts & Pack Layout.md` → `10 - Studio & VSCode Schemas.md` → `26 - Example - Minimal Dimension.md` |
+| Shape terrain and lay out biomes | `11 - Dimensions.md` → `12 - Regions.md` → `13 - Biomes.md` → `14 - Generators & Noise.md` |
+| Add caves, surface detail, and vegetation | `15 - Caves & Carving.md` → `16 - Surfaces, Decorators & Deposits.md` → `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md` |
+| Place a building or structure | `18 - Structures Overview.md` first to pick an approach, then `19 - Objects.md` + `20 - Object Placement.md` for single `.iob` objects, `21 - Jigsaw Structures.md` for multi-piece Iris structures, or `22 - Native Structures & Datapacks.md` for vanilla/datapack ones |
+| Ship a pack to a production server | `25 - Pack Management.md` → `06 - Worlds & Lifecycle.md` → `07 - Pregeneration.md` → `31 - Operator Runbooks.md` |
+| Make another plugin or mod work with Iris | `28 - Integrations.md` → `30 - Platform Differences.md`; if you're writing Java against Iris, start at `90 - API - Getting Started.md` |
 
-Each tutorial gives an observable gate. Stop and resolve that gate before layering on the next system; otherwise a missing biome key can look like a cave, decorator, or structure failure later.
+Each tutorial page ends with something you can observe — a world that loads, a chunk that generates, a hotload that lands. Confirm that before moving to the next page. Iris failures cascade misleadingly: a biome key you typo'd in step two shows up three systems later as a cave, decorator, or structure that "doesn't work," and you'll debug the wrong thing.
 
 ## Platforms
 
-| Platform | Artifact | Minecraft | Notes |
+One plugin jar covers the whole Bukkit family; each mod loader gets its own jar. Pick by what your server runs, not by feature set — the generator is the same code on all of them.
+
+| Platform | Artifact | Minecraft | What's different |
 |---|---|---|---|
-| Paper / Purpur / Leaf / Canvas | plugin jar | 26.1.2 – 26.2 | Full plugin feature set |
-| Folia | plugin jar | 26.1.2 – 26.2 | Region-safe scheduling; runtime world create is staged for restart (see `01 - Installation & Platforms.md`, `06 - Worlds & Lifecycle.md`) |
-| Spigot / CraftBukkit | plugin jar | 26.1.2 – 26.2 | Full plugin feature set |
-| Fabric | mod jar | 26.2 | Server worldgen + client HUD; Fabric Loader 0.19.3+ |
-| Forge | mod jar | 26.2 | Server worldgen + client HUD; Forge 65.0.4+ |
-| NeoForge | mod jar | 26.2 | Server worldgen + client HUD; NeoForge 26.2.0.12-beta+ |
+| Paper / Purpur / Leaf / Canvas | plugin jar | 26.1.2 – 26.2 | Nothing; this is the reference plugin target |
+| Spigot / CraftBukkit | plugin jar | 26.1.2 – 26.2 | Nothing for generation. Paper-only APIs degrade gracefully |
+| Folia | plugin jar | 26.1.2 – 26.2 | Region-safe scheduling, and `/iris create` cannot build a live world at runtime — it stages the world and requires a restart. See `01 - Installation & Platforms.md` and `06 - Worlds & Lifecycle.md` |
+| Fabric | mod jar | 26.2 | Server worldgen plus an optional client HUD; needs Fabric Loader 0.19.3+ and Java 25 |
+| Forge | mod jar | 26.2 | Same; needs Forge 65.x (built against 26.2-65.0.4) |
+| NeoForge | mod jar | 26.2 | Same; needs NeoForge 26.2.x (built against 26.2.0.12-beta) |
 
-Plugin identity: name `Iris` (from root project name), command `iris` with aliases `ir` / `irs`, `folia-supported: true`, `load: STARTUP`, `api-version` 26.1 (loads on 26.1.2 and 26.2). Soft-depends include PlaceholderAPI, WorldEdit, item plugins, MythicMobs; Multiverse-Core is ordered after Iris (`loadbefore` / paper `load: AFTER`).
+The plugin registers as `Iris` with command `/iris` (aliases `/ir`, `/irs`), `folia-supported: true`, `load: STARTUP`, and `api-version: 26.1` — the low api-version is deliberate so one jar loads on both 26.1.2 and 26.2. Its descriptor declares two permissions, `iris.all` (the whole command tree) and `iris.treefeller` (survival tree felling only), both defaulting to op. Optional soft-dependencies load before Iris; Multiverse-Core is ordered *after* Iris so Multiverse sees Iris generators once they exist. Full list in `01 - Installation & Platforms.md`.
 
-Mod id on all three loaders: `irisworldgen`.
+All three mod loaders use mod id `irisworldgen`, and register `/ir` and `/irs` as command redirects the same way the plugin does.
 
 ## Feature map
 
+Every feature of Iris is documented on exactly one page. Find the subject, go there.
+
 | Area | What it covers | Doc |
 |---|---|---|
 | Install and platforms | Plugin vs mod jars, data dirs, first boot, native worldgen matrix | `01 - Installation & Platforms.md` |
@@ -67,7 +75,7 @@ Mod id on all three loaders: `irisworldgen`.
 | Integrations | WorldEdit, Multiverse, Mythic, item plugins, tree feller | `28 - Integrations.md` |
 | Client HUD | Client mod HUD and protocol channel | `29 - Client HUD & Protocol.md` |
 | Platform matrix | Bukkit vs Fabric / Forge / NeoForge differences | `30 - Platform Differences.md` |
-| Operator checks | Manual verification | `31 - Operator Runbooks & Smoke Tests.md` |
+| Operator checks | Manual verification | `31 - Operator Runbooks.md` |
 | Determinism | Goldenhash cross-platform gate | `32 - Determinism & Goldenhash.md` |
 | Performance | Threads, mantle, SIMD, pregen caps | `33 - Performance Tuning.md` |
 | Maintainer — MC version bump | Version bump procedure | `85 - Maintainer - MC Version Bump.md` |
@@ -79,40 +87,44 @@ Mod id on all three loaders: `irisworldgen`.
 | API — tree feller | Tree feller service | `93 - API - Tree Feller.md` |
 | API — modded | Modded public API (`art.arcane.iris.modded.api`) | `94 - API - Modded.md` |
 
-Docs `00`–`33` are for operators and pack authors in reading order. `85`–`87` are maintainer checklists. `90`–`94` are for plugin and mod developers.
+## Content model
 
-## Content model (brief)
+Six terms carry most of the documentation. Learn them here and the rest of the set reads much faster.
 
-| Term | Meaning |
+| Term | What it is |
 |---|---|
-| Pack | Directory of JSON and `.iob` 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 or datapack structures) |
-| Studio | Transient authoring world with live pack hotload and VSCode schemas; deleted on close and purged at startup |
-| World pack snapshot | Production worlds copy the pack into `<world>/iris/pack` and read that copy (see `05 - Concepts & Pack Layout.md`) |
+| Pack | A folder of JSON and `.iob` files under `packs/<key>/`. It needs at least one `dimensions/*.json` to count as a pack at all — a folder without one is treated as absent and will be re-downloaded |
+| Dimension | The root config for one world type: height range, generation modes, which regions it uses, what native content it imports. One dimension file is one world's ruleset |
+| Region / biome / generator | The authoring units under a dimension. Regions divide the map, biomes fill regions, generators produce the actual heightmap noise |
+| Object / structure | Placed content. An object is a single saved build (`.iob`); a structure is either an Iris jigsaw of several objects, or a vanilla/datapack/mod structure Iris allows through |
+| Studio | A throwaway authoring world that reads the live pack folder and hotloads your edits into new chunks. Deleted when you close it, and any leftovers are purged at startup |
+| World pack snapshot | A production world copies the pack into `<world>/iris/pack` at creation and reads only that copy forever after. This is the single most common source of "my edits did nothing" — see `05 - Concepts & Pack Layout.md` |
 
 ## Project layout
 
+Relevant if you're building Iris or filing a bug against a specific subsystem.
+
 | Path | Role |
 |---|---|
-| `core/` | Pure-JVM engine, pack loader, pregen, studio services, localization catalogs |
-| `core/agent/` | Agent helper module used by the core build |
-| `spi/` | Platform SPI and pure-JVM contracts (`IrisPlatform`, protocol types) |
-| `adapters/bukkit/plugin/` | Bukkit plugin main, commands, public Bukkit API, Paper plugin descriptor |
+| `core/` | The engine: pack loader, generation pipeline, pregen, studio services, localization catalogs. Pure JVM, no platform types |
+| `core/agent/` | Java instrumentation agent (premain/agent-class jar) consumed by the core build |
+| `spi/` | The platform contract (`IrisPlatform`, protocol types) that lets `core/` stay platform-free |
+| `adapters/bukkit/plugin/` | Bukkit plugin main class, the Director command tree, the public Bukkit API, and both plugin descriptors |
 | `adapters/bukkit/nms/v26_2_R1/` | NMS bindings for the current Minecraft line |
-| `adapters/minecraft-common/` | Shared adapter code used by Bukkit and mod loaders |
-| `adapters/modded-common/` | Shared Fabric / Forge / NeoForge worldgen, commands, services |
-| `adapters/client-common/` | Client HUD and world-type screens |
-| `adapters/fabric/`, `adapters/forge/`, `adapters/neoforge/` | Standalone loader builds (own `settings.gradle`) |
-| `probe/` | Offline tooling and stub platform |
-| `buildSrc/` | Shared Gradle helpers (artifact verification, API generation) |
-| `dist/` | Built consumer jars after `buildAllToOut` |
-| `docs/` | Authoritative product and API documentation |
+| `adapters/minecraft-common/` | Source shared by the Bukkit and mod-loader adapters |
+| `adapters/modded-common/` | Source shared by Fabric, Forge, and NeoForge: worldgen hooks, Brigadier commands, services |
+| `adapters/client-common/` | Client-dist source: HUD, keybinds, world-type screens |
+| `adapters/fabric/`, `adapters/forge/`, `adapters/neoforge/` | The three loader builds. Each is a standalone Gradle build with its own `settings.gradle` |
+| `probe/` | Offline tooling and a stub platform for running the engine without a server |
+| `buildSrc/` | Gradle helpers: artifact verification, NMS bindings, API generation |
+| `dist/` | Where `buildAllToOut` drops the finished consumer jars |
+| `docs/` | This documentation set, which is the authority over any hosted copy |
+
+`minecraft-common`, `modded-common`, and `client-common` are source trees only — they have no `build.gradle` and are not Gradle projects. The loader builds pull them in as extra source directories.
 
 ## Developer build check
 
-Set `JAVA_HOME` to JDK 25, then run the repository gate from the Iris root:
+Set `JAVA_HOME` to a JDK 25, then from the Iris root:
 
 ```text
 java -version
@@ -120,29 +132,31 @@ java -version
 ./gradlew buildAllToOut
 ```
 
-The check passes when `build` completes with no failed tasks and `buildAllToOut` publishes one current jar per supported platform under `dist/`. `build` already runs the test suite; use `./gradlew test` when you need to rerun tests without assembling every artifact.
+The check passes when `build` finishes with no failed tasks and `buildAllToOut` leaves one current jar per platform in `dist/`. `build` already runs the tests, so use `./gradlew test` only when you want to rerun tests without reassembling every artifact.
 
-`buildAllToOut` writes every platform jar into `dist/`:
+At version `4.0.0-26.2` the four jars are named like this — the CraftBukkit one carries the supported Minecraft *range*, the loader jars carry `<mc>+<loader>`:
 
-```
-Iris v<version> [CraftBukkit] <mc>.jar
-Iris v<version> [Fabric] <mc>+<loader>.jar
-Iris v<version> [Forge] <mc>+<loader>.jar
-Iris v<version> [NeoForge] <mc>+<loader>.jar
+```text
+Iris v4.0.0-26.2 [CraftBukkit] 26.1.2-26.2.jar
+Iris v4.0.0-26.2 [Fabric] 26.2+0.19.3.jar
+Iris v4.0.0-26.2 [Forge] 26.2+65.0.4.jar
+Iris v4.0.0-26.2 [NeoForge] 26.2+26.2.0.12-beta.jar
 ```
 
-Per-platform: `./gradlew buildBukkit`, `buildFabric`, `buildForge`, `buildNeoforge`. SPI jar: `./gradlew :spi:jar` → `spi/build/libs/`.
+Build one platform at a time with `./gradlew buildBukkit`, `buildFabric`, `buildForge`, or `buildNeoforge`. The SPI jar comes from `./gradlew :spi:jar` and lands in `spi/build/libs/`.
 
-Modded adapters are driven with their own project root when developing:
+To iterate on a loader adapter, drive it from its own project root — these are separate Gradle builds, so a root-level invocation won't reach them:
 
-```
+```text
 ./gradlew -p adapters/fabric   runServer
 ./gradlew -p adapters/forge    runServer
 ./gradlew -p adapters/neoforge runServer
 ```
 
-`-PincludeModdedAdapters=true` can surface those builds in the root composite for IDE import only; it is off by default because each adapter includes the root build back for `core`/`spi` substitution.
+`-PincludeModdedAdapters=true` surfaces those builds in the root composite for IDE import. It's off by default because each adapter includes the root build back for `core`/`spi` substitution, which closes a composite cycle.
 
-Current version property: `irisVersion=4.0.0-26.2` in `gradle.properties`.
+A passing Bukkit jar proves nothing about the loaders. Loom, ForgeGradle, and ModDevGradle each fail in their own ways, so if a loader build breaks while the root build is green, rerun that adapter from its own root and fix its first error rather than re-running the root build.
 
-If a mod-loader build fails while the root Bukkit/core build passes, rerun that adapter from its own project root and fix the first loader-specific error. Do not treat a Bukkit jar or core test pass as proof that Fabric, Forge, or NeoForge compiled.
+The current version lives in `gradle.properties` as `irisVersion=4.0.0-26.2`.
+
+Next: install Iris with `01 - Installation & Platforms.md`.