rivencraft/docs/PORTING.md

Porting plan

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.

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. In progress.
3. Ages — dimension definitions backed by data packs, deterministic seeds, lifecycle management, and persistence.
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.
6. Instability — deterministic validation and effects with server-safe behavior.
7. Structures and polish — libraries, crystals, portals, recipes, models, sounds, advancements, compatibility, and migration tests.

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 legacy repository.
• Preserve LGPL-3.0-or-later compatibility for the complete distributed mod.

First vertical slice

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

• Persistent, network-synchronized link-target data component.
• Linking Book binding with dimension, block position, yaw, and pitch.
• Server-authoritative cross-dimension travel with world-border, collision, fluid, and floor checks.
• Nearby landing search and clear failure messages.
• Descriptive Book identity and Age reference components.
• Return-link creation as part of Descriptive Book travel.
• Lectern/book-stand interaction.
• 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.

Version policy

Versions follow x.y.z:

• x: major release point.
• y: number of completed milestones.
• z: iteration within the active milestone, including bug-fix releases.

Starting work on a milestone increments z. Completing it increments y and resets z to zero. The first milestone-2 slice is therefore 0.1.1, and milestone 2 completion will be 0.2.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.