Compendium Building Primer

March 20, 2024 08:38

The following contains information specific to Partners on the Roll20 Marketplace.

Those interested in creating Compendiums should have a firm grasp of the rule system they would like to create for and ideally have some familiarity with HTML, JSON, wiki writing, and/or authoring Structured Data. If you are interested in further documentation or scheduling a meeting with one of our Content Producers for individual onboarding, please reach out to licensing@roll20.net.

Recommendation

If you are unfamiliar with any of the above, we currently recommend engaging one of our vetted third-party conversion contractors for Compendium Expansion creation.

Any violation or vandalism of the Compendium will result in removal.

Compendium Tools Page

In order to access the Compendium Tools page you need to have edit access for at least one Compendium Expansion. These must be set by a Roll20 Admin; reach out to licensing@roll20.net or submit a support ticket to this Help Center.

If you have the “Owner” compendium permission you have edit access to all Expansions within the book(s) you own.
If you have the “Editor” compendium permission you have edit access to all Expansions which you are an editor of.
If you have the “Deputy” permission and are a marketplace creator with at least one Compendium tied to your account you have edit access to all expansions in your Item Management page.

On Roll20 you can reach the Compendium Tools page by clicking the dropdown menu from your name in the upper right corner and selecting Compendium Tools.

Compendium Tools Dropdown.jpg

Currently the Compendium Tools page provides the ability to view or delete pages within a compendium that you own. This is done by first selecting the Compendium Book then the Compendium Expansion and clicking on the Show button next to View Pages.

First, choose.jpg

From here you can either click the hyperlinked page names to visit a specific page or click the check boxes to the left of the page name to select them. Selected pages can be deleted all at once by clicking the Delete Section button. Additionally, if you’d like to sort by category you can do so using the dropdown menu below Category.

From here.jpg

Building A Compendium

Page Creation

Upon becoming a Roll20 Marketplace Partner and receiving approval to create Compendium Expansions, you will be given access to a blank "book" to start editing and filling with content. During the process of creating the staging area for the book, you'll want to assemble a list of Categories needed for your game system (Rules, Monsters, Items, Spells, etc). You will want to have the organization structure straightened out before work on the Compendium begins; if you are creating an expansion for a system like D&D 5e, we will provide you with a template.

Once you're given the URL for the new Compendium book by the Roll20 Team, you create new pages by tacking on the name of the new page at the end of the URL in the address bar and hitting Enter. (example: https://roll20.net/compendium/MyBook/Test Page) For special characters like spaces, parenthesis, and apostrophes: once you hit Enter, the page name will be adjusted to use HTML Code for the needed ASCII characters automatically.

NOTE: Please do not use colons ":" in page URLS. These are read as categories by the URL and will make your page unusable

Since the page does not yet exist, the Compendium will display a page that says:

Not Found: [page name]

We don't currently have a page that matches that name. Try again?

Or maybe you'd like to create this page?

Below this will be a drop-down menu for the Category you wish to add the page to. If this is the very first page, you'll not have any available Category to choose from in the drop-down other than Miscellaneous to start with, so this is where you should start adding your own Categories.

NOTE: Pages created in Miscellaneous and BookIndex categories cannot be edited by anyone but a Roll20 developer. Please avoid these categories.

Once you've set or added a Category to the page, click on the blue Create Page button to create it. This will drop you onto the newly created page to start editing it.

Editing a Page

Once created, a Compendium page will be split up into two distinct parts: A Text Editor and then an Attributes Table underneath.

Text Editor

The text editor can switch between a WYSIWYG and an HTML version by clicking on the </> button which is the last button on the right side of the text editor's toolbar. Be sure to click the </> button after inputting your HTML to let the page update before saving. The text editor is where you include monster/class/race bios, feats, and abilities. Page content is readable outside of any created statblocks. Use heading tags (<h1>, <h2>, <h3>, Etc.) in a consistent manner to split your content up for efficient integration. It is incredibly important that text formatting is also kept consistent throughout the entirety of the Compendium book.

Uploading Images

Most editing can be done at the standard "roll20.net" web address. For uploading images, URLs must be edited on "app.roll20.net". Images can then be dragged into the appropriate area and will upload automatically. The Roll20 compendium automatically resizes and resamples images. If this is not desired, the HTML tag for each image needs to be edited.

Dynamic Linking

You do not need to manually create page links within the text copy of your Compendium pages. Page linking is done automatically after Roll20 initiates a Compendium build. This automated process scans through the text contents of every single entry of the Compendium to match strings up with any available page titles. When a match is found (the page name and string must be identical save for Capitalization), the string is automatically hyperlinked to the matched page. This process will happen when the Compendium is live.

Note: The autolinker can be gregarious. Take care in naming pages with a common phrase such as "Magic"

Creating List Pages

For large lists of relevant pages, many game systems may benefit from a searchable list.

