Creating macros

I am messing about with the roll20 system and I was wondering if there is a primer or guide on scripting.
I don't know if what I want to do is doable through a macro or needs api calls.

https://wiki.roll20.net/Macros


This covers a lot of bases. It was good enough to get me started.

As for macro or API, what are you looking to do? What system? The macros can do a lot of heavy lifting, but they can't do everything.

For now some scripts for initive, combat rolls and damage, ammunition counter for ranged weapons.

As for which gaming system to pair it with say any version of DnD. I can alter the scripts then if the engine changes.
I upgraded to Mentor level in case I needed api calls for any of this.
I'm sure this is fairly straight forward if you know what you're doing.

"Any version of DnD..." should be no more than a google search away. I expect there are plenty of OSR/SRD/PF/4e games being played, and millions of variations of macros in use.

DnD is nice because it uses a pretty straightforward system (d20+bonus<>DC). 2nd ed attack matrices (THAC0) will be easier to macro than 1st ed, though I think you could probably do the latter with a rollable table. And that's only if you want your players to immediately know their success or failure. If you want to be sneaky about it, just do a basic roll macro with a result (d20+bonus=).

For the API, check out this thread.

Thanks Tom. Very helpful. Will read the wiki and mess about with the macros some more.

Are there any other guides and examples to creating macros besides the Wiki listed above?
The system seems to be much more complex than the guide indicates but I am too slow to figure out on my own how to do the cool stuff, Of course its possible the macro system is just a weak little tool and the guide has all one needs, but I'm hoping I am just not finding what I need.
Some questions and some things I would like to do.

When rolling the default initiative macro and hitting a min or max on the die, the result shows up boxed. Great. I am assuming its doing that because of the [ ] braces around the calculation. Can this crit detection be used in any way?
I would like my macro to see the attack roll as a crit or miss and respond with the appropriate damage roll.

I would like to keep track of arrows automatically, and keep the total in one of the tokens 'bars'.

Can you use some kind of if/then statement?

Is there a more extensive guide somewhere is really the main question. Thanks.

Daniel S. said:

When rolling the default initiative macro and hitting a min or max on the die, the result shows up boxed. Great. I am assuming its doing that because of the [ ] braces around the calculation. Can this crit detection be used in any way?
I would like my macro to see the attack roll as a crit or miss and respond with the appropriate damage roll.

I would like to keep track of arrows automatically, and keep the total in one of the tokens 'bars'.

Can you use some kind of if/then statement?

Is there a more extensive guide somewhere is really the main question. Thanks.

Unfortunately, the answers to your questions all are "not without using the API." The wiki pretty much has all of the relevant information for dice rolling and macros - I can't comment on how well documented the API is on it.

Good to know, just saved me lots of time, Thanks. :)

Here's some simple examples:

/me leaps into action! [[1d20 + 5 &{tracker}]]


/me defends himself from the assault!
[DEFENSES]
AC:18 / 18Flat / 13Touch
Fort:[[1d20 + 3]] Ref:[[1d20 + 7]] Will:[[1d20 + 1]]
Resist 5 : cold/elec/fire
CMD:19


/me grips his longspear firmly and THRUSTS!
Attack:[[1d20 + 7]](+2 if charge)
Damage:[[1d8 +5 ]] + SA:[[2d6]]
Crit Threat: 20/x3
Confirm:[[1d20 + 7]] for addt'l [[ {1d8+5} + {1d8+5} ]]


/me rolls his shoulders and prepares for a feat of ATHLETICS!
Acrobatics:[[1d20 + 10]]
Jump:[[1d20 + 3]] Climb:[[1d20 + 8]]
Swim:[[1d20 + 7]] Ride:[[1d20 + 3]]


General Skill Check:[[ 1d20 + ?{Skill Bonus|0} ]]

I'm looking to write three scripts, they can be macros or API.

1) All characters (PCs or NPCs) have an attack value with a dice roll and a static defence value.
I'm having a little trouble getting the system to roll the attack for a targeted character, check the attack against the defence and display (Hit, Miss, Fumble, Critical). A 1 being a fumble and a 10 being a critical. I don't want the player to know how close to hit or miss they were, since that gives away the defence of the enemy.

2) If an attack hits roll for damage (that's easy enough) but also apply -2 points to the Armor value of the character that got hit per attack it protects against.
I figure I can put the armor value as a bar on the token, but not sure how I can get it to go down or up. This might be something I have to do manually as DM.

3) An ammo counter, most of the attacks in the game will be using ranged weapons, I need to have a counter for how much ammo is left in the magazine for the weapon, if possible to have this effect another value holding the amount of ammo being carried.

I"m learning a lot reading these forums, and you are some of the most helpful people out there.
I'd be very grateful if someone could help me with this.

