mirror of
https://github.com/VolmitSoftware/Iris.git
synced 2026-08-27 12:41:43 +00:00
Fixes
This commit is contained in:
Brian Neumann-Fopiano
@@ -1,13 +1,13 @@
|
||||
# 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.
|
||||
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 managed `overworld` and `underworld` beta packs are downloaded when missing; packs live under each platform’s data directory.
|
||||
|
||||
## Installation outcome
|
||||
|
||||
Complete one platform path below. A successful install has all three results:
|
||||
|
||||
1. Iris reaches its enabled/ready state without an exception.
|
||||
2. The platform data directory contains `settings.json` and a loadable `packs/overworld/` directory.
|
||||
2. The platform data directory contains `settings.json` and loadable `packs/overworld/` and `packs/underworld/` directories.
|
||||
3. `/iris` prints help from the server console. On a modded client, the Iris keybind category is an additional client-side check, not a substitute for the server check.
|
||||
|
||||
Keep the previous jar/mod and the entire Iris data directory until the new build passes these checks. Replacing the binary does not update pack snapshots already stored inside worlds.
|
||||
@@ -22,7 +22,7 @@ Keep the previous jar/mod and the entire Iris data directory until the new build
|
||||
| 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) |
|
||||
| Network | Outbound HTTPS on first boot for the GitHub IrisDimensions Overworld and Underworld beta release assets |
|
||||
|
||||
Before replacing an existing installation:
|
||||
|
||||
@@ -37,7 +37,7 @@ Do not copy multiple Iris platform jars into the same `plugins/` or `mods/` dire
|
||||
|
||||
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).
|
||||
3. On first boot Iris provisions `overworld` and `underworld` into `plugins/Iris/packs/` when missing from their IrisDimensions `beta` release ZIPs.
|
||||
4. Settings are written at `plugins/Iris/settings.json` if absent (`IrisSettings.read()`).
|
||||
|
||||
Validate the plugin install from the server console:
|
||||
@@ -45,6 +45,7 @@ Validate the plugin install from the server console:
|
||||
```text
|
||||
/iris version
|
||||
/iris pack validate pack=overworld
|
||||
/iris pack validate pack=underworld
|
||||
```
|
||||
|
||||
The first command must report the running Iris, platform, and Minecraft versions. The second must resolve the downloaded pack and finish without blocking validation errors. Then complete the disposable-world workflow in `02 - Getting Started.md`; a command response alone does not prove that the generator can create chunks.
|
||||
@@ -66,16 +67,17 @@ Before creating a real world, run the Bukkit fresh-install smoke in `31 - Operat
|
||||
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.
|
||||
4. On first boot, if `config/irisworldgen/modded.json` has `autoDownloadDefaultPack` true (default), Iris installs the managed `overworld` and `underworld` beta releases when missing, followed by a configured non-managed `defaultPack` when applicable, before the forced worldgen datapack is written.
|
||||
|
||||
Validate the server-side mod install:
|
||||
|
||||
```text
|
||||
/iris version
|
||||
/iris pack validate overworld
|
||||
/iris pack validate underworld
|
||||
```
|
||||
|
||||
The install passes when Iris reports the expected loader/version, `config/irisworldgen/packs/overworld/dimensions/` contains a dimension JSON file, and validation has no blocking errors. Restart once before creating a world if the pack or its generated dimension-type datapack was installed during this boot.
|
||||
The install passes when Iris reports the expected loader/version, both managed pack directories contain their primary dimension JSON, and validation has no blocking errors. Restart once before creating a world if a pack or its generated dimension-type datapack was installed during this boot.
|
||||
|
||||
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.
|
||||
|
||||
@@ -118,7 +120,7 @@ Pack resolution for engines, commands, and the forced datapack uses `config/iris
|
||||
| Key | Default | Effect |
|
||||
|---|---|---|
|
||||
| `defaultPack` | `overworld` | Pack auto-download and default create pack name |
|
||||
| `autoDownloadDefaultPack` | `true` | Async prefetch at boot when pack missing |
|
||||
| `autoDownloadDefaultPack` | `true` | Async prefetch of both managed beta packs and any configured non-managed default when 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 |
|
||||
@@ -142,17 +144,17 @@ Full key list: `03 - Configuration.md`.
|
||||
|
||||
| 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` |
|
||||
| Plugin | `DefaultPackBootstrapProvisioner` independently manages the Overworld and Underworld beta assets under `packs/overworld` and `packs/underworld`, then compiles the aggregate datapack once |
|
||||
| Mod | If `autoDownloadDefaultPack` is enabled, async install of both managed beta packs plus any distinct configured default 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`).
|
||||
Manual install: `/iris download <pack>` (alias `dl`). `overworld` and `underworld` use their beta-release assets and ignore the branch argument; other packs use `IrisDimensions/<pack>/<branch>` (default branch `stable` — see `25 - Pack Management.md`).
|
||||
|
||||
## Installation recovery
|
||||
|
||||
| Symptom | Check | Recovery |
|
||||
|---|---|---|
|
||||
| Iris does not appear in `/iris version` | Wrong directory, wrong platform jar, duplicate jar, Java mismatch, or an enable exception | Stop the server, keep only the matching artifact, confirm Java 25, and fix the first Iris exception in the startup log |
|
||||
| `settings.json` exists but `packs/overworld` does not | Default-pack download failed or is still incomplete | Restore outbound HTTPS or install a complete pack, then restart; do not create an empty `overworld` folder |
|
||||
| `settings.json` exists but a managed pack is absent | Managed beta download failed or is still incomplete | Restore outbound HTTPS or install the complete release pack, then restart; do not create an empty pack folder |
|
||||
| Pack validates but modded height/biomes use fallbacks | Forced datapack was generated after registries loaded | Restart once with the pack already installed, then create a new disposable world |
|
||||
| Bukkit command is denied for a non-op | `iris.all` is missing | Grant `iris.all`; `iris.treefeller` controls only survival tree felling |
|
||||
| Client HUD is absent but server commands work | Client mod missing, disabled keybind, or server capability not negotiated | Install the matching client mod, reconnect, and verify the Iris keybind category; server generation does not require the client HUD |
|
||||
|
||||
@@ -15,7 +15,7 @@ Treat each numbered section as a gate. Confirm the world is loaded before telepo
|
||||
- Iris installed per `01 - Installation & Platforms.md`
|
||||
- Java 25 server or mod instance running
|
||||
- Operator / gamemaster access (`iris` commands; modded mutating commands require permission level 2 / gamemasters)
|
||||
- Default pack present (auto-downloaded on first boot) or an installed pack under the platform packs directory
|
||||
- Managed Overworld and Underworld packs present (auto-downloaded on first boot) or the required project pack installed under the platform packs directory
|
||||
|
||||
## Argument style
|
||||
|
||||
@@ -263,7 +263,7 @@ The session passes when the production world loads again after a clean restart a
|
||||
| Bukkit optional args without `key=` | Parse error | Use `seed=1337`, not a bare second number for optional params |
|
||||
| Mod pregen while another job runs | Start fails | `/iris pregen stop` then start again |
|
||||
| Studio closed mid-edit | World discarded | Edits on disk in `packs/` remain; reopen studio |
|
||||
| Default pack download blocked | Create/open fails missing pack | Allow HTTPS or `/iris download overworld` offline install of a pack tree |
|
||||
| Managed pack download blocked | Startup or create/open fails with a missing pack | Allow HTTPS or install with `/iris download overworld` and `/iris download underworld`; an offline install must contain each complete pack tree |
|
||||
| `type=default` vs pack key | Resolves via `generator.defaultWorldType` | Prefer explicit `type=overworld` or your pack key |
|
||||
|
||||
## Quick reference
|
||||
|
||||
@@ -244,8 +244,8 @@ Path: `<configDir>/irisworldgen/modded.json`. Written with defaults on first loa
|
||||
|
||||
| Key | Type | Default | Notes |
|
||||
|-----|------|---------|-------|
|
||||
| `defaultPack` | string | `"overworld"` | Default pack for bootstrap download/install |
|
||||
| `autoDownloadDefaultPack` | boolean | `true` | Download default pack when missing |
|
||||
| `defaultPack` | string | `"overworld"` | Default create pack; a distinct non-managed value is also prefetched when enabled |
|
||||
| `autoDownloadDefaultPack` | boolean | `true` | Download missing managed Overworld/Underworld beta packs and any distinct configured default |
|
||||
| `primaryWorld` | string | `""` | Primary Iris dimension id for player routing |
|
||||
| `routePlayersToPrimaryWorld` | boolean | `true` | Route players to primary when set |
|
||||
| `mainWorldPack` | string | `""` | Pack (or `pack:dimensionKey`) for main-world preset |
|
||||
|
||||
@@ -79,7 +79,7 @@ Tree feller on mod loaders uses platform permission APIs (`irisworldgen:treefell
|
||||
| `load` | `import` | **Bukkit** | `<world>` | Load managed Iris world |
|
||||
| `unload` | | **Bukkit** | `<world>` | Unload Iris world |
|
||||
| `debug` | | Both | — | Toggle `general.debug` and save settings |
|
||||
| `download` | `dl` | Both | `<pack> [branch=stable] [overwrite=false]` (`overwrite` alias `force`) | Download pack project |
|
||||
| `download` | `dl` | Both | `<pack> [branch=stable] [overwrite=false]` (`overwrite` alias `force`) | Download a pack; `overworld` and `underworld` resolve to managed beta release ZIPs |
|
||||
| `metrics` | `measure` | Both | — | Generation metrics (player / current Iris level) |
|
||||
| `reload` | | Both | — | Reload `settings.json` and locale; modded also schedules forced datapack regeneration |
|
||||
| `seed` | | **Modded** | — | Print world/engine seeds (gamemaster) |
|
||||
@@ -102,7 +102,7 @@ Tree feller on mod loaders uses platform permission APIs (`irisworldgen:treefell
|
||||
|
||||
---
|
||||
|
||||
On Bukkit, `overwrite=true` is deliberately restart-only. The name may resolve to a safe `iris:*` world or exactly the configured main, `_nether`, or `_the_end` alias; arbitrary `minecraft:*` and foreign namespaces are rejected. Iris stages and validates a fresh pack snapshot, compare-and-swaps only that world's `bukkit.yml` generator and seed, and retains the existing dimension folder as a rollback backup until the restarted world proves its Iris identity, pack, dimension, environment, and seed. Multiple distinct slots may be staged before one restart. `main=true` is valid with overwrite only when the name is the configured main-world name. Exact vanilla slots preserve the authoritative seed shared by the existing level, regardless of the supplied `seed`; this keeps Overworld/Nether/End coordinate generation aligned. Use ordinary new-main promotion when a new level seed is required.
|
||||
On Paper-family servers, `overwrite=true` is deliberately restart-only; Spigot rejects it because it has no pre-registry plugin bootstrap. The exact target dimension folder must already exist; use ordinary `/iris create` for a new world. The name may resolve to a safe `iris:*` world or exactly the configured main, `_nether`, or `_the_end` alias; arbitrary `minecraft:*` and foreign namespaces are rejected. Iris stages and validates a fresh pack snapshot, compare-and-swaps only that world's `bukkit.yml` generator and seed, and retains the existing dimension folder as a rollback backup until the restarted world proves its Iris identity, pack, dimension, environment, and seed. Multiple distinct slots may be staged before one restart. `main=true` is valid with overwrite only when the name is the configured main-world name. Exact vanilla slots preserve the authoritative seed shared by the existing level, regardless of the supplied `seed`; this keeps Overworld/Nether/End coordinate generation aligned. Use ordinary new-main promotion when a new level seed is required.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -103,7 +103,7 @@ Live overworld also contains authoring-only or empty trees that loaders do not r
|
||||
2. `dimensions/` is missing.
|
||||
3. `dimensions/` has no `*.json` files.
|
||||
|
||||
A downloaded archive is also rejected unless it contains exactly one loadable dimension (install key becomes that dimension’s load key). Presence of a pack on disk is defined as a safe pack directory with at least one non-symlink `dimensions/*.json` file.
|
||||
A downloaded archive without an expected key is rejected unless it contains exactly one loadable dimension, whose load key becomes the install key. Managed-release and listing downloads carry an exact expected primary key, so their archive may retain additional dimension resources; the expected dimension selects the folder key and the entire pack still validates before publication. Presence of a pack on disk is defined as a safe pack directory with at least one non-symlink `dimensions/*.json` file.
|
||||
|
||||
## Snippets
|
||||
|
||||
|
||||
@@ -126,11 +126,11 @@ Runtime world creation is disabled on Folia. `/iris create` instead:
|
||||
|
||||
## Exact world-slot replacement
|
||||
|
||||
`overwrite=true` uses lifecycle kind `WORLD_REPLACE` and always stages for restart on Bukkit-family servers, including Paper and Folia. It accepts safe `iris:*` keys and only the three exact vanilla slots resolved from the configured level name: `minecraft:overworld`, `minecraft:the_nether`, and `minecraft:the_end`. A vanilla slot requires a matching pack environment (`NORMAL`, `NETHER`, or `THE_END`), and Nether/End replacement requires the server's matching allow setting to be enabled; foreign namespaces, other `minecraft:*` keys, path traversal, links, and special filesystem entries fail closed. `main=true` may accompany overwrite only for the configured main-world name. Minecraft stores one authoritative seed for the existing level, so all three exact vanilla slots preserve that loaded primary-world seed and report when it differs from the command's `seed`; changing the level seed remains the ordinary new-main promotion workflow.
|
||||
`overwrite=true` uses lifecycle kind `WORLD_REPLACE` and always stages for a complete Paper-family restart, including Paper, Purpur, Leaf, and Folia; Spigot has no early registry bootstrap and rejects this mode. The exact target dimension folder must already exist; ordinary create remains the path for a new world. It accepts safe `iris:*` keys and only the three exact vanilla slots resolved from the configured level name: `minecraft:overworld`, `minecraft:the_nether`, and `minecraft:the_end`. A vanilla slot requires a matching pack environment (`NORMAL`, `NETHER`, or `THE_END`), and Nether/End replacement requires the server's matching allow setting to be enabled; foreign namespaces, other `minecraft:*` keys, path traversal, links, and special filesystem entries fail closed. `main=true` may accompany overwrite only for the configured main-world name. Minecraft stores one authoritative seed for the existing level, so all three exact vanilla slots preserve that loaded primary-world seed and report when it differs from the command's `seed`; changing the level seed remains the ordinary new-main promotion workflow.
|
||||
|
||||
The transaction copies and validates a fresh frozen pack under a same-filesystem sibling stage, fingerprints it, journals the original target state and `bukkit.yml` generator/seed, then compare-and-swaps that one configuration entry. Distinct slots can be queued before one restart. During Iris `STARTUP`, before Bukkit loads worlds, each authorized transaction atomically moves the old exact dimension directory to a retained sibling backup and publishes its stage. There is no chunk merge: old region, entity, POI, and Iris data remain only in the backup, while the target starts with the staged pack snapshot.
|
||||
The transaction copies and validates a fresh frozen pack under a same-filesystem sibling stage, fingerprints it, binds its journal to the canonical level root and logical world name, records the original target and `bukkit.yml` generator/seed, then compare-and-swaps that one configuration entry. Distinct slots can be queued before one restart. Paper bootstrap reconciles each authorized transaction before Iris compiles its aggregate datapack or Minecraft builds registries: it atomically moves the old exact dimension directory to a retained sibling backup and publishes the stage. The filesystem must support atomic replacement for the world directories, journal, and `bukkit.yml`; Iris refuses the operation without falling back to a non-atomic destructive move. Publication retains Paper's per-world `data/paper/metadata.dat`, `data/paper/level_overrides.dat`, and `data/minecraft/world_gen_settings.dat` so the replacement keeps the exact slot metadata and authoritative seed. Old `region`, `entities`, `poi`, and Iris runtime data are never merged; they remain only in the backup while the target starts with the staged pack snapshot.
|
||||
|
||||
The backup is deleted only after `WorldLoad` proves the exact namespaced identity, Iris generator, selected dimension, seed, vanilla-slot environment, and unchanged pack fingerprint. A failed runtime check journals rollback, restores the prior `bukkit.yml` generator/seed with compare-and-swap semantics, requests another restart, and restores the retained directory before that restart loads worlds. A crash between either atomic move or journal write is retried idempotently. Conflicting manual configuration, changed staged bytes, unsafe storage, or corrupt journals block Iris world admission and preserve the stage/backup for operator recovery instead of guessing or deleting.
|
||||
The backup is eligible for asynchronous deletion only after `WorldLoad` proves the exact namespaced identity, Iris generator, selected dimension, seed, vanilla-slot environment, and unchanged pack fingerprint; cleanup failure retains its committed journal and retries without rolling back a verified world. A failed runtime check journals rollback and requests another restart, then cold bootstrap restores the retained directory and prior `bukkit.yml` generator/seed before registry or world loading. A crash between any move, configuration write, or journal phase is retried idempotently. Conflicting manual configuration, changed roots or logical names, changed staged bytes, unsafe storage, duplicate/corrupt journals, or irreconcilable transaction state abort the early bootstrap and preserve recoverable artifacts instead of guessing or deleting.
|
||||
|
||||
## Studio create
|
||||
|
||||
|
||||
@@ -34,13 +34,13 @@ If validation reports a missing edge, restore or repair that resource before pac
|
||||
| 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 |
|
||||
| Managed beta packs | Pack names `overworld` and `underworld` use their IrisDimensions **beta release ZIPs**, not arbitrary branch archives |
|
||||
| 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 |
|
||||
| `branch` | `stable` | GitHub ref when the pack is not a managed beta |
|
||||
| `overwrite` | `false` | Force replace existing present pack |
|
||||
|
||||
### Install pipeline (`PackDownloader`)
|
||||
@@ -48,12 +48,12 @@ If validation reports a missing edge, restore or repair that resource before pac
|
||||
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.
|
||||
4. Unpack to temp; require a single pack home directory.
|
||||
5. Open as datapack-compiler `IrisData`. A normal download without an expected key requires exactly one dimension; a managed or listing download selects its exact expected dimension while retaining and validating any additional dimension resources in the same pack.
|
||||
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`.
|
||||
Managed beta sources are `IrisDimensions/overworld` (`overworld.zip`) and `IrisDimensions/underworld` (`underworld.zip`). Startup treats their ownership independently: an operator-edited or linked pack is preserved without preventing the other managed pack from updating.
|
||||
|
||||
## Validate
|
||||
|
||||
|
||||
@@ -109,7 +109,7 @@ Worlds created from a pack store a **copy** at:
|
||||
|
||||
`StudioSVC.installIntoWorld` and `replaceIntoWorld` copy the source pack tree into that directory. Runtime generation for a normal world reads the world copy, not the global `packs/` tree. Studio worlds hotload the pack under `packs/` directly.
|
||||
|
||||
First install often downloads the default overworld release into `packs/` (`downloadDefaultOverworld` / `/iris download` flows — see `02 - Getting Started.md`, `25 - Pack Management.md`).
|
||||
First install downloads the managed Overworld and Underworld beta releases into `packs/`; `/iris download overworld` uses the same Overworld asset (see `02 - Getting Started.md`, `25 - Pack Management.md`).
|
||||
|
||||
## High-level layout (shipping overworld)
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ Hotload: Bukkit file-watch engine; modded 3s poll. Same invalidate/reload/locale
|
||||
|
||||
| Concern | Bukkit | Modded |
|
||||
|---------|--------|--------|
|
||||
| Create | `/iris create` → managed world name, generator Iris, optional main-world; `overwrite=true` stages exact Iris/vanilla-slot replacement for restart | `/iris create` or `/iris world enable` → dimension id + pack injection |
|
||||
| Create | `/iris create` → managed world name, generator Iris, optional main-world; on Paper-family servers `overwrite=true` stages replacement of an existing exact Iris/vanilla slot for restart | `/iris create` or `/iris world enable` → dimension id + pack injection |
|
||||
| Load / unload | `/iris load` (`import`), `/iris unload` | `/iris world disable` unloads; no separate load command |
|
||||
| Remove / delete | `/iris remove` optional folder delete | `/iris world delete` wipes chunk/mantle data |
|
||||
| Primary / main world | create `main=true` for a new level root, or name the configured main with `overwrite=true` for journaled in-place dimension replacement | `modded.json` primary + `routePlayersToPrimaryWorld`; `/iris world mainworld`, `replace-overworld` |
|
||||
@@ -49,7 +49,7 @@ Hotload: Bukkit file-watch engine; modded 3s poll. Same invalidate/reload/locale
|
||||
| Studio world | Transient studio world via StudioSVC; `/iris jigsaw` can select the Jigsaw Studio generator for one activation | Studio dimension under `irisworldgen:studio_*`; no Jigsaw Studio authoring command tree |
|
||||
| Folia | Regionized schedulers; pregen `runtimeSchedulerMode` forces `FOLIA` when regionized | N/A (not Bukkit Folia) |
|
||||
|
||||
Default pack bootstrap still downloads the IrisDimensions overworld release into `packs/overworld` when missing (shared provisioner).
|
||||
Startup installs the IrisDimensions Overworld and Underworld beta releases into `packs/overworld` and `packs/underworld` when missing. Paper bootstrap publishes both in one rollback scope before compiling the aggregate datapack; legacy Bukkit and modded startup use the same managed release sources.
|
||||
|
||||
Modded startup quarantines a corrupt persistent-dimension registry as `iris-dimensions.json.broken-<timestamp>` and continues without those dynamic worlds. Recovery details are in `06 - Worlds & Lifecycle.md`.
|
||||
|
||||
@@ -76,7 +76,7 @@ Jigsaw pack resources are shared runtime data, but in-game Jigsaw Studio is not
|
||||
| Jigsaw Studio create/grid/marker capture/rules/export | yes | no | no | no |
|
||||
| Saved planar/spatial Iris jigsaw runtime | yes | yes | yes | yes |
|
||||
| Pack validate / cleanup / download | yes | yes | yes | yes |
|
||||
| Exact restart replacement of configured Overworld/Nether/End slots | yes | no | no | no |
|
||||
| Exact restart replacement of configured Overworld/Nether/End slots | Paper/Purpur/Leaf/Folia | no | no | no |
|
||||
| Pregen | yes (Paper-like / Folia modes) | yes (`moddedPregenInFlight`) | yes | yes |
|
||||
| Studio open/close/vscode/package | yes | yes | yes | yes |
|
||||
| Object wand / paste / save / undo | yes | yes | yes | yes |
|
||||
|
||||
@@ -25,7 +25,7 @@ GoldenHash details and file layout: `32 - Determinism & Goldenhash.md`.
|
||||
## A. Fresh install and first world (Bukkit-family)
|
||||
|
||||
1. Install the CraftBukkit-family jar into `plugins/` (Paper, Purpur, Folia, Spigot, Leaf, Canvas as advertised). Require Java 25. See `01 - Installation & Platforms.md`.
|
||||
2. Start the server once. Confirm Iris enables, default pack download completes when no pack is present, and `settings.json` is written under the Iris data directory.
|
||||
2. Start the server once. Confirm Iris enables, managed `overworld` and `underworld` beta downloads complete when absent, and `settings.json` is written under the Iris data directory.
|
||||
3. Create a world with a fixed seed and teleport into it:
|
||||
|
||||
```
|
||||
@@ -36,21 +36,21 @@ GoldenHash details and file layout: `32 - Determinism & Goldenhash.md`.
|
||||
4. Join or teleport into the world. Confirm non-empty terrain, surface biomes, and no repeating console stack traces on first chunks.
|
||||
5. Gate: world is loaded as an Iris world; chunks generate without enable-time crash; console shows no fatal engine init failure.
|
||||
|
||||
## A.1 Exact vanilla-slot replacement (Bukkit-family)
|
||||
## A.1 Exact vanilla-slot replacement (Paper-family)
|
||||
|
||||
Use a disposable server whose configured level name is `world`, with a valid `NETHER` Iris pack and a generated vanilla Nether containing a unique marker chunk. Record hashes of the old Nether `region`, `entities`, and `poi` files before staging.
|
||||
Use a disposable server whose configured level name is `world`, with a valid `NETHER` Iris pack and a generated vanilla Nether containing a unique marker chunk. Record hashes of the old Nether `region`, `entities`, and `poi` files, and retain copies of `data/paper/metadata.dat`, `data/paper/level_overrides.dat`, and `data/minecraft/world_gen_settings.dat` for comparison before staging.
|
||||
|
||||
1. Run `/iris create world_nether type=<nether-pack> seed=1337 overwrite=true`. Gate: the command says the replacement is staged, the loaded Nether and its files remain unchanged, `bukkit.yml` now names `Iris:<dimension>`, and one pending replacement journal plus one sibling stage exists.
|
||||
2. Optionally stage the configured main name with a `NORMAL` pack and the End alias with a `THE_END` pack. Gate: each distinct slot gets its own transaction and no live dimension folder is moved.
|
||||
3. Restart normally. Gate: Iris publishes before Bukkit world loading; `minecraft:the_nether` loads with the Iris generator, requested dimension and seed; its frozen `iris/pack` exists; no old `region`, `entities`, or `poi` file was merged into the target; and the marker chunk is absent.
|
||||
4. Gate after `WorldLoad`: the retained sibling backup and journal disappear only after identity, environment, seed, dimension, and pack-fingerprint verification succeeds.
|
||||
3. Restart normally. Gate: Iris publishes before aggregate-datapack compilation and Bukkit world loading; `minecraft:the_nether` loads with the selected Iris dimension, the prior Paper per-world metadata files, and the authoritative shared level seed; its frozen `iris/pack` exists; no old `region`, `entities`, or `poi` file was merged into the target; and the marker chunk is absent.
|
||||
4. Gate after `WorldLoad`: the journal advances to committed cleanup only after identity, environment, seed, dimension, and pack-fingerprint verification succeeds; asynchronous cleanup then removes the retained sibling backup and journal without stalling the world thread.
|
||||
5. Restart again and generate fresh Nether chunks. Gate: the exact vanilla identity and Iris generator persist, ordinary Nether portals still target `minecraft:the_nether`, and no pending stage/backup/journal returns.
|
||||
6. Repeat once with a deliberately changed staged pack or conflicting `bukkit.yml` value before restart. Gate: Iris refuses publication or world admission, preserves recoverable artifacts, and never guesses a target. For a post-publication verification failure, gate that Iris restores the prior configuration, requests the controlled rollback restart, and restores the retained original directory before world load.
|
||||
6. Repeat once with a deliberately changed staged pack or conflicting `bukkit.yml` value before restart. Gate: early Paper bootstrap aborts before registry/world loading, preserves recoverable artifacts, and never guesses a target. For a post-publication verification failure, gate that Iris journals rollback and requests the controlled restart, then restores the retained original directory and prior configuration before datapack compilation or world loading.
|
||||
|
||||
## B. Fresh install and first world (Fabric / Forge / NeoForge)
|
||||
|
||||
1. Install the matching mod jar into `mods/`. Fabric requires Loader ≥ declared floor; Forge/NeoForge require their declared floors. See `01 - Installation & Platforms.md` and `30 - Platform Differences.md`.
|
||||
2. Start dedicated server (or integrated singleplayer for client-mod smoke). Confirm Iris boots, default pack installs, and datapack/biome registration completes.
|
||||
2. Start dedicated server (or integrated singleplayer for client-mod smoke). Confirm Iris boots, both managed beta packs install, and datapack/biome registration completes.
|
||||
3. Create a world with fixed seed (positional mod syntax):
|
||||
|
||||
```
|
||||
|
||||
@@ -270,7 +270,7 @@ Gate: every advertised server, loader, client, and content path completes the sa
|
||||
|
||||
### Confirmed release blockers and follow-ups
|
||||
|
||||
- [ ] Freeze the default overworld pack to an immutable release input. The runtime downloader currently follows the mutable `master` branch, so any recorded tree checksum remains reproducible only while that upstream content is unchanged. Immutable branch/tag/commit URL resolution is implemented, but published commit `8e32852ee6ecd039fae27a36f701f57cdc02e83f` predates the five local slime-category and biome-tag corrections, the dormant standard entity resource restoration, and removal of the legacy default ambient-spawner attachments; publish those pack edits under a new commit/tag before pinning automatic installs.
|
||||
- [ ] Publish and retain anonymously downloadable `beta` assets for both managed pack repositories before shipping a build that requires dual bootstrap. Runtime uses the mutable Overworld and Underworld beta release URLs; record each downloaded asset checksum for a release baseline, and move production installs to immutable release inputs when the beta streams are promoted.
|
||||
- [x] Make modded GoldenHash metadata use the active Iris engine seed. Fabric, Forge, and NeoForge generated identical output from Iris seed `1337`, but filenames and headers recorded each vanilla level seed, preventing one captured baseline file from being reused directly across loaders.
|
||||
- [x] Correct the default overworld pack's slime spawn category from implicit `MISC` to explicit `MONSTER` in `biomes/vanilla/mangrove_swamp.json`, `biomes/swamp/cambian-drift.json`, `biomes/swamp/cambian-drift-extended.json`, `biomes/swamp/marsh.json`, and `biomes/swamp/marsh-rotten.json`. NeoForge exposes the bad category at startup; all loaders generate the same bad datapack entry, which can affect natural slime spawning and mob-cap accounting.
|
||||
- [x] Extend `PackValidator` to reject authored custom-biome spawn categories that disagree with the live entity category instead of allowing the bad datapack to reach loader validation.
|
||||
|
||||
@@ -248,7 +248,7 @@ Paths relative to the loader config directory (`config/`):
|
||||
|
||||
Pack install root is `config/irisworldgen/packs`, not `config/iris`. Missing pack at world open is a hard failure with the expected absolute path (no silent vanilla terrain).
|
||||
|
||||
Async default-pack prefetch at boot when `autoDownloadDefaultPack` is set and `defaultPack` is missing (`IrisDimensions/<pack>` from `master`). Failures log a pointer to `/iris download <pack>`.
|
||||
When `autoDownloadDefaultPack` is enabled, startup asynchronously installs missing `overworld` and `underworld` managed beta releases, plus a distinct configured non-managed `defaultPack`. Failures log a pointer to `/iris download <pack>`; managed beta names always resolve to their release assets rather than the requested branch.
|
||||
|
||||
Forced datapack contributes presets, dimension types, and biomes under `irisworldgen` (ids from pack/dimension names). Regenerated on pack change / studio hotload. Failure to inject (mixin/event not applied) logs once:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user