Revision as of 15:13, 7 October 2021

Page Updated:   2021-10-07

This is about a Roll20 feature exclusive to Pro-subscribers (and often to players in a Game created by a Pro-subscriber). If you'd like to use this feature, consider upgrading your account.

This page is about creating/editing Custom Character Sheets(Pro feature), and how to use <button> HTML element.

The <button> have three roll20-specific types that can be used in character sheets; type="roll", type="action", type="compendium".

This guide gives a rundown of how each type is used, together with some examples on how to implement common things. More examples could be added under the appropriate section.

These tips & examples are made to work with Legacy Sheet, so need adjustments to work with newer CSE-sheets. See the Character Sheet Enhancement-page for more info. Andreas J. (talk) 16:12, 15 April 2021 (UTC)

General

The code for the Example Buttons displayed at the top of this page:

<button type="roll" name="roll_exampleroll1" value="/roll d20 + 4" ></button>
<button type="roll" name="roll_exampleroll2" value="/roll d20 + 4">Roll Button</button>
<button type="action" name="act_exampleaction" >Action Button</button>
<button type="compendium" name="act_actionexample" >Compendium Button</button>

Examples of default Roll Button, Action Button, and Compendium Button

Roll Button

The common use for buttons in Roll20 is for making a roll button. By default, roll buttons show a d20 icon, and if any text is added to be displayed on the button, it is shown after the d20 icon.

Example:

<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck">Roll Bluff</button>

• type-attribute must be set to roll
• value-attribute defines the the roll macro
• name-attribute allows the roll to be referenced in external Macros&q Text Chat as well as dragged to the Macro Quickbar. The name must be prefixed with roll_ for it to work, and each roll button should have a unique name.
  • Buttons names in repeating sections gain a unique prefix in their name based on their RowID and the rep section's name, placing the name last.
  • if you have multiple buttons with the same name, and you call the button name, Roll20 seems to call the last button in the HTML.
  • if button has no name, it cant be dragged to quickbar nor referenced in the chat.
• (optional) add text to the Roll Button. in the above example, the button will show the d20 icon and the text "Roll Bluff". If left empty, the button only shows the default d20 icon. See the example image on this page.

To call a named roll button in the chat, it works similarly like calling a defined Ability macro from the A & A tab, e.g. %{Bob|BluffCheck}. This will call the "BluffCheck" button of the character named "Bob".

Roll Macro

Details on creating more advanced roll macros, check Complete Guide to Macros & Rolls‎.

The roll macro is placed in the value field.

<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck"></button>

For creating more advanced rolls, you can choose to have parts of the macro defined in an attribute(and more easily edited by the player or sheetworkers, or use Roll Templates:

<button type="roll" value="&{template:default} {{name=Magic attack (@{character_name}) }} {{Roll=[[@{intelligence}d6 + @{mana}d6 ]]}}" name="roll_Magic1"></button>

Don't add line-breaks to to your roll macro or it might break the entire roll. Leave the whole <button>-element on a single row.

See also:

• Select Attributes for Sheet Roll - An advanced technique for a dynamic roll button

Roll Query, with Toggle

In your roll macro you can include an option roll query, that gives a popup asking if you want to add some modifier, either through a simple text field, or a dropdown. However, some users of the sheet might not always use it, so an option to turn on/off this popup is a good idea.

Here is a simple way you can have an optional element in your rolls that can be toggled with a simple checkbox.

<span>Modifier popup for rolls?<input type="checkbox" name="attr_rollmod" value="?{Modifiers?|0}"></span>
<input type="number" name="attr_composure" value="1" >
<button type="roll" name="roll_composure" value="&{template:default} {{name=Composure check}} {{result=[[(@{composure} + @{rollmod})d6]]}}"></button>
<input type="number" name="attr_reaction" value="1" >
<button type="roll" name="roll_reaction" value="&{template:default} {{name=Reaction check}} {{result=[[(@{reaction} + @{rollmod})d6]]}}"></button>

You can then use the checkbox's rollmod-attribute in multiple buttons at the same time, which means you can toggle the roll query on the whole sheet at the same time.

If you want to have more options, you can replace the checkbox with an <select> like this:

<select name="attr_rollmod">
   <option value="0" checked>Nothing</option>
   <option value="?{Modifier?|0}">Ask for Roll Modifier</option>
   <option value="@{level}">Add level to roll</option>
</select>

Initiative

More info: Macros#Rolling_For_Initiative & Turn Tracker

To send a roll result directly to the Turn Tracker, first, select the Token you wish to roll for initiative, use make a roll that has the &{tracker} in it.

Examples:

<button type="roll" name="roll_init" value="/roll 1d10 + 2 &{tracker}"></button>
<button type="roll" name="roll_init2" value="/roll 1d20 + ?{Modifier?|0} &{tracker}">Init</button>
<button type="roll" name="roll_initiative" value="&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod} &{tracker}]]}}"></button>

Roll Template

Main Article: 'Roll Templates

With your roll buttons, you can make simple rolls like /roll d20 + @{bluff}}, but in many cases you might want to make use of Roll Templates to create better output of your rolls. Roll Templates can also be used to create pseudo-conditional behavior, such as showing a roll section only if you roll a critical success on a previous section.

