Define writing and symbol data model (#17 )

Describe your changes
Complete Milestone 3 documentation (#12 )
2026-09-23 14:24:40 -04:00 · 2026-09-23 06:30:15 -04:00 · 2026-09-23 05:51:59 -04:00 · 2026-09-23 05:41:38 -04:00 · 2026-09-23 02:44:02 -04:00 · 2026-09-23 02:15:39 -04:00
46 changed files with 1644 additions and 520 deletions
@@ -0,0 +1,27 @@
 ---
 name: Bug report
 about: Incorrect behavior or a regression in Rivencraft
 title: ""
 labels: type/bug
 assignees: ""
 ---
 ## Observed behavior
 Describe what happened, including the dimension, book type, preview mode, and
 installed optional mods when relevant.
 ## Expected behavior
 Describe what should have happened.
 ## Reproduction
 1. List the minimum steps needed to reproduce the problem.
 2. Include the Rivencraft, NeoForge, and optional-mod versions.
 3. Attach the relevant log or crash report.
 ## Acceptance criteria
 - [ ] The reproduction no longer fails.
 - [ ] A focused regression check covers the corrected behavior when practical.
@@ -0,0 +1,21 @@
 ---
 name: Implementation task
 about: A scoped feature, refactor, compatibility, or documentation task
 title: ""
 labels: type/feature
 assignees: ""
 ---
 ## Goal
 Describe the behavior or outcome this task should deliver.
 ## Acceptance criteria
 - [ ] Add observable acceptance criteria.
 - [ ] Cover persistence, migration, or compatibility when applicable.
 - [ ] Record the validation required before closing the issue.
 ## Context
 Link related issues, upstream references, and relevant design constraints.
@@ -4,10 +4,12 @@ Rivencraft is a clean, incremental port of the ideas and gameplay of
 [Mystcraft Legacy](https://github.com/Mystcraft/Mystcraft-Legacy) to Minecraft
 1.21.1 on NeoForge.
-The bootstrap and books/linking milestones are complete. The project currently
+The bootstrap, books/linking, and Ages milestones are complete. Milestone 4 is
-provides functional Linking Books and randomly seeded, persistent vanilla-like
+building the writing system on a data-pack symbol catalog and persistent
-Ages created from page-free Descriptive Books. Symbols, instability, and the
+ordered-writing model. The project currently provides functional Linking Books
-full writing mechanics have not been ported yet.
+and randomly seeded, persistent vanilla-like Ages created from page-free
 Descriptive Books. Instability and full symbol-to-world grammar interpretation
 have not been ported yet.
 ## Linking Book
@@ -60,6 +62,10 @@ according to the configured Return Link policy.
 Server owners can set `descriptive_books.return_link_mode` in Rivencraft's
 server config to `ON_CREATION` (default), `ALWAYS`, or `DISABLED`.
 Age creation, persistence, lifecycle commands, configuration, backups, and
 administrator recovery are documented in [docs/AGES.md](docs/AGES.md).
 Data-pack runtime profiles are documented in
 [docs/AGE_PROFILES.md](docs/AGE_PROFILES.md).
 ## Requirements
@@ -77,6 +83,9 @@ view. Without either integration, Rivencraft uses its built-in animated linking
 panel. Clients can set `book_preview.mode` in
 `rivencraft-client.toml` to `AUTO`, `IMMERSIVE_PORTALS`, `PONDER`, or `LEGACY`.
 Unavailable optional renderers safely fall back to `LEGACY`.
 The complete backend matrix, supported combinations, cleanup behavior, and
 known upstream limits are documented in
 [docs/PREVIEW_COMPATIBILITY.md](docs/PREVIEW_COMPATIBILITY.md).
 ## Build and run
@@ -107,8 +116,8 @@ Mystcraft Legacy targets Forge for Minecraft 1.12.2. Rivencraft therefore
 ports one subsystem at a time onto current registries, codecs, data packs, and
 NeoForge APIs instead of importing the legacy source tree wholesale.
-See [docs/PORTING.md](docs/PORTING.md) for the initial roadmap and provenance
+See [docs/PORTING.md](docs/PORTING.md) for the roadmap, live Gitea tracking
-rules.
+links, architectural direction, and provenance rules.
 ## License
@@ -0,0 +1,109 @@
 # Age creation and administration
 ## Creation
 A page-free Descriptive Book creates an Age when the player assigns a name and
 presses **Create**. Rivencraft immediately assigns a UUID, derives a unique
 Minecraft-safe dimension identifier from the requested name, rolls a seed and
 traits, and persists that definition before asking Dynamic Dimensions to create
 the runtime world. Names that normalize to the same identifier receive stable
 suffixes such as `_2` and `_3`.
 The selected terrain profile, biome distribution, lighting, weather, celestial
 period, celestial angle, and phase are deterministic and become part of the
 saved definition. A five-by-five cobblestone platform with clear headroom is
 prepared at a safe arrival point. The completed book and every copy carrying
 the same UUID resolve to that definition.
 Creating an Age can take several ticks. The book cannot be reopened while its
 creation request is active. If creation is interrupted after the definition is
 saved, using the book again resumes from the same immutable definition instead
 of rolling a replacement.
 ## Persistence
 Rivencraft owns each Age definition for the lifetime of a world. A definition
 contains the Age UUID, canonical name, seed, generation version, runtime
 dimension identifier, spawn, and deterministic traits. Definitions are stored
 in the Overworld saved data and are never rerolled during ordinary loading.
 Runtime terrain and entity data remain in the normal world dimension storage
 managed by Minecraft and Dynamic Dimensions. Back up the complete world folder
 while the server is stopped; copying only a dimension folder does not preserve
 the authoritative Age registry.
 ## Lifecycle
 An Age definition is created before its runtime dimension. If dimension
 creation is interrupted, the saved definition remains authoritative and the
 same Age is reconstructed the next time its Descriptive Book is used.
 Registered Ages load when the server starts. A book also loads its destination
 on demand when an administrator previously unloaded it. Unloading retains the
 definition and world folder, so existing books continue to reference the same
 Age and later reload the same terrain.
 Rivencraft does not automatically delete Ages. Safe permanent deletion needs a
 complete reference index for books in inventories, containers, Book Stands,
 and unloaded chunks. Until that exists, retaining the definition prevents an
 administrator action from silently orphaning books.
 Destination-preview chunk loaders are temporary. Rivencraft releases them when
 the book closes, the player travels, the player disconnects, the destination
 Age is unloaded, or the server stops.
 ## Commands
 The commands require permission level 2.
 - `/rivencraft age list` lists every registered Age and whether its runtime
  dimension is currently loaded.
 - `/rivencraft age unload <dimension>` safely unloads one Age. Players in that
  Age are handled by Dynamic Dimensions, and its definition and world data are
  retained. Use the command suggestions to select a registered dimension.
 Opening a Descriptive Book for an unloaded Age loads it again from its saved
 definition.
 ## Configuration
 Rivencraft writes gameplay settings to the world/server configuration managed
 by NeoForge. `descriptive_books.return_link_mode` accepts:
 - `ON_CREATION` (default): create one Return Link the first time a player
  enters each Age.
 - `ALWAYS`: create a Return Link after every successful Descriptive Book trip.
 - `DISABLED`: never create Return Links automatically.
 Each client has a separate `rivencraft-client.toml`. Its `book_preview.mode`
 setting accepts `AUTO`, `IMMERSIVE_PORTALS`, `PONDER`, or `LEGACY`. This changes
 only presentation and cannot change server-side Age generation or travel
 validation. See [PREVIEW_COMPATIBILITY.md](PREVIEW_COMPATIBILITY.md) for the
 selection matrix and integration limits.
 Runtime generation profiles are server data-pack resources. Their schema,
 override rules, reload behavior, and deterministic fallback are documented in
 [AGE_PROFILES.md](AGE_PROFILES.md).
 ## Administrator recovery
 Use this sequence when a book cannot load an existing Age:
 1. Stop the server and make a copy of the complete world folder.
 2. Start the server and run `/rivencraft age list`. Confirm that the expected
   canonical name and dimension identifier remain registered.
 3. If the Age is listed as unloaded, open its Descriptive Book to reload it.
   This keeps the UUID, seed, profile, traits, and existing world folder.
 4. If a data-pack profile is missing or invalid, restore or repair that pack,
   run `/reload`, then unload and reopen the Age. A removed custom profile uses
   the deterministic `rivencraft:standard` fallback and logs the substitution.
 5. If the definition is missing, restore the complete world backup. Moving a
   dimension folder into another world cannot reconstruct its UUID or books.
 6. If the definition exists but its dimension data is damaged, restore the
   matching dimension data and authoritative world saved data from the same
   backup generation. Do not combine them from different backups.
 There is intentionally no delete command in Milestone 3. Do not manually
 delete an Age definition or rename its dimension folder: books may exist in
 inventories, containers, Book Stands, or unloaded chunks, and would be
 orphaned. `/rivencraft age unload` is the supported reversible maintenance
 operation.
@@ -0,0 +1,50 @@
 # Age runtime profiles
 Rivencraft loads Age runtime profiles from server data packs at
 `data/<namespace>/rivencraft/age_profiles/<name>.json`. The resulting profile ID
 is `<namespace>:<name>`. Profiles select registered world-generation resources;
 they do not contain an Age's seed, name, spawn, or rolled traits.
 ## Schema version 1
 ```json
 {
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:overworld",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
 }
 ```
 `terrain` is `noise`, `flat`, or `void`. Noise profiles require
 `noise_settings` and `biome_preset` references. Every profile requires a
 `dimension_type` reference. Omitted resource references use the Overworld
 entry. Rivencraft validates all referenced entries against the loaded dynamic
 registries during data-pack reload. An invalid profile is rejected.
 The built-in profile IDs are `rivencraft:standard`, `amplified`, `island`,
 `cave`, `flat`, and `void`. Their JSON files are ordinary built-in data-pack
 resources and can be overridden by a higher-priority pack. The example under
 `docs/example-age-profile-pack` can be copied into a world's `datapacks`
 directory. Valid custom profiles join the stable, sorted pool used when a new
 Age rolls its base terrain; the selected ID is then persisted with that Age.
 ## Persistence and reload behavior
 An Age permanently stores its selected profile ID, generation version, seed,
 and rolled traits. `/reload` replaces the profile definitions but does not
 reroll those immutable values. An unloaded Age resolves its stored profile
 again when it loads, so intentional profile overrides affect its runtime
 resources and newly generated chunks.
 A profile removed after an Age was created resolves to `rivencraft:standard`.
 The legacy `rivencraft:random_vanilla` alias also resolves to `standard`.
 Rivencraft logs this fallback. Invalid built-in overrides do not replace the
 required built-in definitions; a reload fails if a required built-in profile
 is absent after resource resolution.
 Only schema version 1 is accepted. A future schema change must add an explicit
 migration path before incrementing the version. The saved Age generation
 version remains independent of this data-pack schema and is never silently
 rewritten.
@@ -1,454 +1,85 @@
-# Porting plan
+# Porting roadmap
-Mystcraft Legacy contains more than 700 Java source files and targets Minecraft
+Rivencraft ports Mystcraft Legacy from Minecraft 1.12.2 to NeoForge 1.21.1.
-1.12.2. The Minecraft world-generation, dimension, registry, networking, and
+The world-generation, dimension, registry, networking, and rendering APIs have
-rendering APIs have all changed substantially since that release. The port is
+changed substantially, so the work is divided into independently testable
-split into independently testable milestones.
+milestones.
 ## Project tracking
 Gitea is the source of truth for project status:
 - [Issues](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/issues) contain
  scoped implementation tasks, bugs, acceptance criteria, and technical
  discussion.
 - [Milestones](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/milestones)
  group issues into the porting phases below and show their live completion
  state.
 - [Releases](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/releases)
  contain user-facing changelogs for shipped versions.
 New work should have an issue before implementation begins. Commits should
 reference the issue number when practical. A milestone closes only after its
 acceptance issue and all required implementation issues are complete.
 ## Milestones
 1. **Bootstrap** — NeoForge 1.21.1 build, mod metadata, item registration, and
   CI. **Complete.**
-2. **Books and linking** — descriptive/linking book data components, lectern-like
+2. **Books and linking** — Descriptive and Linking Book data, Book Stands,
-   interaction, safe teleportation, and return links. **Complete.**
+   safe teleportation, return links, book screens, and destination previews.
-3. **Ages** — dimension definitions backed by data packs, deterministic seeds,
+   **Complete.**
-   lifecycle management, and persistence. Make the legacy-style animated
+3. **Ages** — persistent generated dimensions, deterministic traits,
-   linking panel the built-in destination preview. Provide optional
+   lifecycle management, data-pack integration, and optional destination
-   Create/Ponder and Immersive Portals integrations as alternative rotating-
+   renderer compatibility. **Complete.** See
-   snapshot renderers. The configurable preview modes are `AUTO`,
+   [Milestone 3](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/milestone/8).
   `IMMERSIVE_PORTALS`, `PONDER`, and `LEGACY`; `AUTO` prefers Immersive
   Portals when it is installed, then Create/Ponder, and finally the built-in
   legacy animation.
 4. **Writing system** — pages, symbols, notebooks, desks, and book assembly.
   **In progress.**
 5. **Age grammar** — translate symbol combinations into modern biome, noise,
-   dimension-type, and worldgen configuration. Optional integrations with
+   dimension-type, and world-generation configuration. Optional integrations
-   TerraBlender provide composable biome-region generation, while Serene
+   may add composable biome regions and seasonal behavior.
-   Seasons and Ecliptic Seasons allow Age generation to participate in their
+6. **Instability** — deterministic validation and server-safe effects.
   respective seasonal systems. True Always Snow weather will be introduced
   with these season integrations; until then, its persisted trait uses
   biome-dependent precipitation. None of these integrations are required for
   Rivencraft's core world generation.
 6. **Instability** — deterministic validation and effects with server-safe
   behavior.
 7. **Structures and polish** — libraries, crystals, portals, recipes, models,
   sounds, advancements, compatibility, and migration tests.
 ## Architectural direction
 Age references use UUIDs rather than dimension keys. The server-owned Age
 registry maps each stable identity to its immutable definition and runtime
 dimension, keeping saved books valid if an Age is migrated or regenerated.
 Operational lifecycle and unload behavior are documented in
 [AGES.md](AGES.md). The server data-pack schema for runtime generation is
 documented in [AGE_PROFILES.md](AGE_PROFILES.md).
 The core mod must remain usable without Create, Ponder, or Immersive Portals.
 The built-in legacy animation is the dependency-free destination preview.
 Optional preview modes may use Create/Ponder snapshots or Immersive Portals
 live rendering when their dependencies are installed. The tested selection
 matrix and integration boundaries are documented in
 [PREVIEW_COMPATIBILITY.md](PREVIEW_COMPATIBILITY.md).
 The writing system and Age grammar will build on the existing page-free Age
 path. Page-free books remain a useful deterministic fallback and test fixture
 after written symbol combinations become available.
 Milestone 4 begins with a versioned, data-pack-defined symbol catalog and an
 immutable ordered-writing model. See [WRITING_DATA.md](WRITING_DATA.md). These
 contracts preserve unknown symbol identifiers and store author intent; they do
 not interpret symbols into Age generation, which remains Milestone 5 work.
 ## Provenance rules
 - New code uses the `net.dnorberg.rivencraft` package.
- Adapted Mystcraft code must retain its upstream copyright notice and be
+- Adapted Mystcraft code retains its upstream copyright notice and is tracked
-  tracked in this document or a nearby source comment.
+  in a nearby source comment or commit.
- Do not copy generated, binary, or third-party dependency content from the
+- Generated, binary, and third-party dependency content is not copied from the
  legacy repository.
- Preserve LGPL-3.0-or-later compatibility for the complete distributed mod.
+- The complete distributed mod remains compatible with LGPL-3.0-or-later.
-## First vertical slice
+## Release policy
-The first functional target is: create a Descriptive Book, bind it to one
+The version scheme is documented in the project README. Every published
-server-managed Age definition, travel to that Age, and use a Linking Book to
+version receives a Gitea release containing its changelog, built mod JAR, and
-return. This exercises persistence, networking, dimensions, and safety before
+SHA-256 checksum. Release notes describe user-visible behavior, compatibility
-the symbol grammar is introduced.
+changes, migrations, and validation performed for that version; ongoing task
-
+notes stay in issues.
 ### Milestone 2 progress
 - [x] Persistent, network-synchronized link-target data component.
 - [x] Linking Book binding with dimension, block position, yaw, and pitch.
 - [x] Server-authoritative cross-dimension travel with world-border, collision,
  and fluid checks.
 - [x] Nearby landing search and clear failure messages.
 - [x] Descriptive Book identity and Age reference components.
 - [x] Temporary vanilla-dimension Descriptive Book travel with return-link creation.
 - [x] Lectern-to-Book-Stand conversion, displayed book, activation, removal,
  persistence, and drops.
 - [x] Book-screen foundation with server-authoritative naming, binding, and
  explicit link activation.
 - [x] Ponder dependency and isolated destination-preview level boundary.
 - [x] Server-provided destination snapshots rendered as rotating Ponder scenes.
 - [x] Book Stand floating names synchronized from the stored book stack.
 - [x] Open the stored book screen from a Book Stand with server-validated linking.
 - [x] Automated in-game tests for binding, persistence, and travel.
 The temporary shapeless Linking Book recipe makes the linking subsystem easy
 to test. It can move into the writing/bookbinder progression when that system
 is implemented.
 Age references use UUIDs rather than dimension keys. Milestone 3 will own the
 mapping from that stable identity to server data and a runtime dimension. This
 keeps saved books valid if an Age is migrated or regenerated.
 Vanilla lecterns accept extensible item tags when inserting books, but their
 block entity still validates only vanilla writable and written books. To avoid
 an invalid lectern state, inserting a Rivencraft book converts the lectern into
 a visually compatible Rivencraft Book Stand. Removing the book converts it
 back.
 Mystcraft Legacy did not impose an item cooldown when linking. Rivencraft's
 initial cooldown used Minecraft's item-type cooldown system, which delayed all
 Linking Book stacks at once. Version 0.1.3 removes that cooldown to match the
 legacy behavior.
 Version 0.1.4 moves Linking Book binding and travel behind a book screen. The
 client requests an action, while the server revalidates the held book and owns
 all changes to its destination and custom name. Descriptive Book Age references
 now carry a display name alongside their stable UUID, with backward-compatible
 decoding for existing UUID-only data.
 Version 0.1.5 ensures the book interaction listener opens screens only for the
 logical-client event. This avoids calling the render system from the integrated
 server thread when a book is used in singleplayer.
 Version 0.1.6 gives the Linking Book screen an open-book layout inspired by the
 legacy interface. The destination preview occupies the left page, the book name
 and destination details occupy the right page, and the preview itself is the
 link action; the separate Link and Done buttons have been removed.
 Version 0.1.7 suppresses Minecraft's default full-screen menu blur for the
 Linking Book screen. The open-book texture supplies the GUI background while
 the world remains sharp behind it.
 Version 0.1.8 renders all Linking Book destination details in the same dark ink
 color as the book name for consistent contrast against the parchment.
 Version 0.1.9 synchronizes the Book Stand's stored stack to clients and renders
 its display name as a camera-facing label above the book.
 Version 0.1.10 corrects the nameplate transform and matches Minecraft's normal
 plus see-through text passes so angled stand geometry cannot hide the label.
 Version 0.1.11 opens the stored book interface when a Book Stand is used with
 an empty hand. Linking Books travel through the preview panel, and the server
 revalidates the stand position, interaction distance, stored item, and target.
 Version 0.1.12 replaces the Linking Book screen's convenience text draws with
 explicit no-shadow rendering for clearer dark ink on the parchment texture.
 Version 0.1.13 requests a bounded, server-validated 9-by-7-by-9 block snapshot
 from the held book or nearby Book Stand and renders it as a clipped, rotating
 Ponder world section on the Linking Book's left page.
 Version 0.1.14 expands the destination snapshot to 9-by-7-by-17 blocks along
 the Z axis, rescales the rotating scene to expose that depth, and colors the
 panel background with the destination biome's sky color.
 Version 0.1.15 adds three dedicated-server GameTests covering Linking Book
 component serialization, successful safe travel with restored orientation, and
 rejection of fully blocked destinations. The test suite uses a minimal bundled
 structure template and runs with `./gradlew runGameTestServer`.
 Version 0.1.16 makes destination previews sample a centered 17-by-7-by-17
 volume. The Ponder scene uses a scale that keeps its full horizontal diagonal
 inside the panel, so the complete snapshot remains available during its orbit.
 Version 0.1.17 changes destination previews to a 9-by-128-by-9 volume: a
 square horizontal footprint with a vertical slice spanning 64 blocks below and
 63 blocks above the recorded linking location.
 Version 0.1.18 changes the preview cache to 9-by-64-by-9, spanning 32 blocks
 below and 31 above the link point. Its camera is centered on a 9-by-7-by-9
 window around the link point so the book retains a readable close-up.
 Version 0.1.19 renders the complete 9-by-64-by-9 snapshot in that Ponder
 scene while retaining the target-centered camera framing.
 Version 0.1.20 uses a cubic 18-by-18-by-18 snapshot. The renderer remaps the
 link point within that cube so its existing target-centered camera framing is
 unchanged.
 Version 0.1.21 treats air and leaf blocks as passable linking destinations;
 links no longer require a solid floor beneath the player.
 Version 0.2.0 completes Milestone 2. Until Milestone 3 provides generated Age
 dimensions, Descriptive Book UUIDs deterministically resolve to vanilla
 dimensions and create a bound Return Link to the source on successful travel.
 Version 0.2.1 gives Descriptive Books the same open-parchment layout and
 left-page link interaction as Linking Books.
 Version 0.2.2 adds the same server-provided Ponder destination preview to
 Descriptive Books. If no snapshot is available, the left page shows an
 animated linking-panel fallback.
 Version 0.2.3 requires Descriptive Book destinations to have a sturdy floor,
 while Linking Books continue to permit passable floorless destinations.
 Version 0.2.4 expands Descriptive Book arrival validation with an outward,
 terrain-aware search for an alternate grounded location near an unsafe target.
 Version 0.2.5 uses dimension-appropriate preview skies for vanilla Nether and
 End destinations instead of their inherited Overworld biome sky tint.
 Version 0.2.6 expands destination snapshots to a 32-by-32-by-32 cube while
 keeping the existing target-centered Ponder camera position.
 Version 0.2.7 persists each Age's first successful visit and creates its
 Return Link only for that initial arrival.
 Version 0.2.8 makes Return Link creation a server setting: `ON_CREATION`
 (default), `ALWAYS`, or `DISABLED`.
 Version 0.2.9.0 begins Milestone 3 with a server-owned, world-persistent Age
 registry. Each Age UUID resolves exactly once to an immutable random seed,
 generation profile, generation-version marker, canonical name, and creation
 time. The temporary vanilla-dimension adapter remains in place until runtime
 Age dimensions are introduced by a later release slice.
 Version 0.2.10.0 makes page-free Descriptive Books playable. Naming an
 unwritten book creates a dedicated, persistent vanilla-like Age through the
 Dynamic Dimensions API. Each Age reloads with its server, retains its terrain,
 and receives a five-by-five cobblestone platform with cleared arrival headroom.
 Version 0.2.10.1 improves Age arrival placement. Non-Nether Ages select the
 highest sturdy surface near the origin and fall back to a platform at Y=63 when
 no suitable natural footing exists.
 Version 0.2.10.2 allows leaf blocks to count as proper natural footing when
 selecting the highest arrival surface.
 Version 0.2.10.3 scans each candidate column downward from the dimension's top
 before choosing footing, preventing cave floors from being selected as the Age
 arrival surface. Columns covered by fluid remain ineligible.
 Version 0.2.10.4 restores Mystcraft Legacy's standard linking sound for both
 Linking and Descriptive Books. Successful travel plays the sound at its source
 and destination with the legacy volume and pitch variation.
 Version 0.2.10.5 derives each new Age's saved dimension folder from its
 player-assigned name. Names are converted to safe lowercase resource paths,
 and folder conflicts receive `_2`, `_3`, and later numeric suffixes. Existing
 UUID-based dimension folders remain unchanged for save compatibility.
 Version 0.2.10.6 prevents a Descriptive Book from reopening while its Age is
 being generated. Screen opening now waits for the server's current copy of the
 held or displayed book, so a delayed interaction opens only the completed Age.
 Version 0.2.11.0 adds a dependency-free, legacy-style portal bloom as the
 fallback destination preview for Linking and Descriptive Books. Clients with
 Create installed retain the rotating Ponder snapshot; clients without Create
 use the destination-tinted animation with the original effect's paired noisy
 spirals.
 Version 0.2.11.1 makes Create genuinely optional. Ponder remains a compile-time
 API for the Create integration, while generated mod metadata no longer requires
 Ponder and marks Create as an optional client dependency.
 Version 0.2.12.0 introduces the first legacy-inspired Age generator profiles.
 New page-free Ages deterministically select and persist Standard, Amplified,
 Island, Cave, Flat, or Void base terrain. Existing `random_vanilla` Ages remain
 mapped to their original Overworld generator for save compatibility. Terrain
 alterations such as Skylands, Tendrils, Spheres, and Floating Islands remain
 future Age-grammar work layered above these base profiles.
 Version 0.2.12.1 displays the persisted terrain generator on the description
 side of written Descriptive Books. Newly written books receive the synchronized
 profile immediately, while older books are backfilled from the server-owned Age
 registry when opened.
 Version 0.2.13.0 constructs Standard, Amplified, Cave, and Island terrain from
 Minecraft's worldgen registries instead of borrowing generator instances from
 the vanilla levels. Noise settings and biome-source parameter lists therefore
 honor the server's loaded data packs. Automated coverage also verifies that a
 live Age's seed equals its immutable saved definition; Dynamic Dimensions
 derives both from the Overworld seed and the Age dimension identifier.
 Version 0.2.16.13 gives Cave and Island/Skylands Ages Overworld biomes, sky,
 weather, lighting, and day/night behavior while retaining distinct terrain.
 Caves remain enclosed. Skylands use Minecraft's uniform floating-island noise
 and Overworld-like surfaces without the End's central dragon island.
 Version 0.2.16.14 replaces the Explore text control with a compact eye symbol.
 Books opened from a Book Stand display the control disabled, preventing
 exploration while the book is mounted.
 Version 0.2.16.15 restores Immersive Portals chunk loading for snapshots opened
 from Book Stands. Snapshot chunk loading is independent from whether the Explore
 control is enabled, so mounted books retain live terrain without allowing the
 player to enter Explore mode.
 Version 0.2.17.0 begins persistent random Age traits. New page-free Ages select
 and save a legacy-inspired biome distribution, lighting mode, weather mode, and
 celestial period, angle, and phase. The celestial ranges follow Legacy's random
 symbol fallbacks: period 0.2–2.0, angle 0–360 degrees, and phase 0–1. Existing
 Ages load with normal Legacy defaults instead of being rerolled. This immutable
 trait layer is the foundation for applying each choice to modern worldgen.
 Version 0.2.18.0 applies each Age's persisted lighting trait to its runtime
 dimension. Normal Lighting retains Overworld skylight and ambient brightness;
 Bright Lighting uses Legacy's 0.25 ambient-light floor; Dark Lighting disables
 dimension skylight while retaining local block light. The latter is the closest
 server-safe modern equivalent to Legacy's removed per-dimension light-table
 scaling hook.
 Version 0.2.18.1 prevents Cave Ages from choosing a spawn on their upper roof.
 Their grounded arrival search now begins with the floor below player Y=64 and
 works downward. If it finds no suitable footing, the existing floor-Y=63
 platform fallback places the player at Y=64.
 Version 0.2.19.0 applies persisted weather traits to loaded Ages. Normal uses
 Minecraft's normal weather cycle. Fast and Slow use Legacy's original duration
 and cooldown ranges at half and double normal speed for Minecraft's combined
 rain/thunder weather timer. Off keeps an Age clear;
 Always, Cloudy, Rain, and Snow maintain non-thundering precipitation; Storm
 maintains rain and thunder. Minecraft still chooses rain versus snow from biome
 temperature, so dedicated Snow/Rain biome overrides remain future work.
 Version 0.2.20.0 applies persisted celestial timing to each Age. The saved
 period controls NeoForge's per-dimension clock rate, with a period of 1 matching
 a vanilla 20-minute day, 0.2 running five times faster, and 2 running at half
 speed. The saved phase sets the clock only during first-spawn initialization;
 later loads continue from saved world time. Celestial angle remains persisted
 for a future custom sky renderer because vanilla dimension data cannot rotate
 the sun's render plane.
 Version 0.2.20.1 restores Legacy's Zero Length celestial modifier as a rarer
 random outcome using its effective one-in-seven grammar weight. Zero Length
 freezes an Age at its generated phase without changing the global daylight
 cycle, while nonzero Ages retain their independently scaled clocks.
 Version 0.2.20.2 gives Zero Length Ages a stationary per-dimension clock rate
 instead of advancing and correcting their time once per tick. This keeps the
 integer day time fixed while preventing the client skybox from visually
 bouncing between adjacent celestial positions.
 Version 0.2.21.0 begins applying persisted biome-distribution traits. Native
 Distribution retains Minecraft's data-pack-aware Overworld climate source.
 Single Biome Distribution deterministically selects one registered biome from
 the Age seed and uses it throughout compatible noise-based terrain. Flat and
 Void profiles retain their profile-specific biome sources. Legacy's scaled,
 tiled, and grid layouts require dedicated modern biome sources and remain the
 next distribution work.
 Version 0.2.21.1 changes Cave Ages from Nether noise settings to Minecraft's
 cave noise settings. Caves remain enclosed, but use stone, water, and
 Overworld-like surfaces together with the persisted Native or Single biome
 distribution. This prevents Nether terrain generation from leaking into newly
 generated Cave Age chunks.
 Version 0.2.22.0 applies Tiled Biome Distribution using two deterministic
 Age-seeded biomes in the legacy diagonal-checkerboard layout. Each square is
 16 chunks (256 blocks) wide, matching Mystcraft Legacy's coordinate shift, and
 uses Minecraft's serializable checkerboard biome source so the layout remains
 stable across server reloads.
 Version 0.2.22.1 includes the server-owned Age traits in the validated
 Descriptive Book screen response and displays the terrain, biome distribution,
 lighting, weather, day length, celestial angle, and celestial phase on the
 book's right-hand description page. This works for held books and Book Stands
 without copying mutable Age-generation data onto the item.
 Version 0.2.23.0 applies Grid Biome Distribution using two deterministic
 Age-seeded biomes in Legacy's diagonal checkerboard layout. Each cell is one
 16-by-16-block chunk, and the built-in serializable biome source reconstructs
 the same layout whenever the Age reloads.
 Version 0.2.24.0 applies Tiny Biome Distribution using three deterministic
 Age-seeded biomes and softly bounded seeded regions. Tiny begins at Legacy's
 smallest 16-block nominal scale; the serializable biome source retains its
 seed, selected biomes, and scale across Age reloads.
 Version 0.2.25.0 completes the scaled biome distributions. Small, Medium,
 Large, and Huge reuse Tiny's seeded, softly bounded regions at nominal widths
 of 32, 64, 128, and 256 blocks. Every size selects three deterministic biomes
 and serializes the selection, Age seed, and scale with the runtime dimension.
 Version 0.2.25.1 applies biome-specific material rules without replacing an
 Age's selected terrain profile. End biome columns generate from End stone;
 Nether biome columns use Minecraft's Nether surface rules for netherrack,
 soul sand, basalt, and nylium instead of inheriting Overworld blocks.
 Version 0.2.26.0 applies each Age's persisted celestial angle to the client
 sky. The sun, moon, and stars follow a plane rotated by the saved Legacy-style
 angle in normal gameplay and Immersive Portals previews, while vanilla
 dimensions retain their standard celestial path.
 Version 0.2.26.1 rotates the celestial path around the world's vertical axis,
 allowing the saved angle to change each Age's sunrise and sunset compass
 direction instead of merely tilting the rendered path.
 Version 0.2.14.0 restores the legacy Linking and Descriptive Book artwork for
 inventory items and gives each book its matching open-book texture when placed
 on a Book Stand. Return Linking Books created inside another Age also retain and
 display that Age's saved name instead of exposing its dimension identifier.
 Version 0.2.14.1 gives every newly bound Linking Book a friendly destination
 label. Standard books and Return Links use saved Age names inside Rivencraft
 Ages and the familiar Overworld, The Nether, and The End names in vanilla
 dimensions. Existing vanilla links receive the same presentation at display
 time without requiring item migration.
 Version 0.2.15.0 adds the client-side book-preview mode configuration and the
 selection policy for `AUTO`, `IMMERSIVE_PORTALS`, `PONDER`, and `LEGACY`.
 `AUTO` uses Ponder when Create is present and otherwise uses the built-in
 legacy animation. Explicit optional modes fall back to `LEGACY` when their
 renderer is unavailable.
 Version 0.2.16.0 implements the optional Immersive Portals GUI renderer. Its
 default view orbits the live destination like the Ponder snapshot. The Explore
 control switches to a movable remote camera using movement keys and mouse drag;
 right-click resets the camera and restores the passive book GUI. A validated
 per-player chunk loader exists only while the screen is open and is released
 on close. `AUTO` now prefers Immersive Portals, then Ponder, then `LEGACY`.
 Version 0.2.16.1 corrects Immersive Portals detection to use its NeoForge mod
 ID, `immersive_portals_core`. Rivencraft now also refreshes Immersive Portals'
 integer dimension map whenever saved or newly created Ages are loaded, before
 their chunks can be synchronized to a player.
 Version 0.2.16.2 routes book travel through Immersive Portals' seamless
 teleport API when that mod is installed, preserving its client-world registry
 during links between Ages and vanilla dimensions. The Explore control is also
 positioned fully below the live snapshot window on both book screens.
 Version 0.2.16.3 restores the full window viewport immediately after drawing
 an Immersive Portals snapshot. Book titles, destination details, and controls
 therefore render in their normal page positions instead of being compressed
 inside the snapshot rectangle.
 Version 0.2.16.4 clears the Immersive Portals GUI framebuffer between remote
 world renders, preventing moving camera frames from accumulating into a sky
 smear. The framebuffer now follows Immersive Portals' shared-target lifecycle
 so a queued end-of-frame render cannot target a texture destroyed on GUI close.
 Version 0.2.16.5 expands live-preview chunk loading to Immersive Portals'
 reference eight-chunk radius. Rivencraft prepares the central 3x3 destination
 chunks and requests an immediate tracking update when the GUI opens, providing
 terrain for the first useful snapshot while the remaining chunks stream in.
 Version 0.2.16.6 makes Linking and Descriptive Book screens non-pausing. The
 integrated server now continues ticking in single-player while a book is open,
 allowing live preview chunks to generate and stream into the snapshot.
 Version 0.2.16.7 handles configured movement bindings directly in both book
 screens while Explore mode is active. Movement, jump, and sneak now move the
 remote camera even though Minecraft suspends normal gameplay key states while
 a GUI is open.
 Version 0.2.16.8 links Explore mode to real player movement in the current
 dimension. Entering Explore anchors the source player and destination camera;
 walking, jumping, falling, or being moved shifts the snapshot camera by the
 same displacement while the book remains open and normal collision still
 applies.
 The preview code is separated behind a renderer interface and uses an isolated
 Ponder level populated from server-authoritative destination snapshots.
 ## Version policy
 Versions follow `x.y.z.b`:
 - `x`: major release point.
 - `y`: number of completed milestones.
 - `z`: release slice within the active milestone.
 - `b`: bug-fix and additional-work iteration within that release slice.
 Starting a release slice increments `z` and resets `b` to zero. Completing a
 milestone increments `y` and resets both `z` and `b` to zero. The first
 milestone-2 slice is therefore `0.1.1.0`; a fix on that slice is `0.1.1.1`;
 and milestone 2 completion is `0.2.0.0`.
 ## Milestone 1 acceptance record
 - The project builds on a Java 21 JDK with `./gradlew build`.
 - Mod identity and dependencies are declared in generated NeoForge metadata.
 - Registrations are isolated by registry type and use deferred registration.
 - The Descriptive Book loads with a model, name, tooltip, and creative tab.
 - CI builds every pushed commit and pull request.
@@ -0,0 +1,78 @@
 # Destination preview compatibility
 Rivencraft has three destination preview backends. The selected backend is a
 client presentation detail; the server validates travel and Age generation is
 independent of every preview integration.
 ## Selection matrix
 Set `book_preview.mode` in `rivencraft-client.toml`.
 | Configured mode | Immersive Portals installed | Create/Ponder installed | Selected backend |
 | --- | --- | --- | --- |
 | `AUTO` | yes | either | Immersive Portals |
 | `AUTO` | no | yes | Ponder snapshot |
 | `AUTO` | no | no | built-in legacy animation |
 | `IMMERSIVE_PORTALS` | yes | either | Immersive Portals |
 | `IMMERSIVE_PORTALS` | no | either | built-in legacy animation |
 | `PONDER` | either | yes | Ponder snapshot |
 | `PONDER` | either | no | built-in legacy animation |
 | `LEGACY` | either | either | built-in legacy animation |
 Explicit optional modes fall back directly to `LEGACY`. They do not silently
 select the other optional integration. GameTests exercise every row and every
 dependency-presence permutation.
 ## Book behavior
 Held Linking and Descriptive Books render the selected backend in the preview
 panel. Immersive Portals additionally exposes **Explore**: the player remains
 at the opening position, mouse look controls the remote camera, and
 right-click returns to the standard book view.
 Books on a Book Stand use the same preview panel, but Explore is disabled so
 the player cannot move away and leave a remote preview session owned by the
 stand screen. Closing either screen releases its server chunk loader. Linking,
 disconnecting, unloading the destination Age, and stopping the server also
 release affected loaders.
 The Immersive Portals backend force-loads the initial 3 by 3 destination area
 before registering its wider preview chunk loader. The Ponder backend clears
 the previous snapshot before applying replacement block data. The live backend
 clears its framebuffer on each render and restores the Minecraft viewport
 afterward. These rules prevent stale snapshot frames and book UI elements from
 being captured in the preview.
 ## Supported combinations and upstream limits
 The compatibility baseline is Minecraft 1.21.1, NeoForge 21.1.251, Create
 6.0.10, and Immersive Portals 6.0.7. Core Age generation and the `LEGACY`
 backend run without Create or Immersive Portals; the headless GameTest server
 uses that dependency-free path.
 Immersive Portals 6.0.7 is incompatible with Sodium 0.8.13 for Minecraft
 1.21.1: its Sodium compatibility mixin references the removed
 `OcclusionCuller.Visitor` class and crashes while entering a world. Sodium
 0.6.13 avoids that specific mixin failure. This compatibility boundary belongs
 to Immersive Portals and Sodium, before Rivencraft's preview code runs.
 Immersive Portals reports that some Create contraptions can be invisible when
 the two mods are installed together. Rivencraft does not replace either mod's
 world or contraption renderer, so this remains an upstream rendering limit.
 The `PONDER` or `LEGACY` mode is the supported fallback when live rendering is
 unstable in a particular graphics or mod configuration.
 ## Release verification
 For preview-related releases:
 1. Run `./gradlew runGameTestServer` to verify the complete selection matrix,
   core Age creation, persistence, and travel without optional renderers.
 2. Open held Linking and Descriptive Books once with each available backend.
 3. Open both book types from a Book Stand and confirm Explore is disabled.
 4. With Immersive Portals, enter and leave Explore, travel between dimensions,
   close the screen, and disconnect; confirm destination chunks render and no
   preview loader remains active.
 5. With Ponder, reopen different destinations and confirm the previous
   snapshot does not bleed into the next one.
@@ -0,0 +1,46 @@
 # Writing and symbol data
 Milestone 4 stores what a player wrote without deciding what that writing does
 to an Age. Milestone 5 owns grammar validation, symbol interaction, instability,
 and translation into biome, noise, dimension-type, and other world-generation
 configuration.
 ## Symbol catalog
 The authoritative server catalog loads JSON resources from
 `data/<namespace>/rivencraft/symbols/<path>.json`. The resource ID is the
 symbol ID. For example, `data/rivencraft/rivencraft/symbols/terrain/standard.json`
 defines `rivencraft:terrain/standard`.
 Schema version 1 contains display metadata only:
 ```json
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.terrain.standard",
  "description": "symbol.rivencraft.terrain.standard.description",
  "category": "rivencraft:terrain"
 }
 ```
 `name` and `description` are translation keys, not arbitrary formatted text or
 executable behavior. `category` is a namespaced organizational identifier.
 Invalid definitions are logged and excluded by the server. Menus and future
 page synchronization must obtain resolved display metadata from the server;
 clients never make a symbol valid by naming it.
 Rivencraft ships a small catalog covering terrain, biomes, lighting, weather,
 celestial behavior, and features. It exists to exercise the complete writing
 workflow before Milestone 5 implements the full legacy grammar.
 ## Persistent writing
 `SymbolReference` stores only a namespaced symbol ID. `WritingEntry` is either
 a symbol reference or a baseline link-panel marker. `OrderedWriting` retains up
 to 256 entries in exact player-authored order. All three contracts have both
 persistent codecs and bounded network codecs.
 Removing a data pack never removes its IDs from saved writing. A missing ID is
 resolved as client-safe **Unresolved Symbol** display metadata while retaining
 the original namespaced ID for diagnostics and later restoration. This is
 deliberately different from treating an unknown symbol as valid grammar.
@@ -0,0 +1,7 @@
 {
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:amplified",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,6 @@
 {
  "pack": {
    "pack_format": 48,
    "description": "Example Rivencraft Age runtime profile"
  }
 }
@@ -35,7 +35,7 @@ mod_name=Rivencraft
 # The license of the mod. Review your options at https://choosealicense.com/. All Rights Reserved is the default.
 mod_license=LGPL-3.0-or-later
 # The mod version. Rivencraft uses the x.y.z.b policy documented in README.md.
-mod_version=0.2.26.1
+mod_version=0.3.1.0
 immersive_portals_version=6.0.7
 # The group ID for the mod. It is only important when publishing as an artifact to a Maven repository.
 # This should match the base package used for the mod sources.
@@ -10,11 +10,15 @@ import net.dnorberg.rivencraft.registry.ModBlockEntities;
 import net.dnorberg.rivencraft.registry.ModBiomeSources;
 import net.dnorberg.rivencraft.event.BookStandConversionHandler;
 import net.dnorberg.rivencraft.event.AgeCelestialAngleSync;
 import net.dnorberg.rivencraft.event.AgeLifecycleEvents;
 import net.dnorberg.rivencraft.command.RivencraftCommands;
 import net.dnorberg.rivencraft.network.ModNetworking;
 import net.dnorberg.rivencraft.config.RivencraftConfig;
 import net.dnorberg.rivencraft.config.RivencraftClientConfig;
 import net.dnorberg.rivencraft.book.AgeDimensionService;
 import net.dnorberg.rivencraft.book.AgeWeatherService;
 import net.dnorberg.rivencraft.book.AgeRuntimeProfiles;
 import net.dnorberg.rivencraft.writing.SymbolCatalog;
 import net.neoforged.bus.api.IEventBus;
 import net.neoforged.fml.ModContainer;
 import net.neoforged.fml.common.Mod;
@@ -43,6 +47,11 @@ public final class Rivencraft {
        NeoForge.EVENT_BUS.addListener(AgeWeatherService::onLevelTickPost);
        NeoForge.EVENT_BUS.addListener(AgeCelestialAngleSync::onPlayerLoggedIn);
        NeoForge.EVENT_BUS.addListener(AgeCelestialAngleSync::onPlayerChangedDimension);
        NeoForge.EVENT_BUS.addListener(AgeLifecycleEvents::onPlayerLoggedOut);
        NeoForge.EVENT_BUS.addListener(AgeLifecycleEvents::onServerStopping);
        NeoForge.EVENT_BUS.addListener(RivencraftCommands::register);
        NeoForge.EVENT_BUS.addListener(AgeRuntimeProfiles::register);
        NeoForge.EVENT_BUS.addListener(SymbolCatalog::register);
        LOGGER.info("Initializing Rivencraft");
    }
 }
@@ -1,9 +1,10 @@
 package net.dnorberg.rivencraft.book;
 import dev.galacticraft.dynamicdimensions.api.DynamicDimensionRegistry;
 import dev.galacticraft.dynamicdimensions.api.PlayerRemover;
 import dev.galacticraft.dynamicdimensions.api.event.DimensionRemovedCallback;
 import dev.galacticraft.dynamicdimensions.api.event.DynamicDimensionLoadCallback;
 import java.util.Optional;
 import java.util.OptionalLong;
 import java.util.List;
 import java.util.Comparator;
 import java.util.Collections;
@@ -21,7 +22,6 @@ import net.minecraft.server.MinecraftServer;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.server.level.ServerPlayer;
 import net.minecraft.tags.BlockTags;
 import net.minecraft.util.valueproviders.UniformInt;
 import net.minecraft.world.level.Level;
 import net.minecraft.world.level.block.Blocks;
 import net.minecraft.world.level.biome.Biomes;
@@ -30,7 +30,6 @@ import net.minecraft.world.level.biome.BiomeSource;
 import net.minecraft.world.level.biome.CheckerboardColumnBiomeSource;
 import net.minecraft.world.level.biome.FixedBiomeSource;
 import net.minecraft.world.level.biome.MultiNoiseBiomeSource;
 import net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterLists;
 import net.dnorberg.rivencraft.world.ScaledBiomeSource;
 import net.minecraft.world.level.chunk.ChunkGenerator;
 import net.minecraft.world.level.dimension.BuiltinDimensionTypes;
@@ -56,13 +55,14 @@ public final class AgeDimensionService {
    }
    public static void register() {
        DimensionRemovedCallback.register((dimension, level) -> synchronizeImmersivePortals(level.getServer()));
        DynamicDimensionLoadCallback.register((server, loader) -> {
            ServerLevel overworld = server.overworld();
            for (AgeDefinition age : AgeRegistrySavedData.get(overworld).definitions()) {
                ServerLevel level = loader.loadDynamicDimension(
                        age.dimensionId(),
                        createGenerator(server, age),
-                        createDimensionType(age)
+                        createDimensionType(server, age)
                );
                if (level != null) {
                    applyCelestialClock(level, age);
@@ -104,7 +104,7 @@ public final class AgeDimensionService {
        ServerLevel loaded = DynamicDimensionRegistry.from(server).loadDynamicDimension(
                definition.dimensionId(),
                createGenerator(server, definition),
-                createDimensionType(definition)
+                createDimensionType(server, definition)
        );
        if (loaded == null) {
            Rivencraft.LOGGER.error("Failed to load Age {} as {}", definition.id(), definition.dimensionId());
@@ -115,6 +115,27 @@ public final class AgeDimensionService {
        return loaded;
    }
    /**
     * Unloads an Age while retaining its saved definition and dimension data.
     * A later book access reconstructs the same runtime level from that data.
     */
    public static UnloadResult unload(MinecraftServer server, AgeDefinition definition) {
        ResourceKey<Level> key = dimensionKey(definition);
        if (server.getLevel(key) == null) {
            return UnloadResult.ALREADY_UNLOADED;
        }
        if (ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.closeForDimension(key);
        }
        boolean unloaded = DynamicDimensionRegistry.from(server)
                .unloadDynamicDimension(definition.dimensionId(), PlayerRemover.DEFAULT);
        if (!unloaded) {
            return UnloadResult.FAILED;
        }
        return UnloadResult.UNLOADED;
    }
    private static void applyCelestialClock(ServerLevel level, AgeDefinition age) {
        if (age.traits().hasStoppedCelestialCycle()) {
            // NeoForge rejects an exact zero rate. The smallest positive float
@@ -240,15 +261,15 @@ public final class AgeDimensionService {
    }
    private static ChunkGenerator createGenerator(MinecraftServer server, AgeDefinition age) {
-        ResourceLocation profile = age.generationProfile();
+        AgeRuntimeProfile profile = AgeRuntimeProfiles.resolve(age.generationProfile());
-        if (profile.equals(AgeGenerationProfiles.FLAT)) {
+        if (profile.terrain() == AgeRuntimeProfile.Terrain.FLAT) {
            return new FlatLevelSource(FlatLevelGeneratorSettings.getDefault(
                    server.registryAccess().lookupOrThrow(Registries.BIOME),
                    server.registryAccess().lookupOrThrow(Registries.STRUCTURE_SET),
                    server.registryAccess().lookupOrThrow(Registries.PLACED_FEATURE)
            ));
        }
-        if (profile.equals(AgeGenerationProfiles.VOID)) {
+        if (profile.terrain() == AgeRuntimeProfile.Terrain.VOID) {
            FlatLevelGeneratorSettings settings = new FlatLevelGeneratorSettings(
                    Optional.empty(),
                    server.registryAccess().lookupOrThrow(Registries.BIOME).getOrThrow(Biomes.THE_VOID),
@@ -261,22 +282,11 @@ public final class AgeDimensionService {
        var biomeParameters = server.registryAccess()
                .lookupOrThrow(Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST);
        var noiseSettings = server.registryAccess().lookupOrThrow(Registries.NOISE_SETTINGS);
-        ResourceKey<NoiseGeneratorSettings> settingsKey;
+        ResourceKey<NoiseGeneratorSettings> settingsKey = ResourceKey.create(
-        if (profile.equals(AgeGenerationProfiles.CAVE)) {
+                Registries.NOISE_SETTINGS, profile.noiseSettings());
-            settingsKey = NoiseGeneratorSettings.CAVES;
+        ResourceKey<net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterList> biomePreset =
-        } else if (profile.equals(AgeGenerationProfiles.ISLAND)) {
+                ResourceKey.create(Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST, profile.biomePreset());
-            settingsKey = NoiseGeneratorSettings.FLOATING_ISLANDS;
+        BiomeSource biomeSource = createBiomeSource(server, age, biomeParameters, biomePreset);
        } else if (profile.equals(AgeGenerationProfiles.AMPLIFIED)) {
            settingsKey = NoiseGeneratorSettings.AMPLIFIED;
        } else {
            settingsKey = NoiseGeneratorSettings.OVERWORLD;
        }
        // Cave uses Minecraft's enclosed cave density with stone, water, and
        // Overworld-like surfaces while retaining the Age's biome source.
        // Island/Skylands uses uniform floating-island density without the
        // End's central dragon island. Both use the Overworld environment.
        // random_vanilla is retained as a migration alias for existing Ages.
        BiomeSource biomeSource = createBiomeSource(server, age, biomeParameters);
        NoiseGeneratorSettings baseSettings = noiseSettings.getOrThrow(settingsKey).value();
        return new NoiseBasedChunkGenerator(biomeSource, Holder.direct(withBiomeMaterialRules(baseSettings)));
    }
@@ -323,7 +333,8 @@ public final class AgeDimensionService {
    private static BiomeSource createBiomeSource(
            MinecraftServer server,
            AgeDefinition age,
-            net.minecraft.core.HolderGetter<net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterList> biomeParameters
+            net.minecraft.core.HolderGetter<net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterList> biomeParameters,
            ResourceKey<net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterList> biomePreset
    ) {
        List<net.minecraft.core.Holder.Reference<Biome>> biomes = server.registryAccess()
                .lookupOrThrow(Registries.BIOME)
@@ -370,30 +381,39 @@ public final class AgeDimensionService {
            );
        }
        return MultiNoiseBiomeSource.createFromPreset(
-                biomeParameters.getOrThrow(MultiNoiseBiomeSourceParameterLists.OVERWORLD));
+                biomeParameters.getOrThrow(biomePreset));
    }
-    private static DimensionType createDimensionType(AgeDefinition age) {
+    private static DimensionType createDimensionType(MinecraftServer server, AgeDefinition age) {
        AgeRuntimeProfile profile = AgeRuntimeProfiles.resolve(age.generationProfile());
        DimensionType base = server.registryAccess().lookupOrThrow(Registries.DIMENSION_TYPE)
                .getOrThrow(ResourceKey.create(Registries.DIMENSION_TYPE, profile.dimensionType())).value();
        AgeTraits.Lighting lighting = age.traits().lighting();
        boolean hasSkyLight = lighting != AgeTraits.Lighting.DARK;
        float ambientLight = lighting == AgeTraits.Lighting.BRIGHT ? 0.25F : 0.0F;
        return new DimensionType(
-                OptionalLong.empty(),
+                base.fixedTime(),
                hasSkyLight,
-                false,
+                base.hasCeiling(),
-                false,
+                base.ultraWarm(),
-                true,
+                base.natural(),
-                1.0D,
+                base.coordinateScale(),
-                false,
+                base.bedWorks(),
-                false,
+                base.respawnAnchorWorks(),
-                -64,
+                base.minY(),
-                384,
+                base.height(),
-                384,
+                base.logicalHeight(),
-                BlockTags.INFINIBURN_OVERWORLD,
+                base.infiniburn(),
-                BuiltinDimensionTypes.OVERWORLD_EFFECTS,
+                base.effectsLocation(),
                ambientLight,
-                new DimensionType.MonsterSettings(false, true, UniformInt.of(0, 7), 0)
+                base.monsterSettings()
        );
    }
    public enum UnloadResult {
        UNLOADED,
        ALREADY_UNLOADED,
        FAILED
    }
 }
@@ -33,6 +33,14 @@ public final class AgeGenerationProfiles {
        return RANDOM_PROFILES;
    }
    /** Maps removed legacy aliases to a stable built-in profile. */
    public static ResourceLocation migrationFallback(ResourceLocation profile) {
        if (profile.equals(AgeDefinition.RANDOM_VANILLA_PROFILE)) {
            return STANDARD;
        }
        return isSupported(profile) ? profile : STANDARD;
    }
    private static ResourceLocation id(String path) {
        return ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, path);
    }
@@ -0,0 +1,132 @@
 package net.dnorberg.rivencraft.book;
 import java.util.UUID;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.minecraft.core.BlockPos;
 import net.minecraft.gametest.framework.GameTest;
 import net.minecraft.gametest.framework.GameTestHelper;
 import net.minecraft.nbt.CompoundTag;
 import net.minecraft.nbt.ListTag;
 import net.minecraft.resources.ResourceLocation;
 import net.neoforged.neoforge.gametest.GameTestHolder;
 import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
 /** Saved-data migration and round-trip acceptance coverage for persistent Ages. */
@GameTestHolder(Rivencraft.MOD_ID)
@PrefixGameTestTemplate(false)
 public final class AgePersistenceGameTests {
    private AgePersistenceGameTests() {
    }
    @GameTest(template = "empty")
    public static void everyTraitCombinationRoundTripsWithoutRerolling(GameTestHelper helper) {
        ListTag entries = new ListTag();
        AgeTraits.BiomeDistribution[] distributions = AgeTraits.BiomeDistribution.values();
        AgeTraits.Lighting[] lightingValues = AgeTraits.Lighting.values();
        AgeTraits.Weather[] weatherValues = AgeTraits.Weather.values();
        for (int index = 0; index < distributions.length; index++) {
            UUID id = new UUID(0x524956454E000000L + index, 0x4147450000000000L + index);
            AgeTraits traits = new AgeTraits(
                    distributions[index],
                    lightingValues[index % lightingValues.length],
                    weatherValues[index % weatherValues.length],
                    index == 0 ? AgeTraits.STOPPED_CELESTIAL_PERIOD : 0.25D + index * 0.15D,
                    index * 37.5F,
                    index * 0.1F
            );
            entries.add(entry(
                    id,
                    "Persistent " + distributions[index],
                    9000L + index,
                    AgeGenerationProfiles.all().get(index % AgeGenerationProfiles.all().size()),
                    3 + index,
                    1200L + index,
                    ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, "age/persistent_" + index),
                    new BlockPos(index, 70 + index, -index),
                    traits
            ));
        }
        CompoundTag root = new CompoundTag();
        root.put("Ages", entries);
        AgeRegistrySavedData first = AgeRegistrySavedData.load(root, helper.getLevel().registryAccess());
        CompoundTag serialized = first.save(new CompoundTag(), helper.getLevel().registryAccess());
        AgeRegistrySavedData restored = AgeRegistrySavedData.load(serialized, helper.getLevel().registryAccess());
        for (int index = 0; index < distributions.length; index++) {
            UUID id = new UUID(0x524956454E000000L + index, 0x4147450000000000L + index);
            helper.assertValueEqual(restored.find(id).orElseThrow(), first.find(id).orElseThrow(),
                    distributions[index] + " and its weather, lighting, celestial, and identity data must round-trip");
        }
        helper.succeed();
    }
    @GameTest(template = "empty")
    public static void legacyDefinitionReceivesStableDefaults(GameTestHelper helper) {
        UUID id = UUID.fromString("4d797374-6372-6166-7400-000000000001");
        CompoundTag legacy = new CompoundTag();
        legacy.putUUID("Id", id);
        legacy.putString("Name", "  Legacy Age  ");
        legacy.putLong("Seed", 8675309L);
        legacy.putString("GenerationProfile", AgeDefinition.RANDOM_VANILLA_PROFILE.toString());
        legacy.putLong("CreatedGameTime", 42L);
        ListTag entries = new ListTag();
        entries.add(legacy);
        CompoundTag root = new CompoundTag();
        root.put("Ages", entries);
        AgeRegistrySavedData migrated = AgeRegistrySavedData.load(root, helper.getLevel().registryAccess());
        AgeDefinition definition = migrated.find(id).orElseThrow();
        helper.assertValueEqual(definition.id(), id, "Migration must retain the Age UUID");
        helper.assertValueEqual(definition.name(), "Legacy Age", "Migration must normalize and retain the Age name");
        helper.assertValueEqual(definition.seed(), 8675309L, "Migration must retain the Age seed");
        helper.assertValueEqual(definition.generationProfile(), AgeDefinition.RANDOM_VANILLA_PROFILE,
                "Migration must retain the legacy generation profile for deterministic runtime fallback");
        helper.assertValueEqual(definition.generationVersion(), 1,
                "Definitions predating generation versions must receive version 1");
        helper.assertValueEqual(definition.dimensionId(), AgeDefinition.dimensionId(id),
                "Definitions predating named dimensions must retain the UUID-derived dimension");
        helper.assertValueEqual(definition.traits(), AgeTraits.LEGACY_DEFAULTS,
                "Definitions predating traits must receive stable legacy defaults");
        CompoundTag serialized = migrated.save(new CompoundTag(), helper.getLevel().registryAccess());
        AgeDefinition reloaded = AgeRegistrySavedData.load(serialized, helper.getLevel().registryAccess())
                .find(id).orElseThrow();
        helper.assertValueEqual(reloaded, definition, "A migrated definition must not reroll on its next restart");
        helper.succeed();
    }
    private static CompoundTag entry(
            UUID id,
            String name,
            long seed,
            ResourceLocation profile,
            int version,
            long createdTime,
            ResourceLocation dimension,
            BlockPos spawn,
            AgeTraits traits
    ) {
        CompoundTag entry = new CompoundTag();
        entry.putUUID("Id", id);
        entry.putString("Name", name);
        entry.putLong("Seed", seed);
        entry.putString("GenerationProfile", profile.toString());
        entry.putInt("GenerationVersion", version);
        entry.putLong("CreatedGameTime", createdTime);
        entry.putString("Dimension", dimension.toString());
        entry.putInt("SpawnX", spawn.getX());
        entry.putInt("SpawnY", spawn.getY());
        entry.putInt("SpawnZ", spawn.getZ());
        CompoundTag serializedTraits = new CompoundTag();
        serializedTraits.putString("BiomeDistribution", traits.biomeDistribution().name());
        serializedTraits.putString("Lighting", traits.lighting().name());
        serializedTraits.putString("Weather", traits.weather().name());
        serializedTraits.putDouble("CelestialPeriod", traits.celestialPeriod());
        serializedTraits.putFloat("CelestialAngle", traits.celestialAngle());
        serializedTraits.putFloat("CelestialPhase", traits.celestialPhase());
        entry.put("Traits", serializedTraits);
        return entry;
    }
 }
@@ -91,7 +91,7 @@ public final class AgeRegistrySavedData extends SavedData {
                reference.id(),
                name,
                seed,
-                AgeGenerationProfiles.select(seed),
+                AgeRuntimeProfiles.select(seed),
                AgeDefinition.CURRENT_GENERATION_VERSION,
                createdGameTime,
                dimensionId,
@@ -103,7 +103,7 @@ public final class AgeRegistrySavedData extends SavedData {
        return created;
    }
-    private static AgeRegistrySavedData load(CompoundTag tag, HolderLookup.Provider registries) {
+    static AgeRegistrySavedData load(CompoundTag tag, HolderLookup.Provider registries) {
        AgeRegistrySavedData data = new AgeRegistrySavedData();
        ListTag serializedAges = tag.getList(AGES_TAG, CompoundTag.TAG_COMPOUND);
        for (int index = 0; index < serializedAges.size(); index++) {
@@ -111,12 +111,18 @@ public final class AgeRegistrySavedData extends SavedData {
            if (!entry.hasUUID(ID_TAG)) {
                continue;
            }
-            ResourceLocation profile = ResourceLocation.tryParse(entry.getString(PROFILE_TAG));
+            ResourceLocation profile = entry.contains(PROFILE_TAG, CompoundTag.TAG_STRING)
                    && !entry.getString(PROFILE_TAG).isBlank()
                    ? ResourceLocation.tryParse(entry.getString(PROFILE_TAG))
                    : null;
            if (profile == null) {
                profile = AgeDefinition.RANDOM_VANILLA_PROFILE;
            }
            UUID id = entry.getUUID(ID_TAG);
-            ResourceLocation dimensionId = ResourceLocation.tryParse(entry.getString(DIMENSION_TAG));
+            ResourceLocation dimensionId = entry.contains(DIMENSION_TAG, CompoundTag.TAG_STRING)
                    && !entry.getString(DIMENSION_TAG).isBlank()
                    ? ResourceLocation.tryParse(entry.getString(DIMENSION_TAG))
                    : null;
            if (dimensionId == null) {
                dimensionId = AgeDefinition.dimensionId(id);
            }
@@ -0,0 +1,20 @@
 package net.dnorberg.rivencraft.book;
 import net.minecraft.resources.ResourceLocation;
 /** Data-pack-defined resources used to construct an Age runtime dimension. */
 public record AgeRuntimeProfile(
        int schemaVersion,
        Terrain terrain,
        ResourceLocation noiseSettings,
        ResourceLocation biomePreset,
        ResourceLocation dimensionType
 ) {
    public static final int CURRENT_SCHEMA_VERSION = 1;
    public enum Terrain {
        NOISE,
        FLAT,
        VOID
    }
 }
@@ -0,0 +1,140 @@
 package net.dnorberg.rivencraft.book;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.minecraft.core.RegistryAccess;
 import net.minecraft.core.registries.Registries;
 import net.minecraft.resources.ResourceKey;
 import net.minecraft.resources.ResourceLocation;
 import net.minecraft.server.packs.resources.ResourceManager;
 import net.minecraft.server.packs.resources.SimpleJsonResourceReloadListener;
 import net.minecraft.util.profiling.ProfilerFiller;
 import net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterList;
 import net.minecraft.world.level.dimension.DimensionType;
 import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
 import net.neoforged.neoforge.event.AddReloadListenerEvent;
 /** Loads {@code data/<namespace>/rivencraft/age_profiles/*.json}. */
 public final class AgeRuntimeProfiles {
    private static final Gson GSON = new GsonBuilder().create();
    private static final String DIRECTORY = "rivencraft/age_profiles";
    private static final Map<ResourceLocation, AgeRuntimeProfile> PROFILES = new ConcurrentHashMap<>();
    private AgeRuntimeProfiles() {
    }
    public static void register(AddReloadListenerEvent event) {
        event.addListener(new Loader(event.getRegistryAccess()));
    }
    public static AgeRuntimeProfile resolve(ResourceLocation id) {
        AgeRuntimeProfile profile = PROFILES.get(id);
        if (profile != null) {
            return profile;
        }
        ResourceLocation fallback = AgeGenerationProfiles.migrationFallback(id);
        profile = PROFILES.get(fallback);
        if (profile == null) {
            throw new IllegalStateException("Missing built-in Age runtime profile " + fallback);
        }
        Rivencraft.LOGGER.warn("Age runtime profile {} is unavailable; using deterministic fallback {}", id, fallback);
        return profile;
    }
    public static Map<ResourceLocation, AgeRuntimeProfile> profiles() {
        return Map.copyOf(PROFILES);
    }
    /** Selects from all valid loaded profiles in stable resource-ID order. */
    public static ResourceLocation select(long seed) {
        if (PROFILES.isEmpty()) {
            return AgeGenerationProfiles.select(seed);
        }
        java.util.List<ResourceLocation> ids = PROFILES.keySet().stream().sorted().toList();
        return ids.get(Math.floorMod(Long.hashCode(seed), ids.size()));
    }
    static AgeRuntimeProfile parse(ResourceLocation id, JsonElement json, RegistryAccess registries) {
        JsonObject object = json.getAsJsonObject();
        int schemaVersion = object.has("schema_version") ? object.get("schema_version").getAsInt() : 1;
        if (schemaVersion != AgeRuntimeProfile.CURRENT_SCHEMA_VERSION) {
            throw new IllegalArgumentException("unsupported schema_version " + schemaVersion);
        }
        AgeRuntimeProfile.Terrain terrain = AgeRuntimeProfile.Terrain.valueOf(
                requiredString(object, "terrain").toUpperCase(java.util.Locale.ROOT));
        ResourceLocation noise = location(object, "noise_settings", "minecraft:overworld");
        ResourceLocation biome = location(object, "biome_preset", "minecraft:overworld");
        ResourceLocation dimension = location(object, "dimension_type", "minecraft:overworld");
        if (terrain == AgeRuntimeProfile.Terrain.NOISE) {
            requireRegistryEntry(registries, Registries.NOISE_SETTINGS, noise, id, "noise_settings");
            requireRegistryEntry(registries, Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST,
                    biome, id, "biome_preset");
        }
        requireRegistryEntry(registries, Registries.DIMENSION_TYPE, dimension, id, "dimension_type");
        return new AgeRuntimeProfile(schemaVersion, terrain, noise, biome, dimension);
    }
    private static String requiredString(JsonObject object, String name) {
        if (!object.has(name)) {
            throw new IllegalArgumentException("missing " + name);
        }
        return object.get(name).getAsString();
    }
    private static ResourceLocation location(JsonObject object, String name, String fallback) {
        ResourceLocation id = ResourceLocation.tryParse(object.has(name) ? object.get(name).getAsString() : fallback);
        if (id == null) {
            throw new IllegalArgumentException("invalid " + name);
        }
        return id;
    }
    private static <T> void requireRegistryEntry(
            RegistryAccess registries,
            ResourceKey<? extends net.minecraft.core.Registry<T>> registry,
            ResourceLocation entry,
            ResourceLocation profile,
            String field
    ) {
        if (registries.lookupOrThrow(registry).get(ResourceKey.create(registry, entry)).isEmpty()) {
            throw new IllegalArgumentException(profile + " references missing " + field + " " + entry);
        }
    }
    private static final class Loader extends SimpleJsonResourceReloadListener {
        private final RegistryAccess registries;
        private Loader(RegistryAccess registries) {
            super(GSON, DIRECTORY);
            this.registries = registries;
        }
        @Override
        protected void apply(Map<ResourceLocation, JsonElement> resources,
                             ResourceManager resourceManager,
                             ProfilerFiller profiler) {
            Map<ResourceLocation, AgeRuntimeProfile> loaded = new java.util.HashMap<>();
            resources.forEach((id, json) -> {
                try {
                    loaded.put(id, parse(id, json, registries));
                } catch (RuntimeException exception) {
                    Rivencraft.LOGGER.error("Ignoring invalid Age runtime profile {}: {}", id, exception.getMessage());
                }
            });
            for (ResourceLocation required : AgeGenerationProfiles.all()) {
                if (!loaded.containsKey(required)) {
                    throw new IllegalStateException("Required built-in Age runtime profile is missing: " + required);
                }
            }
            PROFILES.clear();
            PROFILES.putAll(loaded);
            Rivencraft.LOGGER.info("Loaded {} Age runtime profiles", loaded.size());
        }
    }
 }
@@ -76,6 +76,7 @@ public final class LinkingService {
            LinkTarget target
    ) {
        if (ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.close(player);
            ImmersivePortalsChunkLoaders.teleport(
                    player, destinationLevel, position, target.yaw(), target.pitch());
        } else {
@@ -1,44 +1,22 @@
 package net.dnorberg.rivencraft.client.preview;
 import net.dnorberg.rivencraft.config.RivencraftClientConfig;
 import net.dnorberg.rivencraft.compat.PreviewBackendSelector;
 import net.neoforged.fml.ModList;
 /** Selects the configured destination preview while keeping optional integrations optional. */
 public final class DestinationPreviewRenderers {
    private enum Backend {
        IMMERSIVE_PORTALS,
        PONDER,
        LEGACY
    }
    private DestinationPreviewRenderers() {
    }
    public static DestinationPreviewRenderer create() {
        boolean ponderAvailable = ModList.get().isLoaded("create");
        // The mode and priority are established before the optional IP renderer
        // lands, so selecting it currently follows the documented safe fallback.
        boolean immersivePortalsAvailable = ModList.get().isLoaded("immersive_portals_core");
-        return switch (selectBackend(
+        return switch (PreviewBackendSelector.select(
                RivencraftClientConfig.previewMode(), immersivePortalsAvailable, ponderAvailable)) {
            case IMMERSIVE_PORTALS -> new ImmersivePortalsDestinationPreviewRenderer();
            case PONDER -> new PonderDestinationPreviewRenderer();
            case LEGACY -> new LegacyDestinationPreviewRenderer();
        };
    }
    private static Backend selectBackend(
            RivencraftClientConfig.PreviewMode mode,
            boolean immersivePortalsAvailable,
            boolean ponderAvailable
    ) {
        return switch (mode) {
            case AUTO -> immersivePortalsAvailable
                    ? Backend.IMMERSIVE_PORTALS
                    : ponderAvailable ? Backend.PONDER : Backend.LEGACY;
            case IMMERSIVE_PORTALS -> immersivePortalsAvailable ? Backend.IMMERSIVE_PORTALS : Backend.LEGACY;
            case PONDER -> ponderAvailable ? Backend.PONDER : Backend.LEGACY;
            case LEGACY -> Backend.LEGACY;
        };
    }
 }
@@ -0,0 +1,81 @@
 package net.dnorberg.rivencraft.command;
 import com.mojang.brigadier.arguments.StringArgumentType;
 import net.dnorberg.rivencraft.book.AgeDefinition;
 import net.dnorberg.rivencraft.book.AgeDimensionService;
 import net.dnorberg.rivencraft.book.AgeRegistrySavedData;
 import net.minecraft.commands.Commands;
 import net.minecraft.network.chat.Component;
 import net.minecraft.resources.ResourceLocation;
 import net.neoforged.neoforge.event.RegisterCommandsEvent;
 /** Administrative commands for inspecting and safely unloading persistent Ages. */
 public final class RivencraftCommands {
    private RivencraftCommands() {
    }
    public static void register(RegisterCommandsEvent event) {
        event.getDispatcher().register(Commands.literal("rivencraft")
                .requires(source -> source.hasPermission(2))
                .then(Commands.literal("age")
                        .then(Commands.literal("list")
                                .executes(context -> listAges(context.getSource())))
                        .then(Commands.literal("unload")
                                .then(Commands.argument("dimension", StringArgumentType.string())
                                        .suggests((context, builder) -> {
                                            AgeRegistrySavedData.get(context.getSource().getLevel()).definitions()
                                                    .forEach(age -> builder.suggest(age.dimensionId().toString()));
                                            return builder.buildFuture();
                                        })
                                        .executes(context -> unloadAge(
                                                context.getSource(),
                                                StringArgumentType.getString(context, "dimension")
                                        ))))));
    }
    private static int listAges(net.minecraft.commands.CommandSourceStack source) {
        var ages = AgeRegistrySavedData.get(source.getLevel()).definitions().stream()
                .sorted(java.util.Comparator.comparing(AgeDefinition::name))
                .toList();
        source.sendSuccess(() -> Component.literal("Rivencraft Ages: " + ages.size()), false);
        for (AgeDefinition age : ages) {
            boolean loaded = source.getServer().getLevel(AgeDimensionService.dimensionKey(age)) != null;
            source.sendSuccess(() -> Component.literal(
                    (loaded ? "[loaded] " : "[unloaded] ")
                            + age.name() + " — " + age.dimensionId()
            ), false);
        }
        return ages.size();
    }
    private static int unloadAge(net.minecraft.commands.CommandSourceStack source, String requestedDimension) {
        ResourceLocation dimension = ResourceLocation.tryParse(requestedDimension);
        if (dimension == null) {
            source.sendFailure(Component.literal("Invalid dimension id: " + requestedDimension));
            return 0;
        }
        AgeDefinition age = AgeRegistrySavedData.get(source.getLevel()).findByDimension(dimension).orElse(null);
        if (age == null) {
            source.sendFailure(Component.literal("Unknown Rivencraft Age: " + dimension));
            return 0;
        }
        AgeDimensionService.UnloadResult result = AgeDimensionService.unload(source.getServer(), age);
        return switch (result) {
            case UNLOADED -> {
                source.sendSuccess(() -> Component.literal(
                        "Unloaded " + age.name() + ". Its definition and world data were retained."
                ), true);
                yield 1;
            }
            case ALREADY_UNLOADED -> {
                source.sendFailure(Component.literal(age.name() + " is already unloaded."));
                yield 0;
            }
            case FAILED -> {
                source.sendFailure(Component.literal("Dynamic Dimensions refused to unload " + age.name() + "."));
                yield 0;
            }
        };
    }
 }
@@ -1,11 +1,13 @@
 package net.dnorberg.rivencraft.compat;
 import java.util.IdentityHashMap;
 import java.util.Map;
 import java.util.WeakHashMap;
 import net.minecraft.core.BlockPos;
 import net.minecraft.server.MinecraftServer;
 import net.minecraft.server.level.ServerPlayer;
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.resources.ResourceKey;
 import net.minecraft.world.level.Level;
 import net.minecraft.world.phys.Vec3;
 import qouteall.imm_ptl.core.api.PortalAPI;
 import qouteall.imm_ptl.core.chunk_loading.ChunkLoader;
@@ -14,12 +16,12 @@ import qouteall.q_misc_util.dimension.DimensionIntId;
 /** Isolated server bridge; this class is loaded only when Immersive Portals is installed. */
 public final class ImmersivePortalsChunkLoaders {
-    private static final Map<ServerPlayer, ChunkLoader> LOADERS = new WeakHashMap<>();
+    private static final Map<ServerPlayer, ChunkLoader> LOADERS = new IdentityHashMap<>();
    private ImmersivePortalsChunkLoaders() {
    }
-    public static void open(ServerPlayer player, ServerLevel level, BlockPos center) {
+    public static synchronized void open(ServerPlayer player, ServerLevel level, BlockPos center) {
        close(player);
        int centerChunkX = center.getX() >> 4;
        int centerChunkZ = center.getZ() >> 4;
@@ -37,13 +39,28 @@ public final class ImmersivePortalsChunkLoaders {
        ImmPtlChunkTracking.immediatelyUpdateForPlayer(player);
    }
-    public static void close(ServerPlayer player) {
+    public static synchronized void close(ServerPlayer player) {
        ChunkLoader loader = LOADERS.remove(player);
        if (loader != null) {
            PortalAPI.removeChunkLoaderForPlayer(player, loader);
        }
    }
    public static synchronized void closeForDimension(ResourceKey<Level> dimension) {
        LOADERS.entrySet().removeIf(entry -> {
            if (!entry.getValue().dimension().equals(dimension)) {
                return false;
            }
            PortalAPI.removeChunkLoaderForPlayer(entry.getKey(), entry.getValue());
            return true;
        });
    }
    public static synchronized void closeAll() {
        LOADERS.forEach(PortalAPI::removeChunkLoaderForPlayer);
        LOADERS.clear();
    }
    /** Registers runtime dimensions and sends the revised ID map to connected clients. */
    public static void dimensionsChanged(MinecraftServer server) {
        DimensionIntId.onServerDimensionChanged(server);
@@ -0,0 +1,30 @@
 package net.dnorberg.rivencraft.compat;
 import net.dnorberg.rivencraft.config.RivencraftClientConfig;
 /** Pure selection policy for optional destination preview integrations. */
 public final class PreviewBackendSelector {
    public enum Backend {
        IMMERSIVE_PORTALS,
        PONDER,
        LEGACY
    }
    private PreviewBackendSelector() {
    }
    public static Backend select(
            RivencraftClientConfig.PreviewMode mode,
            boolean immersivePortalsAvailable,
            boolean ponderAvailable
    ) {
        return switch (mode) {
            case AUTO -> immersivePortalsAvailable
                    ? Backend.IMMERSIVE_PORTALS
                    : ponderAvailable ? Backend.PONDER : Backend.LEGACY;
            case IMMERSIVE_PORTALS -> immersivePortalsAvailable ? Backend.IMMERSIVE_PORTALS : Backend.LEGACY;
            case PONDER -> ponderAvailable ? Backend.PONDER : Backend.LEGACY;
            case LEGACY -> Backend.LEGACY;
        };
    }
 }
@@ -0,0 +1,26 @@
 package net.dnorberg.rivencraft.event;
 import net.dnorberg.rivencraft.compat.ImmersivePortalsChunkLoaders;
 import net.minecraft.server.level.ServerPlayer;
 import net.neoforged.fml.ModList;
 import net.neoforged.neoforge.event.entity.player.PlayerEvent;
 import net.neoforged.neoforge.event.server.ServerStoppingEvent;
 /** Server-authoritative cleanup for resources that exist only while a preview is active. */
 public final class AgeLifecycleEvents {
    private AgeLifecycleEvents() {
    }
    public static void onPlayerLoggedOut(PlayerEvent.PlayerLoggedOutEvent event) {
        if (event.getEntity() instanceof ServerPlayer player
                && ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.close(player);
        }
    }
    public static void onServerStopping(ServerStoppingEvent event) {
        if (ModList.get().isLoaded("immersive_portals_core")) {
            ImmersivePortalsChunkLoaders.closeAll();
        }
    }
 }
@@ -6,10 +6,14 @@ import net.dnorberg.rivencraft.book.AgeDimensionService;
 import net.dnorberg.rivencraft.book.AgeGenerationProfiles;
 import net.dnorberg.rivencraft.book.AgeReference;
 import net.dnorberg.rivencraft.book.AgeRegistrySavedData;
 import net.dnorberg.rivencraft.book.AgeRuntimeProfile;
 import net.dnorberg.rivencraft.book.AgeRuntimeProfiles;
 import net.dnorberg.rivencraft.book.LinkTarget;
 import net.dnorberg.rivencraft.book.LinkingService;
 import net.dnorberg.rivencraft.book.AgeVisitSavedData;
 import net.dnorberg.rivencraft.book.AgeTraits;
 import net.dnorberg.rivencraft.compat.PreviewBackendSelector;
 import net.dnorberg.rivencraft.config.RivencraftClientConfig;
 import net.dnorberg.rivencraft.item.DescriptiveBookItem;
 import net.dnorberg.rivencraft.item.LinkingBookItem;
 import net.dnorberg.rivencraft.registry.ModDataComponents;
@@ -38,6 +42,91 @@ public final class LinkingGameTests {
    private LinkingGameTests() {
    }
    @GameTest(template = "empty")
    public static void previewBackendSelectionCoversOptionalDependencyMatrix(GameTestHelper helper) {
        assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.AUTO, true, true,
                PreviewBackendSelector.Backend.IMMERSIVE_PORTALS);
        assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.AUTO, true, false,
                PreviewBackendSelector.Backend.IMMERSIVE_PORTALS);
        assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.AUTO, false, true,
                PreviewBackendSelector.Backend.PONDER);
        assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.AUTO, false, false,
                PreviewBackendSelector.Backend.LEGACY);
        for (boolean ponderAvailable : new boolean[] {false, true}) {
            assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.IMMERSIVE_PORTALS, true,
                    ponderAvailable, PreviewBackendSelector.Backend.IMMERSIVE_PORTALS);
            assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.IMMERSIVE_PORTALS, false,
                    ponderAvailable, PreviewBackendSelector.Backend.LEGACY);
        }
        for (boolean immersivePortalsAvailable : new boolean[] {false, true}) {
            assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.PONDER,
                    immersivePortalsAvailable, true, PreviewBackendSelector.Backend.PONDER);
            assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.PONDER,
                    immersivePortalsAvailable, false, PreviewBackendSelector.Backend.LEGACY);
        }
        for (boolean immersivePortalsAvailable : new boolean[] {false, true}) {
            for (boolean ponderAvailable : new boolean[] {false, true}) {
                assertPreviewBackend(helper, RivencraftClientConfig.PreviewMode.LEGACY,
                        immersivePortalsAvailable, ponderAvailable, PreviewBackendSelector.Backend.LEGACY);
            }
        }
        helper.succeed();
    }
    private static void assertPreviewBackend(
            GameTestHelper helper,
            RivencraftClientConfig.PreviewMode mode,
            boolean immersivePortalsAvailable,
            boolean ponderAvailable,
            PreviewBackendSelector.Backend expected
    ) {
        helper.assertValueEqual(
                PreviewBackendSelector.select(mode, immersivePortalsAvailable, ponderAvailable),
                expected,
                mode + " selection with Immersive Portals=" + immersivePortalsAvailable
                        + " and Ponder=" + ponderAvailable
        );
    }
    @GameTest(template = "empty")
    public static void dataPackAgeProfilesResolveRegisteredResources(GameTestHelper helper) {
        var registries = helper.getLevel().registryAccess();
        var profiles = AgeRuntimeProfiles.profiles();
        helper.assertTrue(profiles.keySet().containsAll(AgeGenerationProfiles.all()),
                "Every built-in Age runtime profile must survive data-pack validation");
        for (var entry : profiles.entrySet()) {
            AgeRuntimeProfile profile = entry.getValue();
            helper.assertValueEqual(profile.schemaVersion(), AgeRuntimeProfile.CURRENT_SCHEMA_VERSION,
                    entry.getKey() + " must use the current runtime-profile schema");
            helper.assertTrue(registries.lookupOrThrow(net.minecraft.core.registries.Registries.DIMENSION_TYPE)
                            .get(net.minecraft.resources.ResourceKey.create(
                                    net.minecraft.core.registries.Registries.DIMENSION_TYPE,
                                    profile.dimensionType())).isPresent(),
                    entry.getKey() + " must reference a registered dimension type");
            if (profile.terrain() == AgeRuntimeProfile.Terrain.NOISE) {
                helper.assertTrue(registries.lookupOrThrow(net.minecraft.core.registries.Registries.NOISE_SETTINGS)
                                .get(net.minecraft.resources.ResourceKey.create(
                                        net.minecraft.core.registries.Registries.NOISE_SETTINGS,
                                        profile.noiseSettings())).isPresent(),
                        entry.getKey() + " must reference registered noise settings");
                helper.assertTrue(registries.lookupOrThrow(
                                net.minecraft.core.registries.Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST)
                                .get(net.minecraft.resources.ResourceKey.create(
                                        net.minecraft.core.registries.Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST,
                                        profile.biomePreset())).isPresent(),
                        entry.getKey() + " must reference a registered biome preset");
            }
        }
        var missing = net.minecraft.resources.ResourceLocation.fromNamespaceAndPath("example", "removed_profile");
        helper.assertValueEqual(
                AgeRuntimeProfiles.resolve(missing),
                AgeRuntimeProfiles.resolve(AgeGenerationProfiles.STANDARD),
                "A removed custom profile must use the documented deterministic fallback"
        );
        helper.succeed();
    }
    @GameTest(template = "empty")
    public static void linkTargetSurvivesItemSerialization(GameTestHelper helper) {
        LinkTarget expected = new LinkTarget(
@@ -152,6 +241,114 @@ public final class LinkingGameTests {
        });
    }
    @GameTest(template = "empty", timeoutTicks = 400)
    public static void everyTerrainProfileProvidesSafeArrivalAndReturnTravel(GameTestHelper helper) {
        ServerPlayer player = helper.makeMockServerPlayerInLevel();
        BlockPos returnPosition = player.blockPosition();
        helper.getLevel().setBlock(returnPosition.below(), Blocks.STONE.defaultBlockState(), 2);
        helper.getLevel().setBlock(returnPosition, Blocks.AIR.defaultBlockState(), 2);
        helper.getLevel().setBlock(returnPosition.above(), Blocks.AIR.defaultBlockState(), 2);
        LinkTarget returnTarget = new LinkTarget(
                GlobalPos.of(helper.getLevel().dimension(), returnPosition),
                player.getYRot(),
                player.getXRot()
        );
        long worldSeed = helper.getLevel().getServer().overworld().getSeed();
        runTerrainProfileTravel(helper, player, returnTarget, AgeGenerationProfiles.all(), 0, worldSeed);
    }
    private static void runTerrainProfileTravel(
            GameTestHelper helper,
            ServerPlayer player,
            LinkTarget returnTarget,
            java.util.List<net.minecraft.resources.ResourceLocation> profiles,
            int index,
            long worldSeed
    ) {
        if (index >= profiles.size()) {
            helper.succeed();
            return;
        }
        var profile = profiles.get(index);
        AgeReference reference = referenceSelectingProfile(profile, worldSeed);
        LinkTarget destination = AgeDimensionService.resolve(player, reference).orElse(null);
        helper.assertTrue(destination != null, profile + " must create a destination");
        if (destination == null) {
            return;
        }
        helper.runAfterDelay(1, () -> {
            AgeDefinition definition = AgeRegistrySavedData.get(helper.getLevel()).find(reference.id()).orElseThrow();
            helper.assertValueEqual(definition.generationProfile(), profile,
                    "The acceptance fixture must select " + profile);
            var ageLevel = player.getServer().getLevel(destination.location().dimension());
            helper.assertTrue(ageLevel != null, profile + " must create a loaded runtime dimension");
            BlockPos spawn = destination.location().pos();
            helper.assertTrue(ageLevel != null && ageLevel.getBlockState(spawn.below()).is(Blocks.COBBLESTONE),
                    profile + " must create a solid arrival platform");
            helper.assertTrue(ageLevel != null && ageLevel.getBlockState(spawn).isAir()
                            && ageLevel.getBlockState(spawn.above()).isAir(),
                    profile + " must create clear arrival headroom");
            helper.assertValueEqual(LinkingService.travelWithFooting(player, destination),
                    LinkingService.LinkResult.SUCCESS, profile + " must accept safe inbound travel");
            helper.assertValueEqual(LinkingService.travel(player, returnTarget),
                    LinkingService.LinkResult.SUCCESS, profile + " must permit return travel");
            helper.runAfterDelay(1, () -> runTerrainProfileTravel(
                    helper, player, returnTarget, profiles, index + 1, worldSeed));
        });
    }
    private static AgeReference referenceSelectingProfile(
            net.minecraft.resources.ResourceLocation profile,
            long worldSeed
    ) {
        UUID id = UUID.randomUUID();
        for (int candidate = 0; candidate < 100_000; candidate++) {
            String name = "Profile Acceptance " + profile.getPath() + " " + id + " " + candidate;
            var dimension = AgeDefinition.namedDimensionId(name);
            long seed = worldSeed + dimension.hashCode();
            if (AgeRuntimeProfiles.select(seed).equals(profile)) {
                return new AgeReference(id, name);
            }
        }
        throw new IllegalStateException("Could not select profile " + profile);
    }
    @GameTest(template = "empty", timeoutTicks = 100)
    public static void unloadedAgeReloadsWithTheSameDefinition(GameTestHelper helper) {
        UUID id = UUID.randomUUID();
        AgeDefinition definition = AgeRegistrySavedData.resolveOrCreate(
                helper.getLevel(),
                new AgeReference(id, "Lifecycle Test Age " + id)
        );
        var server = helper.getLevel().getServer();
        var first = AgeDimensionService.ensureLoaded(server, definition);
        helper.assertTrue(first != null, "The lifecycle test Age must load");
        helper.runAfterDelay(1, () -> {
            helper.assertValueEqual(
                    AgeDimensionService.unload(server, definition),
                    AgeDimensionService.UnloadResult.UNLOADED,
                    "A loaded Age must unload without deleting its definition"
            );
            helper.runAfterDelay(1, () -> {
                helper.assertTrue(server.getLevel(AgeDimensionService.dimensionKey(definition)) == null,
                        "An unloaded Age must leave the active server level map");
                var reloaded = AgeDimensionService.ensureLoaded(server, definition);
                helper.assertTrue(reloaded != null, "A book must be able to reload an archived Age");
                helper.runAfterDelay(1, () -> {
                    var registered = server.getLevel(AgeDimensionService.dimensionKey(definition));
                    helper.assertTrue(registered != null, "The reloaded Age must rejoin the active server level map");
                    helper.assertValueEqual(registered.getSeed(), definition.seed(),
                            "Reloading an Age must preserve its immutable seed");
                    helper.assertValueEqual(registered.dimension().location(), definition.dimensionId(),
                            "Reloading an Age must preserve its dimension identifier");
                    helper.succeed();
                });
            });
        });
    }
    @GameTest(template = "empty", timeoutTicks = 200)
    public static void legacyBaseTerrainProfilesLoadRuntimeDimensions(GameTestHelper helper) {
        for (var profile : AgeGenerationProfiles.all()) {
@@ -404,7 +601,9 @@ public final class LinkingGameTests {
        }
        helper.assertTrue(level.getChunkSource().getGenerator().getBiomeSource().possibleBiomes().stream().allMatch(holder -> holder.is(biome)),
                "The material test Age must select " + biome.location());
-        // Sample away from the generated arrival platform around the Age spawn.
+        // Sample away from the generated arrival platform. Vanilla surface rules
        // can place a shallow local patch such as gravel over the biome's base block.
        boolean foundExpectedSurface = false;
        int sampleX = 64;
        int sampleZ = 64;
        level.getChunk(sampleX >> 4, sampleZ >> 4);
@@ -413,10 +612,15 @@ public final class LinkingGameTests {
                sampleX,
                sampleZ
        ) - 1;
-        var surfaceState = level.getBlockState(new BlockPos(sampleX, surfaceY, sampleZ));
+        for (int depth = 0; depth <= 8; depth++) {
-        helper.assertTrue(surfaceState.is(expectedBlock),
+            if (level.getBlockState(new BlockPos(sampleX, surfaceY - depth, sampleZ)).is(expectedBlock)) {
                foundExpectedSurface = true;
                break;
            }
        }
        helper.assertTrue(foundExpectedSurface,
                biome.location() + " terrain must expose " + expectedBlock.getDescriptionId()
-                        + " at the surface, found " + surfaceState);
+                        + " across the sampled surface");
    }
    @GameTest(template = "empty")
@@ -0,0 +1,69 @@
 package net.dnorberg.rivencraft.gametest;
 import com.mojang.serialization.JsonOps;
 import io.netty.buffer.Unpooled;
 import java.util.List;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.dnorberg.rivencraft.writing.OrderedWriting;
 import net.dnorberg.rivencraft.writing.SymbolCatalog;
 import net.dnorberg.rivencraft.writing.SymbolReference;
 import net.dnorberg.rivencraft.writing.WritingEntry;
 import net.minecraft.gametest.framework.GameTest;
 import net.minecraft.gametest.framework.GameTestHelper;
 import net.minecraft.network.FriendlyByteBuf;
 import net.minecraft.resources.ResourceLocation;
 import net.neoforged.neoforge.gametest.GameTestHolder;
 import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
 /** Acceptance coverage for Milestone 4's persistent writing contracts. */
@GameTestHolder(Rivencraft.MOD_ID)
@PrefixGameTestTemplate(false)
 public final class WritingDataGameTests {
    private WritingDataGameTests() {
    }
    @GameTest(template = "empty")
    public static void orderedWritingPreservesKnownUnknownAndLinkPanelEntries(GameTestHelper helper) {
        SymbolReference known = reference("rivencraft:terrain/standard");
        SymbolReference unknown = reference("example:removed_symbol");
        OrderedWriting original = new OrderedWriting(List.of(
                WritingEntry.symbol(known),
                WritingEntry.symbol(unknown),
                WritingEntry.linkPanel()
        ));
        var json = OrderedWriting.CODEC.encodeStart(JsonOps.INSTANCE, original).result().orElseThrow();
        OrderedWriting persistentCopy = OrderedWriting.CODEC.parse(JsonOps.INSTANCE, json).result().orElseThrow();
        helper.assertValueEqual(persistentCopy, original,
                "Persistent writing codec must retain entry order and unknown symbol IDs");
        FriendlyByteBuf buffer = new FriendlyByteBuf(Unpooled.buffer());
        OrderedWriting.STREAM_CODEC.encode(buffer, original);
        OrderedWriting networkCopy = OrderedWriting.STREAM_CODEC.decode(buffer);
        helper.assertValueEqual(networkCopy, original,
                "Network writing codec must retain entry order and unknown symbol IDs");
        helper.succeed();
    }
    @GameTest(template = "empty")
    public static void serverCatalogResolvesBuiltinsAndKeepsUnknownReferencesReadable(GameTestHelper helper) {
        SymbolReference known = reference("rivencraft:terrain/standard");
        SymbolReference unknown = reference("example:removed_symbol");
        helper.assertTrue(SymbolCatalog.symbols().size() >= 6,
                "The built-in catalog must exercise every Milestone 4 writing workflow");
        helper.assertTrue(SymbolCatalog.isKnown(known),
                "The built-in Standard Terrain symbol must be server-authoritative");
        helper.assertFalse(SymbolCatalog.isKnown(unknown),
                "An absent data-pack symbol must remain unresolved");
        var unresolved = SymbolCatalog.display(unknown);
        helper.assertFalse(unresolved.resolved(),
                "Unknown symbol display metadata must be marked unresolved");
        helper.assertValueEqual(unresolved.id(), unknown.id(),
                "Unresolved display metadata must preserve the original namespaced ID");
        helper.succeed();
    }
    private static SymbolReference reference(String id) {
        return new SymbolReference(ResourceLocation.parse(id));
    }
 }
@@ -0,0 +1,47 @@
 package net.dnorberg.rivencraft.writing;
 import com.mojang.serialization.Codec;
 import com.mojang.serialization.DataResult;
 import io.netty.buffer.ByteBuf;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
 import net.minecraft.network.codec.ByteBufCodecs;
 import net.minecraft.network.codec.StreamCodec;
 /** Immutable ordered writing shared by pages, notebooks, desks, and books. */
 public record OrderedWriting(List<WritingEntry> entries) {
    public static final int MAX_ENTRIES = 256;
    public static final OrderedWriting EMPTY = new OrderedWriting(List.of());
    public static final Codec<OrderedWriting> CODEC = WritingEntry.CODEC.listOf()
            .validate(entries -> entries.size() <= MAX_ENTRIES
                    ? DataResult.success(entries)
                    : DataResult.error(() -> "Writing exceeds " + MAX_ENTRIES + " entries"))
            .xmap(OrderedWriting::new, OrderedWriting::entries);
    public static final StreamCodec<ByteBuf, OrderedWriting> STREAM_CODEC = StreamCodec.of(
            OrderedWriting::encode, OrderedWriting::decode);
    public OrderedWriting {
        entries = List.copyOf(Objects.requireNonNull(entries, "entries"));
        if (entries.size() > MAX_ENTRIES) {
            throw new IllegalArgumentException("Writing exceeds " + MAX_ENTRIES + " entries");
        }
    }
    private static void encode(ByteBuf buffer, OrderedWriting writing) {
        ByteBufCodecs.VAR_INT.encode(buffer, writing.entries.size());
        writing.entries.forEach(entry -> WritingEntry.STREAM_CODEC.encode(buffer, entry));
    }
    private static OrderedWriting decode(ByteBuf buffer) {
        int size = ByteBufCodecs.VAR_INT.decode(buffer);
        if (size < 0 || size > MAX_ENTRIES) {
            throw new IllegalArgumentException("Invalid writing entry count " + size);
        }
        List<WritingEntry> entries = new ArrayList<>(size);
        for (int index = 0; index < size; index++) {
            entries.add(WritingEntry.STREAM_CODEC.decode(buffer));
        }
        return new OrderedWriting(entries);
    }
 }
@@ -0,0 +1,67 @@
 package net.dnorberg.rivencraft.writing;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import com.google.gson.JsonElement;
 import com.mojang.serialization.JsonOps;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.minecraft.resources.ResourceLocation;
 import net.minecraft.server.packs.resources.ResourceManager;
 import net.minecraft.server.packs.resources.SimpleJsonResourceReloadListener;
 import net.minecraft.util.profiling.ProfilerFiller;
 import net.neoforged.neoforge.event.AddReloadListenerEvent;
 /** Authoritative server catalog loaded from data/&lt;namespace&gt;/rivencraft/symbols. */
 public final class SymbolCatalog {
    private static final Gson GSON = new GsonBuilder().create();
    private static final String DIRECTORY = "rivencraft/symbols";
    private static volatile Map<ResourceLocation, SymbolDefinition> symbols = Map.of();
    private SymbolCatalog() {
    }
    public static void register(AddReloadListenerEvent event) {
        event.addListener(new Loader());
    }
    public static Optional<SymbolDefinition> find(SymbolReference reference) {
        return Optional.ofNullable(symbols.get(reference.id()));
    }
    public static boolean isKnown(SymbolReference reference) {
        return symbols.containsKey(reference.id());
    }
    public static SymbolDisplayMetadata display(SymbolReference reference) {
        SymbolDefinition definition = symbols.get(reference.id());
        return definition == null
                ? SymbolDisplayMetadata.unresolved(reference)
                : definition.display(reference.id());
    }
    public static Map<ResourceLocation, SymbolDefinition> symbols() {
        return symbols;
    }
    private static final class Loader extends SimpleJsonResourceReloadListener {
        private Loader() {
            super(GSON, DIRECTORY);
        }
        @Override
        protected void apply(Map<ResourceLocation, JsonElement> resources,
                             ResourceManager resourceManager,
                             ProfilerFiller profiler) {
            Map<ResourceLocation, SymbolDefinition> loaded = new HashMap<>();
            resources.forEach((id, json) -> SymbolDefinition.CODEC.parse(JsonOps.INSTANCE, json)
                    .resultOrPartial(error -> Rivencraft.LOGGER.error(
                            "Ignoring invalid writing symbol {}: {}", id, error))
                    .ifPresent(definition -> loaded.put(id, definition)));
            symbols = Map.copyOf(loaded);
            Rivencraft.LOGGER.info("Loaded {} writing symbols", loaded.size());
        }
    }
 }
@@ -0,0 +1,47 @@
 package net.dnorberg.rivencraft.writing;
 import com.mojang.serialization.Codec;
 import com.mojang.serialization.DataResult;
 import com.mojang.serialization.codecs.RecordCodecBuilder;
 import java.util.Objects;
 import java.util.regex.Pattern;
 import net.minecraft.resources.ResourceLocation;
 /** Server-loaded, non-executable display metadata for a writing symbol. */
 public record SymbolDefinition(
        int schemaVersion,
        String nameTranslationKey,
        String descriptionTranslationKey,
        ResourceLocation category
 ) {
    public static final int CURRENT_SCHEMA_VERSION = 1;
    private static final Pattern TRANSLATION_KEY = Pattern.compile("[a-z0-9_.-]+");
    private static final Codec<String> TRANSLATION_KEY_CODEC = Codec.STRING.comapFlatMap(
            value -> TRANSLATION_KEY.matcher(value).matches()
                    ? DataResult.success(value)
                    : DataResult.error(() -> "Invalid translation key: " + value),
            value -> value
    );
    public static final Codec<SymbolDefinition> CODEC = RecordCodecBuilder.<SymbolDefinition>create(instance -> instance.group(
            Codec.INT.fieldOf("schema_version").forGetter(SymbolDefinition::schemaVersion),
            TRANSLATION_KEY_CODEC.fieldOf("name").forGetter(SymbolDefinition::nameTranslationKey),
            TRANSLATION_KEY_CODEC.fieldOf("description").forGetter(SymbolDefinition::descriptionTranslationKey),
            ResourceLocation.CODEC.fieldOf("category").forGetter(SymbolDefinition::category)
    ).apply(instance, SymbolDefinition::new)).flatXmap(SymbolDefinition::validate, SymbolDefinition::validate);
    public SymbolDefinition {
        Objects.requireNonNull(nameTranslationKey, "nameTranslationKey");
        Objects.requireNonNull(descriptionTranslationKey, "descriptionTranslationKey");
        Objects.requireNonNull(category, "category");
    }
    public SymbolDisplayMetadata display(ResourceLocation id) {
        return new SymbolDisplayMetadata(id, nameTranslationKey, descriptionTranslationKey, category, true);
    }
    private static DataResult<SymbolDefinition> validate(SymbolDefinition definition) {
        return definition.schemaVersion == CURRENT_SCHEMA_VERSION
                ? DataResult.success(definition)
                : DataResult.error(() -> "Unsupported symbol schema_version " + definition.schemaVersion);
    }
 }
@@ -0,0 +1,44 @@
 package net.dnorberg.rivencraft.writing;
 import com.mojang.serialization.Codec;
 import com.mojang.serialization.codecs.RecordCodecBuilder;
 import io.netty.buffer.ByteBuf;
 import net.dnorberg.rivencraft.Rivencraft;
 import net.minecraft.network.codec.ByteBufCodecs;
 import net.minecraft.network.codec.StreamCodec;
 import net.minecraft.resources.ResourceLocation;
 /** Client-safe symbol presentation selected by the authoritative server catalog. */
 public record SymbolDisplayMetadata(
        ResourceLocation id,
        String nameTranslationKey,
        String descriptionTranslationKey,
        ResourceLocation category,
        boolean resolved
 ) {
    public static final Codec<SymbolDisplayMetadata> CODEC = RecordCodecBuilder.create(instance -> instance.group(
            ResourceLocation.CODEC.fieldOf("id").forGetter(SymbolDisplayMetadata::id),
            Codec.STRING.fieldOf("name").forGetter(SymbolDisplayMetadata::nameTranslationKey),
            Codec.STRING.fieldOf("description").forGetter(SymbolDisplayMetadata::descriptionTranslationKey),
            ResourceLocation.CODEC.fieldOf("category").forGetter(SymbolDisplayMetadata::category),
            Codec.BOOL.fieldOf("resolved").forGetter(SymbolDisplayMetadata::resolved)
    ).apply(instance, SymbolDisplayMetadata::new));
    public static final StreamCodec<ByteBuf, SymbolDisplayMetadata> STREAM_CODEC = StreamCodec.composite(
            ResourceLocation.STREAM_CODEC, SymbolDisplayMetadata::id,
            ByteBufCodecs.STRING_UTF8, SymbolDisplayMetadata::nameTranslationKey,
            ByteBufCodecs.STRING_UTF8, SymbolDisplayMetadata::descriptionTranslationKey,
            ResourceLocation.STREAM_CODEC, SymbolDisplayMetadata::category,
            ByteBufCodecs.BOOL, SymbolDisplayMetadata::resolved,
            SymbolDisplayMetadata::new
    );
    public static SymbolDisplayMetadata unresolved(SymbolReference reference) {
        return new SymbolDisplayMetadata(
                reference.id(),
                "symbol.rivencraft.unresolved",
                "symbol.rivencraft.unresolved.description",
                ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, "unresolved"),
                false
        );
    }
 }
@@ -0,0 +1,24 @@
 package net.dnorberg.rivencraft.writing;
 import com.mojang.serialization.Codec;
 import io.netty.buffer.ByteBuf;
 import java.util.Objects;
 import net.minecraft.network.codec.StreamCodec;
 import net.minecraft.resources.ResourceLocation;
 /** Stable namespaced identity for one writing symbol. */
 public record SymbolReference(ResourceLocation id) {
    public static final Codec<SymbolReference> CODEC = ResourceLocation.CODEC.xmap(
            SymbolReference::new, SymbolReference::id);
    public static final StreamCodec<ByteBuf, SymbolReference> STREAM_CODEC = ResourceLocation.STREAM_CODEC.map(
            SymbolReference::new, SymbolReference::id);
    public SymbolReference {
        Objects.requireNonNull(id, "id");
    }
    /** Remains useful when the defining data pack has been removed. */
    public String unresolvedName() {
        return id.toString();
    }
 }
@@ -0,0 +1,82 @@
 package net.dnorberg.rivencraft.writing;
 import com.mojang.serialization.Codec;
 import com.mojang.serialization.DataResult;
 import com.mojang.serialization.codecs.RecordCodecBuilder;
 import io.netty.buffer.ByteBuf;
 import java.util.Locale;
 import java.util.Objects;
 import java.util.Optional;
 import net.minecraft.network.codec.ByteBufCodecs;
 import net.minecraft.network.codec.StreamCodec;
 /** One ordered unit of book writing. Interpretation belongs to Milestone 5. */
 public record WritingEntry(Kind kind, Optional<SymbolReference> symbol) {
    private static final Codec<Kind> KIND_CODEC = Codec.STRING.comapFlatMap(
            value -> {
                try {
                    return DataResult.success(Kind.valueOf(value.toUpperCase(Locale.ROOT)));
                } catch (IllegalArgumentException exception) {
                    return DataResult.error(() -> "Unknown writing entry kind: " + value);
                }
            },
            value -> value.name().toLowerCase(Locale.ROOT)
    );
    private static final Codec<WritingEntry> RECORD_CODEC = RecordCodecBuilder.create(instance -> instance.group(
            KIND_CODEC.fieldOf("kind").forGetter(WritingEntry::kind),
            SymbolReference.CODEC.optionalFieldOf("symbol").forGetter(WritingEntry::symbol)
    ).apply(instance, WritingEntry::new));
    public static final Codec<WritingEntry> CODEC = RECORD_CODEC.flatXmap(
            WritingEntry::validate, WritingEntry::validate);
    public static final StreamCodec<ByteBuf, WritingEntry> STREAM_CODEC = StreamCodec.of(
            WritingEntry::encode, WritingEntry::decode);
    public WritingEntry {
        Objects.requireNonNull(kind, "kind");
        symbol = Objects.requireNonNull(symbol, "symbol");
        if (kind == Kind.SYMBOL && symbol.isEmpty()) {
            throw new IllegalArgumentException("Symbol writing entries require a symbol reference");
        }
        if (kind == Kind.LINK_PANEL && symbol.isPresent()) {
            throw new IllegalArgumentException("Link-panel writing entries cannot contain a symbol reference");
        }
    }
    public static WritingEntry symbol(SymbolReference symbol) {
        return new WritingEntry(Kind.SYMBOL, Optional.of(symbol));
    }
    public static WritingEntry linkPanel() {
        return new WritingEntry(Kind.LINK_PANEL, Optional.empty());
    }
    private static DataResult<WritingEntry> validate(WritingEntry entry) {
        return entry.kind == Kind.SYMBOL && entry.symbol.isEmpty()
                || entry.kind == Kind.LINK_PANEL && entry.symbol.isPresent()
                ? DataResult.error(() -> "Writing entry contents do not match kind " + entry.kind)
                : DataResult.success(entry);
    }
    private static void encode(ByteBuf buffer, WritingEntry entry) {
        ByteBufCodecs.VAR_INT.encode(buffer, entry.kind.ordinal());
        if (entry.kind == Kind.SYMBOL) {
            SymbolReference.STREAM_CODEC.encode(buffer, entry.symbol.orElseThrow());
        }
    }
    private static WritingEntry decode(ByteBuf buffer) {
        int ordinal = ByteBufCodecs.VAR_INT.decode(buffer);
        if (ordinal < 0 || ordinal >= Kind.values().length) {
            throw new IllegalArgumentException("Unknown writing entry kind ordinal " + ordinal);
        }
        Kind kind = Kind.values()[ordinal];
        return kind == Kind.SYMBOL
                ? symbol(SymbolReference.STREAM_CODEC.decode(buffer))
                : linkPanel();
    }
    public enum Kind {
        SYMBOL,
        LINK_PANEL
    }
 }
@@ -57,6 +57,20 @@
  "trait.rivencraft.weather.snow": "Snow",
  "trait.rivencraft.weather.storm": "Storm",
  "trait.rivencraft.day_length.stopped": "Stopped",
  "symbol.rivencraft.unresolved": "Unresolved Symbol",
  "symbol.rivencraft.unresolved.description": "Missing symbol: %s",
  "symbol.rivencraft.terrain.standard": "Standard Terrain",
  "symbol.rivencraft.terrain.standard.description": "A familiar continental terrain foundation.",
  "symbol.rivencraft.biome.native": "Native Biomes",
  "symbol.rivencraft.biome.native.description": "Use the terrain profile's native biome climate.",
  "symbol.rivencraft.lighting.normal": "Normal Lighting",
  "symbol.rivencraft.lighting.normal.description": "Use normal skylight and ambient brightness.",
  "symbol.rivencraft.weather.normal": "Normal Weather",
  "symbol.rivencraft.weather.normal.description": "Use the normal weather cycle.",
  "symbol.rivencraft.celestial.normal_time": "Normal Time",
  "symbol.rivencraft.celestial.normal_time.description": "Use a normal-length celestial cycle.",
  "symbol.rivencraft.feature.caves": "Caves",
  "symbol.rivencraft.feature.caves.description": "Describe underground cave features.",
  "generator.rivencraft.standard": "Standard",
  "generator.rivencraft.amplified": "Amplified",
  "generator.rivencraft.island": "Island",
@@ -0,0 +1,7 @@
 {
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:amplified",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,7 @@
 {
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:caves",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,5 @@
 {
  "schema_version": 1,
  "terrain": "flat",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,7 @@
 {
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:floating_islands",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,7 @@
 {
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:overworld",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,5 @@
 {
  "schema_version": 1,
  "terrain": "void",
  "dimension_type": "minecraft:overworld"
 }
@@ -0,0 +1,6 @@
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.biome.native",
  "description": "symbol.rivencraft.biome.native.description",
  "category": "rivencraft:biome"
 }
@@ -0,0 +1,6 @@
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.celestial.normal_time",
  "description": "symbol.rivencraft.celestial.normal_time.description",
  "category": "rivencraft:celestial"
 }
@@ -0,0 +1,6 @@
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.feature.caves",
  "description": "symbol.rivencraft.feature.caves.description",
  "category": "rivencraft:feature"
 }
@@ -0,0 +1,6 @@
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.lighting.normal",
  "description": "symbol.rivencraft.lighting.normal.description",
  "category": "rivencraft:lighting"
 }
@@ -0,0 +1,6 @@
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.terrain.standard",
  "description": "symbol.rivencraft.terrain.standard.description",
  "category": "rivencraft:terrain"
 }
@@ -0,0 +1,6 @@
 {
  "schema_version": 1,
  "name": "symbol.rivencraft.weather.normal",
  "description": "symbol.rivencraft.weather.normal.description",
  "category": "rivencraft:weather"
 }
Author	SHA1	Message	Date
dnorberg	b8d23ee0c0	Define writing and symbol data model (#17 ) Build / build (push) Canceled after 0s Details	2026-09-23 14:24:40 -04:00
dnorberg	f276d412b9	Describe your changes Build / build (push) Canceled after 0s Details	2026-09-23 06:30:15 -04:00
dnorberg	954dd7097b	Complete Milestone 3 documentation (#12 ) Build / build (push) Canceled after 0s Details	2026-09-23 05:51:59 -04:00
dnorberg	1937a8c71d	Add Age migration regression coverage (#11 ) Build / build (push) Canceled after 0s Details	2026-09-23 05:41:38 -04:00
dnorberg	24b60706b0	Document and test preview compatibility (#10 ) Build / build (push) Canceled after 0s Details	2026-09-23 02:44:02 -04:00
dnorberg	109acc449a	Add data-pack Age runtime profiles (#9 ) Build / build (push) Canceled after 0s Details	2026-09-23 02:15:39 -04:00
dnorberg	b06fbda461	Complete Age lifecycle management (#8 ) Build / build (push) Canceled after 0s Details	2026-09-23 00:55:26 -04:00
dnorberg	c0bc91858e	Organize project tracking on Gitea (#13 ) Build / build (push) Canceled after 0s Details	2026-09-23 00:43:40 -04:00