Create a new page. For a naming convention, we suggest: <Category> List. Feats, Spells, Monsters, etc. pages should generally fall under the Lists category. Example: Spell List
Click on "Edit Attributes" and set "data-List" to {"searchTerms":[], "columns":[], "filters":[], "sortables":[]}. This attribute should already be created by default, but you may need to Edit/Save the contents of the page for it to appear.
Go to "Edit Content", set "List for Category" to the desired value, and add a new Search Attribute: Attribute = “Category”, Value = <Name of Category>, and Match = “Exact”. Be sure to save your edits.
Editing the list
- "List Display Columns" - This controls what appears under each item column. This is not used if an item card has been defined for the category.
  - "Attribute" - The name of the attribute to be displayed.
  - "Order" - The order in which this attribute is displayed.
  - "Value Replacement" - A .json formatted string of key/value pairs for replacing certain values.
  - For example, {"0":"Cantrip"} makes 0 level spells display as "Cantrip" in the results list.
  - "Sortable" - This is deprecated. Sorting is now controlled in the "Sort Buttons" section
- "Filter Attributes" - This controls the predefined filters available.
  - "Any" - Returns any result where the filter value matches any part of the attribute value.
  - "Exact" - Only returns results where the filter value matches the attribute value exactly.
  - "Inverse" - Only returns results where the filter value does not match the attribute value.
  - "Attribute" - The name of the attribute to be filtered by.
  - "Order" - The order in which this filter is displayed.
  - "Filter Type" - The type of input for the filter.
  - "Default Value" - The default value for the filter.
  - "Match" - How the filter returns the result.
  - "Filter input values" - For select and multiselect filter types, this is a .json formatted string which determines what values are available. If blank, it will populate the selection with all of the possible values.
- "Sort Buttons" - For defining the sortable attributes.
  - "Alphabetical" - The results are sorted alphanumerically, with numbered results returning first. "19 ft." and “40 Winks” would be listed first before “Ale of Drunkening” and "Potion of Sobering", etc.
  - "Numerical" - The results are sorted numerically. The code will find the first numerical value and use that for sorting i.e. "Speed 30 ft. (15 ft. flying)" would then parse out as "30".
  - "Attribute" - The name of the attribute to be sorted by.
  - "Order" - The order in which this button is displayed.
  - "Display Title" - The text to be displayed in the button, if different from the attribute name.
  - "Type" - How the results are sorted.

Attributes Table

Below the Text Editor is the Attributes Table. This area is to input traditional statblock content that is consistent throughout your Categories: Armor Class, Languages, Weaknesses, Immunities, HP, XP, Passive Perception, etc., for Monsters. Weight, Item Type, Armor Class, Stealth rating for Items. Damage Type, Weight, Properties, Damage Die for Weapons. Commonly these Attributes are already broken down into a table within your rule book to carry it over into your Compendium entries.

Adding Attributes

When you're starting off with a new page, there will be no Attributes assigned to it. To start adding Attributes, click on the Edit Attributes link to the right of the Attributes heading. This will not only reveal hidden Attributes (if there are any), but also add a new link at the bottom of the Attributes Table labeled + Add New Attribute.

A drop down menu labeled Choose an attribute... will appear on a new table row. If you have created Attributes previously on other entries, those Attributes will appear as options on this drop down menu. The first option on the menu is Create new attribute... and likely will be what you'll be using mostly until you have all of your desired Attributes created.

A_screenshot_of_the_Create_New_Attribute_field_of_a_Compendium.png

Once selected, an empty field will appear to the right of the drop down menu and a smaller field directly below the drop down menu with the temporary text ,"New Attr Name", within it. As you might expect, the "New Attr Name" field is for the name of the Attribute you wish to create. The blank field on the right is the value the current entry has for this new Attribute. In the example image above, the attribute being created keeps track of an entry's "Element". I am assigning the Element for this entry the value of "Fire". An Attribute's value can be numerical or it could be a string.

Continue adding Attributes as you need in this fashion, either creating them from scratch or choosing from the drop down menu. When you are done, scroll up to the Attributes heading and where the Edit Attributes link used to be. While in Edit Mode, this link's label will change to Save Attributes. Clicking on this not only saves your changes, but it also logs any newly created Attributes so they can be brought up again on a new page.

Editing or Deleting Attributes

You can't delete Attributes until they're saved down first. Once saved, you can click on the Edit Attributes link again to return to Edit Mode. Any previously added/created Attributes will have a pen and trash can icon appear on the right side of the Attribute row when you hover your mouse over any one of them. Clicking on the pen icon will open the Attribute up once more so it can be edited, while the trash can icon will delete the Attribute. Remember to click on Save Attributes to exit out of Edit Mode and save your changes.

Importing Pages from Compendium JSON Files

The Compendium Tools page includes an alternative method of building Compendium Expansions that can be much faster than manually creating pages.

The Compendium JSON Importer allows you to define any number of pages in a JSON file, then upload that file to instantly create those pages in your desired Compendium Expansion.

To begin importing Compendium content, you will first need to format your Compendium page data in a .json file according to Roll20’s Compendium JSON specification. The following example illustrates the complete Compendium JSON schema:

code block 1.JPG

