Guide

Quick rating

Community listing page, reviews here may not be monitored by the author.

How listings work Are you the author?

Guide

By deaddieselOwner

No reviews yet

An interactive in-game guidebook mod featuring smooth UI rendering, Markdown parsing, and 3D multiblock previews.

Mod Loaders
Minecraft
Hosting Partner

Want to reach Minecraft players?

We're looking for a server hosting partner to feature here and other parts of the site. Interested? Send us a message!

Get in touch

About

Description

Guide — Interactive in-game guidebooks for Minecraft

GitHub release version badge MIT License badge GitHub open issues badge GitHub stars badge

Minecraft Forge 1.20.1 badge NeoForge 1.21.1 badge Java 17 and 21 badge Gradle build badge


🧱 Render complex multiblocks. Parse Markdown right inside the UI.
🎬 Play video, GIFs and images — on Windows, macOS and Linux via FFmpeg.
🎨 Fully customizable themes, per-book overrides, custom colors and chapter backgrounds, optional visual effects.


Download on CurseForge Download on Modrinth View source on GitHub Join the Discord server

Features section

📚 Interactive Books 🧱 Multiblock Projection 📝 Markdown Engine
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		 Preview and assemble complex structures step by step.

layers · rotation · zoom · progress HUD · NBT		 Full Markdown rendered live inside the GUI.

tables · links · spoilers · items · mobs · sounds · indentation · search · fulltext
🎬 Multimedia 🎨 Themes & Backgrounds 🖼️ Universal Images
Video, GIF and image playback directly in the book.

JavaCV · FFmpeg · GIF · WebP · URL · fullscreen · ducking · cache		 Every UI element is themeable via JSON, including chapter backgrounds.

per-book · colors · chapterBackground · color · image · URL · effects · lock		 PNG, JPEG, BMP and GIF supported everywhere — icons, backgrounds, media.

PNG · JPEG · BMP · GIF · local · server · URL

Feature Deep Dive section

🔒 Book Gating

• 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.

• 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.
📚 Multi-Book Config Autonomy

• 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.
⚙️ Hot-Reload & Dev-Friendly Pipeline

• 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.

• Developer Mode Toggle: Hide instructional manuals or blueprints from players via config/guide/guide-client.toml while keeping them active for developers.
🧭 Premium Navigation & Search Caret

• 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.

• 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.

• 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.

• 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.
🧩 Advanced Content Rendering

• 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).

• 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.
🎬 Built-in Media System

• 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.
🎨 Themes & Chapter Backgrounds

• 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.
🔗 Mod & Quest Integration

• 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.

Commands section

Command Description
/guide Open the main book catalog from anywhere — no item required
/guide reload Hot-reload all markdown, textures, JSON and themes without restarting the game
/guide list List all books visible to the client. Click a line to insert /guide open <namespace> into chat; hover for details
/guide list server List books the server is currently distributing. Shows index, namespace, dev marker and disk path in hover
/guide open <namespace> Open a specific book by namespace from chat. Supports tab-completion
/guide unlock <tag> [player] Grant an unlock tag to yourself or another player (OP 2 for other players)
/guide lock <tag> [player] Revoke an unlock tag from yourself or another player (OP 2 for other players)
/guide unlocks List all unlock tags currently held by you

• All commands are available to all players by default — no OP or cheat requirements. Granting or revoking another player's tag requires OP level 2.

Supported Versions section

  Loader Game Version JDK Status Branch
Minecraft Forge logo Forge 1.20.1 1.7.1+ 17 🟢 Stable forge-1.20.1
NeoForge logo NeoForge 1.21.1 1.5.1+ 21 🟢 Stable neoforge-1.21.1

• Both branches share the same feature set — multimedia, Markdown rendering, multiblock projection and book gating are on par.

Integrations section

🧩 JEI Bind chapters to items with @bind:mod_id:item. Click guide item passposts to instantly open recipes.
🎬 FFmpeg / JavaCV / JavaCPP Video decoding, transcoding, and frame-level media access through native FFmpeg binaries, wrapped by JavaCV and bundled via JavaCPP for Windows, macOS, and Linux.
💾 Media Cache Automatic background music ducking during playback, plus offline media caching in config/guide/cache/media/.
🔒 KubeJS / FTB Quests / Advancements Book gating hooks into anything that can dispatch a command. Grant tags with /guide unlock <tag> from KubeJS events, FTB Quests rewards, advancement functions, or script packs.

