Iris/docs/plans/2026-04-22-floating-island-shard-domain-warp.md

Floating Island Shard Domain Warp Implementation Plan

Created: 2026-04-22 Status: VERIFIED Approved: Yes Iterations: 0 Worktree: No Type: Feature

Summary

Goal: In the Iris overworld pack (primary testbed: roughplains.json), make floating island shards read as less "mathy / sharply vertical" by enabling the already-wired per-layer domain warp on the two floatingChildBiomes entries.

Architecture: IrisFloatingChildBiomes already defines wallWarpStyle + wallWarpAmplitude fields and exposes them through getWallWarpCng(...). FloatingIslandSample.sample(...) already consumes them at Iris/core/.../FloatingIslandSample.java:220-254 — for each Y layer of an island column, it offsets the footprint XZ sample by a signed 3D noise value before re-testing against footprintThreshold. This gives organic bulge/recession on the side walls without touching the tops (driven by topShapeMode=BIOME) or the bottoms (driven by bottomStyle). The current pack doesn't set wallWarpStyle, so useWarp == false and walls are a straight extrusion of the 2D footprint.

Tech Stack: Iris pack JSON (no Java changes).

---

Scope

In Scope

• Edit [Minecraft Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json.
• Add wallWarpStyle and wallWarpAmplitude to both entries in floatingChildBiomes (mushroom/forest and tropical/wilds).
• Chosen values (answers to Q1/Q2/Q3): wallWarpStyle = {"style":"SIMPLEX","zoom":0.25}, wallWarpAmplitude = 10.0. Identical on both entries.

Out of Scope

• Java source changes inside Iris/core — the warp is already wired. No FloatingIslandSample.java or IrisFloatingChildBiomes.java edits.
• Changing the schema default for wallWarpStyle from null to a non-null value — would silently change behavior for every existing pack; user explicitly chose "pack only".
• Audit of other biomes — Grep confirms floatingChildBiomes only appears in roughplains.json across the overworld pack.
• Any change to topShapeMode, bottomStyle, carveStyle, or footprintStyle (tops and bottoms already look correct).
• Code quality improvements to the warp algorithm (independent X/Z seeds, multi-octave / iq-style warp-the-warp, vertical frequency multiplier) — user declined the "code-side improvement too" option.
• TotalFixes.md entry — repo policy (AGENTS.md) says append to existing sections; will be handled during implementation as part of the DoD if the repo conventions require it.

---

Approach

Chosen: Pack-only enablement of the existing wall-warp feature.

Why: All the plumbing already exists; the missing link is pack configuration. Zero code changes means zero risk of regressing any other floating-island behavior. The user owns this test pack, so they can tune values in follow-up without a code round-trip.

Alternatives considered:

• Flip schema default of wallWarpStyle to a gentle SIMPLEX. Rejected — silently changes behavior for every existing pack/user, and the point of having the feature opt-in is that visual style is a pack-authored choice.
• Rewrite the warp in FloatingIslandSample for higher fidelity (iq-style warp-the-warp, independent X/Z noise hashes, per-axis frequency scaling). Rejected — the current single-pass 3D warp already produces perturbed walls; the author of this ticket observed that the walls look "very sharply vertical" precisely because the feature is off in this pack, not because the existing implementation is inadequate. Revisit only if enabling the feature fails to soften the walls to the user's liking.
• Per-entry tuning (mushroom gentler, tropical heavier). Rejected — user selected "same warp for both". Revisit in a follow-up if the tropical shards (thicker at 112) still read as too vertical compared to mushroom (32).

---

Context for Implementer

• Target file (ONLY file to edit): /Users/brianfopiano/Developer/RemoteGit/[Minecraft Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json
• Do not touch: any file under Iris/core/src/.... This is pack authoring, not code.
• Schema reference: Iris/core/src/main/java/art/arcane/iris/engine/object/IrisFloatingChildBiomes.java:170-176 documents wallWarpStyle and wallWarpAmplitude with accepted values, including the exact example the chosen config is based on ({"style":"SIMPLEX","zoom":0.25} for "gentle undulation"). Amplitude 10 falls between the labeled bands (@Desc line 175: "4..8 = gentle naturalization. 16+ = heavily meandering"), placing it in the lower-medium range — consistent with the user's stated Medium (~8-12 blocks) preference.
• Field type: wallWarpAmplitude is declared double (default 6.0) at IrisFloatingChildBiomes.java:176. In JSON, write 10.0 (not 10) to match the field's declared type and the existing default's literal form — Gson coerces either, but 10.0 is clearer for future pack authors comparing to the default.
• Consumer reference: FloatingIslandSample.java:220-254 — confirms that when both wallWarpStyle != null and wallWarpAmplitude > 0, the per-layer XZ warp activates. No other branch needs to be exercised.
• Field placement convention: Existing entries order properties as footprint* → picker* → altitude* → height → topShape → bottom* → maxThickness → carve* → inheritX → objectShrinkFactor. Insert the two wall-warp fields immediately after maxThickness and before carveStyle — this keeps wall-shaping modifiers grouped and matches the @Desc-style progression from coarse (footprint) → fine (carve) detail. Preserve JSON formatting (4-space indent, trailing commas only where already present).
• Gotchas:
  • JSON (not JSONC) — no comments, no trailing commas after the last key of an object.
  • Iris CNG styles are case-sensitive — use "SIMPLEX" exactly, not "simplex".
  • The file currently has two entries in floatingChildBiomes — both must be updated. The whole point of the change is symmetric behavior on both.

Domain context

• What the warp does at runtime (to guide visual verification): For each Y layer of a candidate island column, the generator computes (sx, sz) = (wx, wz) + 10 × signed_noise3d(wx, wy, wz) (X and Z offsets use decorrelated input coordinates), then re-samples the 2D footprint at (sx, sz) and re-tests against footprintThreshold. This means the horizontal silhouette of a shard can expand or contract by up to ~10 blocks per Y slice — the wall is no longer a vertical extrusion of the footprint. Zoom 0.25 makes the feature size of the warp ~25 blocks, which varies across the ~30-block CELLULAR shards enough to push each shard's silhouette into asymmetric bulges without high-frequency jitter.
• Why tops/bottoms stay clean: Tops are shaped by topShapeMode = BIOME (the target biome's own generators); bottoms by bottomStyle (CELLULAR zoom 0.3 / NOWHERE). The wall warp only perturbs the footprint test inside sample(), not the computed topY or botY — so the nicely-noised caps are untouched.

---

Runtime Environment

This is a Minecraft server plugin — there is no UI to script and no HTTP surface. Verification requires running the Minecraft server with the edited pack and inspecting a generated chunk that contains a floating island.

• Pack hot-reload: Iris supports /iris studio close + /iris studio open or /iris reload <pack> on a live server; the user's workflow memory (project_iris_floating_debug.md) confirms this is the active testbed.
• Deploy path: The pack is already under [Minecraft Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/ — editing the file in place is the deploy step (no build artifact to copy; per AGENTS.md never copy JARs into server plugin folders, but pack JSON edits are safe).
• Health check / restart procedure: Run /iris studio close in-game to close any open studio world, then /iris create <test-world> overworld (or re-open the existing studio world) so the floating child entries re-initialize. Teleport to a floating island column and visually inspect walls.

---

Assumptions

• Both floatingChildBiomes entries are intended to benefit from wall warping — supported by the user's phrasing "the shards" (plural) and Q3 choice "Same warp for both". Task 1 depends on this.
• wallWarpStyle = SIMPLEX, zoom 0.25 + wallWarpAmplitude = 10.0 lands in the lower-medium range between the @Desc labels "4..8 = gentle" and "16+ = heavily meandering" on IrisFloatingChildBiomes.java:175. Task 1 depends on this.
• Iris correctly serializes wallWarpStyle into an IrisGeneratorStyle on pack load. Supported by IrisFloatingChildBiomes.getWallWarpCng(...) reading it via getWallWarpStyle() and FloatingIslandSample:221 consuming the CNG (no reflection path or gated loader). Task 1 depends on this.
• The generator does not cache island solidity in a way that would persist pre-change results — FloatingIslandSample uses CHUNK_MEMO ThreadLocal which is cleared on each chunk build. Task 1 (verification step) depends on this; if stale chunks appear post-edit, regenerate or use a fresh world.
• No other pack files reference roughplains via snippet-inheritance that would also need edits. Supported by Grep of floatingChildBiomes returning only roughplains.json. Task 1 depends on this.

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
JSON syntax error (missing comma, wrong quote) breaks pack load	Low	Medium — pack won't load until fixed	Validate with python3 -m json.tool <file> after edit; check Iris console for load errors on server restart
Amplitude 10 on the taller tropical/wilds shards (112 thick) still reads as too vertical	Medium	Low — purely aesthetic, follow-up tune	Document in "Deferred Ideas" the fallback of bumping tropical amplitude to ~14 or adding scale-aware per-entry tuning
Warp displaces thin edge columns entirely out of the footprint, shrinking island footprint noticeably	Medium	Low — this is the desired effect but could feel over-aggressive at the edges	Amplitude 10 is moderate; if islands feel too shrunken, reduce to 6-8 on follow-up
Enabling warp adds 2 extra 3D noise samples per Y layer inside islands — perf hit on pregen	Low	Low — bounded by island coverage × max thickness; CNG samples are cheap and already-cached	No action needed; if pregen CPS regresses (see project_iris_pregen_perf.md), revisit by disabling warp on one entry
The two entries producing identical warp patterns at the same world XZ (because the warp seed mask 0xA117BA17E0FL is constant across entries) makes them look correlated	Low	Very low — entries don't spatially overlap (picker noise chooses one per column)	Mention as a known-limitation in "Deferred Ideas"; if user ever wants decorrelated warp, add a per-entry seed salt. Not in scope.

---

Goal Verification

Truths

1. wallWarpStyle and wallWarpAmplitude are set on both entries of floatingChildBiomes in roughplains.json.
2. Both entries use identical warp config: {"style":"SIMPLEX","zoom":0.25} and amplitude 10.0.
3. roughplains.json remains valid JSON (parses without error).
4. The placement of the two new keys is inside each floating entry object, adjacent to other wall/interior shaping fields (between maxThickness and carveStyle).
5. No files under Iris/core/ are modified (enforced by git diff --stat showing only the pack JSON changed, if the user is tracking the pack in git).
6. At runtime, a generated floating island in a roughplains region shows horizontal wall perturbation (bulge/recede) rather than a straight XZ extrusion of the 2D footprint. (Manual verification — see scenario MV-001 below.)

Artifacts

• [Minecraft Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json — the edit
• Iris/core/src/main/java/art/arcane/iris/engine/object/IrisFloatingChildBiomes.java:170-176 — schema source (read-only reference, not modified)
• Iris/core/src/main/java/art/arcane/iris/engine/object/FloatingIslandSample.java:220-254 — consumer source (read-only reference, not modified)

---

Manual Verification Scenarios

No browser automation path exists for a Minecraft server plugin. Scenarios are documented for the user to run in-game.

MV-001: Wall warp visually active on roughplains floating islands

Priority: Critical Preconditions: Test world generated (or fresh chunks loaded) using the overworld pack with the edited roughplains.json. Fly mode + /iris studio access. Mapped Tasks: Task 1

Step	Action	Expected Result
1	Restart the server (or /iris reload overworld) so the pack JSON is re-parsed	Iris console logs pack load with no errors mentioning wallWarpStyle or IrisFloatingChildBiomes
2	Generate or teleport to a roughplains region (Y ≥ ~180 where floating islands live)	At least one floating island column visible
3	Fly around the side of a floating island shard	Side walls show horizontal bulges/recesses as Y changes — silhouette is NOT a perfect vertical extrusion of the top outline
4	Compare top surface with earlier screenshots/observations	Top biome surface (mushroom/forest or tropical/wilds) looks the same as before — tops unchanged
5	Compare bottom tail with earlier observations	Bottom tail (dripping/roots) looks the same as before — bottoms unchanged

MV-002: Pack loads as valid JSON

Priority: Critical Preconditions: Edit applied. Mapped Tasks: Task 1

Step	Action	Expected Result
1	Run python3 -m json.tool <pack-path> from shell	Exits 0, no parse error
2	Grep the file for wallWarpStyle	Returns exactly 2 matches (one per floating entry)
3	Grep the file for wallWarpAmplitude	Returns exactly 2 matches

---

Progress Tracking

• Task 1: Enable wall warp on both floatingChildBiomes entries in roughplains.json

Total Tasks: 1 | Completed: 1 | Remaining: 0

---

Implementation Tasks

Task 1: Enable wall warp on both floating child biomes in roughplains.json

Objective: Add wallWarpStyle and wallWarpAmplitude to both entries of floatingChildBiomes in roughplains.json, identical values on both. Dependencies: None Mapped Scenarios: MV-001, MV-002

Files:

• Modify: /Users/brianfopiano/Developer/RemoteGit/[Minecraft Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json

Key Decisions / Notes:

• Insert two keys in each entry, immediately after "maxThickness": N, and before "carveStyle": { ... },.
• Exact JSON to insert (indentation matches surrounding 4-space style — one leading space for the key position based on the file's existing alignment):

"wallWarpStyle": {
    "style": "SIMPLEX",
    "zoom": 0.25
},
"wallWarpAmplitude": 10.0,

• Do this on the mushroom/forest entry (currently the block starting at line 255) AND on the tropical/wilds entry (starting at line 277).
• Do NOT reorder any existing fields.
• Do NOT add wallWarpStyle to the parent biome fields — it is per-entry on IrisFloatingChildBiomes, not on IrisBiome.
• Preserve the existing (minor) indentation quirks in the file as-is; this is a targeted additive edit.
• No performance concern — the warp adds two noise samples per Y layer inside island columns only; CNG results are cached per-entry via AtomicCache in IrisFloatingChildBiomes.

Definition of Done:

• Both floatingChildBiomes entries contain wallWarpStyle: {"style":"SIMPLEX","zoom":0.25} and wallWarpAmplitude: 10.0.
• Pre-edit sanity: grep -rl 'floatingChildBiomes' /Users/brianfopiano/Developer/RemoteGit/[Minecraft\ Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/ returns only roughplains.json (no other pack file needs the same edit).
• python3 -m json.tool <pack-path> exits 0 (valid JSON).
• grep -c 'wallWarpStyle' <pack-path> returns 2.
• grep -c 'wallWarpAmplitude' <pack-path> returns 2.
• MV-001 passes end-to-end on a live test world: side walls of roughplains floating shards exhibit horizontal bulge/recession, while tops and bottoms look unchanged from prior observation.
• No files under Iris/core/ or any other plugin source tree are modified.

Verify:

# JSON validity
python3 -m json.tool /Users/brianfopiano/Developer/RemoteGit/[Minecraft\ Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json > /dev/null

# Field counts
grep -c 'wallWarpStyle' /Users/brianfopiano/Developer/RemoteGit/[Minecraft\ Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json
grep -c 'wallWarpAmplitude' /Users/brianfopiano/Developer/RemoteGit/[Minecraft\ Server]/consumers/plugin-consumers/shared-plugin-data/iris/packs/overworld/biomes/temperate/roughplains.json

Then MV-001 via manual in-game verification on the user's running test server.

---

Deferred Ideas

• Per-entry scale-aware tuning: If the tropical/wilds shards (112 thick) still read as too vertical compared to mushroom/forest (32 thick), bump tropical's wallWarpAmplitude to ~14 while leaving mushroom at 10.
• Per-entry warp decorrelation: Both entries currently sample wallWarp noise from the same RNG mask (0xA117BA17E0FL in IrisFloatingChildBiomes:81). Entries never spatially overlap (the picker routes each column to exactly one), but if visually noticeable correlation ever appears where biomes are adjacent, add a per-entry seed salt.
• Higher-fidelity warp (iq-style): Chain a second noise sample: P' = P + A·n1(P); P'' = P' + B·n2(P'); then sample footprint at P''. Only pursue if the single-pass warp is not expressive enough after Task 1 is tuned.
• Vertical frequency scaling: Expose a wallWarpVerticalScale so the warp varies faster with Y than with XZ — would make adjacent Y slices more different, reducing any residual vertical banding without changing horizontal feature size.
• Schema default flip: Changing IrisFloatingChildBiomes.wallWarpStyle default from null to a gentle SIMPLEX. Out of scope this plan; would silently change behavior for any existing pack.