Iris/docs/01 - Installation & Platforms.md

# 01 - Installation & Platforms

Iris installs as either a Bukkit-family plugin jar or a self-contained Fabric, Forge, or NeoForge mod jar. Java 25 is required on every platform. On first boot the default `overworld` pack is downloaded when missing; packs live under each platform’s data directory.

## Requirements

| Requirement | Value |
|---|---|
| Java | 25 (`--release 25` / `java >= 25` on mod loaders) |
| Minecraft (plugin) | 26.1.2 – 26.2 (`api-version` 26.1) |
| Minecraft (mod) | 26.2 |
| Fabric Loader | 0.19.3+ |
| Forge | 65.0.4+ |
| NeoForge | 26.2.0.12-beta+ |
| Network | Outbound HTTPS on first boot for default pack download (GitHub IrisDimensions overworld release / pack install) |

## Plugin install (Paper / Purpur / Leaf / Canvas / Folia / Spigot)

1. Place the CraftBukkit-labelled plugin jar into `plugins/`.
2. Start the server. Iris loads at `STARTUP` (`plugin.yml` / `paper-plugin.yml`).
3. On first boot Iris provisions the default `overworld` pack into `plugins/Iris/packs/overworld` when missing (source: IrisDimensions overworld `beta` release zip).
4. Settings are written at `plugins/Iris/settings.json` if absent (`IrisSettings.read()`).

Command root: `/iris` (aliases `/ir`, `/irs`). Explicit permission in the descriptor: `iris.treefeller` (default op). Command access uses the Director permission model rooted at `iris.all` (see `04 - Commands & Permissions.md`).

Soft dependencies (optional, not bundled): PlaceholderAPI, CraftEngine, Nexo, ItemsAdder, SCore, ExecutableItems, MythicLib, MMOItems, eco, EcoItems, MythicMobs, MythicCrucible, KGenerators, WorldEdit. Multiverse-Core is ordered after Iris so Multiverse sees Iris generators after Iris is up.

### Folia note

`folia-supported: true`. Engine work uses region-safe scheduling. Runtime `/iris create` does **not** hot-create a live world on Folia: Iris stages world files, pack snapshot, and `bukkit.yml` registration, then requires a server restart before the world generates and loads. After restart, use `/iris load` or rely on the registered world entry as appropriate. See `06 - Worlds & Lifecycle.md`.

## Mod install (Fabric / Forge / NeoForge)

1. Place the matching mod jar into `mods/`.
2. Start the dedicated server (or a client for singleplayer; see below).
3. The jar is self-contained: core, SPI, and required Fabric API modules are bundled where applicable. Mod id: `irisworldgen`.
4. On first boot, if `config/irisworldgen/modded.json` has `autoDownloadDefaultPack` true (default) and `defaultPack` (default `overworld`) is missing, Iris downloads `IrisDimensions/<pack>` (branch `master` for the auto-prefetch path) into the packs folder before the forced worldgen datapack is written.

Packs installed later register custom dimension types (height ranges) and custom biomes through the forced datapack at server start. **Restart once after adding a pack** so worlds get full heights and biomes. Worlds created before that restart run with fallback heights.

### Singleplayer (modded clients)

Installed Iris packs appear as selectable World Types on the Create New World screen (`IRIS:<Pack>` style presets from the forced datapack). The integrated server runs the same engine as dedicated servers.

### Client HUD

Installing the mod jar on a client adds a pregeneration HUD (progress bar, chunks done/total, percent, chunks/s, ETA; yellow while paused). Key `H` (rebindable, category “Iris”) toggles it. The HUD talks to modded Iris servers and Bukkit/Paper Iris over channel `irisworldgen:main` (custom payloads on modded, plugin messaging on Bukkit). Vanilla clients are unaffected and get the server-side boss bar instead; on non-Iris servers the client mod is inert.

## Data directories

### Plugin (`plugins/Iris/`)

| Path | Role |
|---|---|
| `plugins/Iris/settings.json` | Engine settings (`IrisSettings`); created with defaults on first read |
| `plugins/Iris/packs/<key>/` | Installed packs (workspace name `packs`) |
| `plugins/Iris/bootstrap/` | Default-pack provision marker and related bootstrap state |
| `plugins/Iris/datapacks/` | Datapack download cache / staging (Bukkit datapack tooling) |
| `plugins/Iris/languages/overrides/<locale>.json` | Optional server message overrides |
| `<world>/iris/pack/` | Per-world pack **snapshot** used by production engines |

World dimension roots for managed Iris worlds are under the server’s world container (Iris managed dimension storage); see `06 - Worlds & Lifecycle.md`.

