# 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.
- [x] Descriptive Book identity and Age reference components.
- [ ] Return-link creation as part of Descriptive Book travel.
- [x] Lectern-to-Book-Stand conversion, displayed book, activation, removal,
  persistence, and drops.
- [x] Book-screen foundation with server-authoritative naming, binding, and
  explicit link activation.
- [x] Ponder dependency and isolated destination-preview level boundary.
- [ ] Server-provided destination snapshots rendered as rotating Ponder scenes.
- [x] Book Stand floating names synchronized from the stored book stack.
- [ ] Open the stored book screen from a Book Stand.
- [ ] 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.

Age references use UUIDs rather than dimension keys. Milestone 3 will own the
mapping from that stable identity to server data and a runtime dimension. This
keeps saved books valid if an Age is migrated or regenerated.

Vanilla lecterns accept extensible item tags when inserting books, but their
block entity still validates only vanilla writable and written books. To avoid
an invalid lectern state, inserting a Rivencraft book converts the lectern into
a visually compatible Rivencraft Book Stand. Removing the book converts it
back.

Mystcraft Legacy did not impose an item cooldown when linking. Rivencraft's
initial cooldown used Minecraft's item-type cooldown system, which delayed all
Linking Book stacks at once. Version 0.1.3 removes that cooldown to match the
legacy behavior.

Version 0.1.4 moves Linking Book binding and travel behind a book screen. The
client requests an action, while the server revalidates the held book and owns
all changes to its destination and custom name. Descriptive Book Age references
now carry a display name alongside their stable UUID, with backward-compatible
decoding for existing UUID-only data.

Version 0.1.5 ensures the book interaction listener opens screens only for the
logical-client event. This avoids calling the render system from the integrated
server thread when a book is used in singleplayer.

Version 0.1.6 gives the Linking Book screen an open-book layout inspired by the
legacy interface. The destination preview occupies the left page, the book name
and destination details occupy the right page, and the preview itself is the
link action; the separate Link and Done buttons have been removed.

Version 0.1.7 suppresses Minecraft's default full-screen menu blur for the
Linking Book screen. The open-book texture supplies the GUI background while
the world remains sharp behind it.

Version 0.1.8 renders all Linking Book destination details in the same dark ink
color as the book name for consistent contrast against the parchment.

Version 0.1.9 synchronizes the Book Stand's stored stack to clients and renders
its display name as a camera-facing label above the book.

The preview code is separated behind a renderer interface and uses an isolated
Ponder level. The first iteration supplies the animated loading boundary; the
next iteration will add server-authoritative snapshot transport and populate
that level with the destination blocks.

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