1. Roll20 Help Center
  2. Sheet Development
  3. General

Minimum Requirements & Best Practices

To ensure a consistent quality of character sheets in the repository, all submissions must meet the minimum requirements below. 

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 an 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. 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.
  • No <⁠table> used for layout. As a general standard a <⁠table> element should only be used for tabular data. The <⁠table> shall not be used for layouts. See Designing Character Sheet Layout for alternatives.
  • 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 Mod (API) companion scripts. Mod (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.
  • Respect existing sheets. before starting work on a new sheet, ensure that a sheet doesn't already exist for the system you're working on. Building more than one sheet for the same game splits the party, and makes it harder for the game's community to grow on Roll20! Overhauls of existing community sheets which haven't seen maintenance in over a year are permissible if you can't get in contact with the original author. In those cases, efforts must be taken to convert existing attributes from the old sheet so that the data in existing campaigns does not get erased.
  • 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 that are looking to be added to the repository. Aspiring sheet authors new to front-end development should focus on meeting the minimum requirements above for their sheet's version one. However, once you are comfortable with the basics, the suggestions below can take the sheet one step further and make it really shine.

  • CSS Wizardry. 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 no longer accept 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 best practice guidelines to help increase consistency among sheet authors in order to provide a maintainable code repository for the community.

Attributes/Inputs

  • Attribute names should be in lowercase. For the sake of consistency, everyone doing this makes programming 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.

Dark Mode Styling Details

  • Theme Switch
    When a user switches to dark mode, the virtual tabletop adds the specific CSS class .sheet-darkmode to the <body> element. When flipping the switch back to light, that class is removed.
  • Theme Change
    By adding color choices to the end of your sheets your sheet’s CSS, wrapped in a body.sheet-darkmode { } users will see the change when they flip the switch.

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 ^{ } 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. 
  • Include all images in the Git Repository. Images should be included in the GitHub repository for easy access, reduced external dependencies, and simpler updates.

Read more at Beginner's Guide to GitHub.

General HTML/CSS/Coding

General tips that apply 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 others to contibute and collaborate. 18 Tips on writing readable code
  • Follow general HTML/CSS style guides. When not contradiction Roll20-specific best practice, follow recommended style-guides to keep your code consistent and more readable, such as:
Was this article helpful?
25 out of 37 found this helpful