rivencraft/docs/CURRENT_IMPLEMENTATION.md

Current implementation (Milestone 7 development)

This is the maintained technical overview of Rivencraft as of the 1.0.0.2 slice. It describes implemented behavior, not every behavior in Mystcraft Legacy. The README is the player introduction; milestone summaries 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, Legacy M7 audit, and Age administration.

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. Its status readout is off by default; /rivencraft binder messages enable makes it visible only to OPs. Symbol Pages are composed at runtime from Legacy glyph assets. Number pages 0–24 set color strength or, immediately before a Length, Angle, Phase, or Size modifier, its 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, writing data, generation profiles, and library/Ruins rules.

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 and runtime policy.

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.

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 separates tested behavior from unverified multiplayer/restart/optional-mod combinations. The Milestone 7 acceptance record records release evidence and remaining validation limits.