rivencraft/docs/LEGACY_M7_AUDIT.md

Milestone 7 Legacy audit

Baseline: Mystcraft Legacy source at 9bc8ddc (0.13.7.06), checked against the local 0.13.7.06 asset/class extraction. Source and reused assets are LGPL-3.0; see asset provenance. This records behavior targets, not byte-for-byte 1.12.2 world generation.

Already implemented

Rivencraft has books, Ages, symbol writing, book stands, a desk, binder, Ink Mixer, link modifiers, safe travel, and optional previews. Crystal Formations, the blue Crystal Block, budding crystals, shards, and Star Fissures were completed in Milestone 5; #76 and #77 must not reimplement them. Vanilla and modern structures are separately page-gated. The Mystcraft library below is neither one of those structures nor a player-authorable page.

Libraries: target for #76

• ChunkProviderMyst installs a scattered-library generator in every Age. MapGenScatteredFeatureMyst picks one candidate per 32×32-chunk region with 0–23 chunk offsets and salt 14357617. Its biome restriction is commented out. There is no Library page and no nearest-structure implementation. Keep automatic sparse placement, modernized for current structure spacing and height APIs, without forcing distant chunks.
• ComponentScatteredFeatureSmallLibrary makes one randomly rotated 11×10×11 building at average ground height, with downward cobblestone supports. Its palette is cobblestone, stone stairs/slabs, cobble walls, planks, bookshelves, webs, and air. Preserve its recognizable shape and interior; define safe placement for Cave/Void/Sky Island terrain rather than fabricating ground.
• Loot placement puts one chest at local (4,1,2) and up to five book-bearing lecterns at (6,2,2), (8,2,4..6), (6,2,8). The treasure table rolls 4–8 plus 1–2 bonus rolls: dynamically registered symbol pages and static vial/booster/leather/paper. LootTableHandler rerolls lectern contents up to 100 times and requires symbol rank ≥3. Use data-driven server loot, document substitutes for unavailable items, and prevent loot duplication after restart.
• The attempted hook into desert pyramid, jungle temple, stronghold library, and dungeon loot uses TreasureGenWrapper, whose addLoot is empty in this revision. It is not evidence that those vanilla chests actually yield pages.

Crystal portals: targets for #77–#78