<button type="roll" name="roll_attack" value="&{template:default} {{name=Attack}} {{To Hit=[[1d20+@{str}]]}} {{Damage=[[2d8+2]]}}">

There exist a Default roll template that can be accessed in any sheet, but it's a much better idea to at least use Jakob's Better Default Rolltemplate which is just a cleaner version of the default template, and is at least a start for creating your own.

To include Jacob's roll template to your sheet, simply copy the HTML code and save it at the end of your sheet's HTML-file, and do the same for the CSS code. You similarly copy other sheet's roll template to your sheet to enable their use.

Token Action

You can force a roll button to appear as a token action on an attached token, by adding class="tokenaction" to the button.

<button type="roll" class="tokenaction" name="roll_initiative" value="&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod} &{tracker}]]}}"></button>

Caution: Token actions will have a fixed location in the order, and users have no ability to control whether those token actions appear or not, and they cannot not be renamed. These are fine to use in custom sheet in your own games, but few or no community sheets have them built in due to this annoyance.

Roll Table

You can use Roll Tables in your roll buttons to create custom rolls, but for it to work, the game needs to have the used roll tables created separately. and made available to the players, for the rolls to work.

<button type="roll" name="roll_fumble" value="/roll 2t[fumble]"></button>

API

See API-section from the Complete Guide to Macros & Rolls for more examples of general use.

