Roll20 Wiki

'''Macros''' are user-defined shortcuts to commands you regularly want to repeat. For example, you can create a macro that shouts a battlecry then performs an attack that you frequently use. Instead of needing to type all of the commands over and over again as you play, you can just type one short command instead.

= Creating and Editing Macros =

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

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

=== Autocomplete ===

Some text areas support the autocompletion of Macro calls (using “#”), [[Journal#Attributes|Attribute calls]] (using “@”) and [[Journal#Abilities|Ability calls]] (using “%”).

The 'Action' text areas of both Macros (on the Edit Macro window) and Abilities (on the [[Journal#Attributes_.26_Abilities_Tab|Attributes & Abilities Tab]]) supports the autocompletion of Macro and Attribute calls. The [[Text Chat]] supports the autocompletion of Macro and Ability calls.

To bring up an autocomplete list, type one of the aforementioned symbols (#, @ or %, as and where appropriate) followed by a sequence letters or numbers (at least one). A Macro, Attribute or Ability will populate the autocomplete list if its name contains this sequence.

Only Macros that you can see in your Collections tab will appear on the autocomplete lists. Likewise, only Attributes (or Abilities) that belong to a [[Journal#Characters|Character]] that you have permission to control will appear on autocomplete lists.

For example, if you have permission to control a Character which contains an Attribute named “Dexterity”, you could type “@dex” (or possibly even just “@x”) into the 'Action' text area of an Edit Macro window to bring up an autocomplete list which contains that Attribute.

'''Tip:''' You can navigate and select items on the autocomplete list using the directional Up and Down keys and the Enter key on your keyboard.

= 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 they will be executed in order when you run the macro.

=== Example ===

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

Macro Name: <br> <code>dagger</code><br><br> Macro Body: <br> <code>/me rams his dagger home</code><br> <code>/roll 1d20+10 vs AC</code><br> <code>/roll 1d4+9 Damage</code><br>

Then, simply by typing <code>#dagger</code> it would run the entire script and look like this:

[[File:AttackMacro.JPG]]

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

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

This would first emote, then send &quot;<i>I smite you!</i>&quot; to the chat, and then make the two rolls afterwards.

= 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: <code>#damage</code> <code>#attack</code> and <code>#both</code>

Macro <code>#damage</code> = <code>/roll 1d4+11</code><br> Macro <code>#attack</code> = <code>/roll 1d20+9</code><br> Macro <code>#both</code> = <br> <code>#attack</code><br> <code>#damage</code>

== Nesting in a 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.

<pre>?{Which macro?|Attack,#use-sword |Defend,#use-shield }</pre>

=== Troubleshooting ===
Due to the [[Dice_Reference#Roll20_Dice_Specification|order of operations]], macro calls nested within Roll Queries are fully expanded before the query is executed. This means that if a macro nested within a Roll Query contains any problematic characters, which conflict with Roll Query syntax (such as "}" "," and "|"), that nested macro may cause the Roll Query to break (because it will use those characters in the called macro instead of the characters in the rest of your roll query). 

If this is the case, it may be necessary to either remove or replace problematic characters within that nested macro with HTML entities (see: [[Macros#Advanced_Usage_for_Roll_Queries|Advanced Usage for Roll Queries]]). Note that macros which contain HTML entities may no longer function autonomously and must be saved as [[Journal#Abilities|Abilities]].

= Nesting Abilities =

An ability is another name for a macro which 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. To type a vertical pipe once you've found the key hold shift as if you were to uppercase a letter and then press it.

<big>'''Note:'''</big> 
Currently the ability reference symbol (%) does not auto complete at this time like the attribute reference symbol (@) or macro reference symbol (#) do. You must type the entire thing yourself.

=== Example ===

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

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

=== More Examples ===
Here are some system-specific examples;

[[Dungeons_and_Dragons_Next#More_Examples|DnD 5e/Next macros]]

[[Macros_-_Pathfinder_Examples|Pathfinder macros]]

=== Ability Command Buttons ===
Ability Command Buttons can be used to call Abilities (or [[Character_Sheets#Sheet_Rolls|sheet button rolls]]) from a clickable button in the text chat. They are very closely related to [[API:Chat#API_Command_Buttons|API Command Buttons]].
<br><br>
Their syntax is as follows:
<pre>[Label](~<keyword>|<ability name>)</pre>
As with [[Journal#Attributes|Attribute]] and [[Journal#Abilities|Ability]] calls, the '''keyword''' is your choice of <code>selected</code>, <code>target</code> or <code><Character name></code>
<br><br>
If you have an Ability Command Button saved somewhere within one of the tabs of the [[Journal#Character_Window|Character Window]], you can choose to omit a keyword:
<pre>[Label](~<ability name>)</pre>

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

= Attribute Macros =

A culmination of the above examples can be used in what we call Attribute Macros. By using an Attribute, that is assigned to a [[Journal|Character]], as a variable modifier you can create complex Character based macros. Since the variable used in the Macro is linked to a Character Attribute, the value will sync when changed in the [[Journal|Character]] editor.

=== Video tutorial on using Abilities ===
<br>A very basic look at using abilities for more simple rolls. (ex. Will Save, Skill Checks, etc.)
<br>[https://www.youtube.com/watch?v=gIOsFeCsY0k Attributes & Abilities]

== Using a Selected Token with a Macro ==
The &quot;selected&quot; 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 do:

<pre data-language="javascript">/roll 1d20 + @{selected|bar1}</pre>

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

<pre data-language="javascript">/roll 1d20 + @{selected|Intelligence}</pre>

You can pull the Name of the currently selected token's by using the &quot;token_name&quot; variable.

<pre data-language="javascript">/em @{selected|token_name} fires his gun!</pre>

If the selected token has a character journal linked to it you can pull the Name from the character journal instead using the &quot;character_name&quot; variable.

<pre data-language="javascript">/em @{selected|character_name} blocks with his shield!</pre>

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

<pre data-language="javascript">%{selected|Attack}</pre>

Finally, we've introduced a 3rd argument for variables, allowing you to pull the "max" of a bar or attribute:

<pre data-language="javascript">
/roll 1d20 + @{Guard|Intelligence|max}
/roll 1d20 + @{selected|bar2|max}</pre>

Also, all names (for Characters, attributes, and abilities) are not case-sensitive when you use them, so &quot;GUARD&quot; and &quot;guard&quot; will now both match the Character &quot;Guard&quot;.

Hint: To find the complete list of attributes for your character, you can go into that character's sheet and click the tab &quot;Attributes & Abilities&quot;. Here you can also add your own attributes to be used by macros by simply clicking &quot;+ Add&quot;.

= Using a Targeted Token with a Macro =

Very similar to using the "selected" keyword to pull information from a selected token (as illustrated above), you can also use the "target" keyword to access information such as variables and/or abilities of a "target" token.  This command lets players choose from tokens that they cannot normally select, which is excellent when they have to roll against enemies.  For example, if you told a player to roll a single 1d20 roll against a target you've advised has a "strength" attribute to overcome.  The roll would look like:

<pre data-language="javascript">/roll 1d20 - @{target|strength}</pre>
This will bring up a prompt screen for the player to select which token target they are rolling against:

[[File:Choosetarget.png]]

Again, the "target" keyword is almost identical in usage to the "selected" keyword as outlined above in the ways it can be employed-- the two primary difference being that it allows players to utilize values from tokens they are not controlling and that the syntax is slightly different for referencing a "max" part of an attribute. See the [[#Advanced Usage|advanced usage]] subsection below for more details on the complete syntax.

=== Referencing Repeating Attributes ===

==== By RowIndex ====
Attributes in a repeating row can be referenced by their '''RowIndex'''.  For a repeating section named Items, you could access the ItemBonus attribute for the second item on a character with the following syntax:
<pre data-language="javascript">@{selected|repeating_items_$1_itembonus}</pre>

'''Note:''' The '''RowIndex''' of an attribute starts at 0 (index is the offset from the top), so the first row uses '''$0''', the second uses '''$1''', the third uses '''$2''', etc.

==== 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''':

<pre data-language="html">
&lt;div class="repitem" data-reprowid="-KC0zCLum1Rq3V5wssyE"&gt;
</pre>
The '''RowID''' is then used in place of the '''RowIndex''':
<pre data-language="javascript">@{selected|repeating_items_-KC0zCLum1Rq3V5wssyE_itembonus}</pre>

=== Advanced Usage ===

The full syntax for the target variable is:

<pre data-language="javascript">@{target|<target_name>|<attribute_name>|<optional_flags>}</pre>
(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:

<pre data-language="javascript">@{target|Target1|HP} vs @{target|Target2|AC}</pre>

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

<pre data-language="javascript">@{target|Target1|HP|max}</pre>

Note that if you want to use the "max" flag you must specify the name of the target yourself, 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:

<pre data-language="javascript">/em strikes out at @{target|foe|name}!
**To Hit**: [[1d20+3]] vs. @{target|foe|npc_AC} AC
</pre>

= Roll Options =
&quot;Roll options&quot; are &quot;flags&quot; that you can set anywhere in a roll to tell the roll system you'd like to do special things with the roll result.

=== Rolling For Initiative ===
To send a roll result directly to the turn tracker, first, select the Token you wish to roll for initiative and then use the below roll option in your macro:

<code>/roll 1d20 + 5 &{tracker}</code>

The &quot;tracker&quot; roll option tells Roll20's roll system, &quot;Show the results of this roll, but also use the result as the value in the turn tracker.&quot; If the token that you have selected doesn't already have a turn in the turn order, one will be added. If it already has at least one turn, all current turns 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:

<code>/roll 1d20 + 5 &{tracker:+}<br />
/roll 1d20 + 5 &{tracker:-}</code>

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:

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

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: <code>@{tracker|Item Name}</code>.

=== Suppressing Errors Messages ===

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

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

= 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:

<pre data-language="javascript">
/roll 2d20 + ?{Modifier|0}
</pre>

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

====Examples====

If I want a macro for 1d20+x (<i>where x is my variable value</i>) I could create the following macro:<br> <code>#d20</code> <code>/roll 1d20+</code><br> then, when running the macro, type <code>#d20</code><code>4</code> to get <code>/roll 1d20+4</code><br><br>

===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:
<pre>?{Name of Query|Option1|Option2|Option3|Option4|Option5}</pre>

You can also specify a different value for the result other than label like so:
<pre>?{Name of Query|Label 1,value1|Label 2,value2}</pre>

====Examples====

Special Attack
<pre>... + [[ ?{Sneak Attack?|No, 0|Yes, 3d6} ]] + ?{Power Attack?|No, 0|Yes, 6 [Power Attack!]}</pre>
5e Attack Roll
<pre>[[ ?{Attack Type|Standard, 1d20|Advantage, 2d20kh1|Disadvantage, 2d20kl1} ]]</pre>

Cure Spell
<pre>?{Which Cure spell are you casting?| 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.}</pre>
<br>

=== Advanced Usage for Roll Queries ===

Roll Queries currently end at the first closing curly brace the parser encounters. Within a Roll Query, other characters that serve as Roll Query syntax (vertical bars and commas) will always be treated as such by the parser, potentially causing unwanted behavior when placed within the Roll Query for other purposes. To work around this, replace '''''some''''' but '''''not all''''' of these "problematic" characters with their HTML entities (see notes below).

{| class="wikitable"
|-
! Character || Replacement
|-
| &#124;|| &amp;#124;
|-
| &#44;|| &amp;#44;
|-
| &#125;|| &amp;#125;
|}

Due to the [[Dice_Reference#Roll20_Dice_Specification|order of operations]], <u>calls</u> (i.e. @{[[Journal#Attributes|Attribute]]}, %{[[Journal#Abilites|Ability]]}, #[[Macros#Creating_and_Editing_Macros|Macro]]) are parsed to their ''values'' before Roll Queries are executed.

For example, Attribute <u>calls</u> (e.g. @{selected|HP}) are parsed to (i.e. replaced by) either their Current ''value'' or their Max ''value'' (depending on whether that <u>call</u> contains the "max" flag, i.e. @{selected|HP|max}).

Again, the (normally-problematic) characters that are part of Attribute and Ability <u>calls</u> are parsed to their ''values'' '''before''' they can affect a Roll Query.

Hence, <u>calls</u> are not problematic! Do not subject them to character replacements! Never do this: @{target&amp;#124;token_name&amp;#125;

====Roll Query Troubleshooting====
Locate and replace all problematic characters within the ''values'' of any Attributes, Abilities or Macros.

Since those ''values'' now contain HTML entities, they are probably unable be able to be <u>called</u> individually (i.e. outside of a Roll Query). So, you might now consider directly inserting these ''values'' into your Roll Query, replacing their <u>call</u>.

Macros which contain HTML entities may no longer function autonomously.

At this time, reopening a Macro saved under the Collections tab of the Sidebar causes HTML entities within to be reverted; if the Macro is then saved, so are those reversions. This behaviour is not present within [[Journal#Abilities|Abilities]].

To reiterate an important point: '''do not subject any @{Attribute}, %{Ability} or #Macro <u>calls</u> to any character replacements.'''

====Example (nesting Roll Queries)====
<pre style="overflow:auto; width:auto;">?{Name of Query|Label 1,?{value1&amp;#124;Label 1A&amp;#44;value1A&amp;#124;Label 1B&amp;#44;value1B&amp;#125;|Label 2,?{value2&amp;#124;value2&amp;#125;}</pre>

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

{| class="wikitable"
|-
! Character !! Replacement
|-
| & || &amp;amp;
|}

====Example====
<pre style="overflow:auto; width:auto;">?{Name of Query|Label 1,?{value1&amp;#124;Label 1A&amp;#44;?{value1A&amp;amp;#124;Label 1Ai&amp;amp;#44;value1Ai&amp;amp;#124;Label 1Aii&amp;amp;#44;value1Aii&amp;amp;#125;&amp;#124;Label 1B&amp;#44;?{value1B&amp;amp;#124;Label 1Bi&amp;amp;#44;value1Bi&amp;amp;#124;Label 1Bii&amp;amp;#44;value1Bii&amp;amp;#125;&amp;#125;|Label 2,?{value2&amp;#124;value2&amp;#125;}</pre>

= Macro Bar =

You can also 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 like normal. Then, to enable the macro quick bar, check off &quot;Show macro quick bar&quot; in the settings menu<br>

[[File:showquickbar.png|border]]

Then, to add a macro to the bar, simply check the &quot;In bar&quot; option next to the macro's name. If you have forgotten to turn the macro quickbar on, toggling on a macro will auto-enable the quickbar to display.


[[File:macroinbar.png|border]]


The quickbar, and any macros that you have selected should now appear on the bottom of your screen, underneath the character portraits. If you'd like to re-arrange the buttons on the bar, hover your mouse over the button that you'd like to move. A handle will appear on the right side of the button. You can drag the button around the bar by using this handle. Click on that handle to reorganize the button or drag it off to remove it.

[[File:macrobar.png|border]]

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

== Macro Menu ==
You 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 for the local user.

[[File:MacroRightClickMenu.png|border]]

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

[[Category:Docs]]