Main Article: Building Character Sheets

This page is about the <button> and it's known options for usage in creating Custom Character Sheets(Pro feature).

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

Roll Button

Example:

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

• the type-attribute must be set to roll
• the roll macro is defined in the value-attribute.
• the optional name-attribute allows the roll to be referenced in external Macros and Abilities. The name must be prefixed with roll_ for this to work, and each roll button should have a unique name. Buttons in repeating sections automatically gain a unique prefix/suffix in their name.

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

To construct more advanced rolls, you should check the Macros and the Dice Reference pages.

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, such as:

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

See also:

• Roll Queries - How to use Roll Queries in your buttons
• Select Attributes for Sheet Roll - An advanced technique for a dynamic roll button

Initiative

Macros#Rolling_For_Initiative

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.

Example:

/roll 1d20 + 5 &{tracker}

&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod}]]}} &{tracker}

API

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.

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>

Action Button

Example:

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

Action buttons can be used as events to trigger Sheetworkers.

• 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.

Two common uses:

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

Adjust Stats Examples

Made 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">

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);
   });
});

Styling Roll Buttons

Styling Roll Buttons shows a few examples on how to style your button to look differently.

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.

See Also

• Building Character Sheets - Main Article
• Macros - how to construct the macros used inside buttons
  • Initiative Roll
  • Roll Queries - How to use Roll Queries in your buttons
• Dice Reference - The Roll20 dice/math syntax
• Select Attributes for Sheet Roll - An advanced technique for a dynamic roll button
• API - if you want to create roll buttons that uses API commands