Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Building Compendiums

From Roll20 Wiki

Jump to: navigation, search

As of December 1st, 2016, Roll20 has opened the ability for community members to build their own Compendiums for available OGL systems outside of D&D 5th Edition SRD and the Pathfinder SRD. A volunteership program is now available for potential members to volunteer to become a Compendium Editor. These new Compendiums will have all of the features of the original two Compendiums, including Character Sheet integration and drag and drop functionality. Editors will be working to help push content to our users and are expected to respect the rules of the site and the game they are working on - any violation or vandalism of the Compendium will result in removal from the project team.

Editors should have a firm grasp of the rule system they would like to prepare and ideally have some familiarity with HTML, wiki writing, and/or authoring Structured Data. Structured data is strongly suggested to begin a Compendium, however we will consider manual submissions if the data is not available.

At present, Roll20 will be limiting one Editor per game system Compendium. After an initial Compendium project is completed, an Editor may be considered to help contribute towards other future Compendiums in collaborative projects.

Contents

How to Become a Volunteer

If you are interested in volunteering to help, please email team@roll20.net and provide the following information:

Subject: New Compendium Volunteer

   Do you have experience with basic html text editors?
   What game would you like to bring to the Compendium?
   Does the game have an OGL? (Please share a link to the OGL)
   In 2 to 3 sentences, please describe your experience with these games.
   Are you familiar with Structured Data?
   Do you know how to obtain the Structured Data for the game you are considering?
   Please share your Roll20 account email.

Upon approval, editors will be connected to their Compendium teams & the Roll20 staff via email to help facilitate organization and discuss any roadblocks. All approved volunteers will receive a special account badge.

Building A Compendium via JSON Import

The ideal method of Compendium building is to break down your game system into a series of JSON files; one for each page of your Compendium book. Then, compile them as a zip file or assemble them into a dropbox link which is later imported into Roll20's Compendium library by the Roll20 team. This is far easier to do when your OGL system is already cataloged on an online database where you can pull and reuse the HTML formatting and existing structured data already provided.

If your OGL system does not have an online database, you may need to go through the following Manual Process of Building a Compendium if it must be designed from scratch.

JSON File Basics

A JSON file is a JavaScript filetype meant for data storage and exchange. You can create them in any text editor that you would commonly use to write HTML documents (Notepad++ or Sublime Text or Atom, for example). The JSON's filename should match the "name" object's value within the JSON file itself.

The Basic Structure of a Compendium Page JSON

{
  "name": "Page Name",
  "content": "This is the content that would make up the bio & skills/abilities of an NPC or the body copy for a rule page",
  "data": {
    "Source": "The Game System or Book Source this page is from",
    "Category": "The Category the Compendium page would be filed under"
  }
}

The JSON file for a Compendium page REQUIRES the objects "name", "content", and "data". Also under the "data" object, the elements "Source" and "Category" is ALSO required in the JSON file; otherwise, the Compendium page will not be generated. Even if the page does not contain attributes, like a rule page, it still requires a data object with Source and Category elements with assigned values.

The three objects name, content, and data make up the entirety of the Compendium page.