Library implementation (#76)

The operator-only test controls are /rivencraft library test-spacing 8 (roughly 16× normal candidate density in newly generated chunks), /rivencraft library test-spacing (show the current setting), and /rivencraft library test-spacing reset (return to Legacy spacing). The override affects only the current Age, lasts only until server restart, and never retroactively places libraries in existing chunks. Normal sites remain eligible. A spacing of 1 attempts a candidate in every new chunk and may be expensive. /rivencraft library nearest searches nearby test sites while the override is active. /rivencraft library test-place is a separate OP-only manual test: it places a library about 13 blocks ahead of the player in the current Age if an 11×11×11 volume is clear, building a one-block cobblestone platform below it. The command reports the chest coordinates; it does not alter natural spawning or make the manual library a locate candidate. Move to open ground if the command rejects the site.

Libraries now use Legacy's 32×32-chunk region and 0–23 offset with salt 14357617, one candidate per region. A candidate builds only on a dry, sturdy, nearly level 11×11 surface with clear headroom; its entire rotated footprint stays in that one chunk. Cave terrain is skipped, Void naturally fails the ground check, and Sky Islands can host a library only on a suitable island top. Rejected candidate sites are not retried elsewhere in the region. This is intentionally safer and sparser than cutting through a modern village, tree, ocean, or cliff. The building now places data/rivencraft/structure/mystcraft_library.nbt, generated from all 694 ordered Legacy block placements. The old two-block lectern locations are emptied in the template and replaced at runtime by one-block Rivencraft Book Stands with page loot. The chest is also populated at runtime. Regenerate the template with python scripts/generate_legacy_library_template.py; the script pins and checksums the Legacy source.

The cobblestone supports, stone stairs/slabs, planks, shelves, webs, one chest, and five book stands now follow Legacy's block layout via the packaged template. Players can also place a page on an empty vanilla Lectern, converting it to a Rivencraft Book Stand; sneak-use retrieves the page. The stand renders the page item and its symbol name rather than a book model. libraries.loot_mode is a server config with LEGACY (default) and AGE_ONLY choices. In LEGACY, the chest uses data/rivencraft/loot_table/chests/mystcraft_library.json, with 4–8 main and 1–2 bonus rolls; Rivencraft Ink Vials replace Legacy vials, and ordinary books/experience bottles replace its unavailable booster item. Stands use random catalog symbol pages, excluding generated block/biome entries. In AGE_ONLY, the chest and stands contain only pages from the Age's frozen authored active symbols, or its selected random terrain/features/biome pool; there are no supplies. If an Age has no eligible symbols, the stand falls back to an ordinary book. The Legacy rank ≥3 gate cannot be carried over because Rivencraft symbols have no rank field. A stand's page and Age-only chest pages are saved in block entities; Legacy chests keep their assigned loot table/seed. Neither rerolls on player interaction or restart. Config changes affect only future libraries; existing generated chunks are never retroactively populated.

For a manual check, create a fresh surface Age and run /rivencraft library nearest as an operator. It examines up to 128 deterministic candidates in a six-region radius, one candidate chunk per server tick; this can generate those chunks. It teleports only to a marked intact library with clear floor/headroom, or reports that none was found. Confirm one chest and up to five page-bearing stands, take a page and chest contents, leave/restart, and confirm they do not reappear. Right-click an empty vanilla Lectern with a Symbol Page; it should become a stand displaying that page and symbol name. Sneak-right-click with an empty hand to retrieve it and restore the vanilla Lectern. Switch libraries.loot_mode to AGE_ONLY, create another fresh Age, and confirm its new library contains only pages that describe that Age (no paper, books, ink or bottles); switching modes must not refill an existing library. Repeat with a second player and with Flat, Cave, Void, and Sky Island Ages: only suitable exposed surfaces should host a library. The archived generation GameTest checks deterministic spacing, negative-coordinate regions, the single-chunk footprint, Age-only page filtering, stand storage, and locator marker detection.

• A Book Receptacle attaches to a Crystal Block on any face except downward and holds a Linking or Descriptive Book. The Legacy recipe is eight Crystal Blocks around an empty center. Removing the book or its crystal support deactivates the portal; breaking the receptacle drops the book. TileEntityBookReceptacle activates/shuts down on server-side book changes.
• PortalUtils grows portal cells through a connected crystal network. Its tension test requires opposing crystal/portal neighbors on at least two axes; this is more flexible than a single fixed rectangular frame. Active cells trace a path to one receptacle. Modernize the unbounded flood/path walks with loaded-chunk and volume bounds, server validation, and persistent block-entity state.
• BlockLinkPortal is translucent, non-solid, lit, validated on neighbor changes/random ticks, tinted by the book destination, and routes collisions to the receptacle's book. ItemLinking.onPortalCollision marks travel external, maintains momentum, disables platform generation, and uses the portal sound. The book remains in the receptacle. #77 owns core behavior; #78 owns restart recovery, protection, multiplayer, cooldowns, chunk tickets, and deleted destinations. A buildable portal is distinct from the existing Star Fissure.
• Legacy portal assets include textures/blocks/book_receptacle.png, crystal.png, animated portal.png with its .mcmeta, receptacle/crystal/portal block models and blockstates, textures/entity/linkbook.png, and sounds/linking/link-portal.ogg. Check these before creating art for #80, and add each reused file to provenance. Legacy's rendering pipeline itself cannot be copied unchanged to 1.21.1.

Handheld books and Return Links

ItemLinking.activate calls onLink before travel. If the player uses the exact book in the selected main-hand slot and the Following flag is absent, it removes the book and spawns an EntityLinkbook in the origin world. Following books stay in hand. The entity can be opened, picked up by sneaking with an empty hand, damaged, and collected by a hopper minecart.

Issue #75's comment calls this a despawning drop. The code differs subtly: EntityLinkbook explicitly cannot despawn, but takes one starvation damage every 10,000 ticks and damage while wet. It can eventually be destroyed if left unattended; a vanilla item entity's fixed five-minute timeout is not parity. A modern equivalent should retain the visible book and avoid silently deleting its Age identity at that timeout.

Legacy's travel path creates no automatic Return Link. Rivencraft currently defaults to ON_CREATION via DescriptiveBookItem and descriptive_books.return_link_mode. Per #75's comment, change the new-config default to DISABLED while retaining ON_CREATION and ALWAYS as opt-ins. Existing saved server configs must keep their explicit value. Handheld-book drop and Return Link default are tracked in #85, not portal-frame logic.

Crafting, sounds, and progression

Area	Legacy evidence and modern boundary
Crafting	Legacy recipes specify the Receptacle, Binder, Mixer, Folder, Desk, and other writing blocks. RecipeLinkingbook combines one Link Panel and leather anywhere in the grid. Rivencraft already has Binder, Mixer, Ink Vial, Notebook, Desk, Crystal Block, and Linking Book recipes. #79 adds only missing recipes/processes; preserve vanilla-Lectern conversion, noncraftable Blank Pages, and optional JEI.
Sounds	Sounds registers pop, link, disarm, following, intra-link, fissure-link, portal-link, and meteor roar. The matching OGGs are in the local extraction. Rivencraft already carries link, fissure-link, and meteor roar. #80 should reuse and credit available Legacy files before creating alternatives.
Advancements	Legacy advancement JSONs have inventory milestones for a symbol page, unlinked Linking Book, and Age Book; a Writing Desk trigger; a safe Age-travel trigger; and a hidden Quinn trigger. #81 should use modern server-owned criteria. Quinn has no established Rivencraft equivalent and should be documented or deliberately omitted, not awarded on preview.

Test boundaries and modern adaptations

• #76: deterministic sparse, automatic libraries with the 11×10×11 shape, chest and up to five book stands; test restart and nonstandard terrain without forcing distant chunks.
• #77: receptacle/crystal activation, connected-frame validation, sound/color, travel through the existing book/Age service, and rejection of invalid books or frames.
• #78: full-restart recovery, multiplayer, protection events, loop prevention, destination deletion, and bounded chunk activity.
• #79–#81: data-driven recipes/optional JEI, then assets/audio, then advancements. #82–#83 verify NeoForge 1.21.1 compatibility and a focused manual/automated matrix.
• #85: drop active non-Following books at origin, disable Return Links for new configs, preserve existing config choices, and separately test held, stand, and portal travel.

The 1.21.1 world height, biome/structure APIs, dynamic Age lifecycle, NeoForge protection events, and dedicated-server rendering boundaries preclude direct transplantation of Legacy's 1.12 generator, metadata, and fixed-function portal renderer. Keep those adaptations explicit in follow-up tests and documentation.