rivencraft/docs/PORTING.md

Porting roadmap

For a concise current status, start with current implementation and milestone summaries. This file retains the original roadmap and architectural rationale.

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.

Porting principles

The primary goal is to reproduce verified Mystcraft Legacy behavior as closely as practical. Legacy source and the supplied 0.13.7.06 build are the behavioral reference for grammar, probabilities, ordering, defaults, visuals, and gameplay effects. A difference should be deliberate and documented rather than inferred from modern implementation convenience.

Minecraft 1.21.1 has different world heights, registries, threading, networking, data-pack APIs, and server protection expectations. Where an exact port would be unsafe, technically impossible, or incompatible with current Minecraft, Rivencraft preserves the player-visible intent while using bounded modern mechanics. New features may extend Legacy when they fit Age writing and linking, but extensions must be identified separately from compatibility behavior and must not silently change existing saved Ages.

Project tracking

Gitea is the source of truth for project status:

• Issues contain scoped implementation tasks, bugs, acceptance criteria, and technical discussion.
• Milestones group issues into the porting phases below and show their live completion state.
• 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 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.
4. Writing system — pages, notebooks, desks, book assembly, and the baseline Ink Mixer for Link Panels. Symbol effects were deferred to Milestone 5. Complete. See Milestone 4 and writing-system data and migration.
5. Age grammar — translate supported symbol combinations into modern biome, noise, dimension-type, and world-generation configuration, with optional TerraBlender and Serene Seasons integration. Complete for the supported subset. See the acceptance record and Legacy grammar audit.
6. Instability — deterministic validation and server-safe effects. Complete. See the Legacy instability audit and Milestone 6 acceptance.
7. Structures and polish — libraries, crystals, portals, recipes, models, sounds, advancements, compatibility, and migration tests. In progress. See the Milestone 7 regression matrix and Legacy audit.

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. The server data-pack schema for runtime generation is documented in 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.

The writing system and Age grammar build on the existing page-free Age path. Page-free books remain a useful deterministic fallback and test fixture.

Milestone 4 delivered a versioned, data-pack-defined symbol catalog and an immutable ordered-writing model. See WRITING_DATA.md. These contracts preserve unknown symbol identifiers and store author intent; Milestone 5 adds the server-owned interpretation and persistent Age plan. The Ink Mixer is included in Milestone 4 after book assembly; it uses paper and Ink Vials to make baseline Link Panels. Adding modifier ingredients and symbol-driven link properties were delivered in Milestone 5.

Provenance rules

• New code uses the net.dnorberg.rivencraft package.
• Reused legacy art is recorded in ASSET_PROVENANCE.md.
• 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.
• The complete distributed mod remains compatible with LGPL-3.0-or-later.

Release policy

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.