rivencraft/docs/WRITING_DATA.md

Writing and symbol data

Milestone 4 stores what a player wrote without deciding what that writing does to an Age. Milestone 5 owns grammar validation, symbol interaction, instability, and translation into biome, noise, dimension-type, and other world-generation configuration.

Symbol catalog

The authoritative server catalog loads JSON resources from data/<namespace>/rivencraft/symbols/<path>.json. The resource ID is the symbol ID. For example, data/rivencraft/rivencraft/symbols/terrain/standard.json defines rivencraft:terrain/standard.

Schema version 1 contains display metadata only:

{
  "schema_version": 1,
  "name": "symbol.rivencraft.terrain.standard",
  "description": "symbol.rivencraft.terrain.standard.description",
  "category": "rivencraft:terrain"
}

name and description are translation keys, not arbitrary formatted text or executable behavior. category is a namespaced organizational identifier. Invalid definitions are logged and excluded by the server. Menus and future page synchronization must obtain resolved display metadata from the server; clients never make a symbol valid by naming it.

Rivencraft ships a small catalog covering terrain, biomes, lighting, weather, celestial behavior, and features. It exists to exercise the complete writing workflow before Milestone 5 implements the full legacy grammar.

Persistent writing

SymbolReference stores only a namespaced symbol ID. WritingEntry is either a symbol reference or a baseline link-panel marker. OrderedWriting retains up to 256 entries in exact player-authored order. All three contracts have both persistent codecs and bounded network codecs.

Assembled Descriptive Books store OrderedWriting schema version 1 alongside their Age reference. Books assembled in 0.3.7.2 saved writing as a bare list; that form still loads as version 1 without reordering or dropping unknown IDs. Older page-free books without writing continue to work unchanged. Copying a book copies its writing and Age reference; merely copying it never creates a new Age. The Book Binder creates the Age when its finished output is taken. The Descriptive Book screen can inspect the ordered pages by turning them from the bottom corners and identifies unresolved IDs using server-provided symbol metadata. Until Milestone 5, the saved symbols are informational only: Age creation uses the existing random fallback and does not apply them to generation.

Removing a data pack never removes its IDs from saved writing. A missing ID is resolved as client-safe Unresolved Symbol display metadata while retaining the original namespaced ID for diagnostics and later restoration. This is deliberately different from treating an unknown symbol as valid grammar.

Pages

The single stackable rivencraft:page item has a bounded, persistent rivencraft:page_content component. Its explicit states are blank, symbol, unresolved symbol, and baseline link panel. Symbol and unresolved-symbol pages retain their namespaced symbol reference; unresolved pages can be inspected and removed but are rejected as usable writing until their data pack returns.

Only server-side writing operations may create a known symbol page or link panel from vanilla paper. The shared PageItem creation and validation gates reject new pages for identifiers absent from the server catalog. Later Writing Desk and Book Binder packets must call these gates rather than accepting page contents supplied by a client.

The item model uses server-assigned custom-model data derived from the symbol identifier. Built-in pages reproduce Mystcraft Legacy's four-word poem composition from its page background and symbol-component sheet. Data-pack symbols without a bundled resource-pack model use the legacy question-mark fallback while keeping their real identifier and display metadata.

The Notebook surface displays pages by their persistent slot index instead of packing occupied pages together. Empty positions through the last placed page appear darkened. While carrying a Page, all available positions are shown for placement. The surface draws the native 30×40 portrait page region from Legacy's book UI atlas; symbols are layered at a uniform scale, while the square item models remain unchanged in inventories.

Ink and baseline link panels

An Ink Vial is crafted from two black dye, a glass bottle, and a water bucket. The bucket remains after crafting. Each vial holds 16 ink units, stored in a persistent, network-synchronized component; only vials with identical remaining ink stack together. When depleted, a vial returns a glass bottle that can be used to craft another. The animated item texture comes from Mystcraft Legacy.

The server config sets ink costs independently for symbol copying (default one unit) and baseline link-panel preparation (default two units). To prepare a panel, hold vanilla paper in one hand and use an Ink Vial in the other. The server checks the held items and sufficient ink before consuming anything. A stack of paper yields exactly one Link Panel Page per use; if the inventory is full, the result is dropped instead of deleted. Symbol copying is implemented by the Writing Desk: it previews a copy of the selected resolved page, then spends paper and ink only when that copy is taken. The desk's 16-unit ink meter refills from an Ink Vial when needed and returns a vanilla glass bottle. Link-property modifiers are deferred beyond this baseline flow.