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