Categories and Entries

Categories and entries

Applies to all versions (1.21.1 and 26.2).

Categories group entries in the landing page. Entries are the readable chapters, made of pages. Both are individual JSON files:

assets/<namespace>/vellumli_books/<book>/<lang>/categories/<id>.json
assets/<namespace>/vellumli_books/<book>/<lang>/entries/<id>.json

The file path under categories/ or entries/ (without .json) becomes the id, and subfolders become part of the id (for example entries/basics/introduction.json has id namespace:basics/introduction).

Category fields

Field	Type	Default	Description
name	string	(required)	Display name. A translation key when the book sets "i18n": true.
description	string	(required)	Description shown near the category.
icon	string	(required)	An item stack string, or a texture path ending in .png.
parent	string	(optional)	Parent category id, fully qualified (namespace:name). Child categories are nested under their parent.
flag	string	""	Config flag gating the category. Omit or leave empty to always load it.
sortnum	int	0	Sort weight. Lower values come first.
secret	boolean	false	Secret categories are hidden while locked.

Example:

{
  "name": "Machines",
  "description": "All the machines in the pack.",
  "icon": "mymod:assembler",
  "parent": "mymod:basics",
  "sortnum": 10
}

Entry fields

Field	Type	Default	Description
category	string	(required)	Category id, fully qualified (namespace:name).
name	string	(required)	Display name. A translation key when the book sets "i18n": true.
icon	string	(required)	An item stack string, or a texture path ending in .png.
pages	array	(required)	The pages of the entry. See Page types.
flag	string	""	Config flag gating the entry.
priority	boolean	false	Priority entries sort before other entries in the same state.
secret	boolean	false	Secret entries are hidden while locked.
read_by_default	boolean	false	If true, the entry never shows as unread.
advancement	resource location	null	The entry is locked until this advancement is completed.
turnin	resource location	null	The entry shows as pending until this advancement is completed.
sortnum	int	0	Sort weight within the category. Lower values come first.
entry_color	hex string	book text_color	Overrides the entry color (hexadecimal RGB, no #).
extra_recipe_mappings	object	(optional)	Maps item stack strings to a page number, for recipe lookup.

Example:

{
  "name": "Assembler",
  "category": "mymod:machines",
  "icon": "mymod:assembler",
  "advancement": "mymod:assemble",
  "sortnum": 5,
  "pages": [
    { "type": "vellumli:text", "text": "The assembler builds parts." }
  ]
}

Sorting

Categories are ordered by:

1. Locked categories last (only when advancement locking is enabled).
2. sortnum, ascending.
3. Name, alphabetically.

Entries are ordered by:

1. Locked entries last.
2. Read state, in the order unread, pending, neutral, completed.
3. priority entries before non-priority entries.
4. sortnum, ascending.
5. Name, alphabetically.

Locking, advancements and secrets

• An entry with an advancement is locked until the player completes that advancement. An entry with a turnin shows as pending until that advancement is completed.
• A secret entry is hidden from the list while it is locked; once unlocked it becomes visible. secret without advancement is never hidden.
• A category is locked while every one of its entries and child categories is locked, and is unlocked as soon as one of them is unlocked. secret categories are hidden while locked.
• Advancement locking can be disabled globally or per book through configuration. When disabling through config flags, the built-in config flags advancements_disabled and advancements_disabled_<bookid> are available for use in flag fields.