GuideBook Mod Wiki

The GuideBook Mod serves as a powerful framework for creating in-game manuals and documentation. Unlike standard written books, GuideBook utilizes an XML-based system to handle complex layouts, including formatted text, images, item renders, and interactive recipes. It is designed to be lightweight and highly compatible, making it a staple for modpack creators who need to explain complex mechanics or progression systems to players.

Key Features

• XML-Driven Content: All book data is stored in easy-to-edit XML files.
• Hierarchical Structure: Content is organized into Books, Chapters, Sections, and Paragraphs.
• Automatic Pagination: The mod automatically handles text flow and page breaks.
• Recipe Integration: Display crafting, smelting, and other machine recipes directly in the book.
• Conditional Visibility: Hide or show content based on installed mods or a player's progress (via Game Stages).
• Hyperlinks: Navigate between sections, open external URLs, or copy text to the clipboard.

While GuideBook is primarily a library for other mods, it includes a base item that players can use to access registered guides. In many modpacks, this item is provided to the player upon spawning or can be crafted manually.

Crafting Recipe

To create the basic Guidebook, combine a standard Book with a Crafting Table in any crafting grid.

Usage

• Right-Click: Opens the Guidebook interface. If multiple books are registered in the modpack, a selection screen will appear.
• Search Bar: Modern versions of the mod include a search bar at the top of the interface to quickly find specific chapters or items.

GuideBook uses a strict hierarchy inspired by HTML. Files are typically located in config/guidebook/ or within a mod's assets folder at assets/modid/guidebooks/.

Core Hierarchy

1. <book>: The root element containing the entire guide.
2. <chapter>: Groups related sections together (e.g., "Getting Started").
3. <section>: Represents a specific topic or page.
4. <paragraph>: The basic unit of text. Supports automatic wrapping.
5. <span>: Used for inline styling and formatting.

Common Attributes

Text within a GuideBook can be styled using the <span> tag or standard Minecraft color codes.

Text Styles

The following attributes can be applied to a <span> tag:

• color: Hex code (e.g., #FF0000) or Minecraft color names.
• bold: true / false
• italic: true / false
• underlined: true / false
• strikethrough: true / false
• obfuscated: true / false (Magic text)

Example Syntax

<paragraph>
 <span color="gold" bold="true">Important:</span> 
 This is a styled sentence within the guide.
</paragraph>

GuideBook allows for rich interactivity beyond simple text reading.

Displaying Items

Use the <item> tag to render a 3D item stack directly on the page.

• Attributes: id (Item ID), count (Quantity), nbt (NBT data string).

Images

Custom textures can be embedded using the <image> tag.

• Attributes: src (Resource location, e.g., modid:textures/gui/image.png), width, height.

Hyperlinks

Links can be used to navigate the book or interact with the system.

• Internal Link: <link target="section_id">Click here</link>
• Web Link: <link url="https://example.com">Visit Website</link>
• Clipboard: <link clipboard="/give @p stone">Copy Command</link>

One of the mod's most powerful features is the ability to pull recipes directly from the game's registry. This ensures that if a modpack changes a recipe, the guidebook updates automatically.

Recipe Tag

• By Output: <recipe output="minecraft:furnace" /> — Displays the first found recipe that results in a furnace.
• By Key: <recipe key="minecraft:stick" /> — Displays a specific recipe by its registry name.

Supported recipe types include standard Crafting (Shaped/Shapeless), Smelting, Blasting, Smoking, and Campfire Cooking. Modded recipe types may require additional compatibility layers depending on the mod version.

Element Conditions

Content can be dynamically hidden based on certain criteria using the condition attribute. This is widely used in "Expert" modpacks to hide information until a player reaches a certain milestone.

• Mod Presence: condition="mod:jei" (Only shows if JEI is installed).
• Game Stages: condition="gamestage:stage_name" (Requires the Game Stages mod).

Template System

Templates allow creators to define a layout once and reuse it across multiple pages. This is ideal for bestiaries or item catalogs where the format remains consistent but the data (name, image, description) changes.

Localization

GuideBook supports standard Minecraft .lang and .json localization files. Instead of hardcoding text in the XML, creators can use translation keys (e.g., guide.modid.welcome) to support multiple languages.

The mod's behavior can be tweaked via the guidebook-client.toml and guidebook-common.toml files located in the config folder.