How to Write Macros for Roll20

This section isn't just for DMs, although DMs will find it very useful. Players can use this technique too. All my players really enjoy having macros pop up when they click on their tokens. You do not need to have a Pro-level subscription or API to use regular macros. You can use them with a free account, even. 

Macros are little bits of custom code you can add to your game that streamlines all kinds of repetitive functions so you spend less time fiddling around with dice and math and looking things up, and more time focusing on the story. 

The picture in this post shows macros across the bottom of the screen. They manage various functions for me with a single click. Across the top of the screen, macros specific to a single token pop up on the screen only when the token is selected. They function the same way. For instance, Atalaya there can shoot her longbow and roll damage with a single click, thus keeping combat fast and exciting and focused more on narrative than mechanics. I don't require my players to use them, but once they started using them, they sure do like them. 

I only require one: and that's the initiative macro. It automatically adds initiative to my tracker without my having to go around the table and bog down the moment by setting up turn order. 

I use them for initiative, for weapon and spell attacks, and to leave myself notes so I don't forget details. It's even possible to make a macro to trigger an animation to accompany a flashy spell. 

It looks complicated at first, but I promise you it's pretty easy once you get the hang of it. These instructions start with how to write a very simple macro, and gets fancier bit by bit. 

Things to remember:

[[ ]] this is where you put your desired dice to be rolled. 

{{ }} This is how you box up your array into a single section of the code. 

= is how you add a title or name to your section if you have a macro with multiple sections. 

&{template:default} before a macro creates a nice, elegant template that is easy to read. 

And keep in mind that if you macro stalls at a specific point, there may be a very hard-to-see space in there that isn't supposed to be. If you have a problem with part of your macro, break it up and run just the first bit, then add the second bit, then the third, until you hit the problem part. Makes it much easier to troubleshoot.

Simple dice roller

This macro will simply roll a twenty-sided die and then and four-sided die:

[[1d20]] [[1d4]]

Simple dice roller with modifiers

This will roll the same dice, but then add your modifiers to the roll. 

[[1d20+4]] [[1d4+2]]

Simple attack macro that labels your rolls

This one does the same thing, but it labels the rolls in the chat.

{{attack=[[1d20+4]]}} {{damage=[[1d4+2]]}}

Attack macro that pulls the target’s Armor Class 

Now we’re getting fancy. This one will roll your attack, but it will also display the target’s AC in the chat with the roll. It will open a box that prompts you to click on the target token.

{{attack=[[1d20+4]] vs. @{target|token_name}'s AC @{target|bar2}}} {{damage=[[1d4+2]]}} {{If Crit :+ Addt'l= [[1d4]] Piercing Dmg}}

*NOTE: This sort of thing gets a little fiddly because you have to tell it where to draw this info from. The bit of code for various functions will be found on the Abilities tab of the character sheets. If you just use tokens the way they are set up when you buy them, this configuration should work, although you may need to test it.)

Attack macro with template

And this one does the same, only it boxes it up nice and neat inside a pretty template. 

&{template:default} {{name=Dagger}} {{attack=[[1d20+4]] vs.  @{target|token_name}'s AC @{target|bar3}}} {{damage=[[1d4+2]]}} {{If Crit :+ Addt'l= [[1d4]] Piercing Dmg}}

You don’t ‘have put only numbers into a macro. You can use it as a sticky note to remind you of things you might forget. For instance, Boz, an NPC, has this macro attached to his token, to remind me that he can use his Uncanny Dodge to halve damage against him. Just seeing it up there reminds me, and I can click on it to view the full text in the chat if I need to. 

Sticky Note Macro

&{template:default} {{name=Uncanny Dodge}} {{Description=When an attacker that you can see hits you with an attack, you can use your reaction to halve the attack’s damage against you.

You can test macros by throwing the code into the chat and hitting enter. You can also just put them into your “abilities” tab and test them there. And third, you can store them in your “macro” section over there in your right-hand column. Look for the section with the three dots and three lines over in the top right-hand side of the column. Click on that icon to open a “macros” section that you can store your macros in. 

Here's a link to a running list of macros I have made for various things. I apologize in advance for the mess.

The map in the picture is made from tile packs:

Village to Pillage: City Walls by Gabriel Pickard (who never disappoints)
Quick Encounters: Cursed Woods by Gabriel Pickard

Vile Tiles: Overgrown Decals by Gabriel Pickard (can you tell who my favorite tile pack creator is?)

One of the many reasons I like Pickard's work is because...well...the roofs come off those houses. 

Back to The Riverport Rebels page.