Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Macros"

From Roll20 Wiki

Jump to: navigation, search
m (Advanced Usage)
(Fixed formatting mistake in the macro body)
 
(182 intermediate revisions by 35 users not shown)
Line 1: Line 1:
'''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.
+
{{revdate}}{{HCbox|{{hc|articles/360037256794-Macros Macros}} }}{{clear}}
 +
{{NavMacroDocs}}'''Macros''' are user-defined shortcuts to commands you regularly want to repeat and write in the {{Text Chat}}. 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 =
+
The Macro menu can be found under the {{Collections}}-tab. For quick access, these saved rolls and commands can be added to the [[Macro Quick Bar]] or [[Token Actions]] where you can more quickly access them during play. You can also Drag-n-Drop Roll buttons from some [[Character Sheets]] to it.
  
Go to the My Settings tab (housed under the small gear 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.
+
* '''[[Complete Guide to Macros & Rolls‎]]''' - A comprehensive Guide for all things related to the {{Text Chat}}, Macros, and dice rolling on Roll20, linking to all relevant pages
 +
** [[Dice Reference]] - Info on the dice syntax that can be used in Macros
 +
** {{Text Chat}} - lists the various chat commands that can be used, like <code>/r</code>, <code>/w</code> and <code>/gr</code>
 +
** [[Roll_Templates#Using_Roll_Templates|Roll Templates]] - how you can use Roll Templates with your Macros
  
To use the macro, type ''#'' and the command (e.g. ''#test'') and press enter. There is also a tab auto-complete function for macros.
 
  
= Multiple commands =
+
[[File:Collections_Tab-macros.png|thumb|right|500px| Macros can be saved in their on section under the {{Collections}}-tab]]
  
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.
+
__TOC__
 +
= Creating and Editing Macros =
  
=== Example ===
+
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 {{button|Enter}} after this information to save the command.
  
If I want to create a macro that will include an emote, plus my attack and damage rolls it would look like this:
+
To call a Macro, type <code>#</code> and the command (e.g. <code>#test</code>) and press {{button|Enter}}.
  
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>
+
=== Аutocomplete ===
  
Then, simply by typing <code>#dagger</code> it would run the entire script and look like this:
+
Some text areas support the autocompletion of Macro calls (using <code>#</code>), [[Character#Attributes|Attribute calls]] (using <code>@</code>) and [[Character#Abilities|Ability calls]] (using <code>%</code>).
  
[[File:AttackMacro.JPG]]
+
The 'Actions' text areas of both Macros (on the Edit Macro window) and Abilities (on the [[Character#Attributes_.26_Abilities_Tab|Attributes & Abilities Tab]]) support the autocompletion of Macro and Attribute calls. The <span style="font-family:Pictos;">q</span> [[Text Chat]] supports the autocompletion of Macro and Ability calls.
  
Macros can also include a mix of command and non-command lines, for example:
+
To bring up an autocomplete list, type one of the aforementioned symbols (<code>#</code>, <code>@</code> or <code>%</code>, as and where appropriate) followed by a sequence of letters or numbers (at least one). A Macro, Attribute or Ability will populate the autocomplete list if its name contains this sequence.
  
<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>
+
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 [[Character]] that you have permission to control will appear on autocomplete lists.
  
This would first emote, then send &quot;<i>I smite you!</i>&quot; to the chat, and then make the two rolls afterwards.
+
For example, if you have permission to control a Character which contains an Attribute named <code>Dexterity</code>, you could type <code>@dex</code> (or possibly even just <code>@x</code>) into the 'Action' text area of an Edit Macro window to bring up an autocomplete list which contains that Attribute.
  
= Nesting Macros =
+
'''Tip:''' You can navigate and select items on the autocomplete list using the directional Up and Down keys and the {{button|Enter}} key.
  
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.
+
'''Tip:''' You can click on any roll, on your [[Character Sheet]], then go to the chat window and press the {{button|&uarr;}}(up arrow)-key to reveal the code used. This can be used to combine various rolls into one handy [[button]]!
 +
{{#evp:youtube|SlwAXIDFveo|Creating [[Macros]] in Roll20 (Nick Olivo)|right|650}}
 +
= 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 ===
 
=== Example ===
  
In this example, we'll have three macros: <code>#damage</code> <code>#attack</code> and <code>#both</code>
+
If I want to create a macro that will include an emote, plus my attack and damage rolls it would look like this:
  
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>
+
Macro Name: <br> <code>dagger</code><br><br> Macro Body:
  
== Nesting in a Roll Query ==
+
<pre>/me rams his dagger home
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.
+
/roll 1d20+10 vs AC
 +
/roll 1d4+9 Damage
 +
</pre>
  
<pre>?{Which macro?|Attack,#use-sword |Defend,#use-shield }</pre>
+
Then, simply by typing <code>#dagger</code> it would run the entire script and look like this:
  
=== Troubleshooting ===
+
[[File:AttackMacro.JPG]]
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, that nested macro may cause the Roll Query to break. 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_2|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 =
+
Macros can also include a mix of command and non-command lines, for example:
  
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.
+
<code>#lof</code>:
  
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.
+
<pre>
 +
/me calls upon the power of Moradin!
 +
I smite you!
 +
/roll 1d20+4 vs reflex
 +
/roll 1d8+4 damage
 +
</pre>
  
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.
+
This would first emote, then send &quot;<i>I smite you!</i>&quot; to the chat, and finally make the two rolls afterwards.
  
<big>'''Note:'''</big>
+
=Nesting=
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.
+
{{main|Nesting}}
 +
== Nesting Macros ==
 +
{{:Macros/Nested Macros}}
  
=== Example ===
+
== Nesting Abilities ==
 +
{{:Macros/Nested Abilities}}
  
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 Command Buttons =
 +
Ability Command Buttons can be used to call [[Character#Abilities|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 [[Character#Abilities|Ability]] calls, the '''keyword''' is your choice of <code>selected</code>, <code>target</code> or a character_name. You can also use a character_id as a keyword.
 +
<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>
  
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>
+
Continuing the example from [[Character#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.
  
=== More Examples ===
+
See '''[[Chat Menus]]''' for more examples
Here are some system-specific examples;
+
  
[[Dungeons_and_Dragons_Next#More_Examples|DnD 5e/Next macros]]
+
= Attribute Macros =
 +
You can directly use the stats from character sheets in general macros, by using the name of the character and then mentioning the stat to be used.
  
[[Macros_-_Pathfinder_Examples|Pathfinder macros]]
+
<pre data-language="javascript">
 +
/roll 1d20 + @{Guard|Strength} + @{Guard|attackbonus}
 +
/em @{Alice the Wizard|character_name} casts Mind Bolt, and does [[2d8+@{Alice the Wizard|int_mod}]] damage.
 +
</pre>
  
= 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 [[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 [[Character]] editor.
  
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. The Macro editor supports auto-complete of both nested macros (by pressing “#”) and Attributes from Characters (by pressing “@”).
+
'''Video tutorial(old)'''
 +
* A very basic look at using abilities for more simple rolls. (ex. Will Save, Skill Checks, etc.)
 +
* [https://www.youtube.com/watch?v=gIOsFeCsY0k Attributes & Abilities] (from 2013, likely exists newer versions)
  
[[File:CharMacroSS1.jpg|border]]
+
== Referencing Repeating Attributes ==
 +
Referencing attributes in a [[Repeating Section]] is a bit trickier than normal attributes
 +
=== By RowIndex ===
 +
{{:RowIndex}}
  
Tip: When using &quot;@&quot; in the Macro editor use the directional Up and Down key to select the appropriate Attribute.
+
=== 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 <code>data-reprowid</code>.  The value of this property is the '''RowID''':
  
=== Video tutorial on using Abilities ===
+
<pre data-language="html">
<br>A very basic look at using abilities for more simple rolls. (ex. Will Save, Skill Checks, etc.)
+
&lt;div class="repitem" data-reprowid="-KC0zCLum1Rq3V5wssyE"&gt;
<br>[http://youtu.be/gIOsFeCsY0k Attributes & Abilities]
+
</pre>
 +
The '''RowID''' is then used in place of the '''RowIndex''':
 +
<pre data-language="javascript">@{selected|repeating_items_-KC0zCLum1Rq3V5wssyE_itembonus}</pre>
  
== Using a Selected Token with a Macro ==
+
==Token==
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:
+
How to use the <code>selected</code> and <code>target</code>-keyword to refer to attributes on the token bars, or any connected [[Character Sheet]] to the token.
  
<pre data-language="javascript">/roll 1d20 + @{selected|bar1}</pre>
+
=== Selected Token with a Macro ===
 +
The <code>selected</code>-keyword will allow you to pull information from the currently selected Token on the screen when the roll/macro is executed. If the token [[Link Token|represents a character]], you can also reference attributes from the [[character]] by targeting the linked token.
  
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>
+
'''Example'''
 +
Pull the value of "Bar 1" from the selected token during a roll:
 +
<pre data-language="javascript">/roll 1d20 + @{selected|bar1}</pre>
  
You can pull the Name of the currently selected token's by using the &quot;token_name&quot; variable.
+
If you have a character sheet linked to the token, and you want to use the "intelligence" in a roll:
 +
<pre data-language="javascript">/roll 1d20 + @{selected|Intelligence}</pre>
  
 +
'''Names:'''
 +
You can pull the Name of the currently selected tokens by using the <code>token_name</code>-variable.
 
<pre data-language="javascript">/em @{selected|token_name} fires his gun!</pre>
 
<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.
+
If the selected token has a character linked to it, you can pull the Name from the character journal instead, using the <code>character_name</code>variable.
 
+
 
<pre data-language="javascript">/em @{selected|character_name} blocks with his shield!</pre>
 
<pre data-language="javascript">/em @{selected|character_name} blocks with his shield!</pre>
  
Line 102: Line 141:
 
<pre data-language="javascript">%{selected|Attack}</pre>
 
<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:
+
Finally, we've introduced a third argument for variables, allowing you to pull the "max" of a bar or attribute:
 
+
 
<pre data-language="javascript">
 
<pre data-language="javascript">
 
/roll 1d20 + @{Guard|Intelligence|max}
 
/roll 1d20 + @{Guard|Intelligence|max}
/roll 1d20 + @{selected|bar2|max}</pre>
+
/roll 1d20 + @{selected|bar2|max}
 +
</pre>
  
Also, all names (for Characters, attributes, and abilities) are not case-insensitive when you use them, so &quot;GUARD&quot; and &quot;guard&quot; will now both match the Character &quot;Guard&quot;.
+
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;.
+
'''Hint:''' To find a list of attributes for your character, you can look at it's [[Character#Attributes_.26_Abilities_Tab|Attributes & Abilities]]-tab. All stats that isn't their default values are displayed here, apart from those that are part of a [[Repeating Section]].
  
= Using a Targeted Token with a Macro =
+
Here you can also add your own attributes to be used by macros by simply clicking &quot;+ Add&quot;.
  
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:
+
====Attributes and Character Sheets====
 +
Character Sheets introduce a large number of attributes that you might want to reference in your custom macros. One thing to be aware of is the '''[[Auto-Calc]] Formula Attribute'''. Often times, a character sheet will have an attribute which is calculated from a formula involving other attributes. Referencing that attribute will show the formula instead of the value. 
 +
<pre>@{selected|character_name} has @{selected|action_points} points left.</pre>
 +
<blockquote>''"Rolf has ((ceil(((13+0)+(14+0))/12)+0)+0) points left."''</blockquote>
 +
 
 +
To get around this, you need to wrap the attribute reference in an [[Inline Roll]]:
 +
<pre>@{selected|character_name} has [[@{selected|action_points}]] points left.</pre>
 +
<blockquote>''"Rolf has 3 points left."''</blockquote>
 +
 
 +
=== Targeted Token with a Macro ===
 +
 
 +
Very similar to using the <code>selected</code> keyword to pull information from a selected token (as illustrated above), you can also use the <code>target</code> keyword to access information such as variables and/or abilities of a <code>target</code> 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 <code>strength</code> attribute to overcome.  The roll would look like:
  
 
<pre data-language="javascript">/roll 1d20 - @{target|strength}</pre>
 
<pre data-language="javascript">/roll 1d20 - @{target|strength}</pre>
Line 121: Line 171:
 
[[File:Choosetarget.png]]
 
[[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 primary difference being that it allows players to utilize values from tokens they are not controlling.
+
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.
  
=== Advanced Usage ===
+
==== Advanced Usage for Targeted Attribute Calls ====
  
 
The full syntax for the target variable is:
 
The full syntax for the target variable is:
Line 142: Line 192:
 
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:
 
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}!
+
<pre data-language="javascript">/me strikes out at @{target|foe|character_name}!
 
**To Hit**: [[1d20+3]] vs. @{target|foe|npc_AC} AC
 
**To Hit**: [[1d20+3]] vs. @{target|foe|npc_AC} AC
 
</pre>
 
</pre>
  
= Roll Options =
+
===Token Bar===
&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.
+
You can target the values of "bar1", "bar2", or "bar3".
  
=== Rolling For Initiative ===
+
<pre data-language="javascript">
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:
+
/roll 1d20 + @{selected|bar1}
 +
/roll 1d20 + @{selected|bar2|max}
 +
</pre>
  
<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.
+
'''@{target}'''
  
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:
+
If you use the <code>target</code> for checking a bar's max value, you must include an arbitrary name to the target, like shown in the [[#Targeted Token with a Macro|Targeted Token with a Macro]]-section.
 +
<pre data-language="javascript">
 +
@{target|first|bar1|max}
 +
@{target|second|bar1|max}
 +
@{target|Guard|bar2|max}
 +
</pre>
  
<code>/roll 1d20 + 5 &{tracker:+}<br />
+
= Roll Options =
/roll 1d20 + 5 &{tracker:-}</code>
+
&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 ===
 +
{{:Macros/Initiative}}
  
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:
+
=== Suppressing Errors Messages ===
  
<code>/me @{selected|token_name} ends their turn. [[10 &{tracker:-}]]</code>
+
The &quot;noerror&quot; roll option will suppress any errors (such as variable not found errors) in a roll.
  
Note that the tracker flag works both in regular rolls and inline rolls.
+
<code>/roll 1d20 + @{selected|nonexistent_attribute} &{noerror}</code>
  
 
= Using a variable with a Macro =
 
= Using a variable with a Macro =
Line 175: Line 234:
 
</pre>
 
</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.
+
When the macro is executed, a prompt will appear asking for the modifier to include. If no modifier is specified, the <code>|0</code> part of the query tells it to use 0 as the default value.
  
 
More information on Roll Queries is available in the [[Dice Reference]].
 
More information on Roll Queries is available in the [[Dice Reference]].
Line 187: Line 246:
 
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>
 
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===
+
=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.
 
You can specify a list of options which can be presented to the player, rather than only a free-form text field.
Line 195: Line 254:
  
 
You can also specify a different value for the result other than label like so:
 
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>
+
<pre>?{Name of Query|Label 1, value1|Label 2, value2}</pre>
  
 
====Examples====
 
====Examples====
  
 
Special Attack
 
Special Attack
<pre>... + ?{Sneak Attack?| No, [[0]] |Yes,[[3d6]] + ?{Power Attack? | No, [[0]] | Yes, [[6]] }</pre>
+
<pre>... + [[ ?{Sneak Attack?|No, 0|Yes, 3d6} ]] + ?{Power Attack?|No, 0|Yes, 6 [Power Attack!]}</pre>
5e Attack Roll
+
D&D 5e Attack Roll
 
<pre>[[ ?{Attack Type|Standard, 1d20|Advantage, 2d20kh1|Disadvantage, 2d20kl1} ]]</pre>
 
<pre>[[ ?{Attack Type|Standard, 1d20|Advantage, 2d20kh1|Disadvantage, 2d20kl1} ]]</pre>
  
 
Cure Spell
 
Cure Spell
<pre>?{Which Cure spell are you casting?| Cure Light Wounds, **Cure Light Wounds** Target Regains [[1d8+5]] HP.|  
+
<pre>?{Spell|
Cure Moderate Wounds, **Cure Moderate Wounds** Target Regains [[2d8+8]] HP.|  
+
  Cure Light Wounds, **Cure Light Wounds** Target Regains [[1d8+5]] HP. |  
Cure Serious Wounds, **Cure Serious Wounds** Target Regains [[3d8+8]] HP.}</pre>
+
  Cure Moderate Wounds, **Cure Moderate Wounds** Target Regains [[2d8+8]] HP. |  
 +
  Cure Serious Wounds, **Cure Serious Wounds** Target Regains [[3d8+8]] HP.
 +
}</pre>
 
<br>
 
<br>
  
=== Advanced Usage ===
+
=== Advanced Usage for Roll Queries ===
 +
{{main|Roll Queries & Nesting}}
  
Roll Queries currently end at the first closing brace the parser encounters. Other characters that serve as query syntax (including 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 characters with their HTML entities:
+
{{:Roll Query/Nested}}
  
{| class="wikitable"
+
====Chat Menus: An Alternative====
|-
+
Making advanced roll queries is hard. An alternative is to make a [[Chat Menus]], which post a list of options into chat, each with their own button to click. They are much easier to make and maintain.
! Character || Replacement
+
|-
+
| &#124;|| &amp;#124;
+
|-
+
| &#44;|| &amp;#44;
+
|-
+
| &#125;|| &amp;#125;
+
|}
+
 
+
'''*Note:''' Due to the [[Dice_Reference#Roll20_Dice_Specification|order of operations]], @{Attribute}, %{Ability} and #Macro ''calls'' are converted to their ''assigned values'' before Roll Queries are executed. That is to say, the vertical bar and closing brace characters that exist as the syntax of Attribute and Ability calls are replaced before those characters are able to prove problematic to a Roll Query that they are nested within. On the flip side, if the assigned value of a nested Attribute, Ability or Macro contains any problematic characters, that nested item will cause its Roll Query to break as surely as if that item's assigned value was inserted directly into its Roll Query in place of its call. So, if the assigned value of your nested Attribute, Ability or Macro ''does'' contain problematic characters, consider replacing any or all instances of that nested item's call with that item's assigned value, and then subjecting that assigned value to the above character replacements. '''All said, subjecting any Attribute, Ability or Macro calls to any character replacements will, under most use cases, cause that call to fail!'''
+
 
+
====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 =
 
= Macro Bar =
 +
{{main|Macro Quick 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>
+
In the '''Macro Quick Bar''', you can create quick access buttons for any of your macros that will appear in a bar at the bottom of the screen.
  
 +
 +
<div style="column-width:600px;">
 +
'''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]]
 
