Guide

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

📚 Interactive Books Direct-from-disk compilation. Multi-book namespaces, zero JAR packing. _{sidebar search favorites keyboard 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}
🎬 Multimedia Video, GIF and image playback directly in the book. _{JavaCV FFmpeg GIF WebP URL fullscreen ducking cache}	🎨 Themes Every UI element is fully themeable via JSON. _{per-book colors effects lock skinning}	🌍 Localization Each book carries its own translations. _{lang/*.json fallback namespaces runtime}

📚 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 video / sound playback, plus offline media caching.

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
}

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

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

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.

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.

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Links

Tags

Creators

Details

📚 Interactive Books

🧱 Multiblock Projection

📝 Markdown Engine

🎬 Multimedia