Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools


From Roll20 Wiki

Revision as of 09:14, 3 March 2022 by Andreas J. (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
API ScriptAuthor: Henning K
Version: 1.1
Last Modified: 2020-01-04
Code: MetaMacros
Dependencies: None
Conflicts: None

This script extends the Roll20 macro "language" by enabling:

  • comments // like this one
  • multi-line commands, indicated by \ at end of line
  • textual inclusion of other macros using $include macroname
  • textual substitution macros like $attack(hit,dam) = /me hits AC [[1d20+{hit}]] for [[1d8+{dam}]] damage

Macros written in this extended format can be cross-compiled into standard Roll20 macros for execution.

Note that the term macro in the Roll20 context refers to scripts containing multiple commands. We use the term meta-macro to refer to C-style macros (i.e. textual substitution rules).



The syntax of the meta-macro language used in macros to be compiled is detailed below.


Whenever two forward-slashes // are encountered, the remainder of the line is treated as a comment and stripped.

Multi-line commands

Whenever a backslash \ is encountered at the end of a line, the backslash will be stripped and the line will be concatenated with the following line.

Including macros

The $include macroname command (which must appear on a line of its own) will cause the content of the macro macroname to be included in the current macro, in place of the $include command. An exception to this is that if a macro has previously been included, it won't be included again (this prevents infinite circular includes).


Meta-macro definitions take the format $name(param_0, ..., param_n) = body where name, param_0 ... param_n are identifiers, i.e., non-empty strings consisting of alpha-numberic characters and/or _. For meta-macros without any parameters, the ( brackets ) can be omitted.

After a meta-macro has been defined, any occurrance of $name(arg_0, ..., arg_n) will be replaced with the body of the meta-macro definition. Here any occurance of {param_0} ... {param_n} in body will be replaced with arg_0 ... arg_n, respectively. If arg_0 ... arg_n contain any meta-macro invocations, these will be resolved first. If the number of arguments does not match the number of parameters in the meta-macro definition, missing arguments will be treated as the empty string, while extra arguments will be discarded. For meta-macro invocations without any arguments, the ( brackets ) can be omitted.

If the body in a meta-macro definition contains any meta-macro invocations, these will be resolved at the time of definition (this prevents infinite circular resolution). As a result the order of meta-macro definitions matters:

$attack = [[1d20+$bab]]
$bab = 5
/me hits AC $attack
will compile into
/me hits AC [[1d20+$bab]]
as $bab was undefined at the time $attack was defined.

Numerical evaluation (since 1.1)

When using the := operator in a meta-macro definition, the body will be evaluated numerically. Supports ( brackets ), operators +, -, * and /, and functions ceil and floor. Evaluation takes place after substitution, so care must be taken about operator precedence as usual:

$pow = 1 + floor(10/4)
$dam := 2 * $pow

will first substitute the body of $dam to 2 * 1 + floor(10/4) and then evaluate it to 4.

Script Use

Note that all compilation will replace any existing content of the target macro.

Compile a specific source macro into a target macro

The !compile sourceMacro targetMacro command will compile sourceMacro into targetMacro.

Compile a specific source macro

The !compile sourceMacro command will compile sourceMacro into _sourceMacro_.

Compile all source macros

The !compile all command will compile all macros which (1) do not start with _, and (2) contain extension-specific code.

To avoid unnecessary compilation of include files, it is recommended to start their name with _, e.g. _inc_common_macros.


v1.0 (2018-09-26)

  • Release

v1.1 (2020-01-04)

  • Numerical evaluation