Complete Milestone 3 documentation (#12)

.gitea/issue_template/bug.md

@@ -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.

.gitea/issue_template/task.md

@@ -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.

README.md

@@ -4,10 +4,10 @@ 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
-provides functional Linking Books and randomly seeded, persistent vanilla-like
-Ages created from page-free Descriptive Books. Symbols, instability, and the
-full writing mechanics have not been ported yet.
+The bootstrap, books/linking, and Ages milestones are complete. The project
+currently provides functional Linking Books and randomly seeded, persistent
+vanilla-like Ages created from page-free Descriptive Books. Symbols,
+instability, and the full writing mechanics have not been ported yet.
 
 ## Linking Book
 
@@ -60,6 +60,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 +81,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 +114,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
-rules.
+See [docs/PORTING.md](docs/PORTING.md) for the roadmap, live Gitea tracking
+links, architectural direction, and provenance rules.
 
 ## License
 

docs/AGES.md

@@ -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.

docs/AGE_PROFILES.md

@@ -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.

docs/PORTING.md

@@ -1,454 +1,79 @@
-# Porting plan
+# Porting roadmap
 
-Mystcraft Legacy contains more than 700 Java source files and targets Minecraft
-1.12.2. The Minecraft world-generation, dimension, registry, networking, and
-rendering APIs have all changed substantially since that release. The port is
-split into independently testable milestones.
+Rivencraft ports Mystcraft Legacy from Minecraft 1.12.2 to NeoForge 1.21.1.
+The world-generation, dimension, registry, networking, and rendering APIs have
+changed substantially, so the work is divided into independently testable
+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
-   interaction, safe teleportation, and return links. **Complete.**
-3. **Ages** — dimension definitions backed by data packs, deterministic seeds,
-   lifecycle management, and persistence. Make the legacy-style animated
-   linking panel the built-in destination preview. Provide optional
-   Create/Ponder and Immersive Portals integrations as alternative rotating-
-   snapshot renderers. The configurable preview modes are `AUTO`,
-   `IMMERSIVE_PORTALS`, `PONDER`, and `LEGACY`; `AUTO` prefers Immersive
-   Portals when it is installed, then Create/Ponder, and finally the built-in
-   legacy animation.
+2. **Books and linking** — Descriptive and Linking Book data, Book Stands,
+   safe teleportation, return links, book screens, and destination previews.
+   **Complete.**
+3. **Ages** — persistent generated dimensions, deterministic traits,
+   lifecycle management, data-pack integration, and optional destination
+   renderer compatibility. **Complete.** See
+   [Milestone 3](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/milestone/8).
 4. **Writing system** — pages, symbols, notebooks, desks, and book assembly.
 5. **Age grammar** — translate symbol combinations into modern biome, noise,
-   dimension-type, and worldgen configuration. Optional integrations with
-   TerraBlender provide composable biome-region generation, while Serene
-   Seasons and Ecliptic Seasons allow Age generation to participate in their
-   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.
+   dimension-type, and world-generation configuration. Optional integrations
+   may add composable biome regions and seasonal behavior.
+6. **Instability** — deterministic validation and server-safe effects.
 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.
+
 ## Provenance rules
 
 - New code uses the `net.dnorberg.rivencraft` package.
-- Adapted Mystcraft code must retain its upstream copyright notice and be
-  tracked in this document or a nearby source comment.
-- Do not copy generated, binary, or third-party dependency content from the
+- Adapted Mystcraft code retains its upstream copyright notice and is tracked
+  in a nearby source comment or commit.
+- 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
-server-managed Age definition, travel to that Age, and use a Linking Book to
-return. This exercises persistence, networking, dimensions, and safety before
-the symbol grammar is introduced.
-
-### 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.
+The version scheme is documented in the project README. Every published
+version receives a Gitea release containing its changelog, built mod JAR, and
+SHA-256 checksum. Release notes describe user-visible behavior, compatibility
+changes, migrations, and validation performed for that version; ongoing task
+notes stay in issues.

docs/PREVIEW_COMPATIBILITY.md

@@ -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.
+

docs/example-age-profile-pack/data/example/rivencraft/age_profiles/highlands.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "terrain": "noise",
+  "noise_settings": "minecraft:amplified",
+  "biome_preset": "minecraft:overworld",
+  "dimension_type": "minecraft:overworld"
+}

docs/example-age-profile-pack/pack.mcmeta

@@ -0,0 +1,6 @@
+{
+  "pack": {
+    "pack_format": 48,
+    "description": "Example Rivencraft Age runtime profile"
+  }
+}

gradle.properties

@@ -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.0.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.

src/main/java/net/dnorberg/rivencraft/Rivencraft.java

@@ -10,11 +10,14 @@ 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.neoforged.bus.api.IEventBus;
 import net.neoforged.fml.ModContainer;
 import net.neoforged.fml.common.Mod;
@@ -43,6 +46,10 @@ 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);
         LOGGER.info("Initializing Rivencraft");
     }
 }

