# 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. **Active.** See
   [Milestone 3](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/milestone/8).
4. **Writing system** — pages, symbols, notebooks, desks, and book assembly.
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.

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 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.

## Provenance rules

- New code uses the `net.dnorberg.rivencraft` package.
- 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.