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

Difference between revisions of "Building Character Sheets"

From Roll20 Wiki

Jump to: navigation, search
(Building a Character Sheet)
m (Restrictions & Security Filtering)
(32 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{pro only}}
 
{{pro only}}
 
+
[[File:Custom-Sheet-Menu.png|650px|thumbnail|right|The "Sheet Editor", accessible when the Character Sheet is set to "Custom" in the [[Game Settings Page|Game Settings]] ]]
 
==Building a Character Sheet==
 
==Building a Character Sheet==
 
+
[[File:Game Settings Menu Options.jpg|350px|thumbnail|right]]
 
To build a sheet, you must have access to a Pro account.
 
To build a sheet, you must have access to a Pro account.
  
Line 8: Line 8:
 
# Select the Games menu, and select My Games.
 
# Select the Games menu, and select My Games.
 
# Select the game to go to the campaign details page.
 
# Select the game to go to the campaign details page.
# Under the Settings menu, select Game Settings.
+
# Under the Settings menu, select [[Game Settings Page|Game Settings]].
 
# Select Custom from the Character Sheet Template menu.
 
# Select Custom from the Character Sheet Template menu.
  
 
The editor has four tabs: HTML Layout, CSS Styling, Translation, and Preview.
 
The editor has four tabs: HTML Layout, CSS Styling, Translation, and Preview.
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
===Restrictions & Security Filtering===
 +
 +
Generally speaking, character sheets are created with HTML, CSS, and JavaScript( for [[Sheet Worker Scripts|Sheetworkers]]), but there exist some constrains that  is good to know for the intermediate and advanced user. There are a few caveats to be aware of in regards to the security filtering that Roll20 applies to your HTML as well:
 +
 +
'''HTML:'''
 +
 +
In the browser, the character sheet is basically wrapped inside a giant <code><form></code> tag.
 +
