Character Vault
Any Concept / Any System
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 (Troubleshooting)
m (Roll Query Troubleshooting: NEVER REPLACE ATTRIBUTES)
Line 361: Line 361:
You'll notice in the above example, the attribute call wasn't changed. It's very important that you '''never''' replace the characters in <u>calls</u> (i.e. @{[[Journal#Attributes|Attribute]]}, %{[[Journal#Abilites|Ability]]}, #[[Macros#Creating_and_Editing_Macros|Macro]]).
Due to the [[Dice_Reference#Order_of_Operations|order of operations]], <u>calls</u> 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.
Due to the [[Order_of_Operations|order of operations]], <u>calls</u> are parsed to their ''values'' before Roll Queries are executed. If you change characters to their [[Complete_Guide_to_Macros_%26_Rolls#HTML_replacement|HTML entities]], the call will be broken and the macro will fail.
'''Never, ever, do this:''' <code>@{target&amp;#124;token_name&amp;#125;</code>.  
Always leave calls alone: <code>@{target|token_name}</code>  
====Roll Query Troubleshooting: Call Values ====

Revision as of 13:02, 13 April 2021

Attention: Roll20 is no longer maintaining this document on the Community Wiki. For the Official version of this, check the Roll20 Help Center on Macros.

Macro Creation



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


Creating and Editing Macros




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.



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 click on any roll, on your character sheet, then go to the chat window and press the up arrow to reveal the code used. This can be used to combine various rolls into one handy button!

Multiple commands




Macro Name:

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




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


Nesting Macros




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

Nesting in a Roll Query




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


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


Nesting Abilities







Ability %damage = /roll 1d4+11
Ability %attack = /roll 1d20+9
Ability %both =

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

More Examples

Here are some system-specific examples:

Ability Command Buttons


Their syntax is as follows:




[Label](~<ability name>)


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)

  • Attributes & Abilities (from 2013, likely exists newer versions)

Referencing Repeating Attributes

By RowIndex




By RowID



The RowID is then used in place of the RowIndex:



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

Selected Token with a Macro


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!






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



Attributes and Character Sheets




Rolf has 3 points left.

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}




Advanced Usage for Targeted Attribute Calls

The full syntax for the target variable is:





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





Token Bar

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

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


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.


Roll Options


Rolling For Initiative


/roll 1d20 + 5 &{tracker}



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





Suppressing Errors Messages



Using a variable with a Macro


/roll 2d20 + ?{Modifier|0}


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

Specifying a variable in chat



#d20 /roll 1d20+

Drop-Down Prompts for Roll Queries


Here's the syntax:





Special Attack


D&D 5e Attack Roll


Cure Spell


Advanced Usage for Roll Queries


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

?{Choose a Roll|

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.


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

Here are some commonly used ones.

Character Replacement
| &#124;
, &#44;
} &#125;


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

?{Choose a Roll|

Roll Query Troubleshooting: NEVER REPLACE ATTRIBUTES


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.


Roll Query Troubleshooting: Call Values



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 }




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.


?{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; }


Roll Query Troubleshooting: Simplify Where Possible


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

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.


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.

Roll Query Troubleshooting: Nesting Queries


Character Replacement
& &amp;

Here's a generic example of it in use:

?{Name of Query|
   Label 1, ?{value1&#124;
         Label 1Aii&amp;#44; value1Aii
      &amp;#125; &#124;
         Label 1Bii&amp;#44; value1Bii
   &#125; |


Chat Menus: An Alternative


Macro Bar

Main Article: Macro Quick Bar








Macro Menu







Rollable Tables


Related Pages