Roll20 equations let you compute values dynamically inside character sheets, macros, and API scripts by evaluating mathematical expressions and logical rules. This guide explains the core syntax, operator behavior, and pattern-based handling of numeric, boolean, and string results so you can build reliable computations and reduce manual entry. You will learn how to reference attributes, use conditional logic, format output, and debug common errors that arise when parentheses, operator precedence, or data types differ from expectations.
Core Syntax of Roll20 Equations
At the simplest level, a Roll20 equation is a text string that the platform evaluates into a number, text, or boolean. Basic arithmetic uses standard symbols such as + for addition, - for subtraction, * for multiplication, and / for division. Supported functions include abs, floor, ceil, round, max, min, if, pow, sqrt, and logical operators such as && and ||. Expressions are typically wrapped in %{...} in sheet buttons or macro commands, but syntax and scoping differ between character sheet attributes and API scripts. Understanding how numeric types, string types, and boolean types interact is essential to avoid type mismatch and silent miscalculations.
Operands and Operators
Operands can be literal numbers, attribute references such as @{character_name|attr}, or results from nested functions. Operators follow conventional precedence rules, where multiplication and division bind more tightly than addition and subtraction. Explicit parentheses override default precedence and help prevent ambiguity, especially in complex formulas. You also have access to comparison operators (==, !=, , >=) and logical combinators to build conditions that return true or false.
Conditional Logic and the If Function
The if function is a workhorse for building adaptive calculations. It typically follows the pattern if(condition, value_if_true, value_if_false), enabling you to select outputs based on thresholds, health states, or roll results. You can nest if statements or combine them with logical operators to handle multiway branching, but readability often improves when complex decisions are split across helper attributes or discrete steps.
Practical Examples and Common Patterns
Simple arithmetic is straightforward: %{10 + 5 * 2} evaluates to 20 because multiplication is performed first. Using parentheses, %{ (10 + 5) * 2 } evaluates to 30. Conditional damage calculations are common, such as %{ max(0, HP_CURRENT - 10) } to ensure values do not drop below zero. You can also combine numeric results with text using the & operator, for example %{ HP_CURRENT + &{HP_MAX} } to present combined values cleanly in output.
Advanced Formulas and Chaining
For more sophisticated workflows, chaining functions can reduce manual steps and improve consistency. You might use floor to round down damage, round to standardize outputs, and max/min to clamp values within expected ranges. Complex macros often compute several intermediate values by assigning parts of the expression to variables, then assembling the final result. Understanding data flow across these steps helps you debug and refine your logic without rewriting large blocks.
Best Practices and Developer Considerations
- Use explicit parentheses to control evaluation order rather than relying on precedence alone.
- Prefer named attributes and descriptive variable names to make formulas easier to read and maintain.
- Test edge cases such as zero, negative values, and empty fields to avoid unexpected results.
- Document complex logic with comments in macro text or sheet descriptions, especially for shared campaigns.
- Keep performance in mind by avoiding deeply nested functions in frequently triggered macros or repeating sheet calculations.
Testing, Debugging, and Troubleshooting
When an equation produces unexpected output, isolate parts of the expression by evaluating smaller segments in controlled environments. Break complex logic into helper attributes or staged macros to identify where values diverge from expectations. Watch for type mismatches, such as treating a text field as a number, and validate input formats when users enter data manually. Using simple placeholder values during setup makes it easier to verify each component before combining them into a complete formula.
Comparisons and Feature Summary
Different deployment contexts offer varying levels of control, so knowing where your formula runs helps you choose patterns that are robust and maintainable.
| Attribute / Feature | Verified Detail | Source Type |
|---|---|---|
| Wrapped in %{...} | Required for macro commands and some sheet button evaluations | Platform syntax convention |
| Basic arithmetic operators | +, -, *, / with standard precedence rules | Platform documentation and observed behavior |
| Conditional function | if(condition, true_value, false_value) widely supported | Platform documentation and community use |
| Attribute references | Use @{section|attribute} syntax for character sheet fields | Platform documentation and API references |
| Chaining and nesting | Functions can be nested; macros can stage intermediate values | Platform behavior and developer guides |
| Debugging approach | Evaluate subexpressions in isolation to locate errors | Community practice and troubleshooting guides |
Common Pitfalls and How to Avoid Them
One frequent issue is implicit type coercion, where a formula unexpectedly concatenates strings instead of adding numbers. Always verify that referenced attributes contain numeric values or explicitly convert them when needed. Another pitfall is unbalanced parentheses, which can cause errors or produce unintended groupings. Use whitespace and comments to make structure obvious. Also, remember that some functions return text; if numeric output is required, wrap results in appropriate conversion logic or numeric functions.