Directory Structure section

📁 config/guide/books/[book_id]/
┣ 📂 chapters/                 # Content sections directory
┃  ┣ 📄 index.md               # Built-in primary index (English)
┃  ┣ 📄 introduction.md        # Built-in first chapter (English)
┃  ┗ 📂 your_language/         # Language-specific files folder
┃     ┣ 📄 index.md            # Primary index table of contents
┃     ┗ 📄 introduction.md     # Your first guidebook chapter
┣ 📂 lang/                     # Localization files
┃  ┣ 📄 en_us.json             # Localization table for titles and layout indices
┃  ┗ 📄 your_language.json     # Custom language file
┣ 📂 models/                   # Local guidebook 3D model data
┣ 📂 sounds/                   # Background audio assets
┃  ┗ 🎵 your_sound.ogg         # Background music or ambient .ogg file
┣ 📂 videos/                   # Local video files for @video:
┃  ┗ 🎥 your_video.mp4         # Video file playable in the book
┣ 📂 textures/                 # User interface and image assets
┃  ┗ 🖼️ item/your_logo.png     # Local image and animated .gif storage
┣ 📂 structures/               # Structural schematic data
┃  ┗ 🏗️ your_structure.nbt     # Multi-block .nbt blueprint files
┗ 📄 book.json                 # Metadata configuration (Title, catalog icon, namespace)
📄 Example book.json:
{
  "name": "[book_id].book.guide",
  "namespace": "[book_id]",
  "default_chapter": "introduction",
  "icon": "your_logo.png",
  "bg_music": "background_music (without.ogg)",
  "theme": "standard",
  "dev_only": false,
  "index": 0,
  "unlock_tag": ""
}

• index is optional. Books are sorted by it in the selector (lower = earlier). Books without index fall to the end, sorted by namespace.

• unlock_tag is optional. Leave it empty to keep the book public; set a tag (e.g. "secret") to hide the book until the player receives that tag via /guide unlock secret. Tags are per-player and persist across sessions.

Themes section

Every UI element is themeable via JSON. Custom themes live in config/guide/themes/ — copy the template below, change the colors, and save it as a new file (for example, my_theme.json).

Two dedicated colors control both the Ctrl+F panel and the full-text overlay: searchHighlightColor (all matches) and searchHighlightCurrentColor (active match). Built-in palettes ship with tuned defaults per theme.

Each theme can also define its own chapter background — a solid color or an image that replaces the default background for every chapter in books using this theme.