### Mod (`config/` relative to the game instance)

| Path | Role |
|---|---|
| `config/irisworldgen/packs/<pack>/` | Installed packs; valid when `dimensions/<dimension>.json` exists |
| `config/irisworldgen/generated/datapack/iris/` | Generated forced datapack (owned by Iris; do not edit) |
| `config/irisworldgen/modded.json` | Mod-side config: `defaultPack`, `autoDownloadDefaultPack`, primary world routing, main-world override |
| `config/iris/` | Engine data directory: `settings.json` and per-world engine state via `dataFile` |

Pack resolution for engines, commands, and the forced datapack uses `config/irisworldgen/packs`. The engine data folder is `config/iris` — different roots.

### Default `modded.json` keys

| Key | Default | Effect |
|---|---|---|
| `defaultPack` | `overworld` | Pack auto-download and default create pack name |
| `autoDownloadDefaultPack` | `true` | Async prefetch at boot when pack missing |
| `primaryWorld` | `""` | Primary-world router target dimension id |
| `routePlayersToPrimaryWorld` | `true` | Route players from vanilla overworld when primary is set |
| `mainWorldPack` | `""` | Main-world generator override pack ref |
| `mainWorldSeed` | `0` | Seed for main-world override |
| `mainWorldAutoRestart` | `false` | Auto-restart related to main-world override |

## Platform defaults (settings)

`IrisSettings` is shared across platforms. Generator default relevant to install and first world:

| Key path | Default | Effect |
|---|---|---|
| `generator.defaultWorldType` | `overworld` | Bukkit `/iris create` resolves `type=default` to this pack/dimension key |
| `general.language` | `en_US` | Server locale selection |
| `studio.openVSCode` | `true` | Whether studio may launch VSCode |
| `studio.autoStartDefaultStudio` | `false` | Do not auto-open studio on boot |

Full key list: `03 - Configuration.md`.

## First boot pack download

| Platform | Behavior |
|---|---|
| Plugin | `DefaultPackBootstrapProvisioner` downloads `https://github.com/IrisDimensions/overworld/releases/download/beta/overworld.zip` into `packs/overworld` when not already provisioned |
| Mod | If `autoDownloadDefaultPack` and pack missing, async install of configured `defaultPack` into `config/irisworldgen/packs` |

Manual install: `/iris download <pack>` (alias `dl`). Default overworld uses the beta-release path; other packs use `IrisDimensions/<pack>/<branch>` (plugin default branch `stable` for non-default; mod download defaults branch `stable` unless auto-prefetch uses `master` — see `25 - Pack Management.md`).

## Native worldgen over Iris terrain

Iris replaces the chunk generator. Vanilla and mod worldgen only runs where Iris runs it. Identical on every platform:

| Vanilla / mod worldgen | Over Iris terrain | Control |
|---|---|---|
| Structures (vanilla, datapack, mod) | Yes, on by default | `importedStructures.disabled` denies individual keys |
| Placed features: ores, trees, plants, springs, geodes | Yes, **off by default** | `importedFeatures.enabled` per dimension, with per-step and per-key filters |
| Carvers (caves, canyons, mod carvers) | Never | No `NoiseGeneratorSettings` for a carver to sample; use pack `caves` / `carvings` |
| Surface builders and surface rules | Never | Iris builds surfaces from pack palettes |
| Mod biomes | Only as `derivative`, `vanillaDerivative`, `biomeScatter`, or `biomeSkyScatter` target | Iris chooses biomes from the pack |
| Mob spawning, including mod mobs | Yes | Biome spawn tables merged with the vanilla derivative’s |

With `importedFeatures` off (default), chunk output is the pure Iris result. Full control reference: `94 - API - Modded.md` (also applies conceptually on Bukkit for imported native stages).

Independently of that flag, Iris custom biomes inherit biome tags of their vanilla derivative on every platform, so tag-driven content (`#minecraft:is_overworld`, mod spawn rules, etc.) applies to Iris custom biomes.

## Build artifacts

From repo root with JDK 25:

```
./gradlew buildAllToOut
```

Output under `dist/`:

| Pattern | Platform |
|---|---|
| `Iris v… [CraftBukkit] ….jar` | Plugin |
| `Iris v… [Fabric] ….jar` | Fabric |
| `Iris v… [Forge] ….jar` | Forge |
| `Iris v… [NeoForge] ….jar` | NeoForge |

Next: create a world and open studio in `02 - Getting Started.md`. Settings detail in `03 - Configuration.md`.