Macros

Macros are custom shortcuts for frequently repeated commands. For example, you can create a macro that has your character shout a battle cry and automatically perform a commonly used attack. Instead of repetitive typing during gameplay, you can use a single short command

For quick access, you can add these commands to your Quick Bar or Token Actions.

Creating and Editing Macros

Go to the "Collections" tab which is housed under the small dotted-list image in the Sidebar. To enter a macro, first type what you want to call the command. Example: "test". Then to the right, put in the command. This could be typed text, a roll, or emote. Press "Enter" after this information to save the command.

To call a Macro, type # and the command (e.g. #test) and press enter.

Auto-complete

Some text areas support the auto-completion of Macro calls (using “#”), Attribute calls (using “@”) and Ability calls (using “%”).

The 'Actions' text areas of both Macros (on the Edit Macro window) and Abilities (on the Attributes & Abilities Tab) support the auto-completion of Macro and Attribute calls. The Text Chat supports the auto-completion of Macro and Ability calls.

To trigger an auto-complete list, type a symbol (#, @, or %) followed by a sequence of letters or numbers. The auto-complete list will show Macros, Attributes, or Abilities with names containing that sequence

Only Macros that you can see in your Collections tab will appear on the auto-complete lists. Likewise, only Attributes (or Abilities) that belong to a Character that you have permission to control will appear on auto-complete lists.

For example, if you have permission to control a Character that contains an Attribute named “Intelligence”, you could type “@int” into the 'Action' text area of an Edit Macro window. This will bring up an auto-complete list that contains that Attribute.

Multiple Commands

One of the strengths of the macro system is its ability to execute multiple actions with a single command. To do this, simply put each item on its own line, and actions will be executed in order when you run the macro.

Example

If I want to create a macro that will include an emote, plus your attack and damage rolls, the macro would look like this:

Macro Name:
dagger

Macro Body:

/me rams his dagger home
/roll 1d20+10 vs AC
/roll 1d4+9 Damage

Macros can also include a mix of command and non-command lines, for example:

#lof
/me calls upon the power of Moradin!
I smite you!
/roll 1d20+4 vs reflex
/roll 1d8+4 damage

This would first emote, then send "I smite you!" to the chat, and then make the two rolls afterward.

Nesting Macros

Macros can be nested inside each other, which gives the ability to combine macros and call multiple macros with a single action. To nest a macro, simply include the name of the macro you wish to call on its own line inside your macro.

Example

In this example, we'll have three macros: #damage #attack and #both

Macro #damage = /roll 1d4+11
Macro #attack = /roll 1d20+9
Macro #both = 
#attack
#damage

Nesting in a Dice Roll Query

If you are nesting a macro in a Roll Query, be certain there is a space after the macro name so that it is properly recognized.

?{Which macro?|Attack,#use-sword |Defend,#use-shield }

Troubleshooting

Due to the order of operations, Macro calls nested within Dice Roll Queries are fully expanded before whole query is executed. This means that if a macro nested within a Dice Roll Query contains any "problematic characters" that conflict with query syntax (such as "}" "," and "|"), that macro may cause the whole query to break. The reason is that the query will treat problematic characters in the referenced macro as part of the original syntax.

If this is the case, it may be necessary to either remove those problematic characters (within the called macro itself), or replace them with HTML entities.

Macros which contain HTML entity replacements may no longer function outside of a Roll Query. should be saved as Abilities.

Reopening a Collections Macro reverts HTML entities; if that Macro is then saved, those reversions are as well. This behavior is not present within Abilities.

Nesting Abilities

An ability is another name for a macro that is specific to a certain character and is created in a character sheet found on the journal tab. Like macros, abilities can be nested inside each other, which gives you the capacity to chain abilities together and call multiple abilities with a single action.

Nesting an ability is similar to nesting a macro but with a slight twist. Like a macro, simply include the name of the ability you wish to call on its own line inside your calling ability. But in addition, you have to change the number symbol (#) into a percent symbol (%) and then include the name of the character in front of the ability name using a vertical pipe (|) to separate them.

The vertical pipe key can be found above the backslash key (\) on most keyboards. This key will usually be near the enter key on a US keyboard and in the number row on European keyboards.

Example

In this example, we'll have three abilities: %damage %attack and %both and our character who will be named Bugbear

Ability %damage = /roll 1d4+11
Ability %attack = /roll 1d20+9
Ability %both = 
%{Bugbear|attack}
%{Bugbear|damage}

More Examples

Here are some system-specific examples:

DnD 5e/Next macros

Pathfinder macros

Ability Command Buttons

Ability Command Buttons can be used to call Abilities (or sheet button rolls) from a clickable button in the Text Chat. They are very closely related to Mods (API) Command Buttons. 

Their syntax is as follows:

[Label](~<keyword>|<ability name>)

As with Attribute and Ability calls, the keyword is your choice of selected, target or a character_name. You can also use a character_id as a keyword. 

If you have an Ability Command Button saved somewhere within one of the tabs of the Character Window, you can choose to omit a keyword:

[Label](~<ability name>)

Continuing the example from Abilities, Bob the Slayer might insert [Swing Axe!!](~Massive Axe) into another one of his other Abilities so that he could more accessibly fillet his foes.

Attribute Macros

Attribute Macros combine the examples mentioned above. By utilizing an Attribute assigned to a Character as a variable modifier, you can create intricate macros based on the Character. As the variable in the Macro is linked to a Character Attribute, any changes made in the Character editor will automatically update the value.

Using a Selected Token with a Macro

The selected keyword will allow you to pull information from the element that is currently selected on the screen when the roll/macro is executed. So for example, if you want to pull the value of Bar 1 from the selected token during a roll, you can write:

/roll 1d20 + @{selected|bar1}

You can use "bar1", "bar2", or "bar3". In addition, you can pull an attribute from the Character linked to that token:

/roll 1d20 + @{selected|Intelligence}

You can pull the Name of the currently selected tokens by using the "token_name" variable:

/em @{selected|token_name} fires his gun!

If the selected token has a character journal linked to it you can pull the Name from the character journal instead of using the "character_name" variable:

/em @{selected|character_name} blocks with his shield!

You can trigger abilities from the linked character journal by using the ability name as a variable:

>%{selected|Attack}

Finally, we have introduced a 3rd argument for variables, allowing you to pull the "maximum value" of a bar or attribute:

/roll 1d20 + @{Guard|Intelligence|max}
/roll 1d20 + @{selected|bar2|max}

All names, including those of Characters, attributes, and abilities, are not case-sensitive when used. This means that "GUARD" and "guard" will both match the Character named "Guard".

Attributes and Character Sheets

Character Sheets introduce a large number of attributes that you might want to reference in your custom macros. One thing ft h aware of the Auto-Calc Formula Attribute. Characters sheet often have calculated attributes based on formulas involving other attributes. Referencing that attribute will show the formula instead of the value.

@{selected|character_name} has @{selected|action_points} points left.

Rolf has ((ceil(((13+0)+(14+0))/12)+0)+0) points left.

To get around this, you need to wrap the attribute reference in an inline roll:

@{selected|character_name} has [[@{selected|action_points}]] points left.

Rolf has 3 points left.

Using a Targeted Token with a Macro

Similar to using the „selected“ keyword to retrieve information from a selected token, the „target“ keyword allows accessing variables and abilities of a target token. This command enables players to choose from tokens they normally cannot select, which is useful for rolling against enemies. For instance, if you instruct a player to roll a single 1d20 against a target with an „intelligence“ attribute, the roll would appear as follows:

/roll 1d20 - @{target|intelligence}

This will bring up a prompt screen for the player to select which token target they are rolling against:

The target keyword is used similarly to the selected keyword mentioned earlier, with two main differences. First, the "target" keyword allows players to utilize values from tokens they don't control Second, the syntax for referencing the "max" part of an attribute is slightly different. See the advanced usage subsection below for more details on the complete syntax.

Advanced Usage for Targeted Attribute Calls

The full syntax for the target variable is:

@{target|<target_name>|<attribute_name>|<optional_flags>}

(Note that 'target_name' can be anything you like, and can include spaces.)

So if you want to have multiple targets in your macro you can do:

@{target|Target1|HP} vs @{target|Target2|AC}

And if you want to use the maximum of an attribute:

@{target|Target1|HP|max}

Note that if you want to use the "max" of an attribute, you must specify the attribute name, even if you just put "target1" as above.

Additionally, if you use the same target_name in multiple attribute queries, you will only get prompted for it once and the same token will be used to fulfill all of the attribute queries. This also applies when you have multi-line macros or commands:

/me strikes out at @{target|foe|character_name}!
**To Hit**: [[1d20+3]] vs. @{target|foe|npc_AC} AC

Referencing Repeating Attributes

By RowIndex

Attributes in a repeating row can be referenced by their RowIndex. The RowIndex of an attribute starts at 0 (index means the offset from the top), so the first row uses $0, the second uses $1, the third uses $2, etc.

For a repeating section named Items, you could access the ItemBonus attribute for the second item on a character with the following syntax:

@{selected|repeating_items_$1_itembonus}

By RowID

You can also use the RowID to reference the attribute. The benefit of using the RowID is that it is unaffected by a change in order (either by deletion or reordering of rows). To get the RowID (if it isn't provided by the character sheet author in some way), you must look at the source to the sheet. Trace upward in the HTML until you find a tag with a property named data-reprowid. The value of this property is the RowID:

<div class="repitem" data-reprowid="-KC0zCLum1Rq3V5wssyE">

The RowID is then used in place of the RowIndex:

@{selected|repeating_items_-KC0zCLum1Rq3V5wssyE_itembonus}

Dice Roll Options

Dice Roll options are flags used within a die roll to indicate special actions to be performed with the roll result.

Rolling For Initiative

To send a roll result directly to the Turn Tracker, select the Token or initiative and include the following roll option in your macro:

/roll 1d20 + 5 &{tracker}

The "tracker" die roll option in Roll20 shows the roll results and uses the result as the value in the turn tracker. If the selected token doesn't have a turn in the turn order, a new one will be added. If it already has turns, they will be updated with the new value.

In addition, you can add the result of the roll, or subtract the result of the roll, from the current turn value for the selected token by using the following flags:

/roll 1d20 + 5 &{tracker:+} 
/roll 1d20 + 5 &{tracker:-}

For a game such as Shadowrun where you want to subtract 10 from the current initiative after every turn, you could have a global macro like so:

/me @{selected|token_name} ends their turn. [[10 &{tracker:-}]]

Note that the tracker flag works both in regular rolls and inline rolls.

You can even reference these values the same way you would Attributes by using the syntax: @{tracker|Item Name}

Suppressing Errors Messages

The "noerror" roll option will suppress any errors (such as variable not found errors) in a roll.

/roll 1d20 + @{selected|nonexistent_attribute} &{noerror}

Using a variable with a Macro

The easiest way to include a variable with a macro that you specify when it is executed is to use a Roll Query. For example, if you want to add a variable modifier onto a roll, you can make a macro like so:

/roll 2d20 + ?{Modifier|0}

When the macro is executed, a prompt will appear asking for the modifier to include. If no modifier is specified, the "|0" part of the query tells it to use 0 as the default value.

More information on Roll Queries is available in the Dice Reference.

Specifying a variable in chat

If you'd like to use a variable modifier with your macro roll, simply end the macro command with the modifier, and then specify it when calling your macro.

For example: If you want a macro for 1d20+x (where x is my variable value) you could create the following macro:

#d20 /roll 1d20+

#d204

Drop-Down Prompts for Roll Queries

You can specify a list of options which can be presented to the player, rather than only a free-form text field.

Here's the syntax:

?{Name of Query|Option1|Option2|Option3|Option4|Option5}

You can also specify a different value for the result other than label like so:

?{Name of Query|Label 1, value1|Label 2, value2}

Examples

Special Attack:

... + [[ ?{Sneak Attack?|No, 0|Yes, 3d6} ]] + ?{Power Attack?|No, 0|Yes, 6 [Power Attack!]}

D&D 5e Attack Roll:

[[ ?{Attack Type|Standard, 1d20|Advantage, 2d20kh1|Disadvantage, 2d20kl1} ]]

Cure Spell:

?{Spell|
   Cure Light Wounds, **Cure Light Wounds** Target Regains [[1d8+5]] HP. | 
   Cure Moderate Wounds, **Cure Moderate Wounds** Target Regains [[2d8+8]] HP. | 
   Cure Serious Wounds, **Cure Serious Wounds** Target Regains [[3d8+8]] HP.
}

Example (nesting Roll Queries)

?{Name of Query|
   Label 1, ?{value1|
      Label 1A, value1A |
      Label 1B, value1B 
   } |
   
   Label 2, ?{value2|value2} 
}

It is possible to achieve further levels of nesting by "stacking" HTML entities:

Example

?{Name of Query|
   Label 1, ?{value1|
      Label 1A, ?{value1A|
         Label 1Ai, value1Ai |
         Label 1Aii, value1Aii
      } |
      
      Label 1B, ?{value1B|
         Label 1Bi, value1Bi |
         Label 1Bii, value1Bii
      }
   } |

   Label 2, ?{value2|value2} 
}

Macro Bar

You can create quick access buttons for any of your macros that will appear in a bar at the bottom of the screen. First, create your macro as usual. To enable the macro quick bar, check off "Show macro quick bar" in the settings menu.

To add a macro to the bar, simply check the "In bar" option next to the macro's name. If you have forgotten to turn the macro quick bar on, toggling on a macro will auto-enable the quick bar to display.

The quick bar and selected macros will now be displayed at the bottom of your screen, below the character portraits. To rearrange buttons, hover over a button and use the handle that appears on its right side to drag it. Click the handle to reorganize the button or drag it off to remove it.

Shift+Clicking on a Macro in the macro quick bar will open the editor for that specific macro.

Macro Menu

You as a player or GM can right-click on a Macro Button in the Macro Quickbar to bring up a configuration menu which gives you access to a couple of simple features that affect how the macro is displayed.

Rename

Select the Rename entry to bring up a dialog prompting you for a new name to display for the macro. This is particularly useful for macros created by dragging buttons out of character sheets.

Color

Select the Color entry to bring up a color picker. This allows you to change the background color of the Macro Button to make it easier to pick out your different buttons visually. The color of the button text will change to maintain contrast with the chosen background color.

Rollable Tables

Macros can use Rollable Tables in them. The GM must create and make them visible to the player if players are to be able to use them in macros.

Using Dice Roll Templates

When using a Character Sheet, you'll likely use a Dice Roll Template by clicking the roll button or calling a sheet roll in a macro or ability. No extra action is required on your part as the sheet author has already set it up in advance for you.

If you're interested in using Roll Templates in your own custom macros or creating your own custom templates, read on further.

Using a roll template is straightforward. Include a flag in your chat message to indicate using a Roll Template, and provide the desired data. Here is an example using the default template, available in all games regardless of the system or character sheet:

&{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{damage=[[2d6]]}}

The &{template:<template_name>} specifies the Roll Template to use with the specified name. Then you just provide all the data for the template in the format {{<propertyname>= <value>}}. The "propertyname" that you should use depends on the template -- the Character Sheet documentation should let you know what's available, and we've provided documentation on all of the built-in templates below. "Value" can be either text or an inline roll, including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, not a "/roll" command.

Here is an example that uses a "%{Character|attack}" ability:

&{template:default} {{name=Test With Ability}} {{attack= %{Character_Name|attack} }} {{damage= #damagemacro }}

When Can I Use Roll Templates?

You can use a Roll Template in general messages (without a command like "/desc" or "/emote") and whispers. You can't use roll templates with the "/roll" command; instead, Roll Templates are meant to be used with inline rolls. As long as they use inline rolls, you can use Roll Templates with macros, Character Abilities, and sheet authors can use them inside of their Roll Buttons on sheets.