📄 Example standard.json (config/guide/themes/standard.json):
{
  "id": "standard",                                     // unique theme identifier
  "displayName": "guide.theme.standard",                // display name (plain string or translation key)
  "chapterBackground": {                                // optional chapter background override
    "type": "color",                                    // "color" or "image"
    "value": "0x0A0A0A",                                // RGB color (0xRRGGBB) when type = "color"
    "alpha": 230                                        // 0 = transparent, 255 = opaque
  },
  "colors": {

    // ===== General UI =====
    "panelBackgroundColor":         "0xCC1A1A1A",       // panels background (book pages, side menus)
    "panelHeaderBackgroundColor":   "0xCC111111",       // panel header background
    "borderColor":                  "0xFF4A4A4A",       // default border for panels and windows
    "borderFocusedColor":           "0xFF00D0FF",       // focused element border
    "textColor":                    "0xFFFFFF",         // primary text color
    "textSecondaryColor":           "0x888888",         // secondary text
    "scrollbarTrackColor":          "0x55111111",       // scrollbar track background
    "scrollbarThumbColor":          "0xFF8B8B8B",       // scrollbar thumb
    "buttonColor":                  "0xFF2A2A2A",       // default button
    "buttonHoverColor":             "0xFF3A3A3A",       // button on hover
    "buttonDisabledColor":          "0xFF1A1A1A",       // disabled button

    // ===== Input Fields =====
    "editBoxBackgroundColor":       "0xFF000000",       // input field background
    "editBoxBorderColor":           "0xFFA0A0A0",       // input field border
    "editBoxBorderFocusedColor":    "0xFFFFFFFF",       // input field border on focus
    "editBoxTextColor":             "0xFFFFFF",         // input field text

    // ===== Search Highlight (Ctrl+F) =====
    "searchHighlightColor":         "0x80FFEB3B",       // all match highlights
    "searchHighlightCurrentColor":  "0xC0FF9800",       // currently active match

    // ===== Media Player =====
    "mediaFrameOuterColor":         "0xFF2D2D2D",       // media outer frame
    "mediaFrameInnerColor":         "0xFF4A4A4A",       // media inner frame
    "mediaBackgroundColor":         "0xFF000000",       // playback area background
    "mediaControlPanelColor":       "0xCC000000",       // control panel background
    "mediaTextColor":               "0xFFAAAAAA",       // media player text
    "mediaErrorTextColor":          "0xFFFF5555",       // error text
    "mediaTimeTextColor":           "0xFFCCCCCC",       // playback time text
    "progressBarTrackColor":        "0xFF555555",       // progress bar track background
    "progressBarFillColor":         "0xFF00D0FF",       // progress bar fill
    "progressBarThumbColor":        "0xFFFFFFFF",       // progress bar thumb
    "progressBarThumbOutlineColor": "0xFF000000",       // progress bar thumb outline

    // ===== Inline Elements =====
    "spoilerTitleColor":            "0xFFAA00",         // spoiler title
    "inlineItemBackgroundColor":    "0x550A0A0A",       // inline item background
    "inlineItemBorderColor":        "0x25FFFFFF",       // inline item border
    "inlineItemTextColor":          "0xFFAAAAAA",       // inline item text
    "soundButtonBackgroundColor":   "0xFF2E2E2E",       // sound button background
    "soundButtonBorderColor":       "0xFF5A5A5A",       // sound button border
    "soundButtonTextColor":         "0xFFFFFF",         // sound button text
    "questStrikethroughColor":      "0x77777777",       // strikethrough quest text

    // ===== Tables =====
    "tableHeaderBackgroundColor":   "0xFF222222",       // table header background
    "tableHeaderTextColor":         "0xFFAA00",         // table header text
    "tableRowBackgroundColor":      "0x11000000",       // alternating row background
    "tableBorderColor":             "0xFF3A3A3A",       // table borders
    "tableCellTextColor":           "0xFFFFFF",         // table cell text
    "dividerColor":                 "0xFF3A3A3A",       // block dividers

    // ===== Video Title =====
    "videoTitleBackgroundColor":    "0xCC2D2D2D",       // video title panel background
    "videoTitleBorderColor":        "0xFF5A5A5A",       // video title panel border
    "videoTitleTextColor":          "0xFFFFFF",         // video title text

    // ===== Warnings & Toasts =====
    "warningTextColor":             "0xFF5555",         // primary warning text
    "warningTextSecondaryColor":    "0xFFAAAAAA",       // secondary warning text
    "toastBackgroundColor":         "0xD0101215",       // toast notification background
    "toastTextColor":               "0xFFFFFF",         // toast notification text

    // ===== Structure Panel =====
    "structureFrameColor":          "0x4000FFFF",       // 3D structure preview frame
    "structureTabActiveBackgroundColor":   "0xFF555555", // active tab background
    "structureTabInactiveBackgroundColor": "0xFF222222", // inactive tab background
    "structureTabActiveTextColor":         "0x00FFCC",   // active tab text
    "structureTabInactiveTextColor":       "0x888888",   // inactive tab text
    "structureLayerTextColor":             "0x55FF55",   // structure layer label

    // ===== Placement Projector =====
    "projectorPanelBackgroundColor":       "0xD0101215", // projector panel background
    "projectorPanelBorderColor":           "0x4000D0FF", // projector panel border
    "projectorTitleTextColor":             "0x00D0FF",   // projector panel title
    "projectorButtonBackgroundColor":      "0x15FFFFFF", // default button background
    "projectorButtonHoverBackgroundColor": "0x3000D0FF", // button background on hover
    "projectorButtonBorderColor":          "0x25FFFFFF", // default button border
    "projectorButtonHoverBorderColor":     "0xFF00D0FF", // button border on hover
    "projectorButtonTextColor":            "0xBBBBBB",   // button text
    "projectorButtonHoverTextColor":       "0xFFFFFF",   // button text on hover
    "projectorDoneButtonHoverBackgroundColor":   "0x3000FF55", // "Done" button background on hover
    "projectorDoneButtonHoverBorderColor":       "0xFF00FF55", // "Done" button border on hover
    "projectorCancelButtonHoverBackgroundColor": "0x30FF2244", // "Cancel" button background on hover
    "projectorCancelButtonHoverBorderColor":     "0xFFFF2244", // "Cancel" button border on hover
    "projectorHudTextColor":               "0xFFFFFF"    // projector HUD hint text
  }
}
🖼️ Chapter Background (optional)

