Roll20 dice macros let you automate complex roll sequences so you can focus on playing rather than manual calculations. This guide explains how to build reliable macros for basic and advanced rolls, work with the API chat commands, and avoid common errors that disrupt play. You will learn core syntax, targeting options, permission settings, and how to maintain macros as your game evolves. Whether you are running a campaign or joining a one-shot, clear macro design reduces friction and keeps the table moving.
What Are Roll20 Macros and Why They Matter
A macro in Roll20 is a saved chat command that executes one or more rolls with a single button click in the in-game chat. Well-built macros standardize notation, prevent accidental modifier errors, and speed up repeated actions, such as attack rolls, spellcasting, or damage tracking. For game masters, macros help maintain consistency across sessions and reduce the cognitive load of managing multiple creatures and players. For players, they remove busywork and help the table stay engaged. Because macros rely on the Roll20 API and chat command syntax, understanding how they work is essential for troubleshooting and customization.
Roll20 Macro Basics and Core Syntax
Basic Roll Structure
Every macro starts with the ! character, which tells Roll20 to interpret the line as a chat command rather than plain text. The fundamental pattern is !roll [equation], where the equation follows standard dice notation used by many virtual tabletop platforms. Roll20 supports classic dice operators such as addition, subtraction, multiplication, division, and parentheses for order of operations. You can reference numeric attributes stored on characters, tokens, or objects by wrapping the attribute name in curly braces. For example, !roll /w gm &{template:default} {{name=Attack}} {{attack=[[@{Strength Mod}]]}} {{damage=[[@{Strength Die}]]}} lets a player use their character’s Strength modifier and die in the roll without typing numbers manually.
Attribute References and Variable Use
Attribute references pull saved numbers from a token’s sheet, which keeps rolls accurate when modifiers change. Use @{attribute_name} to reference attributes on the current token or @{target_token_name.attribute_name} to reference another token. Macros can also define temporary variables with the = operator inside the roll equation, which helps simplify complex formulas. For example, !roll /w gm &{template:default} {{name=Spell}} {{total=[[1d20+@{mod}]]}} {{damage=[[@{level}*2]]}} uses a variable-like reference to the modifier attribute and multiplies level by two for damage. When an attribute is updated on the character sheet, all macros using that reference automatically reflect the new value, reducing maintenance overhead.
Text Targets and Chat Display
Macros often include a target prefix such as /w gm to send output only to the game master, or they can use /direct for flavor text that does not roll anything. The default target is public chat, so choosing the right audience keeps tables organized. You can embed template tags like &{template:default} to control how rolls appear in the chat log, including titles, result boxes, and damage breakdowns. Proper use of targets and templates improves readability and ensures that important information, such as hidden rolls or damage totals, reaches the intended viewers without cluttering general chat.
Common Roll Patterns and Practical Examples
Simple attack rolls, saving throws, and skill checks form the backbone of most macro designs. As complexity grows, you may want to chain rolls, include conditional logic, or integrate with other API features. Below are several widely used patterns that balance readability with functionality, along with guidance on when each style is appropriate.
Attack Roll with Hit Location
- Standard attack:
!roll /w gm &{template:default} {{name=Attack}} {{tohit=[[@{Attack Bonus}]]}} {{roll=[[@{d20}]]}} - With hidden roll:
!roll /w gm {{name=Secret Check}} {{roll=[[1d20+@{bonus}]]}} - Saving throw:
!roll /w gm &{template:default} {{name=Reflex Save}} {{saves=[[1d20+@{Reflex}]]}} - Skill check:
!roll /w gm &{template:default} {{name=Perception}} {{skill=[[@{Perception}]]}}
Damage and Healing Rolls
Use separate rolls or combine them into a single macro depending on how much control you want at the table. For straightforward damage, a compact format works well: !roll /w gm &{template:default} {{name=Fireball}} {{damage=[[3d6]]}} {{total=[[3d6+@{Int}]]}}. If you need to apply resistances or multipliers, consider using a whisper to the GM for hidden calculations or adding notes in the template. Healing macros can follow a similar pattern, for example !roll /w gm &{template:default} {{name=Cure Wounds}} {{heal=[[1d8+@{Level}]]}}, ensuring that positive and negative effects remain clearly labeled in the chat history.
Advanced Techniques and API Features
Once you are comfortable with basic macros, you can incorporate advanced behaviors such as conditional output, random tables, and external API calls. Conditional rolls can be approximated using multiple lines in the macro editor, letting you present different templates based on the result. For example, you can design a spell macro that shows a low-level template for small results and a high-level template for critical successes. Random table lookups are possible using a series of linked macros or by integrating script if your Roll20 subscription includes API access. These techniques reduce the number of clicks required to run complex actions and help keep the game’s pacing smooth, especially during combat-heavy sessions.
Setup, Permissions, and Best Practices
Creating and Organizing Macros
To create a macro, open the campaign, type your command in the chat box, and use the macro creation dialog to save it with a descriptive name and icon. Group related macros by naming conventions or by using folders in the API, which makes it easier for players to find the right tool during play. Keep a central reference document that lists each macro’s purpose, required permissions, and any character-specific dependencies. Well-maintained naming and clear documentation reduce confusion when multiple people share the same account or when macros are imported between campaigns.
Permissions and Security
Macro permissions determine who can execute a command, with options for players, trusted players, or the GM only. Set restrictive permissions for destructive or game-changing actions, and use whisper-only output for rolls that should remain hidden from the table. Be cautious when enabling API access, and review third-party macro examples before importing them, since macros can include powerful commands that modify game state. Regularly audit macros and permissions, especially after session changes or when a player leaves the campaign, to maintain a secure and predictable play environment.
Maintenance and Version Control
As rules evolve and characters level up, macros need updates to stay accurate. Use consistent attribute names so that references continue to work after sheet changes, and back up complex macros by exporting them or keeping a text copy of the command line. When you modify a macro, test it in a private session or with dummy tokens to confirm that the output matches your intent. Establish a simple versioning approach, such as adding a date or version tag to the macro name, so you can track changes over a long campaign and revert if something breaks.
Limitations, Troubleshooting, and Alternatives
Roll20 macros depend on attribute accuracy, correct syntax, and appropriate permissions, and they can break when sheets change or when nested references exceed expected limits. Common issues include missing attribute paths, incorrect whisper syntax, and template mismatches that cause rolls not to display. Troubleshooting steps include checking the chat log for error messages, verifying attribute names, and simplifying the macro to isolate the problem. If macros become too complex, consider using Roll20’s API scripts or switching to a platform with built-in scripting, but for many tables, well-designed macros remain a reliable and efficient solution for automating rolls.