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 "Complete Guide to Macros & Rolls"

From Roll20 Wiki

Jump to: navigation, search
m (links to Chat Menus page)
m (Formatting)
 
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This is meant to serve as a comprehensive guide & starting point for figuring out how the {{Text Chat}}, [[Dice Reference|Dice Rolling]], [[Macros]] and related things work and interact with each-other, to find the documentation for each, and to list everything you can write/make appear in the {{Text Chat}}.
 
This is meant to serve as a comprehensive guide & starting point for figuring out how the {{Text Chat}}, [[Dice Reference|Dice Rolling]], [[Macros]] and related things work and interact with each-other, to find the documentation for each, and to list everything you can write/make appear in the {{Text Chat}}.
 
+
{{NavMacroDocs}}
 
This is both for [[Players]] and [[GM|Gamemasters]] who are just writing their own custom rolls or macros to be used in their game, as well as those who [[BCS|build Character Sheets]] and are creating/editing [[Button#Roll Button|Roll Buttons]] for their sheets.
 
This is both for [[Players]] and [[GM|Gamemasters]] who are just writing their own custom rolls or macros to be used in their game, as well as those who [[BCS|build Character Sheets]] and are creating/editing [[Button#Roll Button|Roll Buttons]] for their sheets.
  
 
==[[Text Chat]]==
 
==[[Text Chat]]==
 
[[File:Basic-roll-example.png|right|thumbnail|400px|]]
 
[[File:Basic-roll-example.png|right|thumbnail|400px|]]
The {{Text Chat}}-page shows the basic commands that can be used in the chat, such as <code>/roll</code>(or <code>/r</code>) for making simple rolls, <code>/em</code> for emoting text, <code>/w</code> for whispering to someone, and <code>/gmroll</code>(or <code>/gr</code>) for sending simple rolls to the GM.
+
The {{Text Chat}}-page shows the basic commands that can be used in the chat, such as <code>/roll</code>(<code>/r</code>) for making simple rolls, <code>/em</code> for emoting actions, <code>/w</code> for whispering to someone, and <code>/gmroll</code>( <code>/gr</code>) for sending simple rolls to the GM.
  
 
You can write in the {{Text Chat}} normal text without using any commands like <code>/r</code>.
 
You can write in the {{Text Chat}} normal text without using any commands like <code>/r</code>.
 +
 +
See [[#Chat Commands|Chat Commands]]-sections for examples, or the
  
 
'''Normal macros can't edit stats, only read them.''' To edit stats with a command, you need to use [[#API|API]] in some form.  
 
'''Normal macros can't edit stats, only read them.''' To edit stats with a command, you need to use [[#API|API]] in some form.  
 
<br>
 
<br>
===Text Formatting===
+
===Formatting===
You can use common '''Markdown''' to format you text, and to create hyperlinks.
+
You can use common '''Markdown''' to format you text, and to even create hyperlinks in text shown in the chat.
  
See also:
+
If you hyperlink to to a {{Compendium}} page, it will open up inside Roll20 when clicked.
* [https://app.roll20.net/forum/permalink/9119412/ How to use HTML Styles in chat] - Oosh
+
* [https://app.roll20.net/forum/permalink/9031455/ Using Images as Links] - Oosh
+
* [https://app.roll20.net/forum/permalink/8511142/ Hypertext Macro to Open a Linked Character Sheet  Hypertext Macro to Open a Linked Character Sheet] - Vince
+
  
 +
Tips & Examples:
 +
* {{fpl|9119412/ How to use HTML Styles in chat}} - [[Oosh]]
 +
* {{fpl|9663315/ Tooltips in Text Chat}}
 +
* Making links
 +
** {{fpl|9031455/ Using Images as Links}} - Oosh
 +
** {{fpl|8511142/ Hypertext Macro to Open a Linked Character Sheet  Hypertext Macro to Open a Linked Character Sheet}} - [[Vince]]
 +
** {{fpl|9998276/ link to open a Compendium page from chat}}
 +
* {{fpl|10170199/ %NEWLINE% trick + misc.}} - [[Andreas J.]]
 +
 +
===Markdown===
 +
Markdown is available to let you bold, italic, bold-italic, create a hyperlinks, or include even an image in your macros and text as they appear in the {{Text Chat}}.
 +
<pre style="overflow:auto;white-space:pre-wrap;">
 +
* italics *
 +
** bold **
 +
*** bold italics ***
 +
[Dodge](https://roll20.net/compendium/dnd5e/Rules:Actions%20in%20Combat#h-Dodge)
 +
</pre>
 +
Alternative to adding the markdown into the macros, you can sometimes add the markdown to your [[#Character Attributes]], so you can have a universal macro, and make individual adjustment to to how you want each output to look like.
 +
 +
{{ex}}
 +
<pre>/em his **@{bob|height}}** tall, and can be described as: @{bob|description}}.
 +
</pre>
 
===HTML replacement===
 
===HTML replacement===
When creating some complicated/sofisticated macros, usually involving [[#Nesting|nesting]], you will need to use [https://www.w3schools.com/html/html_entities.asp HTML entities] in parts of the code to trick the Roll20 system to make it behave like you want, or some advanced tricks won't work.
+
When creating some complicated/sophisticated macros, usually involving [[#Nesting|nesting]], you will need to use [https://www.w3schools.com/html/html_entities.asp HTML entities] in parts of the code to trick the Roll20 system to make it behave like you want, or some advanced tricks won't work.
  
Here are the HTML entities used in advanced Roll20 macros:
+
Here are some HTML entities used in advanced Roll20 macros(see [https://www.freeformatter.com/html-entities.html List of HMTL Entities] for full list):
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 74: Line 95:
 
[https://www.freeformatter.com/html-entities.html HTML entities] contains a longer list of all the existing HTML entities, of which only few are used/needed in Roll20 context, but might be useful to check if the above table isn't enough.
 
[https://www.freeformatter.com/html-entities.html HTML entities] contains a longer list of all the existing HTML entities, of which only few are used/needed in Roll20 context, but might be useful to check if the above table isn't enough.
  
See '''[[Macros#Advanced_Usage_for_Roll_Queries|Advanced Usage for Roll_Queries]]''' for examples of use.
+
See '''[[Macros#Advanced_Usage_for_Roll_Queries|Advanced Usage for Roll Queries]]''' for more examples.
  
 
==Chat Commands==
 
==Chat Commands==
Line 104: Line 125:
  
 
===[[Dice Reference|Dice Syntax]]===
 
===[[Dice Reference|Dice Syntax]]===
The [[Dice Reference]] page shows how the syntax for the Roll20 dice rolling works, and all the advanced alternatives you can use, such as rolling Fate Dice, or counting successes rather than the sum of the rolls. It also details when the green "Critical Success" and red "Critical Failure" highlights are shown.  
+
The [[Dice Reference]] page shows how the syntax for the Roll20 dice rolling works, and all the advanced alternatives you can use, such as rolling [[Dice_Reference#FATE_Dice|Fate Dice]], or [[Dice_Reference#Target_Number_.28Successes.29|counting successes]] rather than the sum of the rolls. It also details when the green & red "[[Dice_Reference#Critical_Success_and_Fumble_Points|Critical Success/Failure]]"-highlights are shown.  
  
 
''Tricks:''
 
''Tricks:''
* [https://app.roll20.net/forum/permalink/9171656/ Comparing numbers, greater than or equal to] - Mike deBoston
+
* {{fpl|9171656/ Comparing numbers, greater than or equal to}} - Mike deBoston
* [https://app.roll20.net/forum/permalink/7510681/ Bypass Blank Ability Call Math] - Blue64
+
* {{fpl|7510681/ Bypass Blank Ability Call Math}} - Blue64
* [https://app.roll20.net/forum/permalink/6113861/ Summing "Success" Rolls] - Usually you can't both coun't the success and sum up rolls, but this is a close workaround by Bryan P.  
+
* {{fpl|6113861/ Summing "Success" Rolls}} - Usually you can't both coun't the success and sum up rolls, but this is a close workaround by Bryan P.  
* [https://app.roll20.net/forum/permalink/8068345/ Fake Crits Using Math Instead of Dice] - Noon
+
* {{fpl|8068345/ Fake Crits Using Math Instead of Dice}} - Noon
* [https://app.roll20.net/forum/permalink/8717558/ Auto calculating level specific buffs. (Basic IF/THEN statement, no API)] - Greg S.
+
* {{fpl|8717558/ Auto calculating level specific buffs. (Basic IF/THEN statement, no API)}} - Greg S.
* [https://app.roll20.net/forum/permalink/6003370/ Keep Crits/Fumbles from Display on Attack Rolls] - Scott C.
+
* {{fpl|6003370/ Keep Crits/Fumbles from Display on Attack Rolls}} - [[Scott|Scott C.]]
  
====Order of Operations====
+
====Inline Rolls====
The [[Dice_Reference#Order_of_Operations|Order of Operations]] sections highlights in what order different components resolve, which can become important when you do complicated things.  
+
{{main|Inline Rolls}}
 +
[[File:Roll template default example2.JPG|right|thumb|350px|The output of a '''default template''' that shows an '''inline roll'''(yellow box) ]]
 +
If you use simple roll commands/macros like <code>/roll 2d10+5</code>, the whole command is a dice roll. But when you use [[#Roll Templates|Roll Template]], or have embedded dice rolls with other commands like <code>/em</code>, you use '''inline rolls''', where you wrap <code><nowiki>[[ ]]</nowiki></code> around the calculation for it to be processed. The result of "Normal" dice rolls is shown as individual dice images displaying the result on each dice separately, along with the total result.
  
====Inline Labels====
+
Inline rolls are just like regular rolls, with the following exceptions:
If you want to include additional comments before the end of the roll (we call them &quot;inline labels&quot;), use square brackets. For example, <code>/roll 2d10+5[Fire Damage] + 3d6[Ice Damage]</code>. When these comments are applied directly after a die roll they show up as tool-tips on the dice:
+
  
 +
* You can use them in any chat message, not just a roll. For example, you can do a regular chat message, an emote(<code>/em</code>), or a whisper(<code>/w</code>), with an inline roll included.
 +
* They are evaluated completely before any (<code>/roll</code>) commands, so you can use them as "random variables" in your rolls.
 +
* You will only see the result of the total roll, and you can hover over the result to see the individual dice rolls.
 +
* Highlights
 +
** If an inline roll contains a '''critical success''', it will be highlighted with a green box.
 +
** If there's a '''critical failure''', it's highlighted in red.
 +
** If it has '''both''' (because there was more than one roll), it's in blue.
 +
 +
Also when you mouse-over the inline roll to see the details of the roll, it'll show red and green highlights for the rolls themselves for crits/fumbles.
 +
 +
With inline rolls, the numerical end result is shown in a (yellow) box, and if you hover you mouse over the result, you see the full equation of the roll, along with the result of each.
 +
 +
{{ex}}
 +
<pre>
 +
/em swings their sword and does [[2d6+2]] damage.
 +
</pre>
 +
<pre>
 +
&{template:default} {{name=Test Attack}} {{attack=[[1d20+5]]}}
 +
</pre>
 +
 +
====[[Inline Rolls#Inline Labels|Inline Labels]]====
 +
If you want to include additional comments before the end of the roll (we call them &quot;inline labels&quot;), use square brackets. For example, <code>/roll 2d10+5[Fire Damage] + 3d6[Ice Damage]</code>. Inline labels works both with "normal" rolls and '''inline rolls'''.
 +
 +
When these comments are applied directly after a die roll they show up as tool-tips on the dice:
 
<div class="diceroller">
 
<div class="diceroller">
 
/roll 2d10+5[Fire Damage] + 3d6[Ice Damage]
 
/roll 2d10+5[Fire Damage] + 3d6[Ice Damage]
Line 126: Line 172:
 
This is especially useful if a roll contains multiple variables and you want to look up what number comes from what attribute.
 
This is especially useful if a roll contains multiple variables and you want to look up what number comes from what attribute.
  
 +
'''You can even use sheet attributes in labels.''' Especially useful if the name of the stat can be customized by the user, so the corresponding label should change to reflect the name.
 +
{{ex}}
 +
<pre>
 +
/r @{selected|customskill1}d6[@{selected|customskill1name}] + @{selected|str}[str]
 +
</pre>
  
 +
===[[Order of Operations]]===
 +
{{:Order of Operations}}
 
===[[Macros]]===
 
===[[Macros]]===
 
''Main Article:'' '''[[Macros]]'''
 
''Main Article:'' '''[[Macros]]'''
Line 135: Line 188:
 
* Adding options to user when roll is made('''Roll Queries''')
 
* Adding options to user when roll is made('''Roll Queries''')
 
* Using [[Macros#Using_a_Targeted_Token_with_a_Macro|@{target}]] and [[Macros#Using_a_Selected_Token_with_a_Macro|@{selected}]] to target tokens and their stats. See [[#Token|Token]]-section for interaction with them
 
* Using [[Macros#Using_a_Targeted_Token_with_a_Macro|@{target}]] and [[Macros#Using_a_Selected_Token_with_a_Macro|@{selected}]] to target tokens and their stats. See [[#Token|Token]]-section for interaction with them
** [https://app.roll20.net/forum/permalink/8048203/ Variable numbers of targets in an AoE attack] GenKitty
+
** {{forum|permalink/8048203/ Variable numbers of targets in an AoE attack}} - GenKitty
 
* Automatically add a roll to the [[Turn Tracker]]
 
* Automatically add a roll to the [[Turn Tracker]]
 
* [[Reusing Rolls]]
 
* [[Reusing Rolls]]
Line 153: Line 206:
 
</pre>
 
</pre>
  
'''Drop-down Queries'''
+
=====Drop-down Queries=====
  
You can specify a list of options which can be presented to the [[player]], rather than only a free-form text field. Be mindful about if/when you add spaces inside a Roll Query, as having/not having them changes how things work.
+
You can specify a list of options which can be presented to the [[player]], rather than only a free-form text field. Be mindful about if/when you add spaces inside a Roll Query, as having/not having them changes how things work. If the content of the dropdown query includes chracters like <code>|</code>,<code>{</code>,<code>}</code>, and<code>,</code>, you will likely need to use [[#HTML replacement|HTML replacement]] for them to make it work.
  
 
Syntax:
 
Syntax:
Line 165: Line 218:
 
You can also specify a separate label for each option, instead of displaying the Option itself in the dropdown.
 
You can also specify a separate label for each option, instead of displaying the Option itself in the dropdown.
 
<pre>?{Name of Query|Label 1,Option1|Label 2,Option2}</pre>
 
<pre>?{Name of Query|Label 1,Option1|Label 2,Option2}</pre>
This can be useful if the Option itself is long, or if it's better to describe what the options represent, rather than show exactly what they are.
+
This can be useful if the Option itself is long, or if it's better to describe what the options represent, rather than show exactly what they are.
 
+
  
 
'''Example:'''
 
'''Example:'''
Line 172: Line 224:
 
/r d20+?{Stat:|Strength,2|Dexterity,1}
 
/r d20+?{Stat:|Strength,2|Dexterity,1}
 
</pre>
 
</pre>
 +
 +
If you place the drop-down query at the start of a macro, make sure there is no space after the <code>,</code>, as this will break any macro or command inside it.
 +
 +
<pre>?{Attack|Just roll,/r d20+5|Description,/em swings the sword with a result of [[d20+5]]}</pre>
 +
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
 +
| non-functional version
 +
|-
 +
| <pre>?{Attack|Just roll, /r d20+5|Description, /em swings the sword with a result of [[d20+5]]}</pre>
 +
|}
  
 
You may also split up Roll Queries on multiple rows to make the code more readable. ''Extra line breaks in code isn't generally a good idea, and could be good to avoid to not create errors.''
 
You may also split up Roll Queries on multiple rows to make the code more readable. ''Extra line breaks in code isn't generally a good idea, and could be good to avoid to not create errors.''
 
<pre>
 
<pre>
?{Choose an Attack|
+
/roll 1d20 + ?{Choose an Attack|
   Melee,/roll 1d20 + 3[STR] |
+
   Melee,3[STR] |
   Ranged,/roll 1d20 + 2[DEX] |
+
   Ranged,2[DEX] |
   Magic,/roll 1d20 + 1[INT] }
+
   Magic,1[INT] }
 
</pre>
 
</pre>
  
Line 190: Line 251:
  
  
* [https://app.roll20.net/forum/permalink/6053873/ Query Ordering Without Affecting Functionality] how to borrow API command syntax(works for free users) - Ziechael
+
* {{forum|permalink/6053873/ Query Ordering Without Affecting Functionality}} how to borrow API command syntax(works for free users) - [[Ziechael]]
 
* [[Chat Menus]],by Keith – In some cases, creating a '''chat menu''' for your macros is easier or better than making a complicated Query with several options.
 
* [[Chat Menus]],by Keith – In some cases, creating a '''chat menu''' for your macros is easier or better than making a complicated Query with several options.
  
Line 202: Line 263:
 
If you start nesting queries too much, you need to start using [[Macros#Advanced_Usage_for_Roll_Queries|HTML replacement]] keep the macros working. Once saved, these macros shouldn't be opened(if saved in the {{Collections}}-tab's Macro section, as opening a macro that have HTML replacement will result in those being converted into regular things, breaking your macro.
 
If you start nesting queries too much, you need to start using [[Macros#Advanced_Usage_for_Roll_Queries|HTML replacement]] keep the macros working. Once saved, these macros shouldn't be opened(if saved in the {{Collections}}-tab's Macro section, as opening a macro that have HTML replacement will result in those being converted into regular things, breaking your macro.
  
* [https://app.roll20.net/forum/permalink/6582632/ Drop down Nester] google sheet that generates the HTML replacement code needed. by Scott C.
+
* [https://app.roll20.net/forum/permalink/6582632/ Drop down Nester] google sheet that generates the HTML replacement code needed. by [[Scott C.]]
 
* [https://www.freeformatter.com/html-entities.html HTML entities] contains a longer list of all the existing HTML replacement code, of which only few are used/needed in Roll20 context.
 
* [https://www.freeformatter.com/html-entities.html HTML entities] contains a longer list of all the existing HTML replacement code, of which only few are used/needed in Roll20 context.
  
 
====Initiative====
 
====Initiative====
Main section: [[Macros#Rolling_For_Initiative]]
+
Main section: [[Macros#Rolling_For_Initiative|Rolling for Initiative]]
  
To send a roll result directly to the [[Turn Tracker]], first, select the [[Token]] you wish to roll initiative for, and then make a roll that includes the  
+
To send a roll result directly to the {{Turn Tracker}}, first, select the [[Token]] you wish to roll initiative for, and then make a roll that includes the  
 
<code>&{tracker}</code>-flag. You can also increase/decrease initiative by using <code>&{tracker:+}</code>/<code>&{tracker:-}</code>.
 
<code>&{tracker}</code>-flag. You can also increase/decrease initiative by using <code>&{tracker:+}</code>/<code>&{tracker:-}</code>.
 
+
{{ex}}
Examples:
+
 
* <code>/roll 1d20 + 5 &{tracker}</code>
 
* <code>/roll 1d20 + 5 &{tracker}</code>
 
* <code><nowiki>&{template:default} {{name=Initiative}} {{Roll=[[1d20+4 &{tracker}]]}} </nowiki></code>
 
* <code><nowiki>&{template:default} {{name=Initiative}} {{Roll=[[1d20+4 &{tracker}]]}} </nowiki></code>
Line 218: Line 278:
 
* <code>[[5 &{tracker:-}]]</code> (inline roll that decreases the initiative by a flat <code>2</code>)
 
* <code>[[5 &{tracker:-}]]</code> (inline roll that decreases the initiative by a flat <code>2</code>)
  
See also: [[Cards#Using_Cards_for_Initiative_Order]]
+
See also: [[Cards#Using_Cards_for_Initiative_Order|Using Cards for Initiative Order]]
  
See the [[Turn Tracker]]-page for the Token/Turn Tracker/Character Sheet related info.
+
'''Referencing values on the turn tracker:''' by calling  <code>@{Tracker|character_id}</code> <code>@{Tracker|character_name}</code>, you can check what values are on the turn tracker. ex. <code>Bobs initiative is @{tracker|Bob}.</code>
  
Tricks using the [[Turn Tracker]]:
+
Tricks using the {{Turn Tracker}}:
 
* [https://app.roll20.net/forum/permalink/7537433/ Storing and Reading Values for Macros using the Turn Tracker] - Pat
 
* [https://app.roll20.net/forum/permalink/7537433/ Storing and Reading Values for Macros using the Turn Tracker] - Pat
 
* [https://app.roll20.net/forum/permalink/9085059/ Using Values Stored in Initiative Tracker as Pointers] - Michael L
 
* [https://app.roll20.net/forum/permalink/9085059/ Using Values Stored in Initiative Tracker as Pointers] - Michael L
Line 235: Line 295:
 
<br><br>
 
<br><br>
 
Their syntax is as follows:
 
Their syntax is as follows:
<pre>[Label](~<keyword>|<ability name>)</pre>
+
<pre>
 +
[Label](~<keyword>|<ability name>)
 +
[Dex Check](~Bob|dexterity)
 +
[Dex Check](~selected|dexterity_save)
 +
[Dex Check](~selected|repeating_attack_$0_attack)
 +
</pre>
 
As with [[Journal#Attributes|Attribute]] and [[Journal#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.
 
As with [[Journal#Attributes|Attribute]] and [[Journal#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>
 
<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:
 
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>
+
<pre>
 +
[Label](~<ability name>)
 +
[Dex Check](~dexterity)
 +
</pre>
  
 
'''[[#API_Command_Buttons|API Command buttons]]'''
 
'''[[#API_Command_Buttons|API Command buttons]]'''
Line 273: Line 341:
 
* [https://app.roll20.net/forum/permalink/8788506/ Conditional Text] - Mike deBoston
 
* [https://app.roll20.net/forum/permalink/8788506/ Conditional Text] - Mike deBoston
 
* [https://app.roll20.net/forum/permalink/6852555/ Rollable Encounter Images] - Blue64
 
* [https://app.roll20.net/forum/permalink/6852555/ Rollable Encounter Images] - Blue64
 +
* {{forum|permalink/9898031/ Nesting Roll Tables}}
  
  
Line 296: Line 365:
 
* '''[https://app.roll20.net/forum/permalink/9112320/ Overwriting Template Fields in Macros]''' - Oosh
 
* '''[https://app.roll20.net/forum/permalink/9112320/ Overwriting Template Fields in Macros]''' - Oosh
  
===Images===
 
Various ways to use or show images in macros or the chat.
 
 
* [https://app.roll20.net/forum/permalink/6814834/ Pictures and GIFs in Chat and Abilities] - Blue64
 
* [https://app.roll20.net/forum/permalink/6827714/ Monster Images in Chat] - Kirsty
 
* [https://app.roll20.net/forum/permalink/9031455/ Using Images as Links] - Oosh
 
* [https://app.roll20.net/forum/post/9209645/inserting-images-into-macros Inserting Images into Macros] -forum thread
 
  
 
===Advanced===
 
===Advanced===
  
The [https://app.roll20.net/forum/permalink/5899495/ Stupid Roll20 Tricks (and some clever ones)] contains a large amount of tricks and examples of clever uses for macros etc. that is a must to check out.  
+
{{forum|permalink/5899495/ Roll20 Tips and Tricks (Innovative Solutions to Common Problems)}} contains a large amount of tricks and examples of clever uses for macros etc. that is a must to check out.  
  
 
Here under are mentioned a limited number of the list's tricks(more could be listed or copied entirely to the wiki):
 
Here under are mentioned a limited number of the list's tricks(more could be listed or copied entirely to the wiki):
  
 
* [[Reusing Rolls]] - clever trick to reuse rolls withing the same command. Was discovered in mid-2020.
 
* [[Reusing Rolls]] - clever trick to reuse rolls withing the same command. Was discovered in mid-2020.
* [https://app.roll20.net/forum/permalink/5924364/ Macro Character Sheet] - keithcurtis — [https://app.roll20.net/forum/permalink/7605679/ More info] - gui8312 — [https://app.roll20.net/forum/permalink/6138238/ Giving Players Limited Access] - Kyle.G
+
* {{forum|permalink/9663315/ Tooltips for links, roll buttons etc.}} - RainbowEncoder |{{forum|permalink/6397574/ Tooltip Hack (older)}} - Aranador
* [https://app.roll20.net/forum/permalink/6356266/ DM whispers without breaks]
+
* {{forum|permalink/5924364/ Macro Character Sheet}} - [[keithcurtis]]
* [https://app.roll20.net/forum/permalink/8080373/ Dynamic Multitarget Roll without API] - Barakka
+
** {{forum|permalink/7605679/ More info}} - gui8312
* [https://app.roll20.net/forum/permalink/6137639/ Prefix Trick to Variably Call Attributes] - Kyle G.
+
** {{forum|permalink/6138238/ Giving Players Limited Access}} - Kyle.G
* [https://app.roll20.net/forum/permalink/8511142/ Hypertext Macro to Open a Linked Character Sheet  Hypertext Macro to Open a Linked Character Sheet] - Vince
+
* {{forum|permalink/6356266/ DM whispers without breaks}}
* [https://app.roll20.net/forum/permalink/7406810/ Use a Macro to Report on Obscure Character Abilities and Rules] - macro template for calculating/showing derivative stats that aren't listed on the sheet but can be known, such as how long a character can hold breath. by PapaWhiskey11
+
* {{forum|permalink/8080373/ Dynamic Multitarget Roll without API}} - Barakka
 +
* {{forum|permalink/6137639/ Prefix Trick to Variably Call Attributes}} - Kyle G.
 +
* {{forum|permalink/8511142/ Hypertext Macro to Open a Linked Character Sheet  Hypertext Macro to Open a Linked Character Sheet}} - [[Vince]]
 +
* {{forum|permalink/7406810/ Use a Macro to Report on Obscure Character Abilities and Rules}} - macro template for calculating/showing derivative stats that aren't listed on the sheet but can be known, such as how long a character can hold breath. by PapaWhiskey11
  
===Chat Menus===
+
====Images====
 +
Various ways to use or show images in macros or the chat.
 +
 
 +
* {{forum|permalink/6814834/ Pictures and GIFs in Chat and Abilities}} - Blue64
 +
* {{forum|permalink/6827714/ Monster Images in Chat}} - Kirsty
 +
* {{forum|permalink/9031455/ Using Images as Links}} - [[Oosh]]
 +
* {{forum|post/9209645/inserting-images-into-macros Inserting Images into Macros}}
 +
 
 +
====Chat Menus====
 
''Idea by Keith Curtis''
 
''Idea by Keith Curtis''
  
Line 332: Line 405:
 
List of token-specific stats you can target with the usual <code>@{}</code> commands, that doesn't need to rely on having a [[Link Token|character sheet linked to the token]]:
 
List of token-specific stats you can target with the usual <code>@{}</code> commands, that doesn't need to rely on having a [[Link Token|character sheet linked to the token]]:
  
* <code>bar1</code>,<code>bar2</code>,<code>bar3</code>(max values can also be used, see examples with <code>selected</code> and <code>target</code> how they differ)
+
* <code>bar1</code>,<code>bar2</code>,<code>bar3</code> ''(max values <code>@{bar1|max}</code>, <code>@{bar2|max}</code>, <code>@{bar3|max}</code>)''
 
* <code>token_name</code>
 
* <code>token_name</code>
 
* <code>token_id</code>
 
* <code>token_id</code>
 +
 +
If a character sheet is linked, and you have linked a sheet attribute to one of the bars, you can reference that stat either by targeting the token's bar, or the actual name of the attribute on the sheet.
 +
 +
{{ex}}
 +
* <code>Token **"@{selected|token_name}"** has [[@{selected|bar1}]] out of [[@{selected|bar1|max}]] HP left.</code> - displays the token name and the current/max value of bar1
 +
** token bar max values need to be referenced with <code>@{attrname|max}</code>, using <code>@{attrname_max}</code> doesn't work.
 +
* <code><nowiki>&{template:default} {{name=**Character & Token ID**}} {{Character Name=@{selected|character_name} }}  {{**Character ID**= @{selected|character_id} }} {{**Token Name**= @{selected|token_name} }} {{**Token ID**= @{selected|token_id} }} {{**Bar 1**= @{selected|bar1} / @{selected|bar1|max} }} {{**Bar 2**= @{selected|bar2} / @{selected|bar2|max} }} {{**Bar 3**= @{selected|bar3} / @{selected|bar3|max} }}</nowiki></code>
 +
** a macro that displays the token_id, token_name and token bar values, as well as the character_id & chracter_name if token is linked to a sheet.
  
 
===selected===
 
===selected===
Line 367: Line 448:
 
/roll 1d20 + @{selected|bar2|max}
 
/roll 1d20 + @{selected|bar2|max}
 
</pre>
 
</pre>
 +
 +
On token bars, you must reference max values with the <code>@{selected|bar1|max}</code> syntax, while for character attributes, both <code>@{selected|attrname|max}</code> and <code>@{selected|attrname_max}</code> works.
  
 
===target===
 
===target===
Line 373: Line 456:
 
When using [[Macros#Targeted_Token_with_a_Macro|@{target}]], you make the roll first, and then get prompted to select the target token(s), before the roll is then executed. You can target several tokens/characters in a single roll.
 
When using [[Macros#Targeted_Token_with_a_Macro|@{target}]], you make the roll first, and then get prompted to select the target token(s), before the roll is then executed. You can target several tokens/characters in a single roll.
  
<pre data-language="javascript">/roll 1d20 - @{target|strength}</pre>
+
<pre data-language="javascript">
 +
/roll @{target|bar2}d6
 +
/roll 1d20 - @{target|strength}
 +
</pre>
 
This will bring up a prompt screen for the player to select which token target they are rolling against:
 
This will bring up a prompt screen for the player to select which token target they are rolling against:
  
Line 381: Line 467:
  
 
<pre data-language="javascript">@{target|<target_name>|<attribute_name>|<optional_flags>}</pre>
 
<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.)
+
(Note that <code>target_name</code> is optional if you only have one 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:
 
So if you want to have multiple targets in your macro you can do:
Line 389: Line 475:
 
And if you want to use the max of an attribute:
 
And if you want to use the max of an attribute:
  
<pre data-language="javascript">@{target|Target1|HP|max}</pre>
+
<pre data-language="javascript">
 +
@{target|bar1|max}                                - token max values can only be referenced with "|max"
 +
@{target|HP_max}                                  - max value of HP, from the linked character sheet
 +
@{target|Target1|HP|max}                         - alternative method for the above
 +
@{target|target 1|HP_max} @{target|target 2|HP_max} - check max HP of two tokens
 +
@{target|target 1|HP|max} @{target|target 2|HP|max} - alternative method for the above
 +
</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.
 
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.
Line 401: Line 493:
 
===[[Token Actions]]===
 
===[[Token Actions]]===
 
Token Actions are specially-designated [[Macros|macros]] and [[Journal#Abilities_.28Need_Update.29|character abilities]] (with tokens [[Linking_Tokens_to_Journals|representing a character]]) which appear whenever a token is selected on the screen. They appear in a bar along the top of your screen, and the contents of the bar are context-sensitive. When you select a token, all macro token actions will be shown, as well as ability token actions for the token's linked character (if applicable).
 
Token Actions are specially-designated [[Macros|macros]] and [[Journal#Abilities_.28Need_Update.29|character abilities]] (with tokens [[Linking_Tokens_to_Journals|representing a character]]) which appear whenever a token is selected on the screen. They appear in a bar along the top of your screen, and the contents of the bar are context-sensitive. When you select a token, all macro token actions will be shown, as well as ability token actions for the token's linked character (if applicable).
 +
==Journal==
 +
main page: [[Journal#Journal_Command_Buttons|Journal Command Buttons]]
 +
 +
 +
===Character Attributes===
 +
How to reference character/Character sheet Attributes: [[Journal#Attributes]]
 +
 +
From a custom command, anywhere:
 +
<pre>
 +
/r 1d20+@{Bob|str}
 +
</pre>
 +
 +
If macro is saved to a character's A&A tab, to a token linked to a sheet, or is embedded in the chracter sheet button (code):
 +
<pre>
 +
/em makes a Strength roll of [[1d20+@{str}]]
 +
</pre>
 +
 +
===Character Abilities/Roll Buttons===
 +
 +
'''Button'''
 +
Most char sheets have roll buttons, which can be called directly with a <code>%</code>-command.
 +
 +
<pre>
 +
%{Bob|dexterity} // call the dex roll for a character named bob
 +
%{selected|dexterity} // call the dex roll for the character linked to the selected token
 +
</pre>
 +
 +
'''[[Journal#Abilities|Abilities]]'''
 +
 +
If you have saved custom Abilities to a character's A&A tab, you can call the ability with the same <code>%</code>-syntax as buttons. These are character-specific, so unless other characters have an ability with the same name, it wont work.
 +
 +
<pre>
 +
%{Bob|customability}
 +
%{selected|customability}
 +
</pre>
 +
 +
When writing an ability macro, you dont have to specify the characters name, and can call attributes directly(<code>/r 1d20+@{dex}</code>)
 +
 +
===Handout===
 +
You can add roll buttons with macros to [[Journal#Handouts|Handouts]], with the help of hyperlinks.
 +
 +
*  {{yt.be|pkDC-nP3vCE Running Commands from Handouts in Roll20}} 8min, Nick O.
 +
 +
* {{fpl|9283622/ handout link in macro}} - opens the handout in the [[Journal#External_Journal_Access|External Journal]]
  
 
==[[API]]==
 
==[[API]]==
 
{{pro only}}
 
{{pro only}}
  
'''[[API|API commands]]'''(AKA '''API calls'''), start with <code>!</code> and then the name of the API command, and then write any other parameters for the API. Some API macros can be imbedded into regular macros, such as [[ChatSetAttr]]. To use any API in macros, the specific APIs[[API#Install_API| need to be installed in the game]] for them to work. Here are some examples of API commands/macros.
+
'''[[API|API commands]]'''(AKA '''API calls'''), start with <code>!</code> and then the name of the API command, and then write any other parameters for the API. Some API macros can be embedded into regular macros, such as [[ChatSetAttr]]. To use any API in macros, the specific APIs[[API#Install_API| need to be installed in the game]] for them to work. Here are some examples of API commands/macros.
  
 
'''Example 1:'''
 
'''Example 1:'''
Line 423: Line 559:
  
 
===[[API:Chat#API_Command_Buttons|API Command Buttons]]===
 
===[[API:Chat#API_Command_Buttons|API Command Buttons]]===
 +
{{main|API:Chat#API_Command_Buttons}}
 +
 
They have simple Markdown formatting:
 
They have simple Markdown formatting:
  
Line 434: Line 572:
  
 
''Tricks:''
 
''Tricks:''
* [https://app.roll20.net/forum/permalink/6009949/ 2 column API buttons in Default Roll Template] - Bryan P
+
* {{forum|permalink/6009949/ 2 column API buttons in Default Roll Template}} - Bryan P
  
 
===Relevant API===
 
===Relevant API===
 
APIs that have lots of commands or have lot to do with dice rolling.
 
APIs that have lots of commands or have lot to do with dice rolling.
  
* [[Script:ChatSetAttr]] - can be used inline & mixed in with other macros
+
* '''[[Script:ChatSetAttr|ChatSetAttr]]''' - can be used [[inline]] & mixed in with other macros, and can edit stats, which normal macros can't
 
* [[PowerCards]] - API made to display stats in variety of way in the chat, essentially a sophisticated, API-based version of the Default Roll Template with massive amount of features. It can be used to call other API like ChatSetAttr or TokenMod
 
* [[PowerCards]] - API made to display stats in variety of way in the chat, essentially a sophisticated, API-based version of the Default Roll Template with massive amount of features. It can be used to call other API like ChatSetAttr or TokenMod
* [https://app.roll20.net/forum/permalink/9097236/ InsertArg & XRay] script that gives you a way to interact with information in the game and feed it to the chat and/or other scripts, or to build your own output on the fly.
+
* [[ScriptCards]] - Reworked version of PowerCards, with other features
* [https://app.roll20.net/forum/permalink/4225825/ TokenMod] API that can edit any info on tokens. If token's are linked to a character, the changes to token bars extends to the character sheet.
+
* [[APILogic]] -- Gives If/ElseIf/Else Processing, Inline Math operations, and Variable Muling to Other Scripts | {{forum|permalink/9771314/ APILogic}}
* [https://app.roll20.net/forum/post/9441420/combatmaster-2-dot-0&pagenum=1 Combat Master] Manages many facets of combat. It allows for API and Macro calls at various timing points (beginning of each round, beginning of each turn, when a condition is assigned, when a condition is removed).  
+
* {{fpl|9817678/ SelectManager}} - help other API with properly sharing token selection between other APIs. Often API that can call other APIs doesn't share what tokens are currently selected.
* [https://app.roll20.net/forum/permalink/8458497/ Token Action Maker]
+
* {{forum|permalink/9770117/ libInline}} - provides an easy interface for inlinerolls
* '''Rollable Table Macros''' - a simple script that gets an item from a rollable table and enters its name as a chat message rather than showing it as a rollable table result
+
* {{forum|permalink/9097236/ InsertArg & XRay}} script that gives you a way to interact with information in the game and feed it to the chat and/or other scripts, or to build your own output on the fly.
 +
* [[TokenMod]] – API that can edit any info on tokens. If token's are linked to a character, the changes to token bars extends to the character sheet.
 +
* {{forum|permalink/9441420/ CombatMaster}} Manages many facets of combat. It allows for API and Macro calls at various timing points (beginning of each round, beginning of each turn, when a condition is assigned, when a condition is removed).  
 +
* {{forum|permalink/8458497/ Token Action Maker}}
 +
* [[Script:Rollable_Table_Macros|Rollable Table Macros]] -- a simple script that gets an item from a [[Roll Table|rollable tables]] and enters its name as a chat message rather than showing it as a rollable table result
 
* [[Script:Star Wars: Fantasy Flight Games - Dice Roller]] - API for rolling the custom dice system used in the game
 
* [[Script:Star Wars: Fantasy Flight Games - Dice Roller]] - API for rolling the custom dice system used in the game
* '''It's A Trap!''' Can be used to create a Trap that can automate rolls related to the trap, both for the trap and for the character(such as saves). There exists a generic one, as well as a number of system-specific version designed with popular sheets in mind(D&D5e, Pathfinder 1E)
+
* [[Script:It's a Trap|It's a Trap!]] Can be used to create a Trap that can automate rolls related to the trap, both for the trap and for the character(such as saves). There exists a generic one, as well as a number of system-specific version designed with popular sheets in mind(D&D5e, Pathfinder 1E)
 +
* '''[[API:Script Index]]''' partial list of Roll20 APIs available
  
 
==Character Sheet Creation==
 
==Character Sheet Creation==
Line 479: Line 622:
 
** [[Tokens]]
 
** [[Tokens]]
 
** [[API]]''(Pro Only)'' - API commands can be used in the <span style="font-family:Pictos;">q</span>Text Chat
 
** [[API]]''(Pro Only)'' - API commands can be used in the <span style="font-family:Pictos;">q</span>Text Chat
 +
* [[Forum Tricks]]
 +
** [[Macro Sheet]]
  
 
==Other Guides==
 
==Other Guides==
Line 487: Line 632:
  
 
==TODO==
 
==TODO==
* add image examples of macros used, input + output
+
* add image examples of every macros used, input + output
 
* at least one example for each mentioned concept
 
* at least one example for each mentioned concept
 
* Roll Template examples
 
* Roll Template examples
 
* List rest of the examples from "Stupid Tricks" thread
 
* List rest of the examples from "Stupid Tricks" thread
 +
* copy tips from [[Macros/Pathfinder Examples]]
 +
 +
=See Also=
 +
* {{forum|permalink/5899495/ Roll20 Tips and Tricks (Innovative Solutions to Common Problems)}} - Well maintained List of good Roll20 Tricks.
 +
* [[Macro Character Sheet]] - how to easily move all your macros between games
 +
* {{Text Chat}}
 +
* {{Collections}}
 +
** [[Macros]]
 +
** [[Roll Tables]]
 +
** [[Cards]]
 +
* [[Building Character Sheets]] - {{Pro}}
 +
* [[API]] - {{Pro}}
 +
* [[Campaign Management]]
 +
** [[Link Token|Link Token to Sheet]]
 +
** [[Add Character Sheet]]
 +
** [[GM]] & [[Player]] tools & limits
 +
* [[Browser#Stylus|Stylus Plugin]] - customize the looks of Roll20 for yourself
 
<br>
 
<br>
 
<br>
 
<br>

Latest revision as of 14:37, 17 June 2021

This is meant to serve as a comprehensive guide & starting point for figuring out how the q Text Chat, Dice Rolling, Macros and related things work and interact with each-other, to find the documentation for each, and to list everything you can write/make appear in the q Text Chat.

Macro Creation

Advanced

Misc.

This is both for Players and Gamemasters who are just writing their own custom rolls or macros to be used in their game, as well as those who build Character Sheets and are creating/editing Roll Buttons for their sheets.

Contents

[edit] Text Chat

Basic-roll-example.png

The q Text Chat-page shows the basic commands that can be used in the chat, such as /roll(/r) for making simple rolls, /em for emoting actions, /w for whispering to someone, and /gmroll( /gr) for sending simple rolls to the GM.

You can write in the q Text Chat normal text without using any commands like /r.

See Chat Commands-sections for examples, or the

Normal macros can't edit stats, only read them. To edit stats with a command, you need to use API in some form.

[edit] Formatting

You can use common Markdown to format you text, and to even create hyperlinks in text shown in the chat.

If you hyperlink to to a i Compendium page, it will open up inside Roll20 when clicked.

Tips & Examples:

[edit] Markdown

Markdown is available to let you bold, italic, bold-italic, create a hyperlinks, or include even an image in your macros and text as they appear in the q Text Chat.

* italics *
** bold **
*** bold italics ***
[Dodge](https://roll20.net/compendium/dnd5e/Rules:Actions%20in%20Combat#h-Dodge)

Alternative to adding the markdown into the macros, you can sometimes add the markdown to your #Character Attributes, so you can have a universal macro, and make individual adjustment to to how you want each output to look like.


Example:

/em his **@{bob|height}}** tall, and can be described as: @{bob|description}}.

[edit] HTML replacement

When creating some complicated/sophisticated macros, usually involving nesting, you will need to use HTML entities in parts of the code to trick the Roll20 system to make it behave like you want, or some advanced tricks won't work.

Here are some HTML entities used in advanced Roll20 macros(see List of HMTL Entities for full list):

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

Example use: Here is a macro that won't work:

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

Here is how you use HTML entities in it to replace certain characters to make it work:

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

Advanced Nesting example:

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

HTML entities contains a longer list of all the existing HTML entities, of which only few are used/needed in Roll20 context, but might be useful to check if the above table isn't enough.

See Advanced Usage for Roll Queries for more examples.

[edit] Chat Commands

Main Page: q Text Chat

  • /r, /roll - for making simple rolls. Ex. /r 1d20+5
  • /w - for whispering a message to a person so only they see it. Ex. /w Alice Does the goblin know the paladin?, /w "Bob Smith" Where's the money pouch?!
  • /gr, /gmroll - to make rolls only to the GM. Ex. /gr 2d6+3
  • /em to emote as the character selected. Ex. /em takes out one of his throwing daggers and brandishes it threateningly.
  • /ooc - to message something that is Out-of-character Ex. /ooc I could really use another coffee right now.
  • /talktomyself - To turn off your chat display for all others, including the GM and the chat archive recording. Use it again to turn it back on
  • /fx - used for creating visual effects Ex. /fx beam-acid @{target|Caster|token_id} @{target|Foe|token_id}
  • GM-exclusive:
    • /desc to describe the situation Ex. The old house begins to creak and moan...
    • /as, /emas emote as any character, better version of /em Ex. /as "Sir Bearington" I'm going to eat you for breakfast.


Beyond using the various Roll Commands shown on the q Text Chat-page, here are some other examples of what you can write in the q Text Chat:

  • Macros - Start with #, and start typing the macro name, and a list of your macros will be displayed.
    • Example: writing #testmacro in the chat will roll the macro with that name
  • Roll Templates - &{template:name-of-roll-template} {{sectionname(optional)=content of roll template}}.
    • The Default Roll Template is available in any games, other templates are tied to specific Character Sheet Templates. (E.g. you can only access the specific &{template:simple} when you have D&D 5E by Roll20-sheet in the game).
    • Example: &{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{damage=[[2d6]]}}
    • This will generate a roll template using the default template, displaying "Test Attack" in the purple title, then on a new row the result of 1d20 roll, and on the third row the 2d6 roll
  • Character Abilities/Character Sheet Button - %{character name|ability or roll button name}
    • Example 1; writing %{Sam Bobbins|initiative} in the chat, will work if there exists a Character with that name, who have a Character Ability/Character Sheet Roll Button by that name
    • Example 2: selecting a Token on the map, and then writing %{selected|initiative} in the chat, will work if the token is linked to a character sheet that has an Ability or Roll button with that name.
  • API commands(available in games hosted by a pro user), - Start with ! to call the API command, and then write and parameters it can take
    • Example: writing !MassInit in the chat will trigger an API that uses MassInit as a keyword.

[edit] Dice Syntax

The Dice Reference page shows how the syntax for the Roll20 dice rolling works, and all the advanced alternatives you can use, such as rolling Fate Dice, or counting successes rather than the sum of the rolls. It also details when the green & red "Critical Success/Failure"-highlights are shown.

Tricks:

[edit] Inline Rolls

Main Page: Inline Rolls

The output of a default template that shows an inline roll(yellow box)

If you use simple roll commands/macros like /roll 2d10+5, the whole command is a dice roll. But when you use Roll Template, or have embedded dice rolls with other commands like /em, you use inline rolls, where you wrap [[ ]] around the calculation for it to be processed. The result of "Normal" dice rolls is shown as individual dice images displaying the result on each dice separately, along with the total result.

Inline rolls are just like regular rolls, with the following exceptions:

  • You can use them in any chat message, not just a roll. For example, you can do a regular chat message, an emote(/em), or a whisper(/w), with an inline roll included.
  • They are evaluated completely before any (/roll) commands, so you can use them as "random variables" in your rolls.
  • You will only see the result of the total roll, and you can hover over the result to see the individual dice rolls.
  • Highlights
    • If an inline roll contains a critical success, it will be highlighted with a green box.
    • If there's a critical failure, it's highlighted in red.
    • If it has both (because there was more than one roll), it's in blue.

Also when you mouse-over the inline roll to see the details of the roll, it'll show red and green highlights for the rolls themselves for crits/fumbles.

With inline rolls, the numerical end result is shown in a (yellow) box, and if you hover you mouse over the result, you see the full equation of the roll, along with the result of each.


Example:

/em swings their sword and does [[2d6+2]] damage.
&{template:default} {{name=Test Attack}} {{attack=[[1d20+5]]}}

[edit] Inline Labels

If you want to include additional comments before the end of the roll (we call them "inline labels"), use square brackets. For example, /roll 2d10+5[Fire Damage] + 3d6[Ice Damage]. Inline labels works both with "normal" rolls and inline rolls.

When these comments are applied directly after a die roll they show up as tool-tips on the dice:

/roll 2d10+5[Fire Damage] + 3d6[Ice Damage]

This is especially useful if a roll contains multiple variables and you want to look up what number comes from what attribute.

You can even use sheet attributes in labels. Especially useful if the name of the stat can be customized by the user, so the corresponding label should change to reflect the name.
Example:

/r @{selected|customskill1}d6[@{selected|customskill1name}] + @{selected|str}[str]

[edit] Order of Operations

While the Roll20 dice engine does support basic math and functions such as floor() and ceil(), it is first and foremost a dice engine, and so it has its own order of operations. This means that putting parentheses inside of your dice formula will not always affect the outcome of the roll (for example, you can't force a variable to be interpreted before a macro). Here is the Roll20 Order of Operations:

  1. Abilities are expanded (meaning the definition of the ability is placed in the formula anywhere that ability appears; e.g. %{character name|ability_name} becomes /r 1d4).
  2. Macros are expanded (e.g. #macro-name becomes /r 1d4).
  3. Attribute calls are resolved. (e.g. @{attribute_name} becomes 4)
  4. Steps 1-3 are repeated up to 99 levels deep, or there are no longer any expansions required.
  5. Roll queries are executed up to 99 levels deep (the player making the roll is asked to provide a value for each query, and that value is substituted in where the roll query appears in the formula). Html entities within roll queries are parsed once after each roll query (e.g. } becomes }, but &#125; becomes })
  6. Inline rolls are executed, starting with the most deeply nested inline roll working upward. The overall result of the inline roll is substituted in place where it appeared in the formula.
  7. The remaining roll is executed: first, dice are rolled for any dice (e.g. 2d6 is rolled; including any special dice such as dropped or exploding), then the result of that roll is substituted into the formula.
  8. Mathematical functions like floor() and ceil() are executed.
  9. The entire remaining formula is evaluated, including observing proper Math Order of Operations (parentheses first, then multiplication/division, then addition/subtraction).
  10. Html entities/replacements are processed once more
  11. The message is sent to q Text Chat as well as the API sandbox.


Thank you to Scott C. for additional testing in this matter!

[edit] Macros

Main Article: Macros

The Macros page lists all the the other kind of options for modifying rolls that isn't covered by the Dice Reference-page. Also check the Stupid Roll20 Tricks (and some clever ones)-thread for Advanced and clever tricks that might not be linked on this page yet.

Features include:

[edit] Roll Queries

Sometimes you may have a roll (or a macro) which you want to change every time it is rolled. For example, you may want to roll a variable number of dice, or add a different modifier onto the roll each time you perform the action.

Roll Queries allow you to prompt whoever is performing the roll to fill in a value when the roll is made. The syntax for a roll query is:

?{Prompt Message}
//Example:
/roll ?{Number of Dice}d20
//You can also include a default value:
/roll ?{Number of Dice|1}d20
// 1 would be the default
[edit] Drop-down Queries

You can specify a list of options which can be presented to the player, rather than only a free-form text field. Be mindful about if/when you add spaces inside a Roll Query, as having/not having them changes how things work. If the content of the dropdown query includes chracters like |,{,}, and,, you will likely need to use HTML replacement for them to make it work.

Syntax:

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

Example:

/em attempts ?{Difficulty level|an Easy|a Moderate|a Hard} task.

You can also specify a separate label for each option, instead of displaying the Option itself in the dropdown.

?{Name of Query|Label 1,Option1|Label 2,Option2}

This can be useful if the Option itself is long, or if it's better to describe what the options represent, rather than show exactly what they are.

Example:

/r d20+?{Stat:|Strength,2|Dexterity,1}

If you place the drop-down query at the start of a macro, make sure there is no space after the ,, as this will break any macro or command inside it.

?{Attack|Just roll,/r d20+5|Description,/em swings the sword with a result of [[d20+5]]}
non-functional version
?{Attack|Just roll, /r d20+5|Description, /em swings the sword with a result of [[d20+5]]}

You may also split up Roll Queries on multiple rows to make the code more readable. Extra line breaks in code isn't generally a good idea, and could be good to avoid to not create errors.

/roll 1d20 + ?{Choose an Attack|
   Melee,3[STR] |
   Ranged,2[DEX] |
   Magic,1[INT] }

If you're listing macros in your roll query, you must have a space after the macro name, so Roll20 knows the name ends inside the query.In the below example, the three rolls have been saved into macros on the l Collections-tab which then can be referenced in the macro.

?{Choose an Attack|
   Melee,#str |
   Ranged,#dex |
   Magic,#int }


[edit] Nesting

To some degree, you can nest abilities, macros and queries.

If you start nesting queries too much, you need to start using HTML replacement keep the macros working. Once saved, these macros shouldn't be opened(if saved in the l Collections-tab's Macro section, as opening a macro that have HTML replacement will result in those being converted into regular things, breaking your macro.

  • Drop down Nester google sheet that generates the HTML replacement code needed. by Scott C.
  • HTML entities contains a longer list of all the existing HTML replacement code, of which only few are used/needed in Roll20 context.

[edit] Initiative

Main section: Rolling for Initiative

To send a roll result directly to the t Turn Tracker, first, select the Token you wish to roll initiative for, and then make a roll that includes the &{tracker}-flag. You can also increase/decrease initiative by using &{tracker:+}/&{tracker:-}.
Example:

  • /roll 1d20 + 5 &{tracker}
  • &{template:default} {{name=Initiative}} {{Roll=[[1d20+4 &{tracker}]]}}
  • /roll 1d4 + 1 &{tracker:+} (increases the initiative by 1d4+1)
  • /roll 2 &{tracker:-} (decreases the initiative by a flat 2)
  • [[5 &{tracker:-}]] (inline roll that decreases the initiative by a flat 2)

See also: Using Cards for Initiative Order

Referencing values on the turn tracker: by calling @{Tracker|character_id} @{Tracker|character_name}, you can check what values are on the turn tracker. ex. Bobs initiative is @{tracker|Bob}.

Tricks using the t Turn Tracker:

[edit] Chat Buttons

There are two types of buttons you can create in the Text Chat to be included in a macro/dicerolling result.

Ability Command Buttons

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

Their syntax is as follows:

[Label](~<keyword>|<ability name>)
[Dex Check](~Bob|dexterity)
[Dex Check](~selected|dexterity_save)
[Dex Check](~selected|repeating_attack_$0_attack)

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>)
[Dex Check](~dexterity)

API Command buttons

API Command buttons do not actually use the API—anyone can make and use them. The Chat Menus trick by Keith, uses utilizes them to great length.

[edit] Errors

If there is a mistake in the macro, or an attribute is missing, the roll might not work at all and only send and error message in the chat.

In some cases you can suppress error message and the roll will try to do what it can while removing the error message.

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


[edit] Roll Table

If you have Roll Tables on your l Collections-tab, they can be used in rolls & macros.

Example1:

Let's assume there exist a roll table with the name fumble.

You can roll a table directly in the chat input, or in a macro, simply as 1t[fumble].

Example 2: To roll your "crit-failure" table two time, you would enter /roll 2t[crit-failure]. You can change 2 to whatever number you would like. However, this currently does not work with inline rolls.

You can also roll a table inline in chat or a macro by wrapping it in double square brackets like this [[1t[table-name]]]. Currently, any number beyond 1 does not display for the inline roll, the results are show on mouseover though.


[edit] Roll Templates

Main Page: Roll Templates

You can access the Default Roll template in any game, to structure your results in the Text Chat. You simply write the template in the chat/macro( and don't use the /roll).

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

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


Many character sheets have built in Roll Templates that can only be used with those specific character sheets.

Tricks:

  • Use images with Default Roll Template: If you want to dress up your default template, you can stuff an image in the name portion instead of just text
    • Example: &{template:default}{{name=[x](YOUR_IMAGE_URL#.png)}}{{test=foo}}
  • Overwriting Template Fields in Macros - Oosh


[edit] Advanced

contains a large amount of tricks and examples of clever uses for macros etc. that is a must to check out.

Here under are mentioned a limited number of the list's tricks(more could be listed or copied entirely to the wiki):

[edit] Images

Various ways to use or show images in macros or the chat.

[edit] Chat Menus

Idea by Keith Curtis

Creating a Chat Menus for your macros is a great shortcut to have access to many buttons by only calling the chat menu macro.

[edit] Token

Main Section: Macros#Token

You can target the stats of tokens(and the stats of a linked character sheet) by two methods, using either @{selected}, or @{target}.


[edit] Variables

List of token-specific stats you can target with the usual @{} commands, that doesn't need to rely on having a character sheet linked to the token:

  • bar1,bar2,bar3 (max values @{bar1|max}, @{bar2|max}, @{bar3|max})
  • token_name
  • token_id

If a character sheet is linked, and you have linked a sheet attribute to one of the bars, you can reference that stat either by targeting the token's bar, or the actual name of the attribute on the sheet.


Example:

  • Token **"@{selected|token_name}"** has [[@{selected|bar1}]] out of [[@{selected|bar1|max}]] HP left. - displays the token name and the current/max value of bar1
    • token bar max values need to be referenced with @{attrname|max}, using @{attrname_max} doesn't work.
  • &{template:default} {{name=**Character & Token ID**}} {{Character Name=@{selected|character_name} }} {{**Character ID**= @{selected|character_id} }} {{**Token Name**= @{selected|token_name} }} {{**Token ID**= @{selected|token_id} }} {{**Bar 1**= @{selected|bar1} / @{selected|bar1|max} }} {{**Bar 2**= @{selected|bar2} / @{selected|bar2|max} }} {{**Bar 3**= @{selected|bar3} / @{selected|bar3|max} }}
    • a macro that displays the token_id, token_name and token bar values, as well as the character_id & chracter_name if token is linked to a sheet.

[edit] selected

Main page: @{selected}

When using @{selected}, you need to first select the token you want to use, before making the roll, and you can only have one token using this method.

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

/roll 1d20 + @{selected|bar1}

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:

/roll 1d20 + @{selected|Intelligence}

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

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

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

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

On token bars, you must reference max values with the @{selected|bar1|max} syntax, while for character attributes, both @{selected|attrname|max} and @{selected|attrname_max} works.

[edit] target

Main page: @{target},

When using @{target}, you make the roll first, and then get prompted to select the target token(s), before the roll is then executed. You can target several tokens/characters in a single roll.

/roll @{target|bar2}d6
/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

The full syntax for the target variable is:

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

(Note that target_name is optional if you only have one 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|bar1|max}                                - token max values can only be referenced with "|max"
@{target|HP_max}                                  - max value of HP, from the linked character sheet
@{target|Target1|HP|max}                          - alternative method for the above
@{target|target 1|HP_max} @{target|target 2|HP_max} - check max HP of two tokens
@{target|target 1|HP|max} @{target|target 2|HP|max} - alternative method for the above

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 Actions

Token Actions are specially-designated macros and character abilities (with tokens representing a character) which appear whenever a token is selected on the screen. They appear in a bar along the top of your screen, and the contents of the bar are context-sensitive. When you select a token, all macro token actions will be shown, as well as ability token actions for the token's linked character (if applicable).

[edit] Journal

main page: Journal Command Buttons


[edit] Character Attributes

How to reference character/Character sheet Attributes: Journal#Attributes

From a custom command, anywhere:

/r 1d20+@{Bob|str}

If macro is saved to a character's A&A tab, to a token linked to a sheet, or is embedded in the chracter sheet button (code):

/em makes a Strength roll of [[1d20+@{str}]]

[edit] Character Abilities/Roll Buttons

Button Most char sheets have roll buttons, which can be called directly with a %-command.

%{Bob|dexterity} // call the dex roll for a character named bob
%{selected|dexterity} // call the dex roll for the character linked to the selected token

Abilities

If you have saved custom Abilities to a character's A&A tab, you can call the ability with the same %-syntax as buttons. These are character-specific, so unless other characters have an ability with the same name, it wont work.

%{Bob|customability}
%{selected|customability}

When writing an ability macro, you dont have to specify the characters name, and can call attributes directly(/r 1d20+@{dex})

[edit] Handout

You can add roll buttons with macros to Handouts, with the help of hyperlinks.

[edit] API

API commands(AKA API calls), start with ! and then the name of the API command, and then write any other parameters for the API. Some API macros can be embedded into regular macros, such as ChatSetAttr. To use any API in macros, the specific APIs need to be installed in the game for them to work. Here are some examples of API commands/macros.

Example 1: writing !wd [[4d6+2]] in the chat will trigger the Script:Wild Dice script to make a custom roll output, rolling 3 normal d6 dice, and one Wild Die, presenting it in a table. If the Wild Die comes up as a "1", it, and the value of the highest dice is removed form the roll total. This is not something that can be done with macros alone, which is why this API was created.

Wild-Dice-result-v3-4.png

Example 2:

writing !group-init in the chat will trigger the GroupInitiative(must be installed) API that uses group-init as a keyword. This particular API command would roll initiative order for all selected tokens, if the API is configured to know what stats to roll.

Example 3:

writing &{template:default} {{name=Cthulhu}} !modattr --silent --charid @{target|character\_id} --sanity|-{{Sanity damage=[[2d10+2]]}} --corruption|{{Corruption=Corruption increases by [[1]]}}!!! {{description=Text}} in the chat, and selecting a Token on the map, will decrease sanity by 2d10+2 and increase corruption by 1 for the character selected.

This is the ChatSetAttr API, which can be used standalone with the !modattr command, but more notably, can be incorporated into regular macros, resulting in you being able to both make rolls and have the result change the stats.

[edit] API Command Buttons

Main Page: API:Chat#API_Command_Buttons

They have simple Markdown formatting:

[Attack Roll](!attackroll)

You can also send them into the chat for others to use, but them needs to use HTML Replacement like with Nesting:

[Attack Roll](!attackroll &#64;{target|token_id} &#91;[1d6+&#63;{Bonus|0}]&#93;)

API Command buttons do not actually use the API — anyone can make and use them. The Chat Menus trick by Keith, uses utilizes them to great length.

Tricks:

[edit] Relevant API

APIs that have lots of commands or have lot to do with dice rolling.

  • ChatSetAttr - can be used inline & mixed in with other macros, and can edit stats, which normal macros can't
  • PowerCards - API made to display stats in variety of way in the chat, essentially a sophisticated, API-based version of the Default Roll Template with massive amount of features. It can be used to call other API like ChatSetAttr or TokenMod
  • ScriptCards - Reworked version of PowerCards, with other features
  • APILogic -- Gives If/ElseIf/Else Processing, Inline Math operations, and Variable Muling to Other Scripts |
  • - help other API with properly sharing token selection between other APIs. Often API that can call other APIs doesn't share what tokens are currently selected.
  • - provides an easy interface for inlinerolls
  • script that gives you a way to interact with information in the game and feed it to the chat and/or other scripts, or to build your own output on the fly.
  • TokenMod – API that can edit any info on tokens. If token's are linked to a character, the changes to token bars extends to the character sheet.
  • Manages many facets of combat. It allows for API and Macro calls at various timing points (beginning of each round, beginning of each turn, when a condition is assigned, when a condition is removed).
  • Rollable Table Macros -- a simple script that gets an item from a rollable tables and enters its name as a chat message rather than showing it as a rollable table result
  • Script:Star Wars: Fantasy Flight Games - Dice Roller - API for rolling the custom dice system used in the game
  • It's a Trap! Can be used to create a Trap that can automate rolls related to the trap, both for the trap and for the character(such as saves). There exists a generic one, as well as a number of system-specific version designed with popular sheets in mind(D&D5e, Pathfinder 1E)
  • API:Script Index partial list of Roll20 APIs available

[edit] Character Sheet Creation

Info and links to things that are only relevant or usable for when you're Building/Editing Character Sheets. Consult the rest of the guide for general details.

[edit] Roll Button

The rest of this guide will help in creating more complicated macros, but the main Button#Roll_Button-page have some concrete examples of how macros are implemented in character sheets.

[edit] Sheetworkers

With the info from Macros, fairly complex outputs to the q Text Chat can be made, but to be able to construct complex and dynamic results based on various factors on your character sheet, you will need to use JavaScript to write Sheet Worker Scripts that modify & construct your roll output dynamically.

[edit] Roll Template

When you create/edit a character sheet, you can make your own Roll Templates to make your roll output look like you want, and to do some conditional things such as only showing some sections in case of a critical roll in another sections.

See Creating Roll Templates for how to make your own.

Helper_Functions describes what functions you can build into your sheets.

[edit] Related Pages

  • Complete Guide to Macros & Rolls‎
    • q Text Chat - where the roll results appear, & info on the common chat commands
    • Dice Reference - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
    • Macros - How to create macros, and other info on how the Roll20 qText Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
    • Roll Templates - a method of formatting roll results in the chat, with some extra functions
    • Tokens
    • API(Pro Only) - API commands can be used in the qText Chat
  • Forum Tricks

[edit] Other Guides

[edit] Creating Macros in Roll20(Nick Olivo) YT

Creating Macros in Roll20 (Nick Olivo)

[edit] TODO

  • add image examples of every macros used, input + output
  • at least one example for each mentioned concept
  • Roll Template examples
  • List rest of the examples from "Stupid Tricks" thread
  • copy tips from Macros/Pathfinder Examples

[edit] See Also