Add a chapterBackground block to your theme JSON to override the default background (blur on NeoForge, gradient overlay on Forge). Three source types are supported:

// Solid color with alpha (0 = transparent, 255 = opaque)
"chapterBackground": {
  "type": "color",
  "value": "0x1A0F2E",
  "alpha": 230
}

// Local or server-side image (resolved against the current book folder)
"chapterBackground": {
  "type": "image",
  "path": "textures/bg/my_bg.png"
}

// Direct URL (downloaded in background, cached on disk)
"chapterBackground": {
  "type": "image",
  "path": "https://example.com/background.jpg"
}

• Omit chapterBackground entirely to keep the default background. URL images appear with a short delay on first load; subsequent openings use the cache. Supports PNG, JPEG, BMP and GIF (first frame).

Color format section

Colors are written in 0xAARRGGBB format:

Channel Range Description
AA 00 – FF Alpha channel (transparency). FF = fully opaque, 00 = fully transparent
RR 00 – FF Red channel
GG 00 – FF Green channel
BB 00 – FF Blue channel

• Tip: set alpha below FF (e.g. 80) to make panels semi-transparent.

Requirements section

Component Minimum Recommended Notes
Minecraft 1.20.1 · 1.21.1 1.20.1 or 1.21.1 Pick the branch that matches your loader
Loader Forge 47.x+
NeoForge 21.x+		 Latest stable release Only one is required — choose per branch
Java JDK 17
JDK 21		 17 for Forge
21 for NeoForge		 Version must match the loader branch
JEI (optional) — Latest for your MC build Only needed for recipe integration via @bind:

• Guide works standalone — JEI, Quests, and other integrations are entirely optional.

Reporting Issues section

Found a bug or encountered a crash? Open a ticket on the Issue Tracker.

Info required Example
Minecraft version 1.20.1 · 1.21.1
Loader + version Forge 47.4.20+ · NeoForge 21.1.0+
Guide mod version 1.7.1 · 1.5.1-NeoForge
Related mods List of mods that may interact with Guide
Screenshots Attach if the issue is layout-related
Crash report Full latest.log or crash-report in a code block

• The more details you provide, the faster the issue can be resolved.

GitHub Issues CurseForge Comments Discord

Credits section

  Project Author / Team Contribution
🧩 Just Enough Items (JEI) mezz In-game recipe integration
⚒️ Minecraft Forge LexManos · cpw FML ecosystem · MCP tools
🦊 NeoForge NeoForge Team Modern modding platform for 1.21.1
🎬 JavaCV bytedeco Cross-platform Java wrapper for native media libraries
🎬 JavaCPP bytedeco Native bindings & prebuilt binaries for FFmpeg / OpenCV
🎞️ FFmpeg FFmpeg Team Video decoding, transcoding & stream handling
💙 Open Source Community Everyone Bug reports, docs, and support

License section

Licensed under the MIT License — free to use, modify, and distribute in any modpack environment.

You are allowed to include Guide in your modpack.
Any modpack that uses Guide takes full responsibility for user support queries.
We only support official builds, not custom modified jars.

Footer — Made with love for the Minecraft modding community by deaddiesel


Made with ❤️ for the Minecraft modding community

© deaddiesel · Guide Mod

GitHub release version badge MIT License badge GitHub open issues badge GitHub stars badge

Minecraft Forge 1.20.1 badge NeoForge 1.21.1 badge Java 17 and 21 badge Gradle build badge



🧱 Render complex multiblocks. Parse Markdown right inside the UI.
🎬 Play video, GIFs and images — on Windows, macOS and Linux via FFmpeg.
🎨 Fully customizable themes, per-book overrides, custom colors and chapter backgrounds, optional visual effects.


Download on CurseForge Download on Modrinth View source on GitHub Join the Discord server

📚 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

🎨 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

🔒 Book Gating

▸ 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.

▸ 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.

📚 Multi-Book Config Autonomy

▸ 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.

