Patchouli Mod Wiki

Patchouli is a utility mod designed to provide easy-to-implement, data-driven documentation for Minecraft. Inspired by the Lexica Botania, it allows creators to build beautiful, interactive books without writing a single line of Java code. It is widely used by major mods like Quark, Botania, and Immersive Engineering to provide in-game manuals.

Key Features

• Data-Driven Content: All books, categories, and entries are defined using JSON files.
• In-Game Editor: Includes a built-in text previewer and editor for real-time formatting.
• Rich Text System: Supports colors, bolding, italics, and custom macros.
• Advancement Integration: Content can be locked until the player completes specific advancements.
• Multiblock Visualization: Allows players to project a "ghost" version of a structure into the world to assist with building.
• Localization: Full support for translating books into multiple languages.

Patchouli adds a single primary item that serves as the framework for all in-game documentation.

The Guide Book

• Item ID: patchouli:guide_book
• Properties: The Guide Book is a dynamic item. By itself, it is empty. It becomes a specific mod's manual when assigned a patchouli:book NBT tag.
• Crafting: While Patchouli does not provide a default recipe, most modpacks and mods add a simple recipe (e.g., a Book + a Lever or a Book + a Sapling) to grant the player the specific manual.

Blocks

Patchouli does not add any world-gen blocks or decorative blocks. It functions entirely as a library and UI-based mod. However, it can document every block from every other mod installed in the game.

Patchouli books are organized into a hierarchy of Categories, Entries, and Pages.

1. Categories: The top-level folders that group related topics (e.g., "Basics", "Tools", "Magic").
2. Entries: Individual articles within a category (e.g., "How to Mine", "The Iron Golem").
3. Pages: The actual content of an entry. An entry can have an unlimited number of pages.

Page Types

Patchouli includes several built-in page types to display different kinds of information:

• Text Page (patchouli:text): Displays formatted text. If it's the first page, it shows the entry title.
• Image Page (patchouli:image): Displays one or more images with an optional caption.
• Crafting Page (patchouli:crafting): Displays a 3x3 crafting recipe. Supports JEI integration.
• Smelting Page (patchouli:smelting): Displays a furnace/smelting recipe.
• Multiblock Page (patchouli:multiblock): Displays a 3D structure and allows the player to visualize it in the world.
• Entity Page (patchouli:entity): Renders a live 3D model of a mob or entity.
• Spotlight Page (patchouli:spotlight): Highlights a specific item and provides text about it.
• Quest Page (patchouli:quest): Displays a task that is marked as "complete" when a specific advancement is earned.

One of Patchouli's most powerful features is the ability to help players build complex structures. When viewing a Multiblock Page, players can click a button to "Visualize" the structure.

How it Works

• Ghost Blocks: A translucent version of the structure appears in the world at the player's cursor.
• Placement Guide: As the player places the correct blocks, the ghost blocks disappear.
• Rotation: Players can rotate the visualization to fit their desired orientation.
• Validation: The system checks if the blocks placed match the required block states (including NBT and properties).

Patchouli uses a custom formatting system to style text within books. These codes are placed directly in the JSON strings.

Common Formatting Codes

Macros

Creators can define custom macros to simplify long formatting strings. For example, a macro $(item) could be set to $(c:blue)$(bold) to highlight item names consistently.

Patchouli provides several commands for administrators and book creators to manage documentation in-game.

Commands

• /patchouli reload: Reloads all book data from the patchouli_books folder. Essential for testing changes without restarting the game.
• /patchouli open <book_id>: Forces the specified book to open for the player.
• /patchouli set_flag <flag> <true/false>: Manually toggles a configuration flag for the current session.

Configuration

Configuration is handled via the patchouli-client.toml and patchouli-server.toml files.

• Disable Advancement Locking: If set to true, all entries in all books will be visible regardless of the player's progress.
• Inventory Button: Adds a small button to the player's inventory screen that opens a designated "Main" guide book.
• Testing Mode: Enables additional debug information for book creators, such as showing the internal IDs of entries on hover.

For modpack makers (versions 1.20.1, 1.21.1), Patchouli content is stored in the following directory: instance/patchouli_books/<your_book_name>/

Inside this folder, the structure must follow this pattern:

• book.json: Defines the book's name, landing page text, and visual style.
• en_us/categories/: Contains JSON files for each category.
• en_us/entries/: Contains JSON files for each entry.
• en_us/templates/: Contains custom page layouts.

Note for 1.20+: Patchouli now enforces the use of the Resource Pack system. While the book.json remains in the data folder, all content (entries and categories) should be placed in the assets folder of your mod or resource pack to ensure proper loading and compatibility.