Patchouli Documentation

An entry's ID is the path required to locate it starting from /en_us/entries. For example, an entry located at /en_us/entries/misc/cool_stuff.json has the ID patchouli:misc/cool_stuff.

For modders, the domain used in the ID is the domain in which the book is defined.

Config Flags allow you to dynamically enable or disable content within a Patchouli book (including categories, entries, pages, or template components) based on the game environment or configuration settings.

In your book's JSON structures, you can assign a "flag" tag to an element. If the expression assigned to that flag evaluates to false, the content is disabled and will not appear in the book. If a flag name is used that has not been defined, it defaults to false.

When defining a pattern, the axes follow programming conventions rather than standard cardinal directions. This is critical when placing blocks with specific properties like facing.

• Y-axis: The outer array. Index 0 is the top layer, increasing downwards.
• X-axis: The middle array. Later entries in the array move East.
• Z-axis: The characters within the strings. Later characters in the string move South.

Example for placing stairs facing different directions:

"pattern": [
  [
    " W ",
    "N S",
    " E "
  ]
],
"mapping": {
  "W": "minecraft:oak_stairs[facing=west]",
  "N": "minecraft:oak_stairs[facing=north]",
  "S": "minecraft:oak_stairs[facing=south]",
  "E": "minecraft:oak_stairs[facing=east]"
}

Empty pages can be used as spacers or for aesthetic purposes.

Fields:

• draw_filler (boolean): Determines if the default page filler texture is drawn. Defaults to true. Set to false to render a completely blank page.

{
  "type": "patchouli:empty",
  "draw_filler": false
}

Every page object within a pages array in a Patchouli Entry can use the following common attributes to control visibility, locking, and internal referencing:

• type (String, mandatory): The namespaced ID determining the page type (e.g., patchouli:text). In 1.17+, use fully-qualified namespaced IDs. In 1.16 or earlier, use the short name (e.g., text).
• advancement (String): A resource location pointing to a Minecraft advancement. The page will only appear once this advancement is completed. Leaving it empty or omitting it keeps the page unlocked.
• flag (String): A config flag expression that determines if the page should exist based on user configuration.
• anchor (String): A unique identifier used to refer to this specific page via internal links.

You can pass dynamic data from a book entry into a template using variables.

1. In the Template: Define a variable by prefixing a key with a hash symbol (e.g., "#text").
2. In the Entry: Provide a value for that key at the same level as the type declaration.

Example Template (test_template.json):

{
	"components": [
		{
			"type": "patchouli:text",
			"text": "#text",
			"x": 20,
			"y": 30
		}
	]
}

Example Entry:

{
    "type": "yourbooknamespace:test_template",
    "text": "We just passed in the text from a variable!"
}

Constraints:

• You can define multiple unique variables (e.g., #upper_text, #lower_text).
• Warning: You cannot use variable names that conflict with existing common keys used by Default Page Types.

Patchouli allows you to transform variable values by applying functions. To apply a function, append ->func to the variable name inside the # delimiters.

Key capabilities:

• Chaining: You can chain multiple functions together (e.g., #item->iname->capital).
• Inline Derivation: You can use derived variables directly within a string (e.g., This recipe produces #item->iname#.).
• Logic Guards: Functions that return true or false can be used with the guard attribute in template components to conditionally show/hide elements.

// Example of chaining: getting an item name and capitalizing it
"text": "You need #item->iname->capital#"

Patchouli's original code and assets are licensed under CC-BY-NC-SA 3.0 Unported.

Licensing implications for modders:

• Normal Dependency: If you simply depend on Patchouli via your build system, there are no licensing concerns because the mod is remapped to Intermediary (or SRG for Forge) upon compilation.
• Jar-in-Jar Bundling: If you bundle Patchouli inside your mod using Jar-in-Jar, your mod will include a refmap containing raw Mojang mappings in a JSON file. If this presents a licensing conflict for your project, do not bundle Patchouli; instead, depend on it externally.

It is generally recommended to use normal dependencies rather than Jar-in-Jar to keep archive sizes smaller.

In versions before 1.20, you can create an "extension book" that adds content to an existing book without creating a new item.

• extend (String): The ID of the target book to extend (format: modid:path). For example, patchouli:coolbook extends a book located at /data/patchouli/patchouli_books/coolbook/book.json.
• allow_extensions (boolean): If false, prevents other books from extending this book (defaults to true).

Note: When extend is set, all other keys in the JSON file are ignored. The extension book inherits all entries, categories, templates, and macros from the target book.

{
  "extend": "patchouli:coolbook"
}