Iris/docs/25 - Pack Management.md

# 25 - Pack Management

Pack management covers download/install into the packs workspace, validation, unused-resource cleanup and restore, packaging for distribution, and unsafe replacement of a live world’s pack snapshot. Authoring packs live under the platform packs root; production worlds copy that tree into `<world>/iris/pack` (see `05 - Concepts & Pack Layout.md` and `06 - Worlds & Lifecycle.md`).

See also: `03 - Configuration.md`, `04 - Commands & Permissions.md`, `10 - Studio & VSCode Schemas.md`, `24 - Pack Mods & Snippets.md`, `27 - Example - Configuring Overworld.md`.

## Pack workspace

| Item | Path / rule |
|------|-------------|
| Packs root | Bukkit: plugin data `packs/`; modded: `config/irisworldgen/packs/` (platform data folder) |
| Visible packs | Non-hidden directories listed by `PackDirectoryResolver` |
| Presence | Pack exists if it has safe tree + at least one `dimensions/*.json` (parse failures do not trigger redownload) |
| Safe key | Download destination keys: `[a-z0-9_-]+` |

## Download

### Commands

| Command | Behavior |
|---------|----------|
| Bukkit: `/iris download <pack> [branch=stable] [overwrite=false]`; modded: `/iris download <pack> [branch] [force]` | Download into packs root |
| Default overworld special case | Pack name `overworld` uses IrisDimensions overworld **beta release zip** (`…/releases/download/beta/overworld.zip`), not an arbitrary branch zip |
| Other packs | `IrisDimensions/<pack>/<branch>` GitHub archive search via `StudioSVC.downloadSearch` |

| Param | Default | Notes |
|-------|---------|-------|
| `pack` | required | Folder/key or repo short name |
| `branch` | `stable` | GitHub ref when not default overworld |
| `overwrite` | `false` | Force replace existing present pack |

### Install pipeline (`PackDownloader`)

1. Per-key/ref download lock (concurrent startup and commands do not double-fetch).
2. If pack present and not force → skip network.
3. Download zip (size/entry limits: archive ≤512MiB, ≤100k entries, total uncompressed budget, per-file cap).
4. Unpack to temp; require single pack home directory.
5. Open as datapack-compiler `IrisData`; require **exactly one** dimension; key = that dimension load key.
6. Run `PackValidator.validate`; blocking errors abort install.
7. Publish into `packs/<key>/` with conflict checks (refuses symlink targets; detects dimension-key conflicts with other folders).

Default overworld repository constant: `IrisDimensions/overworld`.

## Validate

| Command | Behavior |
|---------|----------|
| Bukkit: `/iris pack validate [pack=<key>]`; modded: `/iris pack validate [pack]` | Validate one pack or all visible packs; publish into `PackValidationRegistry` |
| Bukkit: `/iris pack status [pack=<key>]`; modded: `/iris pack status [pack]` | Show cached registry results (run validate first) |

### Checks performed (`PackValidator`)

| Check | Blocking vs warning |
|-------|---------------------|
| Missing pack / missing `dimensions/` / no dimension JSON | Blocking |
| Dimension JSON integrity (`PackDimensionValidator`) | Blocking / warnings as emitted |
| Loot graph (`PackLootValidator`) | Blocking |
| Removed worldgen fields (e.g. `fluidBodies`) | Blocking |
| Object surface support | Blocking |
| Unsupported structure transforms (`rotation` / `translate` / `scale` on forbidden surfaces) | Blocking |
| Structure graph + compiled graph validator | Errors blocking; warnings advisory |
| Native structure replacement envelopes | Blocking |
| Spawner → entity references | Blocking |
| Custom biome spawns category resolution | Blocking |
| Content keys / bad block properties (`ContentKeyValidator`) | Blocking when `general.strictContentKeys` or `-Diris.strictContent`; else warnings (palette-sourced stay advisory) |

`isLoadable()` is false when any blocking error exists. Status reports blocking count and up to 10 warnings (plus “more” count).

## Cleanup (unused resources)

| Command | Mode | Behavior |
|---------|------|----------|
| Bukkit: `/iris pack cleanup <pack> [mode=preview]`; modded: `/iris pack cleanup <pack> [apply]` | `preview` (default) | List unused candidates; no writes |
| | `apply` | Quarantine candidates under pack `.iris-trash/<timestamp>/` |

