Guide Tome

One tome. Every manual.

Guide Tome is a Minecraft Forge 1.20.1 mod that gives each player a single, persistent book called the Guide Tome. When a guide book enters your inventory — by pickup, crafting, quest reward, or command — the tome silently absorbs it. The physical book disappears; a new entry is added to your tome's library. Open the tome any time to browse every manual you've ever collected and launch the original book's UI with one click.

No more dragging eight identical lexicons between ender chests. No more losing your "Materials and You" to a lava pocket. One item, forever.

Features

Automatic absorption — never loses a book you don't already have. Guide books are consumed from your inventory the moment they arrive — no interaction required. Works with ground pickup, crafting output, smelting output, container-close (quest rewards, FTB popups, chests), direct inventory grants (KubeJS, /give), and a low-frequency safety sweep (configurable). A book is only ever removed once it's confirmed stored in your tome — if storage fails, the item is left untouched. Absorption is deduplicating. Exactly one copy of each book is ever retained, and extraction always returns one copy. What happens to the rest of a stack is controlled by absorbWholeStack (default true, matching every release before 0.6.0): absorbing a stack of eight identical lexicons stores one and destroys the other seven, and picking up a book you already have consumes it outright. Set absorbWholeStack = false to consume exactly one item per newly-unlocked book and leave the extras physical — duplicates of a book you already own are then never consumed at all.
Add books deliberately, by crafting. Put the Guide Tome and one or more books together in any crafting grid -- the 2x2 inventory grid or a 3x3 table -- and the output is the tome with those books filed into your library. Because it is an explicit act rather than an ambient sweep, this is the one channel that accepts a book you previously extracted, and the only way to store vanilla books: book, writable_book, written_book, enchanted_book and knowledge_book are never absorbed automatically. Each stack becomes its own entry, so two written books with different titles are two rows, and Extract returns the exact original item. An unrecognized item anywhere in the grid makes the recipe produce nothing, so nothing is ever consumed by surprise.
Wearable with Curios (optional). With Curios installed the tome gets its own guide_tome slot with a matching book icon, so it stops occupying an inventory slot for the entire game. It stays in the slot through death regardless of keepInventory, and newly granted tomes go straight there when the slot is free. Curios is entirely optional — without it nothing changes.
Virtual storage. Unlocked books live in a per-player server-side capability, persisted to disk and synced to the client. No duplicated ItemStacks, no inventory clutter. Corrupt or outdated entries are skipped on load rather than breaking your save.
Searchable library UI. The tome opens to a scrolling list of your books with their real item icons and a live count. Search by name, favorite any book (right-click) to pin it to the top, and left-click to launch the original book's native GUI. A book that fails to open tells you why instead of silently doing nothing.
Physical extraction. Click Extract beside an entry to return one physical book with its retained data and remove it from the virtual library. Extracted copies carry a persistent marker that exempts them from automatic re-absorption — including after an inventory-full drop, and for any other player who later picks them up. The exemption survives everything short of an explicit operator command: nothing in normal play clears it, so extract only what you want to keep physical. An operator holding the book can undo a mistaken extraction with /guidetome unmark.
Copies, for shelves and libraries. Click Copy beside an entry to print a spare without giving the entry up. It costs bookCopyCost vanilla books (default one, and nothing at all in creative), and the copy carries the same never-re-absorb marker an extracted book does — which is the point: an unmarked duplicate of a book already in your library would be swallowed by the next inventory sweep about a second later. Copy is what you want for decorating a library room with item frames, lecterns and shelves; Extract is what you want for actually removing a book from the tome.
Pause absorption when you need to. The Absorb: On / Off button at the bottom of the tome screen stops the tome taking books you pick up, craft or carry, so you can sort a chest of dungeon loot in peace. It is per-player, survives death and relogging, and does not block deliberate absorption — crafting a book into the tome still works while paused, as does /guidetome unlock.
Patchouli support — zero compile-time dependency. Guide Tome uses reflection to detect Patchouli at runtime and recognise both flavors of Patchouli books:
- Generic patchouli:guide_book stacks with {patchouli:book: "modid:book_id"} NBT (fast NBT match).
- Custom-item books declared with dont_generate_book: true (e.g. Ars Nouveau's Worn Notebook, Botania's Lexica Botania) — resolved by walking BookRegistry and mapping the book's item to its ID. Opening a custom book replays the item's right-click on both sides so first-use effects (advancements, sounds) fire exactly as they would in the hand.
Built-in integrations. Tinkers' Construct (all six books), Minecraft Comes Alive, Better Animals Plus, Immersive Engineering (manual), Modonomicon, Integrated Dynamics, and EvilCraft are detected and registered automatically when loaded — plus a keyword catch-all that absorbs guide books from mods with no explicit support.
Config- and datapack-driven long tail. Modpack authors can add any standalone book-like item via extraBookItemIds in guidetome-common.toml, or define books in a datapack at data/<namespace>/guidetome/books/*.json — no code, and datapack books sync to clients on dedicated servers.
Public API & IMC. Other mods can register their own GuideSystemAdapter via the public GuideTomeAPI.registerAdapter(...) or via Inter-Mod Communication — including the register_book IMC message with an ImcBook payload for a single openable book.
Audit your pack before it costs a player anything. /guidetome debug scan sweeps every registered item and reports exactly what your current configuration would absorb, grouped by adapter and by mod, plus the items an adapter wanted but a global exclusion protected. Run it after changing the config or adding mods instead of finding out when someone loses a functional book.
Given on first join. The tome is granted automatically the first time a player joins a world — no crafting required. It is granted once; a player who destroys it can be given another with /guidetome give.

What the Tome absorbs

The Guide Tome is a library for persistent documentation — game manuals, mechanics guides, lore books, handbooks. It does not absorb:

Spell scrolls, spellbooks, or skill upgrade items
Learning/XP books or one-time consumable knowledge items
Functional or interactive book-shaped tools and gear
Damageable items or items with live enchantments

A structural safety layer, separate from adapters and tags, vetoes absorption of damageable items, enchanted items, edible items, and (when Iron's Spells 'n Spellbooks is installed) its scrolls (IScroll), spellbooks (SpellBook), and spell containers (ISpellContainer.isSpellContainer). This gate runs before any adapter or the positive #guidetome:guide_books tag and cannot be overridden — not by configuration, not by crafting, not by any adapter priority.

The heuristic catch-all skips items whose registry path contains functional keywords (spell, scroll, caster, focus, rune, wand, skill, level, experience, xp, summon, ability, upgrade, necromancer). This is advisory only and can be overridden by the #guidetome:guide_books tag for a legitimately-named guide the heuristic rejected.

Reabsorbing extracted books

Extracted and copied books carry a persistent marker that exempts them from automatic re-absorption. To return an extracted book to the tome:

Craft it with the Guide Tome in any crafting grid (2x2 inventory or 3x3 table), or
Sneak-use the Guide Tome held in the main hand with the extracted book in the offhand.

The sneak gesture consumes the book only when it was actually stored. If the book is already in the tome, the gesture tells you so and leaves the item. Functional items and unrecognized items are refused with an explanation message.

Extracted copies show a tooltip explaining the marker and both recovery paths.

Installation

For players

Install Minecraft Forge 47.3.0+ for Minecraft 1.20.1.
Download the latest guidetome-<version>.jar from the Releases page or CurseForge.
Drop the jar into your mods/ folder.
Launch Minecraft. The tome will appear in your inventory the first time you join a world.

On a server, install the same version on both sides. Guide Tome negotiates a network protocol version at login, and a mismatch is refused rather than silently tolerated. 1.0.0 uses protocol 6, unchanged since 0.9.0; 0.6.0-0.8.x used 5, so a 1.0.0 client cannot join a 0.8.x server or vice versa.

For modpack authors

Guide Tome works out of the box with no configuration, but you can customise its behaviour via config/guidetome-common.toml:

[absorption]
    absorbOnPickup = true          # Absorb guide books picked up from the ground
    absorbOnCraft  = true          # Absorb crafted/smelted guide books
    # true  = consume the whole source stack (one copy is kept, the rest destroyed)
    # false = consume one item per newly-unlocked book and leave the extras physical
    absorbWholeStack = true

    # Tome + book(s) in a crafting grid -> the tome, with the books added.
    # Also accepts books that were previously extracted from the tome.
    absorbViaCrafting = true
    # Let that recipe accept vanilla books (book, writable_book, written_book,
    # enchanted_book, knowledge_book). They are never absorbed ambiently.
    # To allow written books but not enchanted ones, leave this on and add
    # minecraft:enchanted_book to the #guidetome:absorb_blocklist item tag.
    craftingAcceptsVanillaBooks = true

[integrations]
    # Extra item IDs to treat as single-item guide books.
    # Unknown or malformed IDs are logged and skipped.
    extraBookItemIds = [
        "occultism:dictionary_of_spirits",
    ]

    # Keyword catch-all: absorb any item whose registry path matches a
    # documentation keyword. Disable to absorb only explicitly-supported books.
    absorbUnknownBooks = true

    # Mod IDs the catch-all never touches, for mods whose "book"/"tome" items are
    # functional gear rather than documentation.
    bookBlocklistMods = ["irons_spellbooks", "ars_nouveau", "scriptor"]

    # Individual item IDs the catch-all never absorbs (vanilla books are blocked already).
    bookBlocklist = []

    # Extra global exclusions. Built-in audited safety entries remain active even
    # when an older common config does not contain them.
    absorbExclusionItems = []      # Extra item IDs no adapter may absorb
    absorbExclusionMods = []       # Extra namespaces no adapter may absorb

[ui]
    showUnlockToast = true         # DEPRECATED — moved to guidetome-client.toml (see below)
    allowBookExtraction = true     # Let players return entries to physical items
    allowBookCopying = true        # Let players duplicate an entry, keeping the entry
    bookCopyCost = 1               # Vanilla books charged per copy (0 = free)

[performance]
    # How often (in server ticks) the inventory-sweep fallback runs.
    # Pickup/craft/smelt/container-close are handled separately and always
    # absorb immediately. Set to 1 to restore legacy per-tick sweeping.
    # Players are staggered across the interval rather than all swept on one tick.
    sweepIntervalTicks = 20

    # Server-side cap on favorite toggles per player per second. 0 disables it.
    maxFavoriteTogglesPerSecond = 20

[items]
    grantTomeOnFirstJoin = true    # Give the tome on first login (off for quest-kit servers)

[debug]
    verboseLogging = false         # Extra logging for capability sync and adapter resolution

Per-player display preferences live in config/guidetome-client.toml:

[ui]
    showUnlockToast = true         # Toast notification when a new book is absorbed

showUnlockToast moved in 0.6.0. It is a per-player display preference, and Forge never syncs COMMON configs, so setting it on a dedicated server never affected any player. It now lives in the client config. The old common option is still read for one release so an existing false is not silently reset — while both exist, a false in either file suppresses the toast. Set the client option; the common one will be removed in a future release.

Pickup, crafting, smelting, and container-close absorb books the instant they arrive. The timer-driven sweep runs once per second by default (sweepIntervalTicks = 20) as a safety net for inventory inserts that bypass Forge events (/give, quest-reward grants, direct KubeJS inserts).

When config changes take effect. Every option above is applied on config load and on config reload — including extraBookItemIds, absorbUnknownBooks, bookKeywords, bookBlocklist and bookBlocklistMods, whose adapters are rebuilt from scratch each time. Removing an entry removes its adapter; setting absorbUnknownBooks = false removes the keyword catch-all. Books already absorbed under an older configuration are not revoked — use /guidetome purge for that.

Usage

Join a world. A Guide Tome appears in your inventory.
Pick up, craft, or receive any supported guide book. It is absorbed near-instantly.
To add a book on purpose -- a vanilla written or enchanted book, or one you extracted earlier -- put it in a crafting grid alongside the tome and take the tome back out.
Right-click the Guide Tome (or press the bound key) to open your library.
Type in the search box to filter, left-click an entry to launch its native book UI, right-click to favorite it, click Copy to print a spare, or click Extract to return one physical copy.
Scroll through the list. Click Absorb: On / Off to pause absorption, then press Escape or click Done to close.

The tome itself has EPIC rarity, stacks to 1, and is fire-resistant — losing it is hard, but even if you do, your unlocked books are stored per-player and survive death, item loss, and the loss of the tome.

Supported mods

Out of the box:

Patchouli (and every mod that ships a Patchouli book — Botania, Ars Nouveau, Ice & Fire Delight, etc.)
Tinkers' Construct (all six standard books)
Minecraft Comes Alive, Better Animals Plus, Immersive Engineering (manual), Modonomicon
Integrated Dynamics — "On the Dynamics of Integration"
EvilCraft — "Origins of Darkness"
Iron's Spells 'n Spellbooks — scrolls, spellbooks and spell containers are structurally protected from absorption and never stored, even if misconfigured
A keyword catch-all that absorbs guide books from mods with no explicit support (configurable; see absorbUnknownBooks). It skips block items, vanilla books, blocklisted namespaces, stateful NBT stacks, and names associated with spells, skills, leveling/XP, summoning, abilities, or upgrades, so functional "tome"/"book" gear is left alone.

Permanent hard exclusions (at the structural level, before any adapter runs) protect damageable items, enchanted items, edible items, and a curated list covering functional books from Midnight Apocalypse, Runic Skills, Legendary Additions, Alex's Caves, and many others. These built-in protections remain active when upgrading with an older common config.

Additional books can be enabled via extraBookItemIds in the config or a datapack (data/<namespace>/guidetome/books/*.json). For mod authors building new integrations, see Integration API below.

The Curios slot

With Curios installed the tome gets a dedicated guide_tome slot. It is declared purely in data, so a pack can change it without code:

File	Purpose
`data/guidetome/curios/slots/guide_tome.json`	Slot definition — `order`, `icon`, `drop_rule`
`data/guidetome/curios/entities/player.json`	Attaches the slot to players
`data/curios/tags/items/guide_tome.json`	Which items the slot accepts

Override any of them from a datapack to retexture the icon, move it in the slot order, or drop the slot entirely. Note the slot id is global across mods, and that drop_rule is also declared on the item itself as ALWAYS_KEEP, so removing it from the slot JSON alone will not make the tome droppable on death.

Curios is optional. Without it these files load into nothing and the tome behaves exactly as before.

Forcing or preventing absorption

The structural safety layer runs first and is never overridden: damageable items, enchanted items, edible items, and (when Iron's Spells 'n Spellbooks is installed) its scrolls, spellbooks and spell containers are never absorbed, period. Not by the positive tag, not by config, not by any adapter.

After that gate, two append-friendly item tags give packmakers explicit control over the catch-all, taking precedence blocklist > positive tag > heuristic:

#guidetome:guide_books — force-absorb an item the heuristic would otherwise skip (e.g. a legitimately-named book the looksFunctional check rejects). This tag cannot override the structural safety layer.
#guidetome:absorb_blocklist — hard opt-out; an item here is never absorbed by any adapter, even if it is also in guide_books. The blocklist applies at the policy level and overrides every adapter.

Both ship empty ("replace": false); add entries from a datapack at data/guidetome/tags/items/<tag>.json. For hard, cross-adapter namespace-level exclusions, use absorbExclusionMods; bookBlocklistMods is heuristic-only.

Players have two controls of their own that need no config at all: the Absorb: On / Off toggle in the tome screen pauses ambient absorption for that player, and any book produced by Copy or Extract is permanently exempt from re-absorption. Note that absorbOnPickup = false alone does not stop the periodic inventory sweep — the player toggle and the exemption marker do.

Auditing a modpack

The keyword catch-all is deliberately broad, so the safety question for a pack is "which items in my pack does my configuration actually absorb?" Answer it before shipping:

Start the pack and run /guidetome debug scan. It classifies every registered item through the same code path absorption uses, and prints how many items would be absorbed, broken down by adapter and by mod.
Read the full report it writes to guidetome-scan.txt in the server directory. Items are grouped by mod, each naming the adapter that would claim it, followed by the items an adapter claimed but a global exclusion protected — that second list is what your exclusion entries are currently buying you.
Anything in the first list that is functional gear rather than documentation goes into absorbExclusionItems / absorbExclusionMods (hard, all adapters) or the #guidetome:absorb_blocklist tag.
Re-run the scan. Config changes apply on reload, so you do not need to restart between passes.
Use /guidetome debug identify while holding a specific item to see why one particular item is or isn't classified as a book, and /guidetome debug scan <namespace> to review a single mod in chat.

If a functional book was already absorbed before you excluded it, /guidetome purge lists the affected library entries and purge confirm removes them.

Commands

/guidetome (requires permission level 2). Every player-scoped subcommand takes an optional <target> player, so operators can inspect and repair another player's library from the server console. Omit it to act on yourself. All output is localized.

list [<page>] / list <target> [<page>] — list unlocked books, 20 per page, favorites marked. A bare number is read as a page and a name as a player; a player whose name is only digits is reachable with a selector such as @a[name="5"].
give [<target>] — grant a Guide Tome.
unlock <system> <book> [<target>] / lock <system> <book> [<target>] — add or remove a book entry.
purge [<target>] — list library entries that the current global exclusion lists would no longer absorb (matched by book id and by retained stack). purge confirm [<target>] removes exactly the entries that were listed. Entries with no retained stack (legacy key-only entries) cannot be recovered and remain a purge matter. This is the destructive path; for items that can be returned, use recover instead.
recover [<target>] — list library entries that the current exclusion rules no longer permit, typically functional books absorbed before 1.0.1's structural safety. recover confirm [<target>] returns each as a physical item (marked as extracted, so it will not be re-absorbed) and removes the entry only after delivery succeeds. This is the non-destructive answer when a good item was absorbed under older rules.
unmark [<target>] — clear the extraction exemption from the held book so it can be absorbed again. The only thing that clears the marker; use it to undo a mistaken extraction.
debug dump — list every registered adapter with its priority.
debug identify [<target>] — explain how the held item would be classified: its id, extraction marker state, absorb_blocklist and #guidetome:guide_books membership, the functional-item verdict and reason, the first adapter that would match (and, for the catch-all, which keyword matched), and a final absorb/no-absorb verdict. For Patchouli books, also reports the book form (generic/custom), the open strategy and the resolved opener item. The fastest way to diagnose why a book is or isn't being absorbed.
debug scan [<namespace>] — audit the whole pack before players lose anything. Sweeps every registered item and reports exactly what the current configuration would absorb, grouped by adapter and by mod, distinguishing hard exclusions, functional-item exclusions, heuristic rejections, and unrecognized items. Writes the full report to guidetome-scan.txt in the server directory; pass a namespace to list one mod's items in chat. Run this after changing the config or adding mods.

Integration API

Guide Tome exposes a small public API for third-party mods to register their own guide systems.

Via direct API call (requires Guide Tome as a compile dependency)

import com.otectus.guidetome.api.GuideTomeAPI;
import com.otectus.guidetome.api.GuideSystemAdapter;

GuideTomeAPI.registerAdapter(new MyGuideAdapter());

A GuideSystemAdapter provides:

systemId() — a unique ResourceLocation identifying your guide system.
identify(ItemStack) — returns an Optional<BookKey> if the stack represents one of your books.
open(BookKey, Player) — opens the book's native UI client-side.
displayName(BookKey), displayIcon(BookKey) — for the tome's library listing.
Optional: supportsBulkEnumeration() + enumerateAll() to list all known books (used for the "all" tab if you add one).

Via IMC (no compile dependency on Guide Tome)

// Register a whole guide system:
InterModComms.sendTo("guidetome", "register_adapter", () -> myAdapterInstance);

// Or register a single openable book (the item is used as icon and opened via its use()):
InterModComms.sendTo("guidetome", "register_book",
        () -> new ImcBook(new BookKey(systemId, bookId), new ItemStack(myBookItem)));

The register_adapter payload must implement GuideSystemAdapter; register_book accepts an ImcBook (or a plain BookKey for a message-only entry). Use GuideTomeAPI.API_VERSION to check compatibility. See ImcHandler.java for details.

Building from source

git clone https://github.com/otectus/guide-tome.git
cd guide-tome
./gradlew build

The jar will be placed in build/libs/. Every push and pull request is built and tested by .github/workflows/build.yml.

Builds are reproducible: archives use a fixed file order and no file timestamps, and the jar manifest carries an Implementation-Timestamp only when SOURCE_DATE_EPOCH is set (as CI does, from the commit date). Identical sources therefore produce an identical jar.

For a development client:

./gradlew runClient

Architecture

For a deep dive into the mod's internals — capability design, server-authoritative filtering, adapter registry, reflective Patchouli integration, and more — see GUIDE-TOME-ARCHITECTURE.md.

License

MIT — see LICENSE. You are free to use, modify, and redistribute this mod, including in modpacks, provided attribution is preserved.

Credits

Otectus — author, code, design.
vazkii — for Patchouli, the book framework this mod plays so well with.
The Forge MDK, Parchment mappings, and the Minecraft Forge community.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
gradle/wrapper		gradle/wrapper
src		src
tools/gui		tools/gui
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CURSEFORGE_DESCRIPTION.md		CURSEFORGE_DESCRIPTION.md
LICENSE		LICENSE
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
guide-tome.png		guide-tome.png
settings.gradle		settings.gradle

Navigation Menu

Repository files navigation

Guide Tome

Features

What the Tome absorbs

Reabsorbing extracted books

Installation

For players

For modpack authors

Usage

Supported mods

The Curios slot

Forcing or preventing absorption

Auditing a modpack

Commands

Integration API

Via direct API call (requires Guide Tome as a compile dependency)

Via IMC (no compile dependency on Guide Tome)

Building from source

Architecture

License

Credits

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Guide Tome

Features

What the Tome absorbs

Reabsorbing extracted books

Installation

For players

For modpack authors

Usage

Supported mods

The Curios slot

Forcing or preventing absorption

Auditing a modpack

Commands

Integration API

Via direct API call (requires Guide Tome as a compile dependency)

Via IMC (no compile dependency on Guide Tome)

Building from source

Architecture

License

Credits

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages