Guide

📘 Guide — Universal Documentation System

A lightweight, modular, and highly customizable in-game guide system for Minecraft Forge 1.20.1+.
Perfect for modpack creators, server networks, or custom mod developers — featuring 100% data isolation,
direct-from-disk media streaming, and zero virtual resource pack overhead.

🧱 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, optional visual effects.

📚 Multi-Book Autonomy Direct-from-disk compilation. Automated blueprint generation. Clean book selector with isolated namespaces. config/guide/books/ · namespaces · selector	⚙️ Hot-Reload Pipeline Runtime layout swapping via /guide reload. Quick-access chat navigation. Developer mode toggle. /guide · hot-reload · dev-mode	🧭 Premium Navigation Overhauled search caret with EN/Cyrillic support. Smart sidebar sub-menus. Unbreakable tracking and history. search · @submenu: · history
🧩 Content Rendering Natural indentation. Direct media streaming. Consolidated multi-block NBT projection. @image: · @gif: · NBT	🎬 Built-in Media Video, GIF, image URLs, sounds, and smart background music ducking. @video: · @sound: · FFmpeg · ducking	🔗 Mod & Quest Integration Live server-synced checkboxes. JEI chapter binding via @bind:. UUID-bound · NBT-safe · JEI

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

⚙️ 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.

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

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

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

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

⌨️ 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

▸ Both commands are available to all players by default — no OP or cheat requirements.

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

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

🧩 JEI	Bind chapters to items with @bind:mod_id:item. Click guide item passposts to instantly open recipes.
📝 Flexmark-Java	Full CommonMark-compliant Markdown parsing engine that powers live in-GUI rendering of chapters, tables, links, spoilers, and indentation.
🎬 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/.

📁 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
}

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

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

{
  "id": "standard",                                     // unique theme identifier
  "displayName": "guide.theme.standard",                // display name (plain string or translation key)
  "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

    // ===== 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
  }
}

Color format

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.

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.

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.5.0 · 1.3.0-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.

✦	🧩 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

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.

Made with ❤️ for the Minecraft modding community

© deaddiesel · Guide Mod