rivencraft/docs/CURRENT_IMPLEMENTATION.md

# Current implementation (Milestone 7 development)

This is the maintained technical overview of Rivencraft as of the 0.6.11.0
slice. It describes implemented behavior, not every behavior in Mystcraft
Legacy. [The README](../README.md) is the player introduction;
[milestone summaries](MILESTONES.md) explain how the implementation arrived
here. The linked deep dives are retained as historical audits and should be
read with their version dates in mind.

## Books, linking, and previews

- Linking Books bind a named position and direction. Same-dimension use needs
  Intra Linking. Descriptive Books refer to a persistent Age UUID and keep
  their authored page order. Copies keep that identity.
- Book screens use Legacy-inspired page spreads and destination panels. `AUTO`
  selects optional Immersive Portals first, then Create/Ponder, then the built-in
  animation. Travel is validated on the server regardless of renderer.
- Handheld travel drops the active book at its departure point as a visible
  book entity. Book Stands and crystal portals keep the book in place. Disarm
  drops carried items; Maintain Momentum rotates and carries velocity.
- A vanilla Lectern converts to a Book Stand when given a Rivencraft book or
  page. A Book Receptacle in a connected Crystal Block frame activates a
  vertical or horizontal portal. Immersive Portals can display a live view;
  otherwise the Legacy-style animated surface remains. Portal arrivals use
  existing safe footing; a Descriptive portal does not generate a platform.
- Automatic Return Links default to `DISABLED`, with `ON_CREATION` and `ALWAYS`
  server options. Linking Books do not generate platforms by default; a
  creative Link Modifier can explicitly enable that property.

See [preview modes](PREVIEW_COMPATIBILITY.md), [Legacy M7 audit](LEGACY_M7_AUDIT.md),
and [Age administration](AGES.md).

## Ages, writing, and structures

- Dynamic Dimensions AR Edition creates Age worlds. Each Age has a saved UUID,
  safe dimension ID, seed, spawn, traits, versioned generation plan, and
  optional season mode. Page-free or Link-Panel-only books get seeded random
  choices. Authored supported pages override the appropriate choices.
- Terrain choices are Standard, Amplified, Island, Cave, Flat, and Void. Cave
  terrain uses cave/Nether biomes and an appropriate spawn search; normal
  terrain starts from exposed surfaces. If no safe arrival site exists, the
  Age-creation path can construct a non-dropping Crystal Platform at Y=63.
- The server catalog accepts typed data-pack symbols. The Binder preserves
  written order and diagnoses conflicts. Symbol Pages are composed at runtime
  from Legacy glyph assets; number pages 0–24 set color strength and, when
  immediately before a Length, Angle, or Phase modifier, their numeric value.
  Celestial pages can create multiple suns/moons with independent color, size,
  angle, period, phase, and direction; authored eclipses affect light.
- The Writing Desk stores tabs and copies known Symbol Pages with paper and
  ink. Notebooks hold ordered pages; the Binder consumes a Link Panel and cover
  to make a finished Descriptive Book. The Ink Mixer makes Link Panels and
  rolls Disarm, Intra Linking, and Maintain Momentum from additives. Blank
  Pages are internal bases, not a craftable or JEI-listed output.
- Features include terrain additions, decorations, configurable block/fluid
  materials, ores, vanilla structures including newer 1.21 structures,
  Legacy-style libraries, crystals, obelisks, and star fissures. Optional Ruins
  templates gain authorable pages. Some biome/terrain combinations or feature
  placements are deliberately unsupported and are diagnosed during binding.

See [symbol semantics](SYMBOL_SEMANTICS.md), [writing data](WRITING_DATA.md),
[generation profiles](AGE_PROFILES.md), and [library/Ruins rules](RUINS_COMPATIBILITY.md).

## Instability and optional mods

Invalid or excessive writing and valuable generated blocks can add
instability. Block abundance is profiled in loaded chunks, so its contribution
and selected effects can change as the Age is explored; the authored plan is
not rewritten. Effects are bounded to loaded Ages and include status effects,
colored decay, lightning, explosions, meteors, burning, and erosion. Operator
commands expose the score and providers; the book GUI does not. See
[scoring](INSTABILITY_SCORE.md) and [runtime policy](INSTABILITY_RUNTIME.md).

JEI, Create/Ponder, Immersive Portals, TerraBlender, Serene Seasons with
GlitchCore, and Ruins are optional. TerraBlender can supply biomes from any mod
using its eligible regions; Biomes O' Plenty is a test example. Serene Seasons
has per-Age normal/no/eternal modes and live Age enrollment. Ecliptic Seasons
is not integrated because its 1.21.1 API lacks supported live registration and
per-Age calendar control. See the [optional-mod matrix](MILESTONE_7_REGRESSION.md).

## Persistence and boundaries

An Age registry definition and its dimension folder belong to the **same
whole-world backup**. Known older book/writing, plan, workstation, and Age
formats have migration or stable-default handling. Unknown symbol IDs remain
in books; missing registry objects or removed dimension mods can still prevent
world loading. The OP-only Link Modifier can retire an unoccupied Age. That
operation marks its UUID dead and moves its dimension data to a sibling
`<world>-retired-ages/<uuid>` folder; it is not ordinary book maintenance.
Do not use it without a backup.

This is not an exact port of every Legacy generator, page, hazard, or client
renderer. Modern safety budgets and NeoForge's dimension/biome APIs require
adaptations. The [Milestone 7 regression matrix](MILESTONE_7_REGRESSION.md)
separates tested behavior from unverified multiplayer/restart/optional-mod
combinations. Issue [#84](https://truenas-scale.tail180fb1.ts.net:8443/dnorberg/rivencraft/issues/84)
is the final Milestone 7 acceptance and release gate.