Latest revision as of 16:07, 30 November 2021

Page Updated:   2021-11-30

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

You can use Roll Queries in rolls, macros, abilities, emotes, whispers -- pretty much anywhere in the app. Note that if you use the same exact wording for a Query, Roll20 will only ask for the value the first time it's encountered in the roll. So in this example:

/roll 1d20 + ?{Bonus1} vs ?{MinToSucceed} + ?{Bonus1}

Roll20 will ask for "Bonus1" only once and use it in both places.

[edit] Dropdown

See also: Macros#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/number field in your Roll Query.

Here's the syntax:

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

You can also specify a Separate label for each value, instead of directly showing the values as options:

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

Examples

Dropdown Query without labels

r/ ?{How many dice?|1|2|4|8}d6

Attack Dropdown

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

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] Nesting

You can nest things inside each-other, but it can get complicated.

[edit] HTML Entities

When creating some complicated 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/Escape Characters that are commonly useful to escape when creating advanced Roll20 macros. See HTML Entities or special character for more:

|, }, and , are the most common character that need to be replaced in nested macros.

Character	Replacement
| (pipe)	|, (|)
,	,, (,)
{	{, ({)
}	}, (})
&	&, (&)
space	 , ( )
=	=, (=)
_	_, (_)
(	(, (()
)	), ())
[	[, ([)
]	], (])
<	&#60;, (&lt;)
>	&#62;, (&gt;)
`(backtick, grave accent)	&#96;, (&grave;)
*(asterisk)	&#42;, (&ast;)
!	&#33;, (&excl;)
"(doublequote)	&#34;, (&quot;)
#	&#35;, (&num;)
-(hyphen)	&#45;, (&dash;)
@	&#64;, (&commat;)
%	&#37;, (&percnt;)

[edit] Nesting Queries

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} |
   DEX,/roll 1d20 + @{DEX} + ?{Bonus} |
   CON,/roll 1d20 + @{CON} + ?{Bonus} }

[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|token_name}.
• 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}
Ranged-attack: /roll 1d20+ @{DEX} + ?{Bonus|0}
Psychic-attack: /roll 1d20+ @{WIS} + ?{Bonus|0}

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|0} |
   Ranged,/roll 1d20+ @{DEX} + ?{Bonus|0} |
   Psychic,/roll 1d20+ @{WIS} + ?{Bonus|0} }

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:

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

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|
      Label 1A,?{value1A|
         Label 1Ai, value1Ai |
         Label 1Aii, value1Aii
      } |
      
      Label 1B,?{value1B|
         Label 1Bi, value1Bi |
         Label 1Bii, value1Bii
      }
   } |

   Label 2,?{value2|value2} 
}

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

• D&D 5E Macros
• Pathfinder macros
• Stargate macros
• Star Wars D6 Macros
• Cypher system macros
• Chat Menus
• Category:Macros

[edit] Coming Update: Nested Query Improvement

Now on Dev Server: Roll Query Improvements! July 20th, 2021

In the near future, some, if not all, character substitutions might become redundant, when roll20 improves nested Roll Query handling in macros.

Now on the Dev Server(

Pro

^info-users) for testing, improved roll query parsing!

Recently, an update to our character sheet code broke a workaround that some sheets were using to implement nested roll queries. Rather than fixing this workaround, we did a little extra work to properly support nested queries. Now, you should be able to nest roll queries inside of each other without needing to use any character codes.