# 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

- [x] Persistent, network-synchronized link-target data component.
- [x] Linking Book binding with dimension, block position, yaw, and pitch.
- [x] Server-authoritative cross-dimension travel with world-border, collision,
  fluid, and floor checks.
- [x] 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.