Revision as of 15:23, 7 April 2014

This feature is currently in testing on the Dev Server, and will launch with the Data Delve update in May

Character Sheets are a new feature in Roll20 which allow you to use a digital sheet that's similar to a traditional paper character sheet while playing your game. The creator of a game can choose a character sheet template when setting up the game, and all characters in the game will use that sheet template.

Choosing a Character Sheet

(TODO)

Character Sheet Basics

If there is a character sheet template enabled for your game, there will be a new tab on when you open up a Character in your Journal labeled "Sheet". Clicking this tab will open the Character Sheet. The layout and look of your sheet, as well as what fields are available, will be determined by the template that the creator of the game has chosen.

The most basic way to interact with a sheet is simply by filling in values. You can type in text boxes, choose from drop-down menus, use checkboxes and radio buttons, etc. As you fill out the sheet, all of your changes are automatically saved.

Some fields may have default values already included. You can modify these values as needed for your particular Character. Some fields are also auto-calculating. As you fill out other parts of the sheet, those fields will auto-update to reflect their new values. You cannot modify those fields directly.

In addition to fields, your sheet may feature repeating sections. These are sections (for example, the "Skills" section in the example sheet shown to the right) where you can put more than one item in a list. Just click the "Add" button beneath the section to add a new entry. You can click the "Modify" button to delete existing entires.

Your sheet may also feature roll buttons. These are pre-defined rolls included with the sheet which allow you to quickly make attacks, roll checks, etc. These rolls will use the values that you have filled in on the sheet to function, so they're always up-to-date.

Advanced Character Sheet Usage

Interaction with Attributes

Sheets in Roll20 are a presentation layer for the Attributes system. This means that every field on the sheet is "backed" by a corresponding Attribute on the Character. For example, if there is a field called "Strength" on the sheet, there will also be an attribute called "Strength" in the Attributes & Abilities listing tab. As you update the sheet, the attribute is updated, and vice versa. This also allows you to link the sheet to a token the same way you would link an Attribute to a token, via the "Represents" box on the Token Settings dialog.

Interaction with Macros and Abilities

You can reference sheet values in your Macros and Abilities by referencing the corresponding Attribute. For example, @{Character Name|Strength} would use the "Strength" attribute, which is also the "Strength" field on the sheet (which would have name='attr_Strength' in the sheet builder). If the Sheet has a "Strength" field which hasn't been edited yet by the player, then the result of the variable will be either the default value for the field specified on the sheet by the sheet designer, or it will be "" (an empty string).

Interaction with the API

Since all sheet fields are attributes, you can simply use the existing API methods for Attributes to read or update sheet values as needed. Note that if a sheet field has not been edited yet for a Character, that Character will not have an attribute for that field. So be sure to check for "undefined" Attributes when fetching values. Once a sheet has been edited for a Character, the Attribute is available to the API for reading. You can always write to the Attribute even if the sheet hasn't been edited yet by creating that Attribute yourself -- the sheet in-game will update accordingly.

Building a Character Sheet

To build a sheet from scratch, choose the "Custom" option in the drop-down of your Campaign Settings page when choosing a character sheet template. You will be presented with an editor allowing you to build the sheet. The editor has three tabs: HTML/Layout, CSS/Styling, and Preview.

HTML/Layout

HTML is used to define the fields and layout the character sheet template. You can use most of the basic HTML tags, such as p,div,textarea,input,select,img, etc. Note that you cannot use any Javascript on your sheet template.

Creating Fields

To create a field in the sheet, use the <input type="text">, <input type="number">, <input type="checkbox">, <input type="radio">, <select>, or <textarea> tags. For each tag, you must include a name attribute which begins with "attr_" and defines the unique attribute name for this field. For example, <input type="text" name="attr_Strength" /> would create a text input for the "Strength" attribute.

Default Values

You can also optionally include a value attribute on the tag, which will define the default value for the field. For example, <input type="number" name="attr_AC" value="0" /> would define an "AC" field with a default value of "0". If no default value is specified, it is an empty string ("").

Auto-Calculating Values