name: The name object's value will be used for the name of the page. Capitalization matters here and what is enclosed in the quotation marks is what the page's eventual URL will be as well.
content: The value of the content object is the meat of what's to be read on a Compendium page; HTML tags are allowed in the value.
data: Elements listed under data is what will be listed in the Attributes section of the page (items that you would expect in a monster's statblock, for example).

The name and content objects are set in stone, but the attributes you add under data is flexible to what your OGL system needs (with the exception of the required Source and Category elements). BUT! You must be consistent with the naming conventions of your attribute Elements. If you use "AC" on one page, you shouldn't use "Armor Class" on another, and so on.

5th Edition OGL Example

Here is the JSON example of a Bugbear from the 5th Edition OGL Compendium

{
  "name":"Bugbear",
  "id":11963,
  "content":" Traits\n\n**Brute**: A melee weapon deals one extra die of its damage when the bugbear hits with it (included in the attack).\n\n**Surprise Attack**: If the bugbear surprises a creature and hits it with an attack during the first round of combat, the target takes an extra 7 (2d6) damage from the attack.\n\n Actions\n\n**Morningstar**: Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: 11 (2d8 + 2) piercing damage.\n\n**Javelin**: Melee or Ranged Weapon Attack: +4 to hit, reach 5 ft. or range 30/120 ft., one target. Hit: 9 (2d6 + 2) piercing damage in melee or 5 (1d6 + 2) piercing damage at range.\n\n  ","htmlcontent":"<h2>Traits</h2><strong>Brute</strong>: A melee weapon deals one extra die of its damage when the bugbear hits with it (included in the attack).<br><br><strong>Surprise Attack</strong>: If the bugbear surprises a creature and hits it with an attack during the first round of combat, the target takes an extra 7 (2d6) damage from the attack.<br><br><h2>Actions</h2><strong>Morningstar</strong>: Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: 11 (2d8 + 2) piercing damage.<br><br><strong>Javelin</strong>: Melee or Ranged Weapon Attack: +4 to hit, reach 5 ft. or range 30/120 ft., one target. Hit: 9 (2d6 + 2) piercing damage in melee or 5 (1d6 + 2) piercing damage at range.<br><br>",
  "data":{
    "AC":"16 (Hide Armor, Shield)",
    "HP":"27 (5d8+5)",
    "CHA":"9",
    "CON":"13",
    "DEX":"14",
    "INT":"8",
    "STR":"15",
    "WIS":"11",
    "Size":"Medium",
    "Type":"Humanoid (Goblinoid)",
    "Speed":"30 ft.",
    "Roll 0":"Morningstar\n1d20 + 4\n2d8+2",
    "Roll 1":"Melee\n1d20 + 4\n2d6+2",
    "Roll 2":"Ranged\n1d20 + 4\n1d6+2",
    "Senses":"Darkvision 60 Ft.",
    "Skills":"Stealth +6, Survival +2",
    "Source":"SRD 5.0",
    "Category":"Monsters",
    "Alignment":"Chaotic Evil",
    "Languages":"Common, Goblin",
    "Challenge Rating":"1",
    "Passive Perception":"10"
    }
}


Testing your JSON file

If you aren't using a text editor that already checks for JSON validation, you can paste the contents of your JSON file into the text field on jsonlint.com to test its validation via the website.

Building A Compendium Manually

If you have no existing online database to create JSON files from, you'll need to build the Compendium directly in Roll20.

Page Creation

Once selected by the Roll20 team as a Compendium Editor, you will be given access to a blank Compendium book to start editing and fill 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.

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.

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.

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. You may find that writing your Compendium entries in HTML may make Sheet integration easier as you won't get tripped over by unseen/unexpected formatting that can sometimes occur when working in the WYSIWYG version of the editor. The text editor is where you would include monster/class/race bios, feats, and abilities. Any data that can not be contained in a single input field should be placed here. 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.

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.

Creating Category List Pages

Once the individual entries of a Category are created, creating index pages (I.e. Monsters by Name, Equipment by Type, Spells by School, etc) are automatically generated by adding this search template in the Text Editor for the desired index page and saving it.

{{SearchIndex|***filter parameters***|}}

You can use multiple of the following filtering parameters all at once. Simple separate the filters apart with a space as you list them between the two vertical bars.


Category: Assigning the Category attribute will list all entries under the specified Category. The entries will be listed by their entry names in Alphanumerical order.
Example:
{{SearchIndex|Category:Monsters|}}
This will list every single entry that is under the "Monsters" category.


GroupBy: This filter is typically used alongside the Category filter to help sort the resulting list. This will assemble the entries into groups. An example from the D&D 5th Edition SRD is listing [Monsters by their Type] (aberration, goblinoid, ooze, etc) or [Challenge Rating]. Entries within a group will then be listed alphanumerically.
Example:
{{SearchIndex|Category:Monsters GroupBy:Type|}}
This will list the various Monster Types available and then sort the Monster entries via their "Type" Attribute.


Source: If there's a Compendium that is comprised of multiple books, a "Source" Attribute will likely be created to designate which book an entry page is being pulled from. This makes you able to create an index strictly listing content only from a designated source.
Example:
{{SearchIndex|Category:Monsters GroupBy:Type Source:Bestiary2|}}
This will generate a list of entries under the "Monsters" category, grouped by their "Type" attribute, and will only use entries listed with the "Source" Attribute "Bestiary2".

Attributes Table

Attributes Assigned to a Battleaxe Compendium Weapon Entry

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

Creating a New Attribute

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.

Designing for Sheet/Compendium Integration

In order to design a Compendium with character sheet integration in mind, it is recommended that a Compendium editor reaches out to the sheet Author(s) currently maintaining Sheets for their given game system. In order for a Compendium to integrate with a Character Sheet, the Compendium should be using matching Attributes used by the Sheet. Vice versa, the Sheet must be scripted to take advantage of the compendium-drop Event so that it can correctly parse and format the Compendium's content into attack rolls, items, spell slots, feats, etc once a Drag and Drop event occurs onto a sheet field or Tabletop. The Character Sheet & Compendium forum was designed intentionally so that Sheet and Compendium authors would have an easier time collaborating with one another.

Compendium Compatibility

To get started, we recommend reading up on the Compendium Integration section on the Building Character Sheets wiki page on how to enable Drag-and-Drop Functionality on your sheet.

Automated Journal Generation and Statted Token Creation

If you use the 5th Edition OGL by Roll20.html sheet on GitHub as an example; examining lines 7 and 5738 demonstrates how token generation and creating Journals (rather than a Handout) with their NPC version auto-toggled occurs after a Compendium Drag and Drop to the Tabletop.