Managed folders scanned for unreferenced JSON resources: `biomes`, `regions`, `entities`, `spawners`, `loot`, `generators`, `expressions`, `markers`, `blocks`, `mods`.

Excluded from cleanup corpus: `.iris-trash`, `datapack-imports`, `externaldatapacks`, `internaldatapacks`, `datapacks`, `cache`, `objects`, `.iris`.

Cleanup re-scans on apply (not a blind apply of an old preview). Failed apply may leave paths still quarantined and reports them.

## Restore

| Command | Mode | Behavior |
|---------|------|----------|
| Bukkit: `/iris pack restore <pack> [mode=preview]`; modded: `/iris pack restore <pack> [apply]` | `preview` | List latest quarantine dump files and conflicts |
| | `apply` | Move files back from latest dump if destinations free |

Restore **refuses** when destination paths already exist (conflict list). Nothing restored when no quarantine dump exists.

## Package (export)

| Command | Behavior |
|---------|----------|
| Bukkit: `/iris studio package [dimension=default] [obfuscate=false] [minify=true]`; modded: `/iris studio package [pack]` | Compile dimension closure to a zip |

| Param | Default | Notes |
|-------|---------|-------|
| `dimension` | contextual / `default` | Dimension in packs |
| `obfuscate` | `false` | Obfuscate packaged content when true |
| `minify` | `true` | Compact JSON (indent 0) |

Pipeline (`IrisPackageCompiler`):

1. Load dimension and walk regions → biomes → generators, loot, entities, spawners, structures/objects closure.
2. Stage under Iris data `exports/<dimensionKey>/`.
3. Write `package.json` with hash, time, version.
4. Zip to `exports/<dimensionKey>.iris` (compression level 9); delete staging folder.

Does not modify the source pack or any world snapshot.

## Developer update-world (unsafe)

| Command | Behavior |
|---------|----------|
| `/iris developer update-world world=<world> pack=<dimension> confirm=true [fresh-download=false]` | Replace the world’s pack snapshot |

| Param | Default | Notes |
|-------|---------|-------|
| `world` | contextual | Target world folder |
| `pack` / dimension | contextual | Source dimension (live packs root) |
| `confirm` | `false` | Required true; otherwise prints warning only |
| `fresh-download` | `false` | Re-download pack before install |

Implementation:

1. Requires `confirm=true`.
2. Optional `StudioSVC.downloadSearch` when `fresh-download`.
3. Acquires `PACK_MUTATION` / `PACK_PUBLISH` lease.
4. `StudioSVC.replaceIntoWorld` → install into `worldFolder/iris/pack` with `replaceExisting=true` (atomic stage/publish).
5. If an engine still holds that pack data, Iris **restarts the server** after commit (`"An active Iris world pack was replaced."`).

This is intentionally unsafe for production without backups: existing chunks keep old terrain; only future generation and pack-driven systems see new content. Prefer staging a new world when pack contracts change.

## Related operations

| Task | Where |
|------|-------|
| Create studio project from template | `/iris studio create` (`10 - Studio & VSCode Schemas.md`) |
| Open VSCode + schemas | `/iris studio vscode` |
| Import vanilla objects/structures into pack | `/iris studio importvanilla` |
| Structure import | `/iris structure …` |
| Strict content keys | `settings.general.strictContentKeys` (`03 - Configuration.md`) |
| Datapack bootstrap / install | Server configurator + `/iris datapack` (see platform docs) |

## Operator checklist

1. Download or place pack under `packs/<key>/` with `dimensions/*.json`.
2. On Bukkit, run `/iris pack validate pack=<key>` until loadable. Modded uses `/iris pack validate <key>`.
3. On Bukkit, optionally run `/iris pack cleanup <key> mode=preview`, then `mode=apply` after review; restore if needed. Modded uses the `apply` literal.
4. Create world with `/iris create …` (copies pack) or open studio for live edit.
5. To ship on Bukkit: `/iris studio package dimension=<dimension>`.
6. To refresh an existing world pack only after backup: `/iris dev update-world world=<world> pack=<dimension> confirm=true`.