* [https://www.w3schools.com/tags/att_id.asp Id attributes] cannot be used. (Any  ID attributes on one character's sheet would affect another character's sheet in the same campaign when opened
 +
* any [https://www.w3schools.com/whatis/whatis_htmldom.asp DOM] functionalities can't be used
 +
* Do not use reserved HTML tags such as <code><head></code> or <code><body></code> in your character sheet HTML. Doing so will prevent your character sheet from loading in the virtual tabletop
 +
* Some tags like <code><section></code>, <code><header></code>, <code><footer></code>,<code><footer></code> don't work either
 +
* Attribute names are case-insensitive when checked for uniqueness. All inputs (and selects, and textareas, etc.) should have a unique attribute name
 +
* 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.
 +
* <code><svg></code> doesn't seem to be supported
 +
'''CSS:'''
 +
* [https://www.w3schools.com/css/css_rwd_mediaqueries.asp Media queries] doesn't seem to be usable
 +
'''JavaScript'''
 +
* DOM can't be used
 +
* Some javascript functions or functionalities can't be used, See [[Sheet_Worker_Scripts|Sheetworker Documentation]] for more details
 +
 +
'''Other/General:'''
 +
* Limited Font support. The following fonts can be used: <code>Arial</code>, <code>Patrick Hand</code>, <code>Contrail One</code>, <code>Shadows Into Light</code> and <code>Candal</code>
  
 
===HTML Layout===
 
===HTML Layout===
Line 17: Line 46:
 
HTML is used to define the fields and layout the character sheet template. You can use most of the basic HTML tags, such as <code>p, div, textarea, input, select, img</code>, etc. Note that you cannot use Javascript on your sheet template except in the case of [[Sheet_Worker_Scripts|sheet worker scripts]].
 
HTML is used to define the fields and layout the character sheet template. You can use most of the basic HTML tags, such as <code>p, div, textarea, input, select, img</code>, etc. Note that you cannot use Javascript on your sheet template except in the case of [[Sheet_Worker_Scripts|sheet worker scripts]].
  
Note: Do not use reserved HTML tags such as <code><head></code> or <code><body></code> in your character sheet HTML. Doing so will prevent your character sheet from loading in the virtual tabletop.
 
  
 
==== Creating Fields ====
 
==== Creating Fields ====
  
 
To create a field in the sheet, use the <code><input type="text"></code>, <code><input type="number"></code>, <code><input type="checkbox"></code>, <code><input type="radio"></code>, <code><select></code>, or <code><textarea></code> tags. (Note: <code><input></code> tags must have a type specified (text, number, hidden, checkbox, or radio)). For each tag, you must include a <code>name</code> attribute which begins with "attr_" and defines the unique attribute name for this field. For example, <code><input type="text" name="attr_Strength" /></code> would create a text input for the "Strength" attribute. If you want the field to utilize the "max" of an attribute instead of the normal value, you can append "_max" onto the name of the field. For example, <code><input type="text" name="attr_Strength_max" /></code>. You can also use a <code>< span ></code> tag to display a read-only value on your sheet. For example, <code>< span name="attr_Strength"></ span></code>. It is possible to include a span tag that has the same attribute name as an input tag, and the span tag will be updated whenever the input is modified.
 
To create a field in the sheet, use the <code><input type="text"></code>, <code><input type="number"></code>, <code><input type="checkbox"></code>, <code><input type="radio"></code>, <code><select></code>, or <code><textarea></code> tags. (Note: <code><input></code> tags must have a type specified (text, number, hidden, checkbox, or radio)). For each tag, you must include a <code>name</code> attribute which begins with "attr_" and defines the unique attribute name for this field. For example, <code><input type="text" name="attr_Strength" /></code> would create a text input for the "Strength" attribute. If you want the field to utilize the "max" of an attribute instead of the normal value, you can append "_max" onto the name of the field. For example, <code><input type="text" name="attr_Strength_max" /></code>. You can also use a <code>< span ></code> tag to display a read-only value on your sheet. For example, <code>< span name="attr_Strength"></ span></code>. It is possible to include a span tag that has the same attribute name as an input tag, and the span tag will be updated whenever the input is modified.
 
'''Note: Attribute names are case-insensitive when checked for uniqueness. All inputs (and selects, and textareas, etc.) should have a unique attribute name.'''
 
  
 
==== Default Values ====
 
==== Default Values ====
Line 63: Line 89:
 
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 <code><button></code> tag. The <code>type</code> attribute should be set to "roll". The roll itself is defined in the <code>value</code> attribute. You can also add a <code>name</code> attribute which allows the roll to be referenced in external Macros and Abilities. A full example of a bluff check roll might look like: <code><button type='roll' value='/roll 1d20 + @{Bluff}' name='roll_BluffCheck'></button></code>. Note that you can reference attributes/fields on the sheet using the <code>@{AttributeName}</code> syntax. You could also then roll that example in other Macros or Abilities using <code>%{CharName|BluffCheck}</code>. '''Note:''' The names you give your Sheet Rolls must be unique from any Ability names on your Characters if you want to reference them in Abilities or Macros. You can also just not give your Sheet Rolls names if you just want them to only be rolled by clicking the button on the Sheet itself.
 
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 <code><button></code> tag. The <code>type</code> attribute should be set to "roll". The roll itself is defined in the <code>value</code> attribute. You can also add a <code>name</code> attribute which allows the roll to be referenced in external Macros and Abilities. A full example of a bluff check roll might look like: <code><button type='roll' value='/roll 1d20 + @{Bluff}' name='roll_BluffCheck'></button></code>. Note that you can reference attributes/fields on the sheet using the <code>@{AttributeName}</code> syntax. You could also then roll that example in other Macros or Abilities using <code>%{CharName|BluffCheck}</code>. '''Note:''' The names you give your Sheet Rolls must be unique from any Ability names on your Characters if you want to reference them in Abilities or Macros. You can also just not give your Sheet Rolls names if you just want them to only be rolled by clicking the button on the Sheet itself.
  
'''See also:''' [[Macros#Rolling_For_Initiative|Initative Roll]]
+
'''See also:'''
 +
* [[Macros#Rolling_For_Initiative|Initiative Roll]]
 +
* [[Macros#Drop-Down_Prompts_for_Roll_Queries|Roll Queries]] - How to use Roll Queries in your buttons
 +
* [[Dice Reference]] - The Roll20 dice/math syntax
  
 
==== Columns and Layout ====
 
==== Columns and Layout ====
Line 69: Line 98:
 
Many sheet authors recommend using your own CSS for styling and to layout the sheet. Roll20 provides a few basic classes you can use to organize things into a simple column-based layout. To use them, just create a div with a class of '3colrow', '2colrow', or 'row'. Then inside of that div, create a div for each column with a class of 'col'. For example, to create a 3-column layout, you would could:
 
Many sheet authors recommend using your own CSS for styling and to layout the sheet. Roll20 provides a few basic classes you can use to organize things into a simple column-based layout. To use them, just create a div with a class of '3colrow', '2colrow', or 'row'. Then inside of that div, create a div for each column with a class of 'col'. For example, to create a 3-column layout, you would could:
  
<pre data-language="javascript">
+
<pre data-language="html">
 
<div class='3colrow'>
 
<div class='3colrow'>
 
<div class='col'>
 
<div class='col'>
Line 82: Line 111:
 
</div>
 
</div>
 
</pre>
 
</pre>
 +
 +
For more flexible and advanced CSS, you are encouraged to explore the popular [https://css-tricks.com/snippets/css/a-guide-to-flexbox/ CSS Flexbox] and [https://css-tricks.com/snippets/css/complete-guide-grid/ CSS Grid] frameworks.
 +
 +
Here's a character sheet template using [https://github.com/clevett/SheetTemplate Flexbox], and another one using [https://github.com/Anduh/Roll20-grid-template Grid]
  
 
==== Repeating Sections ====
 
==== 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 <code><fieldset></code> tag. Add a class called "repeating_''sectionname''" to the tag, and inside the tag put the fields that each item will have. Note that no two sections on your sheet should have the same name, and that you cannot use underscores in your sectionname. Here's an example of a Skills listing:
+
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 <code><fieldset></code> tag. Add a class called "repeating_''sectionname''" to the tag, and inside the tag put the fields that each item will have.  
  
<pre data-language="javascript">
+
{{mbox | text = '''Warning:''' Each section name should be unique, and you cannot use underscores in your sectionname.  Do not use <code>repeating_melee_weapon</code>. Use <code>repeating_melee</code>, or <code>repeating_meleeweapon</code>.  }}
 +
 
 +
Here's an example of a Skills listing:
 +
 
 +
<pre data-language="html">
 
<h3>Skills</h3>
 
<h3>Skills</h3>
 
<fieldset class="repeating_skills">  
 
<fieldset class="repeating_skills">  
Line 101: Line 138:
 
</pre>
 
</pre>
  
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").
+
When the sheet is displayed, Roll20 will automatically include an '''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 <code>attr_dtype</code> and <code>attr_skillname</code>).
  
Internally, each repeating item is stored in an attribute like so: "repeating_skills_-ABC123_dtype" or "repeating_skills_$0_skillname". The ID (the "-ABC123" part of the previous example) will never change for a repeating section row, so you can reference it in macros, abilities, and using the API. New rows that you add will be randomly assigned a new unique ID. Rows are currently ordered in the order in which they were created.
+
Internally, each repeating item is stored in an attribute like so: <code>repeating_skills_-ABC123_dtype</code> or <code>repeating_skills_$0_skillname</code>. The ID (the <code>-ABC123</code> part of the previous example) will never change for a repeating section row, so you can reference it in macros, abilities, and using the API. New rows that you add will be randomly assigned a new unique ID. Rows are currently ordered in the order in which they were created.
 
+
 
+
'''Note: All attributes in the repeating section should have a unique name globally. So if you have 'attr_Qty' in your repeating section, don't have another field called 'attr_Qty' outside of a repeating section or in another repeating section. Repeating sections are hard or impossible to create around a HTML table, and is recommended to be placed within a single cell. '''
+
 
+
==== 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.
+
  
 +
{{mbox | text = '''Note:''' All attributes in the repeating section should have a unique name globally. So if you have <code>attr_Qty</code> in your repeating section, don't have another field called <code>attr_Qty</code> outside of a repeating section or in another repeating section. Repeating sections are hard or impossible to create around a HTML table, and is recommended to be placed within a single cell. }}
  
 
==== Only Use Classes, not IDs ====
 
==== Only Use Classes, not IDs ====
Line 132: Line 160:
 
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:
 
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 general, but it prevents you from changing any of the Roll20 application CSS outside of the character sheets.
+
* All of your CSS styles will be restricted to the <code>.charsheet</code> parent class. So if you put a style called <code>input</code>, the system will automatically prefix that with <code>.charsheet input</code>. This shouldn't affect you in general, 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 <code><input class='shortfield'></code>, when processing your layout it will be changed to <code><input class='sheet-shortfield'></code>.
+
* Note that by default, any HTML classes defined in your HTML layout which don't begin with <code>attr_</code>, <code>roll_</code> or <code>repeating_</code> will be prefixed with <code>sheet-</code>. So for example, if you want to style some of your input tags to be shorter than others and you define the HTML as <code><input class='shortfield'></code>, when processing your layout it will be changed to <code><input class='sheet-shortfield'></code>.
  
  
Line 143: Line 171:
  
 
====Default Sheet Settings====
 
====Default Sheet Settings====
Selectable options can be specified in the sheet.json file provided with your Custom Character Sheet. These options provide default settings across all Characters when your Character Sheet is in use.
+
Selectable options can be specified in the <code>sheet.json</code> file provided with your Custom Character Sheet. These options provide default settings across all Characters when your Character Sheet is in use.
  
 
Read more at '''[[Default Sheet Settings| Default Sheet Settings]]'''
 
Read more at '''[[Default Sheet Settings| Default Sheet Settings]]'''
Line 165: Line 193:
 
The [https://app.roll20.net/compendium 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.
 
The [https://app.roll20.net/compendium 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.
  
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 [https://github.com/Roll20/roll20-character-sheets/blob/master/5th%20Edition%20OGL%20by%20Roll20/sheet.json sheet.json file of the 5th Edition OGL Sheet by Roll20] on Github.
+
To designate compatibility with a Compendium, just include the Compendium's short name in the "compendium" field of your <code>sheet.json</code> file. For an example, see the [https://github.com/Roll20/roll20-character-sheets/blob/master/5th%20Edition%20OGL%20by%20Roll20/sheet.json sheet.json file of the 5th Edition OGL Sheet by Roll20] on Github.
  
  
Line 174: Line 202:
 
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 <code>compendium-drop-target</code> to the <code>div</code> tag surrounding the section you want to fill in. For repeating sections, place this inside of the <code>fieldset</code> tag. Then, add the <code>accept="Attribute Name"</code> attribute to one or more <code>input, select, textarea</code> tags. Here's a simple example which would be compatible with the [https://app.roll20.net/compendium/dnd5e/Fireball Fireball entry] from the 5th Edition SRD Compendium.
 
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 <code>compendium-drop-target</code> to the <code>div</code> tag surrounding the section you want to fill in. For repeating sections, place this inside of the <code>fieldset</code> tag. Then, add the <code>accept="Attribute Name"</code> attribute to one or more <code>input, select, textarea</code> tags. Here's a simple example which would be compatible with the [https://app.roll20.net/compendium/dnd5e/Fireball Fireball entry] from the 5th Edition SRD Compendium.
  
<pre data-language="javascript">
+
<pre data-language="HTML">
  
 
<fieldset class="repeating_spells">
 
<fieldset class="repeating_spells">
Line 264: Line 292:
  
 
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.
 
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.
[[Category:Docs]]
+
 
 +
===Common Mistakes===
 +
 
 +
'''1.''' Forgetting to name attributes with the <code>attr_</code> (e.g. <code><input type="number" name="attr_dexterity"></code> vs. <code><input type="number" name="dexterity"></code>). This results in no data being saved in the field after the sheet is closed.
 +
 
 +
'''2.''' Forgetting to add <code>sheet-</code> to the class names in your <code>.css</code> file. This is not need in the <code>.html</code> file, Roll20 automatically assumes all classes have that prefix there. See [[Building Character Sheets#CSS Styling|CSS Styling]]
 +
 
 +
'''3.''' Not looking at existing sheets. Seeing how existing sheets have been made  and structured can help you avoid reinventing the wheel or making mistakes  as result of knowing HTML/CSS/JavaScript but having little familiarity with how character sheets are created. All sheets in the Character sheet repository are under MIT license so are free(and encouraged) to be used as templates for creating your own sheet, instead of making everything from scratch.
 +
 
 +
'''4.''' Not asking for help when you get stuck. Roll20 has a small but active community who works with creating and improving character sheets, and are often eager to help out if you got stuck on some feature you've tried to figure out. [https://app.roll20.net/forum/category/277980 Roll20 Character Sheet & Compendium Forums]
  
 
==Roll20 Character Sheets Repository==
 
==Roll20 Character Sheets Repository==
Line 274: Line 311:
 
To ensure a consistent quality of character sheets in the repository, all submissions must meet the minimum requirements below. Before submitting a pull request on GitHub please test your code in Roll20 using the Custom sheet.
 
To ensure a consistent quality of character sheets in the repository, all submissions must meet the minimum requirements below. Before submitting a pull request on GitHub please test your code in Roll20 using the Custom sheet.
  
===='''1. Code of Conduct.'''====
+
====1. Code of Conduct.====
  
 
* The [https://wiki.roll20.net/Terms_of_Service_and_Privacy_Policy#Play_Nice_Clauses Roll20's Code of Conduct] applies to character sheets and they must adhere to it.
 
* The [https://wiki.roll20.net/Terms_of_Service_and_Privacy_Policy#Play_Nice_Clauses Roll20's Code of Conduct] applies to character sheets and they must adhere to it.
  
* '''Do not infringe on intellectual property'''. Community sheets should not include character creation or advancement due to potential copyright restrictions. 'By Roll20' sheets may include this content thanks to our partnerships with game creators. Sheets that are developed from the code of a 'By Roll20' will need to ensure any character creation or advancement options code it removed. Its okay to have attributes that auto-calculate based on other attributes (including the current level). We'll let you know if your submitted sheet violates this rule.
+
* '''Do not infringe on intellectual property'''. Community sheets should not include character creation or advancement due to potential copyright restrictions. 'By Roll20' sheets may include this content thanks to our partnerships with game creators. Sheets that are developed from the code of a 'By Roll20' sheet will need to ensure any character creation or advancement options code is removed. It's okay to have attributes that auto-calculate based on other attributes (including the current level). We'll let you know if your submitted sheet violates this rule.
  
 
* There is one specific requirement for Character Sheets. All submissions of new pull requests for any character sheet containing an area for “gender” will need to make that a open text input (as opposed to a drop down menu containing a predefined list of options). This guideline is reflective of our ongoing efforts to be inclusive in our approach to facilitating gaming -- we want the maximum amount of people to be able to game the way that provides them the most fun. In this case, taking the time to address this small programming change makes a huge difference to our community.
 
* There is one specific requirement for Character Sheets. All submissions of new pull requests for any character sheet containing an area for “gender” will need to make that a open text input (as opposed to a drop down menu containing a predefined list of options). This guideline is reflective of our ongoing efforts to be inclusive in our approach to facilitating gaming -- we want the maximum amount of people to be able to game the way that provides them the most fun. In this case, taking the time to address this small programming change makes a huge difference to our community.
  
===='''2. Good Code'''====
+
====2. Good Code====
  
 
* '''Minimum styling'''. All character sheets should have a small amount of CSS & HTML styling to make them aesthetically pleasing and usable. For example elements should not unintentionally overlap when a window is resized. The sheet should be familiar to players who are used to seeing the paper version of that sheet. It need not be identical to the paper version and should avoid violating any copyright, but it also shouldn't be laid out in such a crazy way that players will have a hard time understanding how to use it. '''Design for ease of use first and foremost.'''
 
* '''Minimum styling'''. All character sheets should have a small amount of CSS & HTML styling to make them aesthetically pleasing and usable. For example elements should not unintentionally overlap when a window is resized. The sheet should be familiar to players who are used to seeing the paper version of that sheet. It need not be identical to the paper version and should avoid violating any copyright, but it also shouldn't be laid out in such a crazy way that players will have a hard time understanding how to use it. '''Design for ease of use first and foremost.'''
Line 292: Line 329:
 
* '''Chrome & Firefox Compatible'''. The two official supported browsers of Roll20 are Chrome & Firefox. All character sheets need to be tested for functionality and styling in these two browsers.
 
* '''Chrome & Firefox Compatible'''. The two official supported browsers of Roll20 are Chrome & Firefox. All character sheets need to be tested for functionality and styling in these two browsers.
  
===='''3. A Satisfactory Experience'''====
+
====3. A Satisfactory Experience====
  
 
* '''Character Sheets must be standalone by default'''. All basic sheet functionality must be usable without external requirements such as images or fonts hosted outside Roll20, and API companion scripts. API companions are a welcome supplement for character sheets but to ensure accessibility & functionality to community members at all of subscription levels the sheet must be usable by default without outside requirements.
 
* '''Character Sheets must be standalone by default'''. All basic sheet functionality must be usable without external requirements such as images or fonts hosted outside Roll20, and API companion scripts. API companions are a welcome supplement for character sheets but to ensure accessibility & functionality to community members at all of subscription levels the sheet must be usable by default without outside requirements.
Line 318: Line 355:
 
* '''[https://wiki.roll20.net/Building_Character_Sheets#Compendium_Integration Compendium Integration]'''. By designating that your sheet is compatible with a Compendium, players will have direct access to that Compendium in the right sidebar during gameplay. Compendiums are still a growing feature on Roll20 and integration is not yet available to the majority of game systems.
 
* '''[https://wiki.roll20.net/Building_Character_Sheets#Compendium_Integration Compendium Integration]'''. By designating that your sheet is compatible with a Compendium, players will have direct access to that Compendium in the right sidebar during gameplay. Compendiums are still a growing feature on Roll20 and integration is not yet available to the majority of game systems.
  
* '''Include attribute names in Titles'''. Adding <code>title=@{attribute_name}</code> helps macro creators find the name of attributes easier. Titles are occasionally used for other purposes so use your best judgement.
+
* '''Include attribute names in Titles'''. Adding <code>title=@{attribute_name}</code> helps macro creators find the name of attributes easier. Titles are occasionally used for other purposes so use your best judgment.
  
* '''Link to wiki page''' If you have created a wiki page for your sheet, you could link to in in the ''sheet.json'' 's ''instructions'' section
+
* '''Link to wiki page''' If you have created a wiki page for your sheet, you could link to in in the ''sheet.json'' 's <code>instructions</code> section
  
 
===Best Practices===
 
===Best Practices===
Line 326: Line 363:
 
These are general best practice guidelines to help increase consistency among sheet authors in order to make more maintainable code repository for the community.
 
These are general best practice guidelines to help increase consistency among sheet authors in order to make more maintainable code repository for the community.
  
 +
====Attributes/Inputs====
 
* '''Attribute names should be in lowercase'''. For the sake of consistency everyone doing this makes the programming life a little easier.
 
* '''Attribute names should be in lowercase'''. For the sake of consistency everyone doing this makes the programming life a little easier.
  
* '''Avoid !important'''. Whenever possible try to avoid using <code>!important</code> in CSS as it can create a cascading effect of ever more !importants.
+
* '''RPGs have weird words'''. Utilize <code>spellcheck="false"</code> for text inputs and textareas to prevent the browser from indicating spell errors.
  
* '''Avoid Asynchronous cascades'''. Whenever possible avoid asynchronous cascades for sheet workers. An example of this is, getAttrs -> calculations -> setAttrs -> getAttrs -> calculations -> setAttrs… A better way to do this is getAttrs for everything you'll need then do all necessarily calculations before finally using a single setAttrs.
+
* '''Use fewer Attributes & Inputs'''. The more attributes and inputs you have the slower the sheet will load. This is not a concern for the average sheet but robust sheets such as the ''D&D 5E Sheet by Roll'' or the ''Pathfinder (Community)'' excess attributes & inputs can lead to performance issues if left unmanaged.
  
* '''Don't repeat sheet- for CSS Class'''. Sheet- is automatically added to the CSS classes in the HTML so repeating it in the HTML is redundant. For example in the HTML instead of <code>class="sheet-strRow"</code> just do <code>class="strRow"</code>.
+
* '''Spans over disabled inputs'''. [https://wiki.roll20.net/CSS_Wizardry#Attribute-Backed_.3Cspan.3Es Attribute-backed spans] are more efficient than disabled inputs.
  
* '''Include a minimum width'''. Including a minimum width on the sheet will help with resizing. Try to not exceed the default width when a sheet opens for the first time, approximately 800px-900px. Character sheets with an NPC view may be smaller and elaborate PC sheets are sometimes bigger. 
+
====Sheetworkers & Roll Templates====
  
* '''Include all images in the Git Repository'''. Images should be included in the GitHub repository for easy access, reduced external dependencies, and simpler updates.
+
* '''Avoid Asynchronous cascades'''. Whenever possible avoid asynchronous cascades for sheet workers. An example of this is, getAttrs -> calculations -> setAttrs -> getAttrs -> calculations -> setAttrs… A better way to do this is getAttrs for everything you'll need then do all necessarily calculations before finally using a single setAttrs.
  
* '''Use fewer Attributes & Inputs'''. The more attributes and inputs you have the slower the sheet will load. This is not a concern for the average sheet but robust sheets such as the ''D&D 5E Sheet by Roll'' or the ''Pathfinder (Community)'' excess attributes & inputs can lead to performance issues if left unmanaged.
+
* '''Sheet Workers over Auto Calculated attributes'''. Sheet workers trigger when events happen which improves performance for character sheets over auto calculated attributes since these events occur less frequently.
  
* '''RPGs have weird words'''. Utilize <code>spellcheck="false"</code> for text inputs and textareas to prevent the browser from indicating spell errors.
+
* '''Place rolltemplates and sheetworkers at bottom of the html page''' It's considered [https://www.htmlgoodies.com/html5/javascript/best-practices-for-combining-javascript-with-html.html best practice to place JavaScript at end of pages]
  
* '''Sheet Workers over Auto Calculated attributes'''. Sheet workers trigger when events happen which improves performance for character sheets over auto calculated attributes since these events occur less frequently.
+
====Other Roll20-specific====
  
* '''Spans over disabled inputs'''. [https://wiki.roll20.net/CSS_Wizardry#Attribute-Backed_.3Cspan.3Es Attribute-backed spans] are more efficient than disabled inputs.
+
* '''Avoid !important'''. Whenever possible try to avoid using <code>!important</code> in CSS as it can create a cascading effect of ever more !importants.
  
* '''Try to be close to XHTML standard'''. For example ending elements with a slash like this <code><input ... /></code>.
+
* '''Don't include''' <code>sheet-</code> '''for CSS Class names in the HTML'''. <code>sheet-</code> is automatically added to the CSS classes in the HTML, so it's redundant to repeat it there. Leaving it out also increases readability if lots of classes are used.
 +
** For example in the HTML, instead of <code>class="sheet-strRow"</code>, just do <code>class="strRow"</code>.
 +
: WARNING: the above is untrue for classes of <rolltemplate> elements. For those, you do need to specify the full class name (i.e. starting with <code>sheet-</code>) or your rolltemplates will simply stop working.
  
* '''Use inline styles as a last resort'''. Inline styles are less maintainable code and external style sheets are almost always a better option. Keep <code>style =</code> attributes in the HTML to as few as possible.
+
* '''Include a minimum width'''. Including a minimum width on the sheet will help with resizing. Try to not exceed the default width when a sheet opens for the first time, approximately 800px-900px. Character sheets with an NPC view may be smaller and elaborate PC sheets are sometimes bigger.  
  
 
* '''Use Supported Fonts'''. There are five named fonts you can use for text: Arial, Patrick Hand, Contrail One, Shadows Into Light, and Candal. There are also a variety of [https://wiki.roll20.net/CSS_Wizardry#Icon_Fonts icon fonts].
 
* '''Use Supported Fonts'''. There are five named fonts you can use for text: Arial, Patrick Hand, Contrail One, Shadows Into Light, and Candal. There are also a variety of [https://wiki.roll20.net/CSS_Wizardry#Icon_Fonts icon fonts].
 +
 +
* '''Use ^{ } for translations in button macros'''. In your button macros using ^{key} will insert the appropriate key from the appropriate language's translation json. This makes roll templates more adaptable to other languages.
 +
 +
====GitHub/Sheet Submission====
  
 
* '''Use <code>git branch</code> for your work in progress'''. Create a new branch to store your work in progress. Only merge finished code into the ''roll20-character-sheets'' master branch when its ready for a pull request. This will help prevent submitting pull requests with unfinished code which can result in a delay for your code merge. Better yet, fork the roll20-character-sheets repository, and submit your pull requests through GitHub. More information can be found at the [https://wiki.roll20.net/Beginner%27s_Guide_to_GitHub Guide to GitHub].
 
* '''Use <code>git branch</code> for your work in progress'''. Create a new branch to store your work in progress. Only merge finished code into the ''roll20-character-sheets'' master branch when its ready for a pull request. This will help prevent submitting pull requests with unfinished code which can result in a delay for your code merge. Better yet, fork the roll20-character-sheets repository, and submit your pull requests through GitHub. More information can be found at the [https://wiki.roll20.net/Beginner%27s_Guide_to_GitHub Guide to GitHub].
  
* '''Use ^{ } for translations in button macros'''. In your button macros using ^{key} will insert the appropriate key from the appropriate language's translation json. This makes roll templates more adaptable to other languages.
+
* '''Include all images in the Git Repository'''. Images should be included in the GitHub repository for easy access, reduced external dependencies, and simpler updates.
 +
 
 +
====General HTML/CSS/Coding====
 +
General tips that applies beyond just working with creating character sheets for Roll20
 +
 
 +
* '''Try to be close to XHTML standard'''. For example ending elements with a slash like this <code><input ... /></code>.
 +
* '''Use inline styles as a last resort'''. Inline styles are less maintainable code and external style sheets are almost always a better option. Keep <code>style =</code> attributes in the HTML to as few as possible.
 +
* '''Write readable code''' If the code is more readable, it's easier for other sto contibute and collaborate. [https://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code--net-8118 15 Tips on writing readable code]
 +
* '''Follow general HTML/CSS Styleguides''' When not contradiction Roll20-specific best practice, follow recommended style-guides to keep your code consistent and more readable, such as:
 +
** [https://google.github.io/styleguide/htmlcssguide.html Google's HTML/CSS Styleguide]
 +
** [https://css-tricks.com/css-style-guides/ css-tricks.com Style Guides collection]
 +
 
 +
==See Also==
 +
===Sheet Templates/Examples===
 +
* [https://github.com/Roll20/roll20-character-sheets/tree/master/kitchensink Roll20's character sheet] template
 +
* [https://github.com/clevett/SheetTemplate Cassie's Flexbox-based sheet template]
 +
* [https://github.com/Anduh/Roll20-grid-template CSS Grid sheet template]
 +
* [https://github.com/joesinghaus/Blades-template Sheet template based on Blades in the Dark] by Jakob
 +
==Useful scripts==
 +
* [https://github.com/Anduh/SublimeSettings SublimeSettings] - Roll20-specific HTML Syntax highlight for [https://www.sublimetext.com/ Sublime Text]
 +
* [https://github.com/Anduh/acsi ACSI] - Automation for adding translation attributes to a sheet
 +
==Related Pages==
 +
* [[CSS Wizardry|CSS styling]]
 +
* [[Sheet Worker Scripts|Sheetworkers]]
 +
* [[Roll Templates|Roll Template Creation]]
 +
* [[Character Sheet i18n|Sheet translation]]
 +
* [[Dice Reference]] - how the Roll20 dice/math works
 +
* [[Macros]]
 +
* [[:Category:Character Sheet Creation|List of pages with "Character Sheet Creation"-category]]
 +
* [[Sheet Requests| List of Character Sheet Requests]] (that are not yet represented on Roll20)
 +
* [[Character Sheet Index]] - List of Character Sheets on Roll20 (not always up to date)
 +
* [https://app.roll20.net/forum/category/277980 Roll20 Forums - Character Sheets & Compendiums] - Best place for getting help form other sheet creators and current info
 +
 
 +
 
 +
<br />
 +
[[Category:Docs]]
 +
[[Category:Character Sheet Creation]]

Revision as of 18:23, 12 November 2019

The "Sheet Editor", accessible when the Character Sheet is set to "Custom" in the Game Settings

Contents

Building a Character Sheet

Game Settings Menu Options.jpg

To build a sheet, you must have access to a Pro account.

To edit a custom character sheet for a game:

  1. Select the Games menu, and select My Games.
  2. Select the game to go to the campaign details page.
  3. Under the Settings menu, select Game Settings.
  4. Select Custom from the Character Sheet Template menu.

The editor has four tabs: HTML Layout, CSS Styling, Translation, and Preview.





Restrictions & Security Filtering

Generally speaking, character sheets are created with HTML, CSS, and JavaScript( for Sheetworkers), but there exist some constrains that is good to know for the intermediate and advanced user. There are a few caveats to be aware of in regards to the security filtering that Roll20 applies to your HTML as well:

HTML:

In the browser, the character sheet is basically wrapped inside a giant <form> tag.

  • Id attributes cannot be used. (Any ID attributes on one character's sheet would affect another character's sheet in the same campaign when opened
  • any DOM functionalities can't be used
  • Do not use reserved HTML tags such as <head> or <body> in your character sheet HTML. Doing so will prevent your character sheet from loading in the virtual tabletop
  • Some tags like <section>, <header>, <footer>,<footer> don't work either
  • Attribute names are case-insensitive when checked for uniqueness. All inputs (and selects, and textareas, etc.) should have a unique attribute name
  • 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.
  • <svg> doesn't seem to be supported

CSS:

JavaScript

  • DOM can't be used
  • Some javascript functions or functionalities can't be used, See Sheetworker Documentation for more details

Other/General:

  • Limited Font support. The following fonts can be used: Arial, Patrick Hand, Contrail One, Shadows Into Light and Candal

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 Javascript on your sheet template except in the case of sheet worker scripts.


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. (Note: <input> tags must have a type specified (text, number, hidden, checkbox, or radio)). 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. If you want the field to utilize the "max" of an attribute instead of the normal value, you can append "_max" onto the name of the field. For example, <input type="text" name="attr_Strength_max" />. You can also use a < span > tag to display a read-only value on your sheet. For example, < span name="attr_Strength"></ span>. It is possible to include a span tag that has the same attribute name as an input tag, and the span tag will be updated whenever the input is modified.

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

Character Names

When adding a text field for the name of the character, you can make it automatically link with the journal's character name by giving it the name attribute of attr_character_name.

<input type="text" name="attr_character_name" />

Checkboxes and Radio Buttons

For checkboxes and radio buttons, you must always specify a value attribute.

For checkboxes, if the box is checked the attribute will be set to the value of the checkbox. If it is not checked, it will be set to "0". If you would like a checkbox to be checked by default, add the "checked=true" attribute. For example, <input type='checkbox' name='attr_HasShield' value='1' checked='true' />.

For radio buttons, if one of the radio buttons is selected, the attribute will be set to the value of that radio button. If no radio buttons are selected, the value will be an empty string. At least one of the radio buttons should have the checked="true" attribute to set a default value. Radio buttons are the only type of field where it is permissible to have more then one field with the same "name" attribute. For example, <input type='radio' value='10' name='attr_Multiplier' /><input type='radio' value='25' name='attr_Multiplier' checked='true' />.

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.

Note that you can only include attributes from the current Character. You also can't include macros, abilities, or rolls...just basic math such as @{Intelligence}/2+@{Level}. You also have access to the floor, round, and ceil functions, such as floor(@{Intelligence}/2).

If your auto-calculated field depends of another auto-calculated field(s), you have to add parenthesis around intermediate formula(s). Otherwise miscalculations could appear. Example : <input type="number" name="attr_StrMod" value="(@{Strength}/2)" disabled="true" />

<input type="number" name="attr_StrModLeveled" value="@{StrMod}+@{Level}" disabled="true" />

Note that calculations do not show up in the Preview, they only show on a character sheet in-game.

Auto-calculating values will increase the load of a sheet when its opened and as a result should be used sparingly. Consider using sheet worker scripts to complete calculations that are conditional.

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='roll_BluffCheck'></button>. 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}. Note: The names you give your Sheet Rolls must be unique from any Ability names on your Characters if you want to reference them in Abilities or Macros. You can also just not give your Sheet Rolls names if you just want them to only be rolled by clicking the button on the Sheet itself.

See also:

Columns and Layout

Many sheet authors recommend using your own CSS for styling and to layout the sheet. Roll20 provides a few basic classes you can use to organize things into a simple column-based layout. To use them, just create a div with a class of '3colrow', '2colrow', or 'row'. Then inside of that div, create a div for each column with a class of 'col'. For example, to create a 3-column layout, you would could:

<div class='3colrow'>
<div class='col'>
<!-- Put the content for the first column here -->
</div>
<div class='col'>
<!-- Second column -->
</div>
<div class='col'>
<!-- Third column -->
</div>
</div>

For more flexible and advanced CSS, you are encouraged to explore the popular CSS Flexbox and CSS Grid frameworks.

Here's a character sheet template using Flexbox, and another one using Grid

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" 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 include an 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_-ABC123_dtype or repeating_skills_$0_skillname. The ID (the -ABC123 part of the previous example) will never change for a repeating section row, so you can reference it in macros, abilities, and using the API. New rows that you add will be randomly assigned a new unique ID. Rows are currently ordered in the order in which they were created.


Only Use Classes, not IDs

You should not use IDs on your tags (for example, DO NOT do <input type='text' id='name' />). Since there are multiple copies of each sheet in the DOM at once, using an ID is incorrect since IDs should only be used on unique elements.

This does mean that you cannot utilize ID-linked <label> elements (eg, <label for="my_id">My Label Text</label>). You can place elements inside the label to link them together (eg, <label>Label Text <input ... /></label>), although that can come at the expense of some flexibility in your CSS.

Complete Example

Here's a complete example of a basic Savage Worlds sheet HTML layout and CSS stylesheet: Kitchen Sink example

If you're looking for a more advanced example that makes use of Sheet Workers, Compendium Integration, Roll Templates, and more, see the D&D 5E by Roll20

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 general, 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'>.


Read more at CSS Wizardry

Advanced Sheet Options

Advanced options are not required for a basic character sheet but can enhance your sheet's capability and usability.

Default Sheet Settings

Selectable options can be specified in the sheet.json file provided with your Custom Character Sheet. These options provide default settings across all Characters when your Character Sheet is in use.

Read more at Default Sheet Settings

Sheet Workers Scripts

Sheet Worker Scripts are an advanced feature of the Character Sheets system which allows the sheet author to specify JavaScript which will execute during certain events, such as whenever the values on a sheet are modified. It is highly recommended to use these in place of Auto-Calculating Fields whenever you have values that infrequently change, such as when a Character levels up or adds a new spell or attack.

Read more at Sheet Worker Scripts

Roll Templates

Roll Templates allow you to fully customize how the rolls from your sheet appear in the chat window to all players. It's a great way to make the entire Roll20 experience match a common theme.

Read more at Roll Templates

Compendium Integration

Designating Compatibility for Your Sheet

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.

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

Translating Character Sheets

Character sheets can be translated into other languages using the crowdsourced translation service Crowdin. Character sheet authors have a number of controls over how the sheet is translated, and how the translation is displayed. Users willing to become translators should email team@roll20.net.

Read more at Character Sheet i18n

Patreon and Tipeee Linking Rules for Community Sheet Contributors

For sheet authors that are contributing to the Roll20 community character sheet database, they are approved to advertise via subscription/donation service sites: Patreon and Tipeee. Roll20 is not responsible for any payment transactions and cannot enforce any private arrangements.

In order to qualify, a sheet author must first have their sheet contribution approved by the Roll20 staff and included into the community character Sheet database.

You will want to include your Patreon or Tipeee account information in the sheet.json file that should be included with your sheet submission on GitHub.

The json file should have one of these fields added to it if you wish to advertise with Patreon or Tipeee:

patreon: Place the URL for a Patreon campaign here, and it will appear under your sheet's description when selected. (e.g."https://www.patreon.com/<name>")
tipeee: Place the URL for a Tipeee here, and it will appear under your sheet's description when selected. (e.g. "https://www.tipeee.com/<name>")

For more information, see https://github.com/Roll20/roll20-character-sheets#contributing

Linking to Patreon/Tipeee on the Roll20 Forums

Linking to Patreon or Tipeee on the Roll20 Forums are only permitted for pre-approved community members who have contributing either Character Sheets or API Scripts. If you wish to solicit users directly for funding you may do so privately, but no such links are permitted in a public forum without any contributed material.

Preview Panel

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.

Common Mistakes

1. Forgetting to name attributes with the attr_ (e.g. <input type="number" name="attr_dexterity"> vs. <input type="number" name="dexterity">). This results in no data being saved in the field after the sheet is closed.

2. Forgetting to add sheet- to the class names in your .css file. This is not need in the .html file, Roll20 automatically assumes all classes have that prefix there. See CSS Styling

3. Not looking at existing sheets. Seeing how existing sheets have been made and structured can help you avoid reinventing the wheel or making mistakes as result of knowing HTML/CSS/JavaScript but having little familiarity with how character sheets are created. All sheets in the Character sheet repository are under MIT license so are free(and encouraged) to be used as templates for creating your own sheet, instead of making everything from scratch.

4. Not asking for help when you get stuck. Roll20 has a small but active community who works with creating and improving character sheets, and are often eager to help out if you got stuck on some feature you've tried to figure out. Roll20 Character Sheet & Compendium Forums

Roll20 Character Sheets Repository

The Roll20 GitHub repository is a collection of all the community-contributed character sheets that are available for use on Roll20.  Its intended purpose is to provide fans of game a way of creating system specific support.

Minimum Requirements

To ensure a consistent quality of character sheets in the repository, all submissions must meet the minimum requirements below. Before submitting a pull request on GitHub please test your code in Roll20 using the Custom sheet.

1. Code of Conduct.

  • Do not infringe on intellectual property. Community sheets should not include character creation or advancement due to potential copyright restrictions. 'By Roll20' sheets may include this content thanks to our partnerships with game creators. Sheets that are developed from the code of a 'By Roll20' sheet will need to ensure any character creation or advancement options code is removed. It's okay to have attributes that auto-calculate based on other attributes (including the current level). We'll let you know if your submitted sheet violates this rule.
  • There is one specific requirement for Character Sheets. All submissions of new pull requests for any character sheet containing an area for “gender” will need to make that a open text input (as opposed to a drop down menu containing a predefined list of options). This guideline is reflective of our ongoing efforts to be inclusive in our approach to facilitating gaming -- we want the maximum amount of people to be able to game the way that provides them the most fun. In this case, taking the time to address this small programming change makes a huge difference to our community.

2. Good Code

  • Minimum styling. All character sheets should have a small amount of CSS & HTML styling to make them aesthetically pleasing and usable. For example elements should not unintentionally overlap when a window is resized. The sheet should be familiar to players who are used to seeing the paper version of that sheet. It need not be identical to the paper version and should avoid violating any copyright, but it also shouldn't be laid out in such a crazy way that players will have a hard time understanding how to use it. Design for ease of use first and foremost.
  • Proper HTML Syntax. Proper HTML syntax is encouraged to increase accessibility and make the code maintainable for community contributions. As a general standard a <⁠table> element should only be used for tabular data. The <⁠table> shall not be used for layouts. All new sheets are expected to use proper containers elements such as <⁠div> and <⁠span> elements. Your HTML file must not use <⁠head> or <⁠body> tag, or your character sheet may not load in the virtual tabletop.
  • Unix server compatibility is required. All CSS, HTML, and JSON files are required to be submitted with Unix line endings (LF). A Google search can tell you how to set this in your favorite text editor. Additionally every submission must include a valid sheet.json file and a preview image. Directions for creating a proper sheet.json can be found on the GitHub README.
  • Chrome & Firefox Compatible. The two official supported browsers of Roll20 are Chrome & Firefox. All character sheets need to be tested for functionality and styling in these two browsers.

3. A Satisfactory Experience

  • Character Sheets must be standalone by default. All basic sheet functionality must be usable without external requirements such as images or fonts hosted outside Roll20, and API companion scripts. API companions are a welcome supplement for character sheets but to ensure accessibility & functionality to community members at all of subscription levels the sheet must be usable by default without outside requirements.
  • Functional Roll Buttons. The best sheets not only keep track of character stats, they have the most common rolls for the game system embedded in them. This makes it much easier for new players to play the game by adding intuitive functionality. While you don't have to include every roll in the whole system, including frequently used rolls where appropriate can elevate your sheet to the next level. Games that do not have rolls such as Amber Diceless Roleplaying Game are not required to meet this standard. If you are designing a sheet for a system where this requirement does not apply please include a comment in your pull request.
  • Inputs & Textfields for data tracking. Character sheets for game systems which have attributes and stats should include <input> elements for users to keep track of their data. Whenever possible, use standard names for attributes, spelled out. For example, "intelligence", "strength", and "wisdom". This is important so that if a character is imported into a game with a different sheet, most of the values will be able to transition. If the attribute names are all different, then nothing can be imported. Your best bet is to look at existing sheets for that system and whenever possible use the same attribute names that are already in use. Similarly <textarea> tags should be included were applicable for users to add notes or descriptions. This requirement is highly variable based on the system and if this requirement is not applicable to the game system you are creating a sheet for please include a comment in your pull request.
  • Rules must be readily available. Sheets can be submitted for independent games and homebrew systems. Homebrew games will need to ensure they are not violating copyright for their respective game system. In both cases the rules need to be readily available online to the public.

Beyond the Minimum

The suggestions below are not required of new character sheets requesting to be added to the repository. Aspiring sheet authors new to front end development should focus on meeting the minimum requirements for their sheet's version one. When you are comfortable with the basics, the suggestions below can take the sheet one step further to shine as beacons of high quality fun.

  • CSS Wizardy. Our community of sheet authors are exceptionally clever and creative. They offer here example of ways to leverage the character sheet system.
  • Customized Roll Templates. Roll templates can be customized to match the color scheme & style of your character sheet. Additionally they can be utilized to help users achieve a roll output that matches the game system's specific mechanics.
  • Sheet Workers are a powerful tool!. These scripts are an advanced feature of the Character Sheets system which allows the sheet author to specify JavaScript to execute during certain events, such as whenever the values on an input are modified.
  • Translation Keys. Character Sheet i18n, or internationalization, will allow you to design your character sheet in such a way that our community of translators will be able to translate your sheet into their language, making that language available to anyone on Roll20. As of September 2016, we will no longer be accepting new character sheets that are simply alternate translations of already-existing character sheets.
  • Default Sheet Settings. Selectable options can be specified in the sheet.json file provided with your Custom Character Sheet. These options provide default settings across all Characters when your Character Sheet is in use.
  • Compendium Integration. By designating that your sheet is compatible with a Compendium, players will have direct access to that Compendium in the right sidebar during gameplay. Compendiums are still a growing feature on Roll20 and integration is not yet available to the majority of game systems.
  • Include attribute names in Titles. Adding title=@{attribute_name} helps macro creators find the name of attributes easier. Titles are occasionally used for other purposes so use your best judgment.
  • Link to wiki page If you have created a wiki page for your sheet, you could link to in in the sheet.json 's instructions section

Best Practices

These are general best practice guidelines to help increase consistency among sheet authors in order to make more maintainable code repository for the community.

Attributes/Inputs

  • Attribute names should be in lowercase. For the sake of consistency everyone doing this makes the programming life a little easier.
  • RPGs have weird words. Utilize spellcheck="false" for text inputs and textareas to prevent the browser from indicating spell errors.
  • Use fewer Attributes & Inputs. The more attributes and inputs you have the slower the sheet will load. This is not a concern for the average sheet but robust sheets such as the D&D 5E Sheet by Roll or the Pathfinder (Community) excess attributes & inputs can lead to performance issues if left unmanaged.

Sheetworkers & Roll Templates

  • Avoid Asynchronous cascades. Whenever possible avoid asynchronous cascades for sheet workers. An example of this is, getAttrs -> calculations -> setAttrs -> getAttrs -> calculations -> setAttrs… A better way to do this is getAttrs for everything you'll need then do all necessarily calculations before finally using a single setAttrs.
  • Sheet Workers over Auto Calculated attributes. Sheet workers trigger when events happen which improves performance for character sheets over auto calculated attributes since these events occur less frequently.

Other Roll20-specific

  • Avoid !important. Whenever possible try to avoid using !important in CSS as it can create a cascading effect of ever more !importants.
  • Don't include sheet- for CSS Class names in the HTML. sheet- is automatically added to the CSS classes in the HTML, so it's redundant to repeat it there. Leaving it out also increases readability if lots of classes are used.
    • For example in the HTML, instead of class="sheet-strRow", just do class="strRow".
WARNING: the above is untrue for classes of <rolltemplate> elements. For those, you do need to specify the full class name (i.e. starting with sheet-) or your rolltemplates will simply stop working.
  • Include a minimum width. Including a minimum width on the sheet will help with resizing. Try to not exceed the default width when a sheet opens for the first time, approximately 800px-900px. Character sheets with an NPC view may be smaller and elaborate PC sheets are sometimes bigger.
  • Use Supported Fonts. There are five named fonts you can use for text: Arial, Patrick Hand, Contrail One, Shadows Into Light, and Candal. There are also a variety of icon fonts.
  • Use ^{ } for translations in button macros. In your button macros using ^{key} will insert the appropriate key from the appropriate language's translation json. This makes roll templates more adaptable to other languages.

GitHub/Sheet Submission

  • Use git branch for your work in progress. Create a new branch to store your work in progress. Only merge finished code into the roll20-character-sheets master branch when its ready for a pull request. This will help prevent submitting pull requests with unfinished code which can result in a delay for your code merge. Better yet, fork the roll20-character-sheets repository, and submit your pull requests through GitHub. More information can be found at the Guide to GitHub.
  • Include all images in the Git Repository. Images should be included in the GitHub repository for easy access, reduced external dependencies, and simpler updates.

General HTML/CSS/Coding

General tips that applies beyond just working with creating character sheets for Roll20

  • Try to be close to XHTML standard. For example ending elements with a slash like this <input ... />.
  • Use inline styles as a last resort. Inline styles are less maintainable code and external style sheets are almost always a better option. Keep style = attributes in the HTML to as few as possible.
  • Write readable code If the code is more readable, it's easier for other sto contibute and collaborate. 15 Tips on writing readable code
  • Follow general HTML/CSS Styleguides When not contradiction Roll20-specific best practice, follow recommended style-guides to keep your code consistent and more readable, such as:

See Also

Sheet Templates/Examples

Useful scripts

Related Pages