As you may have read in my earlier posts about JSON objects and JSON arrays, I’ve been working on macros to let me better track conditions on tokens for my D&D 4e game in MapTool. I thought it would be simple, but I ultimately needed to learn about some rather advanced topics. This includes today’s topics: library tokens and the MACRO roll option.

What’s a library token?

A library token is pretty much like any other token, except that its name must begin with “Lib:” (including the colon, but not the quotes). For instance, I created a token called Lib:LibToken1. I’m creative like that.

What’s the point?

While there might be tons of cool things you can do with library tokens, I’ve discovered two so far.

First, they’re handy for storing properties that you’ll want to reference across multiple macros. You theoretically could do this with any token, but library tokens are available no matter what map you’re on, and you’re less likely to accidentally delete them if they get killed (since, you know, they’re not intended to actually be in combat).

Second, if you put a macro called onCampaignLoad on a library token, then it will automatically run whenever you open up the campaign (or whenever your players connect to it). I’m not using this right now, but it’s good to know about for the future.

Third, you can call macros on library tokens from other macros. This is where it gets cool.

What is the MACRO roll option?

If you have any experience with programming other than in MapTool, you might be familiar with subroutines. Good programming often means that you’ll separate little pieces of code from one another and then “call” those other pieces of code when you need them. So, if you have a piece of code that sorts a column of data, let’s say, you’ll keep it separated and then “call” that code whenever you need to sort something.

In MapTool, you do this with the MACRO roll option. Note first of all that it is a roll option, not a function. This means that it comes BEFORE the colon within your square brackets of code, just like the “h” roll option for hiding your results. It also means that if you want to hide the results of the entire macro, you’ll format it as “[h, MACRO…” rather than “[h: MACRO…”.

I’ll note that there’s another way you can handle this, via User Defined Functions (UDF) in MapTool. Basically, you can use the defineFunction() function (wow, that sounds weird) to more or less make one of these called macro roll options into a function rather than a roll option, but that’s a topic for another time.

How does it work?

Let’s say I’ve created a macro on my Lib:LibToken1 library token, and I’ve called it ToggleState. This macro will let me toggle a condition (like Dazed) on or off of another token. I need to tell the ToggleState macro what state I’m toggling (Dazed), which is called an argument.

If I want to call the ToggleState macro, passing it the Dazed argument, it will look something like this:

[MACRO("ToggleState@Lib:LibToken1"): "Dazed"]

The roll option itself (MACRO) comes first. Within parentheses, I tell MapTool the name of the macro I’m calling (ToggleState) and where it can find that macro (on the token called lib:LibToken1) with an @ symbol in between. I then close the parentheses and insert a colon, followed by the argument (“Dazed”).

If you want to call a macro without any argument, you still need to include “” as a dummy argument. Without that, MapTool won’t execute the call.

If I want a bunch of different arguments, I can pass them as a string list or – you knew this was coming – a JSON object or array.

How do you use passed arguments?

Now let’s look at a piece of the macro I’ve called – the ToggleState macro.

[h: StateName=macro.args]

This line of code is accessing the argument I passed to the macro; StateName is set equal to the value of the special variable macro.args, which in this case is equal to “Dazed” (because that’s the value of the argument I passed to the macro). From there, the macro can continue to work, knowing the name of the state to toggle.

How do you pass information back from the called macro?

This is lovely and all, but it will often be useful for the macro I’ve called (ToggleStates) to pass some information BACK to the original macro. In order to do that, I use the special variable macro.return.

[h: macro.return="Toggle successful"]

I can include this line near the end of the called macro (ToggleStates). This sets the value of the special variable macro.return to “Toggle successful”. I can then access this information back in the original Dazed macro:

[h: DeliveredMessage=macro.return]
[r: DeliveredMessage]

Naturally, you can also pass back lists of things, often in a JSON object. So, from the called macro:

[h: ValuesToReturn=json.set('{ }', "Message", "Toggle successful", "NumTokensToggled", 3)]
[h: macro.return=ValuesToReturn]

And then in the calling macro:

[h: ReturnedValues=macro.return]
[h: MessageToDisplay=json.get(ReturnedValues, "Message")]
[h: NumTokensAffected=json.get(ReturnedValues, "NumTokensToggled")]
[MessageToDisplay] on [NumTokensAffected] tokens.

Bringing it all together

Now you know about the advanced tools I had to learn in order to write my state-tracking macro:

• JSON objects
• JSON arrays
• Library tokens
• MACRO roll option

The final step: Showing you how it all comes together! Stay tuned for the exciting conclusion.

-Michael the OnlineDM