Revision as of 08:32, 19 December 2022

Page Updated:   2022-12-19

Go to Roll Query for the full documentation on all types types of nesting

Main Page: Roll Queries & Nesting

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

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

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

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

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

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

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

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

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

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}

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.

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.

Roll Query Troubleshooting: Collections Macros

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

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

Roll Query Troubleshooting: Nesting Queries

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:

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