⚙️ Hot-Reload & Dev-Friendly Pipeline

▸ 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.

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

🧭 Premium Navigation & Search Caret

▸ 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.

🧩 Advanced Content Rendering

▸ 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).

▸ 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.

🎬 Built-in Media System

▸ 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.

🎨 Themes & Chapter Backgrounds

▸ 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.

🔗 Mod & Quest Integration

▸ 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.
⌨️ CommandDescription
/guideOpen the main book catalog from anywhere — no item required
/guide reloadHot-reload all markdown, textures, JSON and themes without restarting the game
/guide listList all books visible to the client. Click a line to insert /guide open <namespace> into chat; hover for details
/guide list serverList books the server is currently distributing. Shows index, namespace, dev marker and disk path in hover
/guide open <namespace>Open a specific book by namespace from chat. Supports tab-completion
/guide unlock <tag> [player]Grant an unlock tag to yourself or another player (OP 2 for other players)
/guide lock <tag> [player]Revoke an unlock tag from yourself or another player (OP 2 for other players)
/guide unlocksList all unlock tags currently held by you

▸ All commands are available to all players by default — no OP or cheat requirements. Granting or revoking another player's tag requires OP level 2.

⚙️ Loader🎮 Game📦 Version☕ JDK🚦 Status🌿 Branch
Minecraft Forge logo Forge 1.20.1 1.7.1+ 17 🟢 Stable forge-1.20.1
NeoForge logo NeoForge 1.21.1 1.5.1+ 21 🟢 Stable neoforge-1.21.1

▸ Both branches share the same feature set — multimedia, Markdown rendering, multiblock projection and book gating are on par.

🧩 JEIBind chapters to items with @bind:mod_id:item. Click guide item passposts to instantly open recipes.
🎬 FFmpeg / JavaCV / JavaCPPVideo decoding, transcoding, and frame-level media access through native FFmpeg binaries, wrapped by JavaCV and bundled via JavaCPP for Windows, macOS, and Linux.
💾 Media CacheAutomatic background music ducking during video / sound playback, plus offline media caching.
🔒 KubeJS / FTB Quests / AdvancementsBook gating hooks into anything that can dispatch a command. Grant tags with /guide unlock <tag> from KubeJS events, FTB Quests rewards, advancement functions, or script packs.
 
config/guide/books/<book_id>/
├── chapters/           # Content sections
│   ├── index.md        # Primary index
│   ├── introduction.md # First chapter
│   └── <language>/     # Language-specific files
├── lang/               # Localization
│   ├── en_us.json
│   └── <language>.json
├── models/             # 3D model data
├── sounds/             # Background audio (.ogg)
├── videos/             # Local video files
├── textures/           # UI and image assets
├── structures/         # Multi-block .nbt blueprints
└── book.json           # Metadata
📄 Example book.json:

{
  "name": "<book_id>.book.guide",
  "namespace": "<book_id>",
  "default_chapter": "introduction",
  "icon": "your_logo.png",
  "bg_music": "background_music",
  "theme": "<theme_id>",
  "dev_only": false,
  "index": 0,
  "unlock_tag": ""
}

▸ index is optional. Books are sorted by it in the selector (lower = earlier). Books without index fall to the end, sorted by namespace.

▸ unlock_tag is optional. Leave it empty to keep the book public; set a tag (e.g. "secret") to hide the book until the player receives that tag via /guide unlock secret. Tags are per-player and persist across sessions.

Every UI element is themeable via JSON. Custom themes live in config/guide/themes/ — copy the template below, tweak the colors, and save it as a new file (for example, my_theme.json).

Two dedicated colors control both the Ctrl+F panel and the full-text overlay: searchHighlightColor (all matches) and searchHighlightCurrentColor (active match). Built-in palettes ship with tuned defaults per theme.

Each theme can also define its own chapter background — a solid color or an image that replaces the default background for every chapter in books using this theme.

📄 Example standard.json (config/guide/themes/standard.json):

