Runic Tome

[0.5.1] — 2026-08-05

A compatibility and absorption-safety release. Runic Tome now preserves the original stack for recognized books while applying one global exclusion policy before any adapter can consume an item. It combines cross-adapter safety controls with reliable reopening for stateful guide books.

Added

• Centralized absorption policy. AbsorptionPolicy runs before every adapter, so global item, namespace, tag, and synthetic-stack exclusions cannot be bypassed by Patchouli, IMC, datapack, tagged, configured, or heuristic integrations.
• Global item and namespace exclusions. absorbExclusionItems defaults to epicfight:skillbook, and absorbExclusionMods defaults to scriptor. Unlike the heuristic-only blocklists, these settings prevent every adapter from absorbing a matching item.
• Live policy reloads. Loading or reloading the common config rebuilds immutable exclusion snapshots without requiring a game restart.
• Policy maintenance helpers. The policy can find and purge already-unlocked entries that now match a global item or namespace exclusion.
• Expanded /runictome debug identify. Diagnostics now report NBT keys, blocklist-tag state, the global policy decision and reason, the adapter that would claim the item, and the final absorb/no-absorb verdict.

Fixed

• Stateful third-party books now reopen correctly. Absorption retains a one-item copy of the identifying stack, including its NBT, and generic/tagged/item-based adapters replay that exact stack on both logical sides. Previously only the registry id survived, so books whose identity or opening parameters lived in NBT appeared in the list but did nothing when clicked.
• Legacy entries can be repaired by reacquiring the book. If an older save contains a book key without its source stack, absorbing another copy backfills the missing stack and syncs it to the client. Existing key-only saves remain loadable.
• Opening a stored book no longer mutates its saved data. The use simulator works on a defensive one-item copy before adding its internal virtual marker, preserving the retained stack exactly as it was absorbed.
• NBT-bearing functional items are no longer guessed to be documentation. The keyword heuristic rejects stacks with meaningful NBT while allowing ordinary cosmetic/bookkeeping keys such as Damage, RepairCost, HideFlags, and display. Explicit and tagged guide integrations remain available for legitimate stateful books.

Changed

• Book capability data now includes an optional source stack. New saves serialize one retained item per unlocked book; old key-only capability data remains valid and loads without migration.
• Unlock synchronization now carries the retained stack. Newly absorbed and repaired books are immediately usable on the client without requiring a relog or dimension change.
• Stack-aware adapter hooks. Generic, tagged, and item-based adapters replay retained stacks on both logical sides, while existing integrations remain source-compatible through default hooks.
• Network protocol 3. Client and server must both use Runic Tome 0.5.1; mixed versions cannot connect.

Config

• absorbExclusionItems — base item IDs that no adapter may absorb.
• absorbExclusionMods — namespaces whose items no adapter may absorb.
• bookBlocklist and bookBlocklistMods remain heuristic-only controls; use the new global exclusions when an item must remain physical regardless of integration priority.

Upgrade notes

• Replace Runic Tome on both the client and server with 0.5.1.
• Books absorbed before 0.5.1 cannot have already-lost NBT reconstructed automatically. Acquire another copy of an affected book and allow the tome to absorb it once to repair the existing entry.
• Review newly generated absorbExclusionItems and absorbExclusionMods values when carrying forward an older common config.