Guide

📚 Interactive Books

Direct-from-disk compilation. Multi-book namespaces, zero JAR packing. Full command suite for listing and opening books.

_{sidebar search /guide list /guide open unlock_tag index hot-reload}

🧱 Multiblock Projection

Preview and assemble complex structures step by step.

_{layers rotation zoom progress HUD NBT}

📝 Markdown Engine

Full Markdown rendered live inside the GUI.

_{tables links spoilers items mobs sounds indentation search fulltext}

🎬 Multimedia

Video, GIF and image playback directly in the book.

_{JavaCV FFmpeg GIF WebP URL fullscreen ducking cache}

📔 Explorer’s Journal

A personal notebook stored in the player’s NBT. Notes, live Markdown preview, checklists, tables and spoilers.

_{notes editor preview checklists markdown NBT sync}

🔭 Guide Scanner

Right-click a block, mob, dropped item or fluid to jump straight to the matching chapter.

_{blocks mobs items fluids @bind: @bind_tag: choice screen}

⌨️ Guide Keybinds

Configurable hotkeys to open the book or the journal without touching the inventory.

_{B N rebindable inventory-aware Curios-aware}

🎨 Themes & Backgrounds

Every UI element is themeable via JSON, including chapter backgrounds.

_{per-book colors chapterBackground color image URL effects lock}

🖼️ Universal Images

PNG, JPEG, BMP and GIF supported everywhere — icons, backgrounds, media.

_{PNG JPEG BMP GIF local server URL}

🎒 Curios Integration

Optional. When Curios is installed, the book and journal can sit in the belt slot and appear on your model.

_{belt render optional}

🧩 Mod & Quest Hooks

JEI bindings, in-book checkboxes, server-synced progress.

_{@bind: @bind_tag: quests UUID NBT}

🔒 Book Gating

Hide books until a per-player unlock tag is granted by any command source.

_{unlock_tag KubeJS FTB Quests advancements}

▸ Per-Player Unlock Tags: Add unlock_tag to any book.json and the book stays hidden in the selector until the player holds the matching tag. Perfect for tutorial books, endgame manuals, or story-gated content.

▸ Command-Driven: /guide unlock <tag> and /guide lock <tag> grant or revoke tags; both accept an optional player argument (OP level 2) for admins. /guide unlocks lists your active tags, /guide unlocks clear wipes them all at once.

▸ Modpack-Friendly: Any system that can dispatch a command works — KubeJS events, FTB Quests rewards, advancements, or custom script packs. State is stored per-player in server-side NBT and synced on login and after every change.

▸ Personal Notebook: The guide_diary item opens a private list of notes stored in the player’s NBT. Every note holds a title, a body, a creation / update timestamp, and the coordinates + dimension where it was created. Notes survive relogs, dimension changes and client reinstalls; other players never see them, even on a server.

▸ Editor & Live Preview: The editor is a true multiline text box with cursor navigation, clipboard support (Ctrl+A/C/V/X) and a themed scrollbar you can drag. The preview renders the note the same way the book does — colors, styles, links, tables, dividers, spoilers and checklists — and refreshes with a 200 ms debounce while you type.

▸ Interactive Checklists: Markdown-style checkboxes (- [ ] / - [x]) toggle on left-click inside the preview. State is stored inside the note itself and saved on every click. Completed tasks show a green checkmark and a strikethrough; task color is set with an &-code prefix before the checkbox (&e- [ ], &c- [ ]).

▸ Journal Markdown Support: &0–&f colors, &l/&o/&n/&m styles, &r reset, external links text, dividers (---, &6---, &l&9---), tables with wrap and drag-scroll, spoilers (@spoiler: / @endspoiler), and checklists. The editor converts &x into §x on the fly, so authors never type the section sign directly.

▸ Network Sync: Two payloads keep the journal in sync — a sync payload (server → client, sent on login) and an update payload (client → server, sent on create / update / delete). Last-write-wins conflict resolution, no confirmation roundtrip.

▸ One-Click Lookup: The guide_scanner item resolves the registry ID of a block, mob, dropped item or fluid and looks it up in the same binding map used by JEI and the G-key shortcut (@bind: / @bind_tag:). A single match opens the chapter instantly; multiple matches open a themed selection screen with a collapsible tree — one book expanded at a time, chapters nested underneath, chapter icons shown.

▸ Entity Raycast: Uses a custom AABB-clip raycast so small dropped items and thin hitboxes are detected correctly — vanilla projectile raycast misses them.

▸ Fluid Fallback: Scans water and lava by fluid ID first, then falls back to the bucket ID (water_bucket / lava_bucket) if no binding is found for the fluid itself.

▸ Cumulative Index: The scanner reads from itemToChapterRefMap, a second index that survives book reloads and covers every visible book — no need to open a book first.

▸ Two Hotkeys: B opens the book selector and N opens the journal. Both are bound to the Guide category and can be rebound at any time in Options → Controls → Guide.

▸ Inventory-Aware: Each key only fires if the matching item (guide_book or guide_diary) is in your main inventory, off-hand, or a Curios slot. No item, no action — this prevents bypassing the book gating system with a hotkey.

▸ Direct-from-Disk Compilation: Automatically maps and loads guidebooks from your local machine at config/guide/books/[book_id]/. No more packing files inside mod JAR archives.

▸ Automated Blueprint Generation: On the very first launch, the mod extracts a complete, ready-to-build guidebook template into your config folder, protecting custom assets from being overwritten during modpack updates.

▸ Clean Book Selector: Features a fully responsive book catalog viewport with active filtering, rendering isolated book namespaces cleanly with zero mod-ID conflicts. Book order can be controlled via the optional index field in each book.json.