{
  "id": "standard", // unique theme identifier
  "displayName": "guide.theme.standard", // display name (plain string or translation key)
  "chapterBackground": { // optional chapter background override
    "type": "color", // "color" or "image"
    "value": "0x0A0A0A", // RGB color (0xRRGGBB) when type = "color"
    "alpha": 230 // 0 = transparent, 255 = opaque
  },
  "colors": {

    // ===== General UI =====
    "panelBackgroundColor": "0xCC1A1A1A", // panels background (book pages, side menus)
    "panelHeaderBackgroundColor": "0xCC111111", // panel header background
    "borderColor": "0xFF4A4A4A", // default border for panels and windows
    "borderFocusedColor": "0xFF00D0FF", // focused element border
    "textColor": "0xFFFFFF", // primary text color
    "textSecondaryColor": "0x888888", // secondary text
    "scrollbarTrackColor": "0x55111111", // scrollbar track background
    "scrollbarThumbColor": "0xFF8B8B8B", // scrollbar thumb
    "buttonColor": "0xFF2A2A2A", // default button
    "buttonHoverColor": "0xFF3A3A3A", // button on hover
    "buttonDisabledColor": "0xFF1A1A1A", // disabled button

    // ===== Input Fields =====
    "editBoxBackgroundColor": "0xFF000000", // input field background
    "editBoxBorderColor": "0xFFA0A0A0", // input field border
    "editBoxBorderFocusedColor": "0xFFFFFFFF", // input field border on focus
    "editBoxTextColor": "0xFFFFFF", // input field text

    // ===== Search Highlight (Ctrl+F) =====
    "searchHighlightColor":         "0x80FFEB3B",       // all match highlights
    "searchHighlightCurrentColor":  "0xC0FF9800",       // currently active match
  
    // ===== Media Player =====
    "mediaFrameOuterColor": "0xFF2D2D2D", // media outer frame
    "mediaFrameInnerColor": "0xFF4A4A4A", // media inner frame
    "mediaBackgroundColor": "0xFF000000", // playback area background
    "mediaControlPanelColor": "0xCC000000", // control panel background
    "mediaTextColor": "0xFFAAAAAA", // media player text
    "mediaErrorTextColor": "0xFFFF5555", // error text
    "mediaTimeTextColor": "0xFFCCCCCC", // playback time text
    "progressBarTrackColor": "0xFF555555", // progress bar track background
    "progressBarFillColor": "0xFF00D0FF", // progress bar fill
    "progressBarThumbColor": "0xFFFFFFFF", // progress bar thumb
    "progressBarThumbOutlineColor": "0xFF000000", // progress bar thumb outline

    // ===== Inline Elements =====
    "spoilerTitleColor": "0xFFAA00", // spoiler title
    "inlineItemBackgroundColor": "0x550A0A0A", // inline item background
    "inlineItemBorderColor": "0x25FFFFFF", // inline item border
    "inlineItemTextColor": "0xFFAAAAAA", // inline item text
    "soundButtonBackgroundColor": "0xFF2E2E2E", // sound button background
    "soundButtonBorderColor": "0xFF5A5A5A", // sound button border
    "soundButtonTextColor": "0xFFFFFF", // sound button text
    "questStrikethroughColor": "0x77777777", // strikethrough quest text

    // ===== Tables =====
    "tableHeaderBackgroundColor": "0xFF222222", // table header background
    "tableHeaderTextColor": "0xFFAA00", // table header text
    "tableRowBackgroundColor": "0x11000000", // alternating row background
    "tableBorderColor": "0xFF3A3A3A", // table borders
    "tableCellTextColor": "0xFFFFFF", // table cell text
    "dividerColor": "0xFF3A3A3A", // block dividers

    // ===== Video Title =====
    "videoTitleBackgroundColor": "0xCC2D2D2D", // video title panel background
    "videoTitleBorderColor": "0xFF5A5A5A", // video title panel border
    "videoTitleTextColor": "0xFFFFFF", // video title text

    // ===== Warnings & Toasts =====
    "warningTextColor": "0xFF5555", // primary warning text
    "warningTextSecondaryColor": "0xFFAAAAAA", // secondary warning text
    "toastBackgroundColor": "0xD0101215", // toast notification background
    "toastTextColor": "0xFFFFFF", // toast notification text

    // ===== Structure Panel =====
    "structureFrameColor": "0x4000FFFF", // 3D structure preview frame
    "structureTabActiveBackgroundColor": "0xFF555555", // active tab background
    "structureTabInactiveBackgroundColor": "0xFF222222", // inactive tab background
    "structureTabActiveTextColor": "0x00FFCC", // active tab text
    "structureTabInactiveTextColor": "0x888888", // inactive tab text
    "structureLayerTextColor": "0x55FF55", // structure layer label

    // ===== Placement Projector =====
    "projectorPanelBackgroundColor": "0xD0101215", // projector panel background
    "projectorPanelBorderColor": "0x4000D0FF", // projector panel border
    "projectorTitleTextColor": "0x00D0FF", // projector panel title
    "projectorButtonBackgroundColor": "0x15FFFFFF", // default button background
    "projectorButtonHoverBackgroundColor": "0x3000D0FF", // button background on hover
    "projectorButtonBorderColor": "0x25FFFFFF", // default button border
    "projectorButtonHoverBorderColor": "0xFF00D0FF", // button border on hover
    "projectorButtonTextColor": "0xBBBBBB", // button text
    "projectorButtonHoverTextColor": "0xFFFFFF", // button text on hover
    "projectorDoneButtonHoverBackgroundColor": "0x3000FF55", // "Done" button background on hover
    "projectorDoneButtonHoverBorderColor": "0xFF00FF55", // "Done" button border on hover
    "projectorCancelButtonHoverBackgroundColor": "0x30FF2244", // "Cancel" button background on hover
    "projectorCancelButtonHoverBorderColor": "0xFFFF2244", // "Cancel" button border on hover
    "projectorHudTextColor": "0xFFFFFF" // projector HUD hint text
  }
}
🖼️ Chapter Background (optional)

