Note
Crucial information is still missing in this article. If you want to expand this article, you are invited to contribute to the wiki.
Spellbook includes a large amount of content by default, but there are still many things one could want that are not yet included or cannot be included by default like custom spells, items, etc.
Such extra content can be added to Spellbook via Books. Spellbook Books are special Spellbook extension files (.spbe) that contain the extra information (such as spells, classes, subclasses, extended spell lists and items). Books can be imported like and other Spellbook extension files but can currently not be generated by Spellbook.
The following article explains how to write a Spellbook Book .
Writing a Book
The Basics
Spellbook books, just like all Spellbook extension files can have either the CBOR or JSON format. Since JSON is much more human-readable, this article will use the latter.
The following is the basic structure of an (empty) Spellbook book extension
!SPBV=2
{
"oldId": null,
"metadata": null,
"extension": [ "ch.phantomphoenix.spellbook.BookData", {
"bookName": "My Book Name",
"spells": [],
"classes": [],
"subclasses": [],
"modifiedLearners": [],
"editions": [],
"items": [],
}
]
}
You can copy this skeleton and skip right to the sections on Spells, Classes, Subclasses, Modified Spell Lists (modifiedLearners) or Items to learn how entries of each type look. The details section below will explain what this structure does in more detail.
This paragraph will explain the basic JSON you'll need to create your own Spellbook book. Each bracket [ or { corresponds to a closing } or ]. We call units of corresponding [ and ] together with their content an array. Units of corresponding { and } together with their content are called objects. Each single a spell, class, subclass, spell list modification or item as described below is an object. To add objects to your book, you add them to the corresponding array.
For example, if spell1 and spell2 are spell objects, you can add them to the array of spells as follows: replace "spells": [] with "spells": [spell1] or "spells": [spell1, spell2]. This will include one or both spells in your book.
Details
SPBV
The first line !SPBV=2 is, strictly speaking, not JSON. It is a header required by Spellbook to identify the version of the data-format without needing to parse JSON first. !SPBV=2 means that the file is using version 2 of the format.
Different versions of the format are incompatible. Newer versions of Spellbook will continue to support older versions of the format, so you will never need to change your version 2 book to be able to import it with the newest version of Spellbook. However, changing the version number without adapting the book to the newest version of the format will almost always break your book.
oldId/bookName
The oldId field is used to allow renamed books to still be seen as a variant of the old book and override it. Importing a book with the same bookName or the same oldId will override the book with the new import. If oldId is null as in the example above, only books with the exact name of the book will be overridden.
Metadata
The metadata field is used of other extensions but is ignored for books.
Extension
The extension field is the one that actually determines the contents of the book. It is an array containing exactly two elements, ch.phantomphoenix.spellbook.BookData to identify the data as book data and an object with the information contained in the book.
Editions
The editions array can only contain the string values e2024 and e5. This field signifies the edition to which the book is relevant. Spells and Classes/Subclasses will only be visible when a relevant edition is selected. A book may be relevant to any number of editions, including to none.
Spells, Classes, Subclasses, ModifiedLearners & Items
The remaining fields are lists of specific types of content a book can have. How each type of content looks exactly can be seen in the corresponding section below.