[[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.
 
  
  
 +
'''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.<br>
 
[[File:macroinbar.png|border]]
 
[[File:macroinbar.png|border]]
  
 +
 +
 +
</div>
  
 
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.
 
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.
Line 261: Line 305:
  
 
== Macro Menu ==
 
== Macro Menu ==
You can right click on a '''Macro Button''' in the '''Macro Quickbar''' to bring up a 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]]
 
[[File:MacroRightClickMenu.png|border]]
  
Line 270: Line 315:
 
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.
 
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]]=
 +
{{apiboxRec}}
 +
Macros can use [[Rollable Tables]] in them. The GM must create and make them visible to player if players are to be able to use them in macros.
 +
=[[API]]=
 +
{{pro only|section}}
 +
{{:Macros/API}}
 +
 +
= Related Pages =
 +
* '''[[Complete Guide to Macros & Rolls‎]]'''
 +
** {{Text Chat}} - where the roll results appear, & info on the common chat commands, such as <code>/r</code>, <code>/w</code> and <code>/gr</code>
 +
** [[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 <span style="font-family:Pictos;">q</span>Text Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
 +
*** [[Reusing Rolls]]
 +
** [[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 <span style="font-family:Pictos;">q</span>Text Chat
 +
* <span style="font-family:Pictos;">l</span> [[Collections]]-tab
 +
** [[Playing Cards]]
 +
** [[Rollable Tables]]
 +
* [[Building Character Sheets]]
 +
** [[Button#Roll_Button|Roll Button]] - how to create a roll button for a character sheet
 +
* [[Reusing Rolls]] - a clever way to reuse rolls within the same command
 +
<br>
 +
<br>
 
[[Category:Docs]]
 
[[Category:Docs]]
 +
[[Category:Macros]]

Latest revision as of 13:47, 17 October 2024

Attention: This page is community-maintained. For the official Roll20 version of this article, see the Help Center for assistance: Macros .

Macros are user-defined shortcuts to commands you regularly want to repeat and write in the q Text Chat. 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.

The Macro menu can be found under the l Collections-tab. For quick access, these saved rolls and commands can be added to the Macro Quick Bar or Token Actions where you can more quickly access them during play. You can also Drag-n-Drop Roll buttons from some Character Sheets to it.


Macros can be saved in their on section under the l Collections-tab

Contents

[edit] Creating and Editing Macros

Go to the l 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: "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.

[edit] Аutocomplete

Some text areas support the autocompletion 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 autocompletion of Macro and Attribute calls. The q 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 of 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 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.

Tip: You can click on any roll, on your Character Sheet, then go to the chat window and press the (up arrow)-key to reveal the code used. This can be used to combine various rolls into one handy button!

Creating Macros in Roll20 (Nick Olivo)

[edit] 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.

[edit] 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:
dagger

Macro Body:

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

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

AttackMacro.JPG

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 finally make the two rolls afterwards.

[edit] Nesting

Main Page: Nesting

[edit] 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.

[edit] 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

[edit] Nesting in a Roll Query

If you are nesting a macro in a Roll Query, make sure there is a space after the macro name, and no space between the , and # so that it is properly recognized by Roll20.

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

Troubleshooting

Due to the order of operations, Macro calls nested within Roll Query are fully expanded before the Roll Query is executed. This means that if a macro nested within a Roll Queries contains any "problematic characters" that conflict with Roll Query syntax (such as } , and |), that nested macro may cause the Roll Query to break (because the Roll Query will treat problematic characters in the called macro as Roll Query 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 replacement entities may no longer function outside of a Roll Query, and should be saved as Abilities.

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


[edit] Nesting Abilities

An ability is a macro which is tied to to a specific character's Attributes & Abilities-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 command.

Nesting an ability is similar to nesting a macro but with a slight twist. Like a macro, simply include the name of the abilities you wish to call on separate lines inside your main ability.

Converting a nested macro to a nested ability

#attack
#damage

becomes

%{bob|attack}
%{bob|dmg}

You need to change the # into %, type {, then the name of the character, a vertical pipe (|), the ability name, and closing the expression with }.


The vertical pipe(|) key can be found above the backslash key \ on most keyboards.

  • US keyboard: usually near the Enter-key. Shift+\ to type
  • European keyboards: Usually found on the number row
  • Finnish, Swedish keyboard: next to the right Shift. AltGr+| to type

Note: 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.

[edit] 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}

Then You can have a chat command where you can choose which ability to use: (example might need converted to HTML Entities):

?{Which ability?|Attack,%{Bugbear|attack} |Damage,%{Bugbear|damage} |Both,%{Bugbear|Both} }


[edit] More Examples

Other pages with macro examples:


[edit] Ability Command Buttons

Ability Command Buttons can be used to call Abilities (or sheet button rolls) from a clickable button in the q Text Chat. They are very closely related to 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.

See Chat Menus for more examples

[edit] Attribute Macros

You can directly use the stats from character sheets in general macros, by using the name of the character and then mentioning the stat to be used.

/roll 1d20 + @{Guard|Strength} + @{Guard|attackbonus}
/em @{Alice the Wizard|character_name} casts Mind Bolt, and does [[2d8+@{Alice the Wizard|int_mod}]] damage.

A culmination of the above examples can be used in what we call Attribute Macros. By using an Attribute that is assigned to a 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 Character editor.

Video tutorial(old)

  • A very basic look at using abilities for more simple rolls. (ex. Will Save, Skill Checks, etc.)
  • Attributes & Abilities (from 2013, likely exists newer versions)

[edit] Referencing Repeating Attributes

Referencing attributes in a Repeating Section is a bit trickier than normal attributes

[edit] By RowIndex

Attributes in a Repeating Section can be referenced by their RowIndex. Another method is to reference it by it's RowID.

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}

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.


[edit] 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}

[edit] Token

How to use the selected and target-keyword to refer to attributes on the token bars, or any connected Character Sheet to the token.

[edit] Selected Token with a Macro

The selected-keyword will allow you to pull information from the currently selected Token on the screen when the roll/macro is executed. If the token represents a character, you can also reference attributes from the character by targeting the linked token.


Example Pull the value of "Bar 1" from the selected token during a roll:

/roll 1d20 + @{selected|bar1}

If you have a character sheet linked to the token, and you want to use the "intelligence" in a roll:

/roll 1d20 + @{selected|Intelligence}

Names: 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 linked to it, you can pull the Name from the character journal instead, using the character_namevariable.

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

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

%{selected|Attack}

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

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

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

Hint: To find a list of attributes for your character, you can look at it's Attributes & Abilities-tab. All stats that isn't their default values are displayed here, apart from those that are part of a Repeating Section.

Here you can also add your own attributes to be used by macros by simply clicking "+ Add".

[edit] Attributes and Character Sheets

Character Sheets introduce a large number of attributes that you might want to reference in your custom macros. One thing to be aware of is the Auto-Calc Formula Attribute. Often times, a character sheet will have an attribute which is calculated from a formula 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."

[edit] 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:

/roll 1d20 - @{target|strength}

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

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 subsection below for more details on the complete syntax.

[edit] 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 max of an attribute:

@{target|Target1|HP|max}

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:

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

[edit] Token Bar

You can target the values of "bar1", "bar2", or "bar3".

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


@{target}

If you use the target for checking a bar's max value, you must include an arbitrary name to the target, like shown in the Targeted Token with a Macro-section.

@{target|first|bar1|max}
@{target|second|bar1|max}
@{target|Guard|bar2|max}

[edit] Roll Options

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

[edit] Rolling For Initiative

To send a roll result directly to the t Turn Tracker, first, select the Token you wish to roll for initiative and then use the below roll option in your macro:

/roll 1d20 + 5 &{tracker}


The "tracker" option tells Roll20's roll system, "Show the results of this roll, but also use the result as the value in the t Turn Tracker." 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:

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

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

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

Reference Values on the t Turn Tracker
Values on the Turn Tracker can be called the same way you would call Attributes from a Character Sheet.


Example:

@{tracker|Item Name}
/em has a initiative of @{tracker|Bob}.
&{template:default} {{name=Party Initiative}} {{Alice= **@{tracker|Alice}** }} {{Bob= **@{tracker|Bob}**}} {{Charlie= **@{tracker|Charlie}**}}


[edit] 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}

[edit] 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.

[edit] 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

[edit] Examples

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

[edit] 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}

[edit] 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.
}


[edit] Advanced Usage for Roll Queries

Main Page: Roll Queries & Nesting


If a macro contains characters used in a Roll Query (like the closing curly brackets, vertical bars, and commas), it can result in undesired behaviour.

For example, say you want to create a dropdown menu which contains a roll query, like so:

?{Choose a Roll|
   STR,/roll 1d20 + @{STR} + ?{Bonus}|
   DEX,/roll 1d20 + @{DEX} + ?{Bonus}|
   CON,/roll 1d20 + @{CON} + ?{Bonus}}

The problem here is that the } character signals the end of a query, and Roll20 isn't smart enough to know that one query is nested inside another. So when that Bonus query is encountered, the }-bracket will cause the dropdown menu to break.

Commas and vertical lines (|) are also part of query syntax, so they can cause problems too.

The way to deal with this, is replace characters with their relevant HTML entities

Change only the needed characters. If you have a nested query, change only the characters in the nested query, not the outer query.

Here's the above example, with a nested dropdown:

?{Choose a Roll|
   STR,/roll 1d20 + @{STR} + ?{Bonus&#125; |
   DEX,/roll 1d20 + @{DEX} + ?{Bonus&#125; |
   CON,/roll 1d20 + @{CON} + ?{Bonus&#125; }

[edit] Roll Query Troubleshooting: NEVER REPLACE ATTRIBUTES

You'll notice in the above example, the attribute call wasn't changed. It's very important that you never replace the characters in calls (i.e. @{Attribute}, %{Ability}, #Macro).

Due to the order of operations, calls are parsed to their values before Roll Queries are executed. If you change characters to their HTML entities, the call will be broken and the macro will fail.

  • Never, ever, do this: @{target&#124;token_name&#125;.
  • Always leave calls alone: @{target|token_name}

[edit] Roll Query Troubleshooting: Call Values

If you call an Attribute, Ability, or Macro, the contents are expanded before resolving. This means if your macro calls another macro, and that macro has a query syntax character (comma, pipe, closing curly bracket), it will cause the macro to fail.

So you need to locate and replace all problematic characters within the values of any Attributes, Abilities or Macros.

Once you've done those, those values now contain HTML entities, the affected calls probably no longer work outside of your Roll Query. So, it's usually best to just directly insert these values into your Roll Query, replacing their call.

Here's an example of a query that calls macros.

?{Choose an Attack|
   Melee,#Melee-attack |
   Ranged,#Ranged-attack |
   Psychic,#Psychic-attack }

At first glance, this looks straight forward. But what if those macros looked like this:

Melee-attack: /roll 1d20+ @{STR} + ?{Bonus|0}
Ranged-attack: /roll 1d20+ @{DEX} + ?{Bonus|0}
Psychic-attack: /roll 1d20+ @{WIS} + ?{Bonus|0}

On their own those macros work fine, but when you try to use them in the dropdown query, that query fails. To get them to work, you'd need to change that bonus query, like so:

Melee-attack: /roll 1d20+ @{STR} + ?{Bonus|0&#125;
Ranged-attack: /roll 1d20+ @{DEX} + ?{Bonus|0&#125;
Psychic-attack: /roll 1d20+ @{WIS} + ?{Bonus|0&#125;

That fixes the roll query, but the macros no longer work properly on their own - the Bonus query isn't recognized.

So you are best off leaving the macros alone, and copying their contents to your dropdown:

?{Choose an Attack|
   Melee,/roll 1d20+ @{STR} + ?{Bonus&#124;0&#125; |
   Ranged,/roll 1d20+ @{DEX} + ?{Bonus&#124;0&#125; |
   Psychic,/roll 1d20+ @{WIS} + ?{Bonus&#124;0&#125; }

And now your query works. Whenever you have an Ability or Macro call in a query, you'll often find it's better just to copy the contents over to to your query and edit in place, as shown above.

[edit] Roll Query Troubleshooting: Simplify Where Possible

It's a good idea to separate out elements that are repeated within each 'row' of the query. For instance, that last query could be rewritten as

/roll 1d20+ ?{Choose an Attack|
   Melee,@{STR} |
   Ranged,@{DEX} |
   Psychic,@{WIS} } + ?{Bonus|0}

The /roll 1d20+ part is common to each rows, so you simplify the macro by moving it out. The + ?{Bonus|0} part is common to all, and can also be moved out of the query, thus avoiding the need for HTML substitution completely.

You won't be able to simplify all advanced queries in this way, but when you can, it makes the macro a lot simpler.

[edit] Roll Query Troubleshooting: Collections Macros

You normally store queries in Macros, saved under the l Collections-tab of the Sidebar. Unfortunately, whenever you open a macro stored there, Roll20 parses the macro and this causes HTML entities to be converted to the characters their represent. This breaks your carefully created macro.

So, if you place macros containing HTML entities there, it's a good idea to store a backup somewhere. This behaviour doesn't happen with Abilities, so many people create a Macro Character Sheet, for storing such macros safely as abilities.

[edit] Roll Query Troubleshooting: Nesting Queries

You can achieve further levels of nesting by "stacking" ampersand & HTML entities:

Character Replacement
& &amp;

Starting from the second level of nesting, the &amp; entity is being used to replace the & in &#124;, &#125; and &#44;, meaning that you need to use &amp;#124;, &amp;#125; and &amp;#44; instead. Subsequent "stacking" of ampersand for further levels of nesting (i.e: &amp;amp;#124;) are possible:

Nesting Level Pipe Closing Brace Comma
0 | } ,
1 &#124; &#125; &#44;
2 &amp;#124; &amp;#125; &amp;#44;
3 &amp;amp;#124; &amp;amp;#125; &amp;amp;#44;
4 ... ... ...

In order to use commands in the nested queries, make sure there are no spaces between the comma of the current layer's label and the question mark of the next query. Here's a generic example of it in use.

?{Name of Query|
   Label 1,?{value1&#124;
      Label 1A&#44;?{value1A&amp;#124;
         Label 1Ai&amp;#44; value1Ai &amp;#124;
         Label 1Aii&amp;#44; value1Aii
      &amp;#125; &#124;
      
      Label 1B&#44;?{value1B&amp;#124;
         Label 1Bi&amp;#44; value1Bi &amp;#124;
         Label 1Bii&amp;#44; value1Bii
      &amp;#125;
   &#125; |

   Label 2,?{value2&#124;value2&#125; 
}


[edit] Chat Menus: An Alternative

Making advanced roll queries is hard. An alternative is to make a Chat Menus, which post a list of options into chat, each with their own button to click. They are much easier to make and maintain.

[edit] Macro Bar

Main Page: Macro Quick Bar

In the Macro Quick 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 like normal. Then, to enable the macro quick bar, check off "Show macro quick bar" in the settings menu.
Showquickbar.png


Then, 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 quickbar on, toggling on a macro will auto-enable the quickbar to display.
Macroinbar.png


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.

Macrobar.png

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

[edit] 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.

MacroRightClickMenu.png

[edit] 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.

[edit] 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.

[edit] Rollable Tables

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

[edit] API

Various APIs that primarily help you out by creating API commands & options that can be used in the q Text Chat.

  • ChatSetAttr -- Create, modify, and delete character attributes via chat commands or macros.
  • ChatTurnManager -- A script to simplify Turn Order Management, and move it into chat.
  • Check It Out(Forum) -- allows players to examine nearby objects(tokens) and learn more information about them by having a message appear in the chat. Can be set up with system-specific properties, such as automated Investigation skill checks that reveal more information based on the rolled result. Readme
  • Dialog(Forum) -- a script that makes chat a bit more fun and easier to parse, especially for games that don't use voice. It also makes it much easier to get the GM's attention in a busy game.sourcecode, by Keith
  • DiscreteWhisper -- multi-recipient whispers with asides and buttons
  • emas -- Provides player !emas and !as commands.(emote as)
  • ScriptCards -- A scripting language in a Mod Script. Used to produce nicely formatted output cards for attacks, spells, and other abilities. Successor to PowerCards
  • SuperNotes(Forum) Mod to pull descriptions from token/character descriptions, Bio, GM fields & more as an caht message. Later version comes with 10 different chat template options.
  • PowerCards -- Create nicely formatted output cards for attacks, spells, and other abilities.
  • Message of the Day -- Greets players that log in with the contents of a particular note.
  • Rollable Table Macros -- Use macros and chat commands with rollable tables
  • Changes how normal macros and API Script calls are processed:
    • MetaMacros -- Precompiler enabling C-style textual substitution macros in macro definitions.
    • Meta-Toolbox -- collection of meta scripts
      • SelectManager -- a way to preserve the portions of a message that are present in a user-generated message but lost in an api-generated message (the selected tokens, who sent the message, and the playerid).
    • Category:API Meta Scripts


[edit] Related Pages