src/main/java/net/dnorberg/rivencraft/book/AgeDimensionService.java

@@ -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();
-        if (profile.equals(AgeGenerationProfiles.FLAT)) {
+        AgeRuntimeProfile profile = AgeRuntimeProfiles.resolve(age.generationProfile());
+        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;
-        if (profile.equals(AgeGenerationProfiles.CAVE)) {
-            settingsKey = NoiseGeneratorSettings.CAVES;
-        } else if (profile.equals(AgeGenerationProfiles.ISLAND)) {
-            settingsKey = NoiseGeneratorSettings.FLOATING_ISLANDS;
-        } 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);
+        ResourceKey<NoiseGeneratorSettings> settingsKey = ResourceKey.create(
+                Registries.NOISE_SETTINGS, profile.noiseSettings());
+        ResourceKey<net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterList> biomePreset =
+                ResourceKey.create(Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST, profile.biomePreset());
+        BiomeSource biomeSource = createBiomeSource(server, age, biomeParameters, biomePreset);
         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,
-                false,
-                true,
-                1.0D,
-                false,
-                false,
-                -64,
-                384,
-                384,
-                BlockTags.INFINIBURN_OVERWORLD,
-                BuiltinDimensionTypes.OVERWORLD_EFFECTS,
+                base.hasCeiling(),
+                base.ultraWarm(),
+                base.natural(),
+                base.coordinateScale(),
+                base.bedWorks(),
+                base.respawnAnchorWorks(),
+                base.minY(),
+                base.height(),
+                base.logicalHeight(),
+                base.infiniburn(),
+                base.effectsLocation(),
                 ambientLight,
-                new DimensionType.MonsterSettings(false, true, UniformInt.of(0, 7), 0)
+                base.monsterSettings()
         );
     }
 
+    public enum UnloadResult {
+        UNLOADED,
+        ALREADY_UNLOADED,
+        FAILED
+    }
+
 }

src/main/java/net/dnorberg/rivencraft/book/AgeGenerationProfiles.java

@@ -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);
     }

src/main/java/net/dnorberg/rivencraft/book/AgePersistenceGameTests.java

@@ -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;
+    }
+}

src/main/java/net/dnorberg/rivencraft/book/AgeRegistrySavedData.java

@@ -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);
             }

src/main/java/net/dnorberg/rivencraft/book/AgeRuntimeProfile.java

@@ -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
+    }
+}

src/main/java/net/dnorberg/rivencraft/book/AgeRuntimeProfiles.java

@@ -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());
+        }
+    }
+}

src/main/java/net/dnorberg/rivencraft/book/LinkingService.java

@@ -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 {

src/main/java/net/dnorberg/rivencraft/client/preview/DestinationPreviewRenderers.java

@@ -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;
-        };
-    }
 }

src/main/java/net/dnorberg/rivencraft/command/RivencraftCommands.java

@@ -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;
+            }
+        };
+    }
+}

src/main/java/net/dnorberg/rivencraft/compat/ImmersivePortalsChunkLoaders.java

@@ -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);

src/main/java/net/dnorberg/rivencraft/compat/PreviewBackendSelector.java

@@ -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;
+        };
+    }
+}

src/main/java/net/dnorberg/rivencraft/event/AgeLifecycleEvents.java

@@ -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();
+        }
+    }
+}

src/main/java/net/dnorberg/rivencraft/gametest/LinkingGameTests.java

@@ -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));
-        helper.assertTrue(surfaceState.is(expectedBlock),
+        for (int depth = 0; depth <= 8; depth++) {
+            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")

src/main/resources/data/rivencraft/rivencraft/age_profiles/amplified.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "terrain": "noise",
+  "noise_settings": "minecraft:amplified",
+  "biome_preset": "minecraft:overworld",
+  "dimension_type": "minecraft:overworld"
+}

src/main/resources/data/rivencraft/rivencraft/age_profiles/cave.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "terrain": "noise",
+  "noise_settings": "minecraft:caves",
+  "biome_preset": "minecraft:overworld",
+  "dimension_type": "minecraft:overworld"
+}

src/main/resources/data/rivencraft/rivencraft/age_profiles/flat.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "terrain": "flat",
+  "dimension_type": "minecraft:overworld"
+}

src/main/resources/data/rivencraft/rivencraft/age_profiles/island.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "terrain": "noise",
+  "noise_settings": "minecraft:floating_islands",
+  "biome_preset": "minecraft:overworld",
+  "dimension_type": "minecraft:overworld"
+}

src/main/resources/data/rivencraft/rivencraft/age_profiles/standard.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "terrain": "noise",
+  "noise_settings": "minecraft:overworld",
+  "biome_preset": "minecraft:overworld",
+  "dimension_type": "minecraft:overworld"
+}

src/main/resources/data/rivencraft/rivencraft/age_profiles/void.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "terrain": "void",
+  "dimension_type": "minecraft:overworld"
+}