rivencraft/README.md

Rivencraft

Rivencraft is a clean, incremental port of the ideas and gameplay of Mystcraft Legacy to Minecraft 1.21.1 on NeoForge.

The bootstrap and books/linking milestones are complete. The project currently provides functional Linking Books and randomly seeded, persistent vanilla-like Ages created from page-free Descriptive Books. Symbols, instability, and the full writing mechanics have not been ported yet.

Linking Book

Craft a Linking Book from a vanilla book and an ender pearl, then use it in the air. An unbound book opens a screen where it can be named and bound to the current location. A bound book opens its destination screen and travels when its preview panel is clicked. The destination is stored on the item and survives inventory and world saves. Travel only succeeds if the target dimension is loaded and a non-fluid, passable landing position can be found nearby.

Successful book travel plays Mystcraft Legacy's original linking sound at both the departure and arrival locations.

Right-click an empty vanilla lectern with a Rivencraft book to convert it into a Book Stand and place the book on it. Use a Linking Book on the stand by right-clicking with an empty hand. Sneak-right-click with an empty hand to take the book back and restore the vanilla lectern. Breaking a Book Stand drops both the stored book and a vanilla lectern.

Bound Linking Books show a rotating Ponder snapshot when Create is installed. Without Create, they use a built-in animated linking panel tinted by the destination sky. The server independently validates every link.

Descriptive Book

Open a page-free Descriptive Book, name its Age, and press Create. Rivencraft assigns the book a permanent Age UUID, selects a deterministic base terrain, creates a dedicated runtime dimension, and prepares a five-by-five cobblestone arrival platform at the highest suitable nearby terrain. Solid blocks and tree leaves are valid footing. Candidate columns are scanned from the top down so cave floors are not selected, and fluid-covered columns are excluded. If no suitable surface is available, the platform is generated at Y=63. Reopen the book and click its preview to travel. The book cannot reopen while its Age is being generated, whether held or on a Book Stand. Once creation finishes, reopening shows the written book. Copies of the written book continue to resolve to the same persistent Age across server restarts.

New Age dimension folders use a Minecraft-safe lowercase form of the assigned name. Conflicts receive incrementing suffixes such as _2 and _3; existing Age folders are never renamed.

Page-free Ages deterministically select one of six base terrains inspired by Mystcraft Legacy: Standard, Amplified, Island, Cave, Flat, or Void. The chosen profile is saved with the Age and does not change when the server restarts.

Linking creates a bound Return Link to the exact source position and orientation according to the configured Return Link policy.

Server owners can set descriptive_books.return_link_mode in Rivencraft's server config to ON_CREATION (default), ALWAYS, or DISABLED.

Requirements

• A Java 21 JDK
• Minecraft 1.21.1
• NeoForge 21.1.251 or newer in the 21.1 line
• Dynamic Dimensions AR Edition 0.9.1 and Bad Packets 0.8.2 (client and server)

Create is optional. When installed, Rivencraft uses its Ponder renderer for book previews when Immersive Portals is absent. Immersive Portals is also optional and takes priority in the default AUTO mode, providing a live rotating destination view. Its Explore button enables WASD and jump/sneak camera movement plus left-drag camera look; right-click returns to the rotating view. Without either integration, Rivencraft uses its built-in animated linking panel. Clients can set book_preview.mode in rivencraft-client.toml to AUTO, IMMERSIVE_PORTALS, PONDER, or LEGACY. Unavailable optional renderers safely fall back to LEGACY.

Build and run

./gradlew build
./gradlew runClient

The built mod is written to build/libs/.

Versioning

Rivencraft versions use x.y.z.b:

• x changes for a major public release.
• y changes when a development milestone is completed.
• z changes for each release slice within the current milestone.
• b changes for bug fixes and additional work within that release slice.

The build component resets to zero when a new release slice begins. Completing a milestone increments y and resets both z and b to zero. For example, milestone 2 development can progress from 0.1.1.0 to 0.1.1.1, then 0.1.2.0; completing the milestone produces 0.2.0.0.

Porting approach

Mystcraft Legacy targets Forge for Minecraft 1.12.2. Rivencraft therefore ports one subsystem at a time onto current registries, codecs, data packs, and NeoForge APIs instead of importing the legacy source tree wholesale.

See docs/PORTING.md for the roadmap, live Gitea tracking links, architectural direction, and provenance rules.

License

Rivencraft is licensed under LGPL-3.0-or-later. Mystcraft Legacy is also LGPL-3.0; copied or adapted upstream code must retain its copyright and license notices. See LICENSE and NOTICE.