Add a chapterBackground block to your theme to override the default background (blur on NeoForge, gradient overlay on Forge). Three source types are supported:

// Solid color with alpha (0 = transparent, 255 = opaque)
"chapterBackground": {
  "type": "color",
  "value": "0x1A0F2E",
  "alpha": 230
}

// Local or server-side image (resolved against the current book folder)
"chapterBackground": {
  "type": "image",
  "path": "textures/bg/my_bg.png"
}

// Direct URL (downloaded in background, cached on disk)
"chapterBackground": {
  "type": "image",
  "path": "https://example.com/background.jpg"
}

▸ Omit chapterBackground entirely to keep the default. URL images appear with a short delay on first load; subsequent openings use the cache. Supports PNG, JPEG, BMP and GIF (first frame).

Colors are written in 0xAARRGGBB format:

ChannelRangeDescription
AA00 – FFAlpha channel (transparency). FF = fully opaque, 00 = fully transparent
RR00 – FFRed channel
GG00 – FFGreen channel
BB00 – FFBlue channel

▸ Tip: set alpha below FF (e.g. 80) to make panels semi-transparent.

ComponentMinimumRecommendedNotes
Minecraft1.20.1 · 1.21.11.20.1 or 1.21.1Pick the branch that matches your loader
LoaderForge 47.x+
NeoForge 21.x+		Latest stable releaseOnly one is required — choose per branch
JavaJDK 17
JDK 21		17 for Forge
21 for NeoForge		Version must match the loader branch
JEI (optional)—Latest for your MC buildOnly needed for recipe integration via @bind:

▸ Guide works standalone — JEI, Quests, and other integrations are entirely optional.

Found a bug or encountered a crash? Open a ticket on the Issue Tracker.

Info requiredExample
Minecraft version1.20.1 · 1.21.1
Loader + versionForge 47.4.20+ · NeoForge 21.1.0+
Guide mod version1.7.1 · 1.5.1-NeoForge
Related modsList of mods that may interact with Guide
ScreenshotsAttach if the issue is layout-related
Crash reportFull latest.log or crash-report in a code block

▸ The more details you provide, the faster the issue can be resolved.

✦🧩 Project👤 Author / Team⚡ Contribution
🧩Just Enough Items (JEI)mezzIn-game recipe integration
⚒️Minecraft ForgeLexManos · cpwFML ecosystem · MCP tools
🦊NeoForgeNeoForge TeamModern modding platform for 1.21.1
🎬JavaCVbytedecoCross-platform Java wrapper for native media libraries
🎬JavaCPPbytedecoNative bindings & prebuilt binaries for FFmpeg / OpenCV
🎞️FFmpegFFmpeg TeamVideo decoding, transcoding & stream handling
💙Open Source CommunityEveryoneBug reports, docs, and support

Licensed under the MIT License.

You are allowed to include Guide in your modpack.
Any modpack that uses Guide takes full responsibility for user support queries.
We only support official builds, not custom modified jars.