# Porting roadmap

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 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, notebooks, desks, book assembly, and the baseline
   Ink Mixer for Link Panels. Symbol effects are deferred until Milestone 5.
   **Complete.** See [Milestone 4](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/milestone/9)
   and [writing-system data and migration](WRITING_DATA.md).
5. **Age grammar** — translate symbol combinations into modern biome, noise,
   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.

Milestone 4 delivered a versioned, data-pack-defined symbol catalog and an
immutable ordered-writing model. See [WRITING_DATA.md](WRITING_DATA.md). These
contracts preserve unknown symbol identifiers and store author intent; they do
not interpret symbols into Age generation, which remains Milestone 5 work.
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 belongs to Milestone 5.

## Provenance rules

- New code uses the `net.dnorberg.rivencraft` package.
- Reused legacy art is recorded in [ASSET_PROVENANCE.md](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.