macros:HowTo:howto

Macro How To

How to automate updating a token property

This section expects that you are already familiar with how to add macro buttons to the MapTool user interface.

Example: Updating Hit Points

Let's say you have a property to represent hit points. We'll call our property HP. Now we want some easy way to update HP, so we're going to create a macro button that executes a macro.

First, consider how you want this to work. We want a window to popup on the screen and ask the user to enter a number. That number will be subtracted from HP, so the user can use a positive number to represent damage and a negative number to represent healing. (We'll show another approach later.)

The first step will be to prompt for the number. MapTool has this ability built-in. All we need to do is use a variable name that doesn't exist yet and MapTool will popup the prompt! The name of the variable is part of the prompt, so we'll use a descriptive name. How about AmountOfDamage?

[ damage = AmountOfDamage ]

Notice the extra variable name and the equals sign? That tells MapTool to calculate whatever is on the right of the equals sign and store the result into the variable on the left. In this case, there's no formula, so this becomes simply a copy -- from the variable AmountOfDamage to damage. But when MapTool tries to read the value of the variable and it doesn't exist, the popup will automatically appear! That's perfect for what we want!

Now the next step is to subtract that from the HP property. Fortunately, what you learned in the last paragraph can be used again:

[ damage = AmountOfDamage ]
[ HP = HP - damage ]

This time the second line calculates the formula on the right (HP - damage) and stores the result into ... HP? Isn't that going to screw up our HP value?

No, it doesn't screw it up, but it does replace that value with the result. And because HP is a property, the result is stored back into the token's property. If you were to right-click on the token and save it to an external file, the new value of HP is stored with it. When the token is later reloaded, that value will come with it.

If you want to add to the hit points instead, you have two choices: either the user can enter a negative number, or you can change the - to a +. The first option is easy because it puts the burden on the user! The second option is really an option -- who wants to edit their macro every time they want to switch from damage to healing? Another choice not listed above would be to create a second macro. Then there could be one macro for adding damage and one for adding healing.

There's a few things still needed here to make this a little prettier, but those are future steps. Go ahead and try this out right now on a token that you create in MapTool. (The default property type, Basic, includes a property named HP.) And try adding the second macro as well, just for the practice. (Believe me, the more practice you get early in the process, the easier it will become later on.)

Example: Let's Rest for a Minute...

((macro that uses another property, HPmax, to reset hit points back to maximum))

Example: One Macro to Rule Them All

((macro that uses input() to prompt for values with radiobuttons))