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

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

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:

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

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

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

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