Getting Started

Getting started

Applies to all versions (1.21.1 and 26.2).

This page walks through the smallest complete Vellumli book: one category, one entry, one text page.

1. Folder layout

Pick a namespace (your mod id is the natural choice; the examples use mymod) and a book name (the examples use mymod_guide). Create these files:

data/mymod/vellumli_books/mymod_guide/book.json
assets/mymod/vellumli_books/mymod_guide/en_us/categories/basics.json
assets/mymod/vellumli_books/mymod_guide/en_us/entries/basics/introduction.json

The book manifest is loaded from data/; categories, entries and templates are loaded from assets/. Content is looked up first for the current language folder and falls back to en_us, so en_us is the safe place to start.

2. A minimal book.json

{
  "name": "mymod.guide.name",
  "landing_text": "Welcome to the guide.",
  "use_resource_pack": true
}

name and landing_text are looked up as translation keys; if no translation exists the text itself is shown, so literal strings work. use_resource_pack must be true for a normal (non-external) book; Vellumli refuses to load a book that leaves it false. See book.json for every field.

3. One category

assets/mymod/vellumli_books/mymod_guide/en_us/categories/basics.json:

{
  "name": "Basics",
  "description": "Everything you need to get started.",
  "icon": "minecraft:crafting_table"
}

name, description and icon are required. See Categories and entries.

4. One entry with one page

assets/mymod/vellumli_books/mymod_guide/en_us/entries/basics/introduction.json:

{
  "name": "Introduction",
  "category": "mymod:basics",
  "icon": "minecraft:book",
  "pages": [
    {
      "type": "vellumli:text",
      "text": "Hello, $(thing)world$()!"
    }
  ]
}

category must be fully qualified (namespace:name). See Page types for the other page types.

5. Getting the book in game

Books that are not marked dont_generate_book get a book item whose contents point at that book. You can:

• Find it in creative search (the item is vellumli:guide_book with the book id stored in the vellumli:book data component).
• Give it directly:

/give @s vellumli:guide_book[vellumli:book="mymod:mymod_guide"]

• Open a book directly with the command (permission level 2):

/open-vellumli-book @s mymod:mymod_guide
/open-vellumli-book @s mymod:mymod_guide mymod:basics/introduction 0

The third form opens a specific entry at a zero-indexed page.

6. Reloading

While developing, you can reload without restarting:

• Use F3 + T to reload resources. This re-reads the asset-side categories, entries and templates and rebuilds book contents.
• Starting or loading a world makes the server send a contents-reload packet to clients.
• Open the book in creative and shift-click the Editor button on the landing page to reload just that book.

The book manifest (book.json), and therefore the list of which books exist, is only read when the book registry is built at startup. Adding or renaming a book requires a restart; editing its contents does not.