Instead of using just normal macros in your rolls, you can choose to include API commands(require for that API to be installed in a game to work.

Depending on how the API you want to incorporate works, you might be able to mix normal macros and API commands in the same button, like using the stat-editing API to automatically remove an arrow when you roll an corresponding attack.

If you use these in sheet that will be published on Roll20 GitHub, you need to make API-based rolls optional.

Star Wars FFG and the Genesys sheet are two examples of sheet that uses custom API for rolling their dice, as the default Roll20 macros can't handle the custom things required.

Script:ChatSetAttr can be combined with normal macros to edit stats while a roll is made, and even make the changes depend on the results for the roll.

There exists a number of API scripts for ammo & spelslot tracking that can be configured to trigger when a roll is made, which means the button itself doesn't have to be edited to accommodate the API as an option, but they can run completely independently.

Wild Die Example

Script:Wild Dice is another API example that could be used in roll buttons.

Button to roll 5d6+2 according with the Wild Die method(and have the highest rolled normal dice be removed from the result if you roll a fumble on your wild die):

<button type="roll" value="!wd [[5d6+2]]" name="roll_wilddieexample" ></button>

Roll Parsing

Main Page: Custom Roll Parsing

As of July 13th, 2021, character sheets can now combine the functionality of roll buttons and action buttons to allow for roll parsing.

You essentially now have an action button that will perform dice rolls, with input from sheetworkers. CRP also requires changes to the Roll Template.

• Official Documentation: Custom Roll Parsing for Character Sheets.
• Oosh's explanation^(Forum)

Example:

<button type="action" name="act_test">Click me</button>

<rolltemplate class="sheet-rolltemplate-test">
    <div class="sheet-template-container">
        <h1>{{name}}</h1>
        <div class="sheet-results">
            <h4>Result = {{roll1}}</h4>
            <h4>Custom Result = {{computed::roll1}}</h4>
        </div>
    </div>
</rolltemplate>

<script type="text/worker">
    on('clicked:test', (info) => {
        startRoll("&{template:test} {{name=Test}} {{roll1=[[1d20]]}}", (results) => {
            const total = results.results.roll1.result
            const computed = total % 4;

            finishRoll(
                results.rollId,
                {
                    roll1: computed,
                }
            );
        });
    });
</script>

Action Button

Action buttons can be used as events to trigger Sheetworkers, and cannot be used for send messages to the q Text Chat.

You can't use underscores in the name of the action button. act_reduce is good, act_reduce_dex is bad

Example:

<button type="action" name="act_activate">Activate!</button>
<script type="text/worker">
on("clicked:activate", function() {
  // write your sheetworker to do things here
  console.log("Activate button clicked"); //example, just sends text to the browser console(hidden)
});
</script>

• the type-attribute must be set to action
• the name-attribute must be defined, and have a act_ prefix to function
  • Do not use action button names that include underscores, otherwise they will fail to trigger as a detectable event for sheetworkers.

It a good idea to display text inside the button .

Common uses:

• Swap between sheet tabs/visible areas (CSS Wizardry Example)
• Increment stats, such as ammo usage
• below are some examples

Change Tabs

Details: CSS_Wizardry#Tabs

You can use action buttons to change what page is shown on the sheet, by having them change the tab name that should be shown.

Adjusting looks of Action buttons is much easier than for the "invisible radio input + span" method for navigating pages.

Adjust Stats Examples

Example^(Forum) by GiGs, and expanded here. Each step is expanded and commented for clarity.

Add one to the level stat , when a button is clicked.

Create an action button on the sheet:

<button type="action" name="act_add">Add level</button>

Then add this code the the sheetworker section of the sheet:

on('clicked:add', function() {
    getAttrs(['level'], function(values) {
        // get the level stat, and coerce into a numerical value.
        const level = +values.level || 0; 
        // increase by 1
        const newlevel = level +1;
        // save the updated attribute to the sheet
        setAttrs({
           level: newlevel 
        });
   });
});

Reducing several stats with one button press.

Create an action button on the sheet:

<button type="action" name="act_reduce">

Then add this code the the sheetworker section of the sheet:

on('clicked:reduce', function() {
    // make an array of the attributes you plan to adjust, for ease of use later
    const attributes = ['list of attributes to adjust'];
    getAttrs(attributes, function(values) {
        const settings = {}; // make a variable to hold the changed attributes
        // loop through the attributes, get the value, then subtract 1
        attributes.forEach(att => {  // in each go through the loop, "att" becomes the next attribute
            let tempattribute = +values.att || 0;
            tempattribute -= 1;
            // store the changed attribute in the settings variable:
            settings[att] = tempattribute;
        });
        // save the updated attributes to the sheet
        setAttrs(settings);
   });
});

Reset Stats

Sometime you might want to reset some stats to their initial values, without having to do it manually or to make a new sheet. This can easily be done with an action button & a sheetworker.

<h3>Main Stats</h3>
<label>Strength: <input name="attr_str" type="number" value=""></label>
<label>Dexterity: <input name="attr_dex" type="number" value=""></label>
<label>Mind: <input name="attr_mind" type="number" value=""></label>
<label>HP: <input name="attr_hp" type="number" value="10"></label>
<button type="action" name="act_reset" class="reset-button">Reset Main Stats</button>

<script type="sheet/worker">
on('clicked:reset', () => {
    setAttrs({
        str: 0,
        dex: 0,
        mind: 0,
        hp: 10
    });
});
</script>

Note: To avoid accidentally pressing the Reset button, it can be a good idea to hide or protect the button. With CSE, you could replace the Reset button with a <a href="#"> link, which opens a Warning Popup, where the actual reset button is located.

Compendium Button

Main Article: Compendium Button

The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.

The syntax is <button type="compendium" value="<entryname>">.

Example:

<button type="compendium" value="Bard">Bard</button>

Styling Roll Buttons

Here are shows a few examples on how to style your button to look differently.

The Action and Compendium buttons looks slightly different by default(see picture at top of article), but can be styled all the same.

Remove the default d20 icon

Want a roll button that doesn't have a d20 image in it? Simple!

CSS:

button[type=roll].sheet-blank-roll-button::before {
  content: '';
}

HTML:

<button class="sheet-blank-button" name="roll_BluffCheck" value="/roll 1d20 + @{Bluff}" type="roll">Bluff</button>

The d20 is a single character with the dicefontd20 font-family in the button's ::before pseudo-element. Setting the content to an empty string removes it.

Roll button with a d6 icon

By using the icon fonts available in Roll20, we can replace the d20 icon it with a different dice, instead of removing it.

CSS:

button[type=roll].sheet-d6-dice::before {
    font-family: 'dicefontd6';
    content: 'F ';
}

HTML:

<button class="sheet-d6-dice" name="roll_dex" value="/roll @{dex}d6" type="roll"></button>

Button to blend in

The Stargate sheet is an example of a sheet that has turned the Attribute & Skill buttons to look like just text, setting the border and button background to transparent, and reducing it's padding.

Button with an image

The Ambition & Avarice sheet has two examples where the roll buttons have been changed from the default d20 icon, to make the d20 and d5 buttons look hand-drawn. For the image to stay in place when you hover over it with a mouse, you need to do some manual adjustments for :hover CSS class for the image position, that may vary depending on the size/shape of the image. Image use in character sheets contains more examples.

Button Dynamic Text

By placing an Attribute-Backed inside the button.

You then have an input elsewhere with the identical name that can then change the value of the attribute displayed on the button.

<button type="roll" value="/roll 3d6" name="roll_attack"><span name="attr_attackname"></span></button>
<input type="text" name="attr_attackname" value="Sword">

See Also

• Building Character Sheets - Main Article
• Complete Guide to Macros & Rolls‎
  • q Text Chat - where the roll results appear, & info on the common chat commands
  • Dice Reference - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
  • Macros - How to create macros, and other info on how the Roll20 qText Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
    • Initiative Roll
    • Roll Queries - How to use Roll Queries in your buttons
  • Roll Templates - a method of formatting roll results in the chat, with some extra functions
  • API(Pro Only) - API commands can be used in the qText Chat
• Specific Tricks
  • Select Attributes for Sheet Roll - An advanced technique for a dynamic roll button
  • Reusing Rolls - clever way of reusing rolls within the same call