Iris/docs/00 - Overview.md

# 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.

## 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 |
|---|---|
| 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` |

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.

## Platforms

| Platform | Artifact | Minecraft | Notes |
|---|---|---|---|
| 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+ |

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`).

Mod id on all three loaders: `irisworldgen`.

## Feature map

| Area | What it covers | Doc |
|---|---|---|
| Install and platforms | Plugin vs mod jars, data dirs, first boot, native worldgen matrix | `01 - Installation & Platforms.md` |
| First steps | Create, load, teleport, pregen, studio | `02 - Getting Started.md` |
| Configuration | `settings.json` keys, defaults, hotload | `03 - Configuration.md` |
| Commands and permissions | Full `/iris` tree, Bukkit vs modded argument style | `04 - Commands & Permissions.md` |
| Pack layout | Roots, keys, snippets, world snapshot vs studio | `05 - Concepts & Pack Layout.md` |
| Worlds | create / load / unload / remove, main world, Folia, pack copy | `06 - Worlds & Lifecycle.md` |
| Pregeneration | Jobs, cache, mantle, HUD | `07 - Pregeneration.md` |
| Localization | Locales, overrides, client lang | `08 - Localization.md` |
| PlaceholderAPI | `%iris_…%` keys and migration | `09 - PlaceholderAPI.md` |
| Studio and schemas | Studio worlds, VSCode workspace, hotload | `10 - Studio & VSCode Schemas.md` |
| Dimensions | Dimension JSON, modes, height, imports | `11 - Dimensions.md` |
| Regions | Region-level content | `12 - Regions.md` |
| Biomes | Biome JSON, layers, custom biomes, spawns | `13 - Biomes.md` |
| Generators and noise | Generators, styles, expressions, images | `14 - Generators & Noise.md` |
| Caves and carving | Cave profiles, field modules | `15 - Caves & Carving.md` |
| Surfaces | Decorators, deposits, palettes | `16 - Surfaces, Decorators & Deposits.md` |
| Procedural decoration | Trees, fungi, coral, crystals, formations, ruins | `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md` |
| Structures overview | Objects vs jigsaw vs native | `18 - Structures Overview.md` |
| Objects | Creating and importing `.iob` | `19 - Objects.md` |
| Object placement | Placing objects in biomes and regions | `20 - Object Placement.md` |
| Jigsaw | Iris multi-piece structures | `21 - Jigsaw Structures.md` |
| Native structures | Vanilla / datapack structures on Iris | `22 - Native Structures & Datapacks.md` |
| Loot and entities | Pack entities, loot, spawners, markers | `23 - Loot, Entities, Spawners, Markers.md` |
| Pack extensions | Reusable snippets and the inactive pack-mod schema | `24 - Pack Mods & Snippets.md` |
| Pack management | Download, validate, cleanup, package, update-world | `25 - Pack Management.md` |
| Minimal pack example | Walkthrough | `26 - Example - Minimal Dimension.md` |
| Overworld example | Editing the shipping overworld | `27 - Example - Configuring Overworld.md` |
| 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` |
| 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` |
| Maintainer — release | Release steps | `86 - Maintainer - Release Checklist.md` |
| Maintainer — readiness | Living readiness tracker | `87 - Maintainer - Release Readiness.md` |
| API — setup | Bukkit public API dependency | `90 - API - Getting Started.md` |
| API — terrain | Terrain query service | `91 - API - Terrain.md` |
| API — events | Engine and pregen events | `92 - API - World Events.md` |
| 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 (brief)

| Term | Meaning |
|---|---|
| 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`) |

## Project layout

| 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 |
| `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 |

## Developer build check

Set `JAVA_HOME` to JDK 25, then run the repository gate from the Iris root:

```text
java -version
./gradlew build
./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.

`buildAllToOut` writes every platform jar into `dist/`:

```
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
```

Per-platform: `./gradlew buildBukkit`, `buildFabric`, `buildForge`, `buildNeoforge`. SPI jar: `./gradlew :spi:jar` → `spi/build/libs/`.

Modded adapters are driven with their own project root when developing:

```
./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.

Current version property: `irisVersion=4.0.0-26.2` in `gradle.properties`.

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.