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, books/linking, and Ages milestones are complete. Milestone 4 is building the writing system on a data-pack symbol catalog and persistent ordered-writing model. The project currently provides functional Linking Books and randomly seeded, persistent vanilla-like Ages created from page-free Descriptive Books. Instability and full symbol-to-world grammar interpretation have not been ported yet.

Milestone 4 now includes stackable blank Pages plus server-created symbol, unresolved-symbol, and baseline link-panel states. Page visuals follow the legacy runtime-composition rules. Craft an Ink Vial from two black dye, a glass bottle, and a water bucket; the bucket is returned. Hold vanilla paper in one hand and use the Ink Vial in the other to prepare a baseline Link Panel Page. Each vial holds 16 ink units, and the default link-panel cost is two units. The spent vial returns a glass bottle. Server owners can adjust the symbol-copy and link-panel costs in the writing section of rivencraft-server.toml. The Ink Mixer now offers a Legacy-style station for producing Link Panels: insert paper and Ink Vials, then take a Link Panel from the result slot. Each vial fills its 16-unit basin and returns a glass bottle; no server tick is needed. The earlier paper-in-one-hand method remains available. Ink modifier ingredients and link properties are planned for Milestone 5. The Writing Desk can copy a selected written page from its collection tabs. The Writing Desk is now craftable from planks, a glass bottle, and a feather. It occupies two adjacent blocks, with one shared inventory; loaded paper and the selected page appear on its Legacy-inspired model. Desks placed before 0.3.6.1 keep their old one-block footprint until broken and placed again; leave an adjacent space when replacing one. Its 88 collection tabs, paper input, ink vial input, empty glass-bottle return, 16-unit ink meter, and inventory persist through world saves; breaking it drops stored contents. The desk screen is a functional foundation using Legacy's original desk and scrollbar textures. Four tabs are visible at once; the controls above and below them move by four (1–4, 5–8, through 85–88). Each viewer can browse a different group. Existing four-tab desks retain their collections and supplies when upgraded. With a notebook selected, pick up a Page from your inventory and click an empty position on the left surface to store one page there. Clear search/filter/sort and turn off ALL to place pages at specific positions; occupied positions are never overwritten. A notebook tab exposes all 27 notebook positions (scroll to reach the rest); a loose-page tab exposes only its one occupied position. Empty tabs have no page storage until a notebook or page is put in the tab slot. Click a page on the desk surface to select it for copying. Drag a page from one notebook position to an empty position to move it, or onto another page to swap their positions. This also works between notebooks shown in the ALL view. Drag a page out of the panel to turn it back into an item. Drop it over a player inventory slot or desk tab to place it there; a tab with a notebook adds it to the first open position. Dropping elsewhere leaves the page on the cursor for normal inventory placement. The source notebook or tab loses the page only after a valid drop. Put vanilla paper in the upper-left slot and Ink Vials in the upper-right; a copy appears in the lower-left result slot when the selected page is valid. Taking it consumes one paper and, by default, one ink. An available vial refills an empty ink meter when inserted or when copying uses its last ink, and returns a vanilla glass bottle to the lower-right slot. Removing a bottle also retries a blocked refill. Refilling waits if that slot is full or contains another item. The AZ control sorts visible pages by name; ALL shows pages held across every desk tab. Search and category filtering narrow the view without granting new pages, and cross-tab copy selection is checked by the server. Selecting a stored page on the desk surface shows its Legacy-proportioned portrait preview and name above the player inventory.

Book Binder

For a new survival Age: craft an Ink Vial, an Ink Mixer, a Writing Desk, and a Book Binder. Put vanilla paper and an Ink Vial in the Ink Mixer to make a Link Panel Page. Place leather (or an empty Notebook) and the Link Panel in the Book Binder, enter an Age name, and take the finished Descriptive Book. Written symbol Pages are optional; without them, the book creates a random Age. To duplicate a Page you already own, store it in a Writing Desk tab, select it, supply paper and ink, and take the copied Page from the output. A Notebook can hold and transfer a larger ordered collection of Pages between desks and the binder.

With JEI installed, Rivencraft displays the Ink Mixer operation in its own category and the hand-use, copying, and binding flows in a Writing category. JEI is optional; vanilla crafting recipes and all writing interactions work without it. For a development client with JEI, run ./gradlew runClient -PwithJei=true.

Craft a Book Binder from three iron ingots and five planks. Put leather or an empty Notebook in the left cover slot. Enter a title, then place a Link Panel Page first in the horizontal page strip. Click a page in the strip with a written Page on the cursor to insert it before that position; click it with an empty cursor to take it out. The arrows or mouse wheel scroll through up to 27 written Pages. Clicking the strip with a filled Notebook imports its Pages at that position and leaves the emptied Notebook on the cursor. The right slot outputs a Descriptive Book once the title, cover, and Link Panel are present. Inputs are consumed only when the result is taken.

The completed book receives its Age identity when assembled. With only a Link Panel, it describes a randomly generated Age. Its writing is stored on the book; the Descriptive Book screen's turned pages show ordered symbols and unresolved IDs. Until Milestone 5, symbols do not affect generation and written books use the same random Age fallback. The Descriptive Book screen follows Legacy's book spread: the title and Age details are on the left, the destination preview is on the right, and clicks in the bottom corners turn pages. Ordered symbol pages appear before the final blank spread; their pictograms await Milestone 5. Link-panel-only books show their details in the enchantment-table font.

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. The Linking Book uses the same Legacy page layout and bottom-corner page turns as the Descriptive Book, but without the Descriptive Book's gold cover edges.

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. Age creation, persistence, lifecycle commands, configuration, backups, and administrator recovery are documented in docs/AGES.md. Data-pack runtime profiles are documented in docs/AGE_PROFILES.md.

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. The complete backend matrix, supported combinations, cleanup behavior, and known upstream limits are documented in docs/PREVIEW_COMPATIBILITY.md.

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.