Public Access
228 lines
12 KiB
Markdown
228 lines
12 KiB
Markdown
# Rivencraft
|
||
|
||
Rivencraft is a clean, incremental port of the ideas and gameplay of
|
||
[Mystcraft Legacy](https://github.com/Mystcraft/Mystcraft-Legacy) to Minecraft
|
||
1.21.1 on NeoForge.
|
||
|
||
The bootstrap, books/linking, Ages, and writing-system milestones are complete.
|
||
The writing system uses 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, binding, and Linking Book crafting 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. Authored writing is compiled once
|
||
into a versioned, server-owned Age plan. The plan freezes the Age seed, resolved
|
||
symbol meanings, page order, and runtime profile, so later data-pack changes do
|
||
not reinterpret an existing Age. An authored terrain page selects its runtime
|
||
profile; other symbol effects are scheduled for later Milestone 5 slices. The
|
||
writing is also stored on the book; the Descriptive Book screen's turned pages
|
||
show ordered symbols and unresolved IDs. 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 an unwritten Linking Book from one Link Panel Page and one leather in any
|
||
two crafting-grid positions. 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.
|
||
Both screens play Minecraft's book-page-turn sound when a page is turned.
|
||
|
||
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](docs/AGES.md).
|
||
Data-pack runtime profiles are documented in
|
||
[docs/AGE_PROFILES.md](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](docs/PREVIEW_COMPATIBILITY.md).
|
||
|
||
## Build and run
|
||
|
||
```shell
|
||
./gradlew build
|
||
./gradlew runClient
|
||
```
|
||
|
||
The built mod is written to `build/libs/`.
|
||
The default dedicated-server GameTest run is deliberately small. Use
|
||
`./gradlew runGameTestServer -PwithArchivedGameTests=true` for the complete
|
||
regression suite before a release or when investigating a related issue. See
|
||
[docs/GAMETESTS.md](docs/GAMETESTS.md).
|
||
|
||
## 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](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](LICENSE) and [NOTICE](NOTICE).
|