Roll 20 macro scripts automate complex tabletop commands so you can focus on storytelling instead of manual dice management. These compact programs run inside the Roll20 platform, triggering effects, updating tokens, and synchronizing game state across players and the game master.
When designed thoughtfully, a Roll 20 macro scales from simple single-action shortcuts to advanced multi-step sequences that handle initiative, conditions, and resource tracking. The following sections break down the core workflow, best practices, and common scenarios you can adapt for your own games.
| Macro Type | Use Case | Complexity | Visibility |
|---|---|---|---|
| Simple Dice | Roll a single attack or damage formula | Low | GM & Players |
| Conditional Attack | Check advantage, cover, or weapon properties before rolling | Medium | GM & Players |
| Token Control | Move, hide, or change bar values on a token | Medium | GM Only |
| Multi-step Sequence | Chain rolls, update journals, and send chat messages | High | Configurable |
| Campaign Script | World-level triggers, timers, or custom apps | Very High | GM Only |
Getting Started with Roll20 Macro Basics
To build your first macro, open the journal, select Macros, and choose Create Macro. Assign a clear name, icon, and command syntax so players recognize its purpose at a glance. Keeping the interface simple reduces accidental misuse during fast combat rounds.
Syntax Structure
The basic command follows a consistent pattern: a roll expression wrapped in /roll or /w for whisper. You can embed chat flags, bar updates, and repeating section references to create fluid interactions without manual intervention.
Advanced Commands and Repeating Sections
Repeating sections are powerful when combined with Roll 20 macro logic, letting you reference character sheets, spell slots, or inventory lines dynamically. By using @{repeating_section|attribute} syntax, your scripts stay adaptable as characters level or gear changes.
Error Handling and Feedback
Robust macros include fallback messages when a check fails or a token is missing. Sending targeted whispers to the GM and clear chat hints helps players understand what happened without breaking immersion.
Optimization and Distribution
Well optimized macros run quickly, avoid redundant rolls, and respect API rate limits. When you share macros with your group, document permissions, required settings, and version numbers so everyone uses the same tested behavior.
Best Practices and Key Takeaways
- Start with small, focused macros and iterate based on player feedback.
- Use repeating sections and dynamic attributes to keep macros resilient across sessions.
- Document syntax, permissions, and limitations directly in the macro notes.
- Test macros in a sandbox campaign before running them in critical encounters.
- Balance automation so that tactical decisions and narrative moments remain engaging for everyone.
FAQ
Reader questions
Can I use Roll20 macro to automate complex character actions like multiattack or spell combos?
Yes, you can chain rolls, condition checks, and bar updates into a single macro to simulate multiattack or spell combos, but you must test edge cases and respect game balance.
How do I make a macro that works for both players and the GM without breaking game balance?
Design macros that request confirmation for powerful effects, limit automatic damage scaling, and clearly separate player shortcuts from GM-only world scripts.
What should I do if my macro stops working after updating my character sheet?
Check attribute names in repeating sections, verify bar references, and update the macro syntax to match any renamed fields or moved rows.
Can Roll20 macro integrate with external APIs or custom apps on the platform?
Yes, you can use custom apps and API calls inside macros, but you must follow Roll20 security policies, respect rate limits, and keep sensitive operations behind GM controls.