Character Sheet Development
Getting Started

General

Reference

Tools & Tips

Git/GitHub

Other

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 i 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 D&D 5E by Roll20 sheet.json file 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 which would be compatible with the Fireball entry from the 5th Edition SRD Compendium.

Helpful Compendium Integration Tip/Example Dec 2023


<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.

Compendium Buttons

Main Page: button

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".

Default Sheet Settings

Main Page: Default Sheet Settings

If you have NPC drag-n-drop integration, it can be good idea to add Default Sheet Settings that enables users to change the positions and values of how NPC token are set up. This can't be applied to normal character sheets.

Charactermancer Development

Main Page: Charactermancer Development

To be able to create a Charactermancer for a sheet, the data used in them needs to be stored in a Compendium, so a sheet requires some form of compendium-integration, before a Charactermancer can be implemented.