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.

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

Nesting

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

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;
*(asterisk)	&#42;
!	&#33;
"(doublequote)	&#34;
#	&#35;
-(hyphen)	&#45;
@	&#64;

Nesting Queries

Nesting Macros

Macros can be nested inside each other, which gives the ability to combine macros, and call multiple macros with a single action. To nest a macro, simply include the name of the macro you wish to call on its own line inside your macro.

Example

In this example, we'll have three macros: #damage, #attack, and #both

Macro #damage

/roll 1d4+11

Macro #attack:

/roll 1d20+9

Macro #both:

#attack
#damage

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.

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.

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

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

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.