📖 Roll20 Macro Guides

Get started in 2 minutes with your first macro and token action

⚡ Quick Start: Macro vs Token Action

Roll20 has two ways to automate your game. Here's the difference in 30 seconds:

🎲 Macro

Always visible in your macro bar. Works without selecting anything.

Best for: GM tools, quick rolls, effects

/roll 1d20

→ Button sits in your macro bar, click anytime

⚔️ Token Action

Appears when you select a token. Automatically uses that character's stats.

Best for: Attacks, saves, character abilities

/roll 1d20+@{strength_mod}

→ Button appears above your token when selected

On This Page

🎲 Your First Macro (1 minute)

Let's create a simple "Roll d20" button that's always available:

  1. Click the Collections tab (folder icon) in Roll20's sidebar
  2. Click + Add in the Macros section
  3. Name it: Roll d20
  4. Paste this code:
/roll 1d20
  1. Check "Show in Macro Bar"
  2. Click Save

✅ Done! You now have a d20 button at the bottom of your screen. Click it anytime to roll.

"I used to type /roll 1d20 every time. Then I took a macro to the knee." 🏹

⚔️ Your First Token Action (1 minute)

Let's create a "Strength Check" button that automatically uses your character's stats:

  1. Open your character sheet
  2. Go to the Attributes & Abilities tab (or gear icon)
  3. Click + Add in the Abilities section
  4. Name it: STR Check
  5. Paste this code:
/me rolls a Strength check: [[1d20+@{strength_mod}]]
  1. Check "Show as Token Action"
  2. Click Save

✅ Done! Select your token on the map → a "STR Check" button appears above it. It automatically pulls your character's Strength modifier!

📋 When to Use Which

🎲 Use Macros For:

  • Quick dice rolls — d20, d100, percentile
  • Rollable tables — random encounters, loot
  • NPC quick checks — generic saves, perception
  • GM announcements — "Roll initiative!"
  • Visual effects — /fx commands
  • Utility tools — whispers, timers, reminders

Always visible in your macro bar. No token needed.

⚔️ Use Token Actions For:

  • Attacks — using your character's bonuses
  • Saving throws — with your modifiers
  • Ability checks — STR, DEX, etc.
  • Spellcasting — with your spell save DC
  • Class features — Rage, Sneak Attack, etc.
  • Character emotes — on-brand RP moments

Appears when you select your token. Uses your stats.

💡 Simple rule: Macros are GM tools and quick buttons. Token Actions are character actions.

Why did the bard's macro fail? Too many {{perform}}ance issues. 🎭

🎯 Syntax Reference

The building blocks you'll see in macros:

/roll 1d20+5 → Roll d20 plus 5 [[2d6+3]] → Inline roll (embedded in text) /w gm secret → Whisper to GM only /em waves → Emote (italic text) ?{Bonus?|0} → Ask user for input @{selected|hp} → Get selected token's HP @{target|ac} → Click a target, get their AC &{template:default} → Pretty formatted output

Common Attribute Names (D&D 5E)

strength_mod, dexterity_mod, constitution_mod intelligence_mod, wisdom_mod, charisma_mod ac, hp, speed, initiative_bonus spell_save_dc, spell_attack_bonus

A wizard, a rogue, and a fighter walk into a macro bar. The cleric was still typing /roll. ⛪

🔧 Advanced Topics

Dropdown Menus

Let users pick from options:

?{Roll Type|Normal,1d20|Advantage,2d20kh1|Disadvantage,2d20kl1}

Combining Macros

Call other macros by name:

#AttackRoll

Abilities vs Macros (Technical)

Token Actions are actually Abilities stored on the character sheet. The difference:

// Macro (Collections tab) - needs @{selected|...} /roll 1d20+@{selected|strength_mod} // Ability (Character sheet) - can use direct attribute /roll 1d20+@{strength_mod}

📚 Go Deeper: Roll20 Wiki Macro Guide has comprehensive documentation.

🚀 Ready to Go?

Browse our library of ready-to-use macros—just copy, paste, and play!

Browse Macros →