Revision as of 17:41, 23 March 2021

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.

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

Action Button

Action buttons can be used as events to trigger Sheetworkers.

Example:

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

• 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

Two common uses:

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

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

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

https://app.roll20.net/forum/permalink/9170158/

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

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

Examples include:

• removing the default d20 icon
• replacing the default dice icon with a d6
• using an image in a button
• making a button look like normal text/blend in better

The Action and Compendium buttons looks slightly different by default(see picture at top of article).

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