▸ Runtime Layout Swapping (/guide reload): Edit markdown files, layout nodes, textures, or JSON localization tables on your disk and instantly re-populate the guidebook memory in-game. Available to all players by default with no OP/cheat requirements.

▸ Quick-Access Chat Navigation (/guide): A dedicated chat handle that routes users directly to the main book catalog viewport from anywhere, removing item dependencies.

▸ Book Listing & Direct Open: /guide list prints all books visible to the client (with index, namespace, dev flag and display name); /guide list server shows what the server is distributing; /guide open <namespace> opens any book by ID with tab-completion.

▸ Item Shortcuts: /guide give <book|scanner|diary> [player] spawns the matching Guide item directly into the inventory, falling back to player.drop() when the inventory is full. Includes a 1-second per-player cooldown and tab-completion for aliases and players.

▸ Developer Mode Toggle: Hide instructional manuals or blueprints from players via config/guide/guide-client.toml while keeping them active for developers.

▸ Overhauled Search Box: Equipped with a clean vertical caret (|) that flawlessly executes movement sequences and text selections across both English and Cyrillic keyboard layouts.

▸ Smart Sidebar Sub-Menus: Seamlessly nests dropdown sub-chapters (@submenu:) and spoilers behind clicks, optimizing render framerates and preventing layout clipping.

▸ Unbreakable Tracking & History: Navigation memory locks the expanded state of sidebar submenus, and text hyperlink hitboxes mathematically track lines perfectly under any dynamic scrollbar offset.

▸ Full-Text Search Overlay: The sidebar search scans chapter content, not just titles. Typing a query opens an overlay with snippets around every match, grouped by chapter. Click a snippet to open the chapter, scroll to the matched line, and highlight the query in-place. The sidebar also keeps chapters that only match by content.

▸ In-Chapter Search (Ctrl+F): A browser-style find panel opens at the bottom of the chapter area. Every match is highlighted (active one in a different color); jump between matches with ↑ / ↓ or Enter / Shift+Enter, with a live N / M counter. Spoilers containing a match auto-expand; spoilers without a match stay collapsed. Search highlight colors are themeable via searchHighlightColor and searchHighlightCurrentColor.

▸ Natural Text Indentation Support: The Markdown engine fully respects space and tab blocks at the start of text sequences, allowing for structured nested lists without desyncing hyperlink areas.

▸ Direct Media Streaming: Renders static images (@image:) and animated GIFs (@gif:) straight from the local book directory, completely neutralizing the checkerboard placeholder texture glitch. Supports PNG, JPEG, BMP and GIF (first frame).

▸ 3D Item & Block Models (@item:): Render rotating 3D item and block models inline in the page. Size is per-instance (16–128 px), alignment is configurable (left / center / right), and both flat items and full blocks respect the declared size. Hover for a tooltip with the registry ID and mod name.

▸ Consolidated Multi-Block NBT Projection: The 3D hologram projector (PlacementProjector) and the page renderer (StructureRenderer) compile .nbt blueprints directly from the config folder. Creators can bundle multi-block structures natively into their guides without external datapacks.

▸ Video Playback: Play local and remote video files (mp4, avi, mkv, webm) directly inside guide pages using the @video: command. Supports direct HTTP(S) links with automatic caching, and includes a custom player with play/pause, stop, replay, volume slider, fullscreen, and a draggable progress bar with seek support.

▸ GIF and Image URL Support: Use direct HTTP(S) links in @gif: and @image: to load animated GIFs and static images (PNG, JPEG) from the internet. Files are cached in config/guide/cache/media/ for offline reuse.

▸ Sound Integration: Use the @sound: command to embed clickable sound buttons that play custom audio files from the book’s sounds/ folder. Supports per-page playback with automatic music ducking.

▸ Smart Background Music Ducking: When a video or custom sound starts, the mod automatically pauses background music and restores it after playback ends.

▸ Client-Only Safety: All media decoders, the FFmpeg native library downloader, the JavaCV bridge, and the texture uploader are annotated @OnlyIn(Dist.CLIENT). Dedicated servers never download FFmpeg binaries and never touch client-only video code.

▸ Fully Themeable UI: Every interface element — panels, borders, buttons, scrollbars, tables, media player, projector — is defined by a JSON theme file. Custom themes are placed in config/guide/themes/ (client or server).

▸ Per-Book Overrides: Set a theme field in book.json to force a specific theme for a book; the global theme is restored when the book is closed. Priority: book theme > locked theme > global theme.

▸ Chapter Backgrounds: Themes can override the default chapter background with a chapterBackground block — a solid color (with adjustable alpha) or an image. Images can be a local file, a server-side file, or a direct URL (downloaded and cached automatically).

▸ Built-in Visual Effects: Optional per-theme effects: bloodEffects, forestEffects, cyberTechEffects, matrixEffects, sakuraEffects, honeyEffects.

▸ Live Server-Synced Checkboxes: Features a client-to-server interactive quest system. Quest completions are bound to player UUIDs and securely saved inside the server-side NBT structure, protecting progression files from local data wipes.

▸ JEI Navigation Ready: Bind chapters to specific item entries using @bind:mod_id:item to trigger matching guide pages directly inside JEI, or click guide item passposts to instantly pull up active recipe sheets.

▸ Curios Belt Slot: The book and journal declare compatibility with the Curios belt slot through a data-driven tag. When Curios is installed, the equipped item is rendered on the player’s model, and the B / N keybinds pick it up from there as if it were in the inventory. Curios is a soft dependency — the mod loads and runs fine without it.