Steven, the macro tool is read only. Meaning your commands can call on data from any ability you have in place, use them in a particular way and then print the result to the chat window. They can not send commands back to the game board or automatically alter any value on a character/token. You must use the API for that. Also, you can not do any sort of If/Then functions with the macros, as in your crit/failure example. You can get it to target a selected token with the &{target} command. (That may not be the exact language. But just search the specific use forum for selected token and targeted token. For example, you could do a roll1d20+(selected tokens BAB) vs (selected targets AC).

Heya Steven,
Rob has the truth of it. Unfortunately each requirement you mentioned can only be done in the API.

The Macro Success/Failure only returns a 0 and a 1, and players can see the roll of any macro on the screen.

Macros cannot change any values or attributes, only read them.

Macros cannot use if/then conditions. The only logic operator built into the Macro system is < (less than or equal to) and > (greater than or eqal to).

So yes, all in all you will need to make an API script for this. You'll probably want to submit a new forum post in the API section, detailing out exactly what you want help to do. The more examples the better.


Cheers.

Mark G. said:

Here's some simple examples:

/me leaps into action! [[1d20 + 5 &{tracker}]]


/me defends himself from the assault!
[DEFENSES]
AC:18 / 18Flat / 13Touch
Fort:[[1d20 + 3]] Ref:[[1d20 + 7]] Will:[[1d20 + 1]]
Resist 5 : cold/elec/fire
CMD:19


/me grips his longspear firmly and THRUSTS!
Attack:[[1d20 + 7]](+2 if charge)
Damage:[[1d8 +5 ]] + SA:[[2d6]]
Crit Threat: 20/x3
Confirm:[[1d20 + 7]] for addt'l [[ {1d8+5} + {1d8+5} ]]


/me rolls his shoulders and prepares for a feat of ATHLETICS!
Acrobatics:[[1d20 + 10]]
Jump:[[1d20 + 3]] Climb:[[1d20 + 8]]
Swim:[[1d20 + 7]] Ride:[[1d20 + 3]]


General Skill Check:[[ 1d20 + ?{Skill Bonus|0} ]]

Mark, are those macros or API Scripts? I see terms and characters I did not see in the Wiki on Macros.
What exactly are those examples of?
Thanks in advance.

Those are plain ol' macros. The terms and characters are largely found in the wiki under Dice Reference for things like adding to the turn tracker, queries and so on. Mark also does some incredibly useful documenting within the macro itself and labels what each part does - great for people new to the game and overworked GMs.

There's also some overlap in practice between macros and character abilities which are described here in the wiki.

Rob M. said:

Steven, the macro tool is read only. Meaning your commands can call on data from any ability you have in place, use them in a particular way and then print the result to the chat window. They can not send commands back to the game board or automatically alter any value on a character/token. You must use the API for that. Also, you can not do any sort of If/Then functions with the macros, as in your crit/failure example. You can get it to target a selected token with the &{target} command. (That may not be the exact language. But just search the specific use forum for selected token and targeted token. For example, you could do a roll1d20+(selected tokens BAB) vs (selected targets AC).

Hi Rob,

I can get an attack roll but it doesn't pick up the targets defence. I might be doing it wrong.

Looks like I need API scripts to do this. I appreciate the help.

Big thank you to everyone who posted here, I appreciate the community spirit and friendly nudges to get where I need to be.

Ahhh gorsh... you'll make me blush :)

But yeah, these are just plain ole' macros. As a Supporter, I don't have access to the API, so I have to learn how to be effective with regular macros. You can't change values with them, but if you're creative enough you can get around a lot of issues.

You mentioned terms and characters you didn't recognize, the only part of those macros that is actual calculations and not just flavor text is whatever is between the Inline Roll brackets [[ ]] . Everything else is just text.

A lot of people encounter the most difficulty figuring out the logic, or how to go about getting the macros or API to do what they want. The actual syntax (code) is actually fairly easy. It can be hard knowing where to start and frustrating if you try to get it all to work together in one go. I always take my programing and/or scripting in pieces; getting each little section to work by itself and then combining the pieces into one complete string of commands.


For example, if I wanted to make a macro to calculate my attack damage in Pathfinder with a two-handed weapon by reading in my character's Strength Attribute, the weapons' Dice, and power attack, I wouldn't try to write it in one shot.


(assumes I have an attribute on my sheet called "STR" written as bonus/total str like 3/16)

- Then I figure out the modifications for a two-handed weapon, which is STR * .5 for using a two-handed weapon.

- Then I have to figure power attack, which is a straight +3 at this level (I cheat and don't usually bother with an attribute since it only changes infrequently)

- Then I put it together, using Inline Roll labels so it's clear what each piece is when someone looks at the roll.

- And finally, I put in some flavor text to make it flow better when used within the game.

All in all, really pretty basic if taken in pieces, but nasty looking if you only look at the finished product.

Hi Rob,

I can get an attack roll but it doesn't pick up the targets defence. I might be doing it wrong.

Looks like I need API scripts to do this. I appreciate the help.

Big thank you to everyone who posted here, I appreciate the community spirit and friendly nudges to get where I need to be.

Are your target tokens linked to a Character Sheet that has an AC or other attribute for defense?
[[ 1d20>@{target|AC} ]] Should prompt you to click a target token, and compare the roll to the target token's "AC" attribute, return a 0 if the rolls is less than the AC or a 1 if it's equal to or greater.

It rolls the attack and doesn't check the defence value.

I have this at the moment:

/roll 1d10+(@{selected|REF}+@{selected|Handgun})>@{target|Defence}


I can turn it into an inline roll but I won't be able to see if it is doing the check properly if I do.

It does roll the die, add the modifiers and show me the result, it just doesn't check if it is higher or lower then the defence.

It should work if you enclose the first section before the > operator with curly braces {}

/roll { 1d10+(@{selected|REF}+@{selected|Handgun}) }>@{target|Defence}

Will try that and report back.

If you put something in an inline roll, you can see the elements of the roll by hovering the cursor over the result.

Thanks Mark, works a treat now