This Compendium JSON defines three pages: “Haunted Mansion,” “Graveyard,” and “Spooky Skeleton.” The first two pages are in the “Lore” category, while the “Spooky Skeleton” page is in the “Monsters” category.

Notice how the first two pages are defined as “PAGE_TITLE”: “PAGE_HTML”, while the “Spooky Skeleton” page is defined with a slightly more complex format:

code block 2.JPG

The simpler format used by “Haunted Mansion” and “Graveyard” is a shorthand for when you just want to import HTML content, while the “expanded” format is required when you also want to import Attributes.

Once your Compendium JSON file is prepared, navigate to Roll20’s Compendium Tools page, then use the dropdowns to select the Compendium Expansion you wish to import into.

Once you have selected an Expansion, click the “Show” button next to the “Import Pages from JSON” heading to reveal the JSON importing interface.

Next, use the “Browse” button to upload the Compendium JSON file from your computer. Finally, click “Import Pages” and wait a few moments for the process to complete. When the import finishes, you will see a “Created Pages” heading and/or an “Updated Pages” heading. Beneath each of these headings, you will see a list of all the pages that were created/updated by the JSON import.

Compendium Integration

The Roll20 Compendium feature is a repository of information such as rules, spells, items, and monsters for select open-license gaming systems. By designating that your sheet is compatible with a Compendium, players will have direct access to that Compendium in the right sidebar during gameplay.

Designating Compatibility for Your Sheet

To designate compatibility with a Compendium, just include the Compendium's short name in the "compendium" field of your sheet.json file. For an example, see the sheet.json file of the 5th Edition OGL Sheet by Roll20 on Github.

If you are using a Custom sheet, there is a Setting on the Game Settings page that will allow you to manually select a Compendium to use for your game.

Enabling Drag-and-Drop Functionality for Your Sheet

In addition to basic compatibility, you have the option of telling Roll20 how information from the Compendium can be included on your sheet directly. This allows players to drag and drop an entry from the compendium directly into your sheet, and Roll20 will fill in the values you specify. To do so, you must add the class compendium-drop-target to the div tag surrounding the section you want to fill in. For repeating sections, place this inside of the fieldset tag. Then, add the accept="Attribute Name" attribute to one or more input, select, textarea tags. Here's a simple example that would be compatible with the Fireball entry from the 5th Edition SRD Compendium.

<fieldset class="repeating_spells"><div class="compendium-drop-target"><input type="text" name="attr_SpellName" accept="Name" /><input type="text" name="attr_SpellDamage" accept="Damage" /><select name="attr_SpellSchool" accept="School"><option value="Abjuration">Abjuration</option><option value="Conjuration">Conjuration</option><option value="Divination">Divination</option><option value="Enchantment">Enchantment</option><option value="Evocation">Evocation</option><option value="Illusion">Illusion</option><option value="Necromancy">Necromancy</option><option value="Transmutation">Transmutation</option></select><input type="checkbox" name="attr_SpellRitual" value="Yes" accept="Ritual"></div></fieldset>

The <Attribute Name> in accept="<Attribute Name>" must match the name of an Attribute from the bottom section of the Compendium entry. Consult each individual Compendium for a listing of what Attributes are available.
For input and textarea tags, the value from the Compendium will be directly inserted.
For input[type=checkbox] and input[type=radio] tags, the box will be checked/radio selected if the value from the compendium exactly matches the value attribute from the tag.
For select tags, the option that matches the Compendium value in either the value attribute OR the text inside the option tag will be selected
You can use accept="Content" if you wish to receive the plaintext content from the entry (the content located above the "Attributes" header).
You can use accept="data" of you want to receive all attributes from a compendium page in a json format.

Note that the process of changing these values will trigger local Sheet Worker and remote API events exactly as if the user themselves had entered the data by hand. So you can also create hidden inputs to accept data from the Compendium and then process that data further using Sheet Workers if you want more control over how the data is presented. See the Spells section in the 5th Edition OGL sheet for an advanced example of this process.

Compendium Buttons

The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.

The syntax is <button type="compendium" value="<entryname>">. Here are a few valid examples:

<button type="compendium" value="Bard"></button>

This is valid syntax, but since there is both a Class and a Monster compendium entry titled "Bard", the resulting window will be present you with a choice of entries rather than going directly to one of them.

<button type="compendium" value="Classes:Bard"></button>

This is the preferred syntax. Specifying the category ensures that there will be only one match.

<button type="compendium" value="Classes:Bard#Spellcasting"></button>

Adding a "#" followed by a subhead title will cause the window to open directly to that section. This example will open the entry for the Bard class, pre-scrolled to the Spellcasting section. If no section with that name is found, the window will open scrolled to the top. Dragging an entry from the compendium contains an attribute specifically for this button, uniqueName, a string containing both the category and entry name, which ensures there will be only one match in the compendium. So, the syntax for this button in a compendium drop section is as follows:

<button type="compendium" name="attr_infoButton" accept="uniqueName"></button>

You can also add a sub-section to this attribute via sheetworker, so if the item dropped from the compendium was a monster, and you want the button to open directly to the "Actions" section, you can set the value of the button to uniqueName + "#Actions".