11 KiB
Ordered Descriptive Book grammar (Milestone 5, issue #30)
WritingGrammar interprets the saved OrderedWriting on the server using only SymbolCatalog's schema-v2 semantics. Client display metadata, page names, and supplied translations never determine an Age's meaning. The parser is pure: it returns immutable parsed entries and indexed diagnostics without changing a book or its pages.
New Binder writing has at most one Link Panel plus 252 symbol pages (the current fixed-slot save-format ceiling, not a Legacy gameplay limit). The Link Panel must be first. A Link-Panel-only book, or an older book with no writing component, keeps the existing random Age path. Any authored supported symbol makes the book a partial or complete grammar. From 0.4.3.0, the server compiles it into a persistent Age plan before consuming Binder inputs or generating chunks.
The supported order follows the representable subset of the Legacy grammar audit: terrain; zero or more biome pages; biome controller; weather; season; lighting; sky effects; zero or more period or phase modifiers; one celestial page; then zero or more features, each optionally preceded by a compatible material page. Biome pages precede the controller that consumes them, and celestial modifiers precede the celestial page. Terrain, controller, weather, season, lighting, sky, and celestial are single-choice categories; identical repeats are duplicates and differing values conflict. Repeated modifiers, biome pages, feature pages, and material pages are intentional and retain their order. An unpaired material page receives a seeded compatible feature during compilation. Angle modifiers remain recognized in the schema but are rejected at binding until a sky renderer can apply sun tilt.
Missing terrain, controller, weather, lighting, celestial, or the controller's minimum biome count is an incomplete warning, not an error: the compiler retains seed-selected traits for missing branches. An omitted terrain page uses a seed-selected profile compatible with authored feature pages, so changing the Age name cannot accidentally select Flat, Void, or Cave terrain for Rocks or Lakes. If no profile can support the writing, binding still rejects it. Native consumes no authored biome pages; Single consumes one; Tiled/Grid and Tiny–Huge require two, with seeded filler when pages are missing. From 0.5.1.0, known misplaced or repeated pages no longer block creation: the book keeps its original order, while the server repairs category order, uses the last single-choice controller, and stores a writing-instability score in the Age plan. A conflicting/repeated choice adds 500; an out-of-order page or misplaced modifier adds 100. Native ignores surplus authored biome pages and Single uses the first, with the conflict recorded as instability. Audited Legacy symbol modifiers also add 500 for each Bright Lighting page and 100 for each Mineshafts, Nether Fortresses, Strongholds, or Villages occurrence after the third. Modern structures configured with the same rule are Bastions, Trial Chambers, Ancient Cities, Shipwrecks, Ocean Ruins, Pillager Outposts, Ruined Portals, Nether Fossils, Buried Treasure, and Trail Ruins. Every repeated structure page increases that structure's placement rate: probability-based structures multiply their chance, grid-based structures use a denser grid, and Strongholds add more positions to each ring and more positions overall. One page retains the vanilla placement rate. Authored structures can generate outside their vanilla biome set; each structure-page occurrence that requires this override adds 100 instability. Seed completion selects compatible biomes where possible. Other feature pages have no direct symbol cost. Incorrectly placed pages are not red-highlighted; their warning remains available as a tooltip. Unknown IDs, schema-v1 display-only symbols, unavailable dependencies/profiles, unsupported semantic effects or feature/material pairs, missing/extra Link Panels, and oversized writing still reject a new Age. The Binder disables output for those fatal errors and shows a red page indication where applicable. Rejected inputs remain removable.
The plan stores the original writing order, the authoritative semantic value of each resolved symbol, the active repaired-page indexes, the writing-instability score, the Age seed, and a copy of the selected runtime profile. An explicit terrain page overrides random terrain selection; an omitted terrain uses a seed-selected compatible profile. The built-in Standard, Amplified, Cave, Island, Flat, and Void terrain pages select their matching generation resources. Age loading uses the frozen runtime profile and does not need the original symbol definition or runtime-profile JSON, though its referenced noise, biome-preset, and dimension-type registry entries must remain available. Existing bound books without plans are not reinterpreted. Page-free and Link-Panel-only books keep the pre-existing random path. Biome and environment pages affect new Ages, and the supported feature subset below is compiled into the same frozen plan. Runtime effects for a nonzero writing-instability score are not implemented yet.
Supported feature pages (issue #35)
Feature pages come after the celestial section. Their order is retained in the plan and in decoration placement. The Caves page adds a second, Age-seeded vanilla cave-carving pass to Noise terrain, including Standard, Amplified, Island, and Cave terrain. It chooses the vanilla Overworld or Nether cave carver from the source biome. This is separate from the Milestone 7 issue about Cave terrain generation. Flat and Void terrain have no suitable solid noise body and reject Caves with a binder diagnostic.
Flowers, Trees, Huge Trees, Rocks, Surface Lakes, Deep Lakes, and Lava Lakes add vanilla placed features after normal biome decoration. Huge Trees currently use vanilla old-growth spruce placement as a modern approximation of Legacy's huge-tree page; it is not the custom Legacy tree generator. Without a preceding material page, each material-bearing feature selects a valid solid block or source fluid from the registered pool. The selection is deterministic for the Age seed and feature occurrence, so repeated feature pages can receive different materials while remaining stable across restarts with the same block registry. The page-specific feature preserves vanilla placement rules other than the biome-list filter, since an authored page deliberately adds it to the Age. Surface and Lava Lakes use a more visible one-in-twelve-chunks attempt rate instead of vanilla lava lakes' one-in-two-hundred; Deep Lakes retain their underground placement. Vanilla biome lava lakes are separate and can still appear alongside authored fluid lakes. These decorations require surface Noise terrain; Cave, Flat, and Void reject them. Flowers and both tree pages require at least one surface Overworld biome and only run in compatible chunks; Nether, End, and tagged cave biomes do not receive surface vegetation. Ravines add a separate Age-seeded vanilla canyon-carving pass to Noise terrain. Unsupported feature IDs and missing vanilla registry entries produce diagnostics instead of becoming no-ops.
Material pages are generated for registered full-collision, non-fluid blocks and genuine source-fluid blocks, including eligible blocks supplied by other mods. Blocks with block entities are excluded. Waterlogged plants and coral are not fluid blocks and receive no pages. Valid source-fluid blocks appear only in the Fluid Pages creative tab; valid full-collision solids appear only in Block Pages. Both categories use the same saved material-page semantics. Put a Block Page before a compatible solid feature (Rocks, Floating Islands, Tendrils, Spheres, Spikes, or Obelisks), or a Fluid Page before a lake feature. A material page with no explicit feature receives a seeded compatible one. A material directly attached to an incompatible feature is rejected. The effective feature and material IDs are frozen with the Age, so future chunks retain their choices after restart. Existing chunks are not retroactively decorated.
Crystal Formations are an authored, material-free feature on exposed solid terrain, including Flat terrain; Cave and Void reject the page. Like Legacy, one in fifteen eligible chunks attempts a formation, with the site fixed by the Age seed and chunk coordinates. The modern formation is a compact mound with budding hearts instead of Legacy's long crystal lines. Budding blocks grow through small, medium, and large buds into clusters using vanilla amethyst timing and sounds. Non-silk cluster harvest yields Crystal Shards; four shards craft one Crystal Block. These blocks and shards use 16×16 textures: Legacy's crystal tile for solids and hue-shifted vanilla amethyst sprites for buds and clusters. A page-free Age can also randomly select Crystal Formations; an authored page always retains its exact choice in the saved plan.
Star Fissures are a material-free feature on every terrain profile, including Cave and Void. The fissure is generated once beside the first resolved spawn, using Legacy's spawn-chunk offset and 10–17 paired, irregular X-span rows running along +Z. Legacy's y=0 portal floor maps to the modern dimension's minimum build height, replacing lower bedrock if present. The rift opens to the sky on ordinary terrain; in Cave terrain it opens into the cavern but stops below the upper bedrock roof. Water in the carved columns is cleared before the portal is placed. Its non-solid portal links to the Overworld spawn with the Legacy fissure sound; the animated starfield is drawn with Minecraft's current End Portal renderer, which uses the same end-sky/end-portal art as Legacy's custom renderer. Random Ages sample Legacy's default small-feature grammar for fissure selection: the stop/one/repeat branches have rank-derived weights 1:1:3, and the fissure has weight 1 of 9 among its small-feature rules. The remainder of random feature selection still follows Rivencraft's current pipeline, rather than running Legacy's entire Age grammar.
The Rivencraft symbol-page creative tabs read a generated index of bundled symbol definitions and group Pages by each definition's category, except biome-controller roles, which appear in a separate Biome Generation tab rather than the Biome tab. Adding another valid JSON symbol under src/main/resources/data/rivencraft/rivencraft/symbols/ includes its page in the matching category tab on the next build; a new bundled category receives its own tab. Registry-derived Block and Fluid Pages have separate tabs and both appear in optional JEI. Registry-derived biome pages share a creative/JEI feed; terrablender:deferred_placeholder is excluded because it is TerraBlender's internal staging biome, not a player-facing biome choice. Other modded biomes remain listed. Link Pages have a separate tab. Blank Pages appear in neither the creative tabs nor JEI's ingredient list. The server catalog still decides whether a page is valid for writing. External server data-pack symbols are not included in this bundled index.