You can include a formula in the default value for the field, and specify the disabled="true" attribute on the field. If you do so, the sheet will display the result of the formula instead of the formula itself. For example, <input type="number" name="attr_StrMod" value="@{Strength}/2" disabled="true" /> would create a "StrMod" field that shows half the Strength value. These auto-calculating attributes can be used in Sheet Rolls, Macros, and Abilities as normal.

Sheet Rolls and Roll Buttons

You can include pre-defined rolls on your sheet. This is a great way to add the rolls that will be needed by the player when using the standard rolls in the game system. For example, you may want to add a "Roll Check" button next to each "Bluff", "Intimidate", etc. field on the sheet. To define a roll, just use the <button> tag. The type attribute should be set to "roll". The roll itself is defined in the value attribute. You can also add a name attribute which allows the roll to be referenced in external Macros and Abilities. A full example of a bluff check roll might look like: <button type='roll' value='/roll 1d20 + @{Bluff}' name='BluffCheck' />. Note that you can reference attributes/fields on the sheet using the @{AttributeName} syntax. You could also then roll that example in other Macros or Abilities using %{CharName|BluffCheck}.

Repeating Sections

Sometimes you may have a type of object where there may be one or more of them, and it's not known ahead of time how many there are. A good example of this is the Skills listing for a Character in Savage Worlds. Roll20's sheets allow you to define a template for each item in the section, and the player can then add as many of these in the listing as they need. To define a repeating section, use a <fieldset> tag. Add a class called "repeating_<sectionname>" (note that no two sections in your sheet should have the same sectionname) to the tag, and inside the tag put the fields that each item will have. Here's an example of a Skills listing:

<h3>Skills</h3>
<fieldset class="repeating_skills">            
     <select name="attr_dtype" class="dtype">                
          <option value="d4">d4</option>
          <option value="d6">d6</option>
          <option value="d8">d8</option>
          <option value="d10">d10</option>
          <option value="d12">d12</option>
      </select>
      <input type="text" name="attr_skillname" />        
</fieldset>

When the sheet is displayed, Roll20 will automatically add "Add" and "Modify" buttons to allow the player to add as many of each item as needed. Each item will have its own set of fields (in the example above, each has its own "attr_dtype" and "attr_skillname").

Internally, each repeating item is stored in an attribute like so: "repeating_skills_0_dtype" and "repeating_skills_0_skillname" for the first item, "repeating_skills_1_dtype" and "repeating_skills_1_skillname", etc. Do not attempt to manage these attributes manually, as if items are added or deleted from the repeating list, what item is stored at each index will change. These repeating attributes are NOT shown in the Attributes listing for players to edit for this reason.

Security Filtering

There are a few caveats to be aware of in regards to the security filtering that Roll20 applies to your HTML:

• All classes that don't start with "attr_", "repeating_", or "roll_" will be prefixed with "sheet-".
• All images will be passed through the Roll20 image proxy to prevent security attacks. This should be largely transparent to you and shouldn't affect anything, but it's something to be aware of.

Complete Example

Here's a complete example of a basic Savage Worlds sheet HTML layout: Savage Worlds example

CSS/Styling

You can use custom CSS to style the way that your sheet looks to players. You can use nearly any CSS styling that you want, including background images, colors, font sizes, etc. There are just a few caveats to note:

• All of your CSS styles will be restricted to the ".charsheet" parent class. So if you put a style called "input", the system will automatically prefix that with ".charsheet input". This shouldn't affect you in-practice, but it prevents you from changing any of the Roll20 application CSS outside of the character sheets.
• Note that by default, any HTML classes defined in your HTML layout which don't begin with "attr_", "roll_" or "repeating_" will be prefixed with "sheet-". So for example, if you want to style some of your input tags to be shorter than others and you define the HTML as "<input class='shortfield'>", when processing your layout it will be changed to "<input class='sheet-shortfield'>". So basically, you should probably prefix your classes in your HTML and CSS with "sheet-" to avoid confusion.

Preview

The preview pane updates in real-time whenever you change the HTML or CSS of your sheet to show you what that sheet will look like in-game. It's very useful for checking while your editing to make sure that the end-result is as you expect it to be.

The Preview pane applies all the same security precautions and filtering as the main Roll20 application. Be sure to right-click and Inspect Element if you are seeing strange behavior (e.g. your styles aren't being applied correctly) -- it may be that there is a security filter that is changing the name of a class or something similar.