More Branching Options

Introduction

This is a guide to two "advanced" (so to speak) macro branching options, [MACRO(): and [TOKEN():]. This guide is currently under construction, so it is far from complete. Rumble 13:57, 7 April 2009 (UTC)

MACRO: Running Other Macros

One of the best practices when you write macros - especially when they become complex - is to keep them streamlined and lean, and only have them do what they need to do - for instance, if you have a macro that adds a skill to a token, it doesn't need to be the same macro that checks to see if an attack hits, or records damage taken. It just adds skills.

Writing macros this way - each macro doing something relatively small - is a good way to keep yourself organized and keep your macros clear (it also makes them easier to fix if something goes wrong!). What's more, it helps keep your memory use lower, so you don't get run into stack overflow errors or, more commonly, slow macros.

But if you do this, how can you make one macro run based on another one - surely, you don't want to have to hit each button every time something happens, right? Enter the [MACRO():] roll option.

What's It Do?

The [MACRO():] roll option is they way you can have one macro - the calling macro - trigger another macro, which we call the called macro. The calling macro can send some information to the called macro, where that information will be handled and processed and probably changed, and then, if you like, the called macro can send some information back to the caller.

Why would I Use It?

Where this comes in handy is in three circumstances: first, when you have some operation that you're always doing, but you have several different ways that it might come up. Second, if you have a macro that everyone uses. The second, and more powerful use, is when you want to manipulate another token besides your own - then you frequenly need to use called macros, because there are some things only a called macro can do!

Common Tasks from Multiple Pathways

Let's look at the first benefit: take, for example, a macro that applies damage to a token in accordance with the Sample Ruleset (in other words, it looks at a token's properties, and then deducts damage from the token's HitPoints property). How many ways can you think a token might get damaged?

1. It could get damaged by an attack from an enemy
2. It could get damaged by an attack from a friend (accidental or otherwise)
3. It could get damaged by falling
4. It could be damaged by a trap

All kinds of ways. Now, suppose you have three macro to handle damage. These macros are called Enemy Attack, Friendly Fire, and Environmental Damage. Each of these causes a token's HitPoints to be reduced, but each also has some special processing to determine just how much HP reduction takes place (it's not important what the special processing is at the moment).

So you have three macros, but each has a common element: they all in the end reduce the token's HitPoints. Consider a couple alternatives - you can:

1. Write each macro separately, including the calculations to reduce HitPoints; or
2. Write a fourth macro, containing just the calculations to reduce HitPoints, and have the three damage handler macros call that fourth to handle the final calculations.

The advantages of the first option are that you only need to write three macros, and you're done. On the other hand, what if you realize you made a mistake in your damage macro? You then have to edit it in three places. In the second option, you only edit one copy of the damage macro.

Tasks Everyone Does

Building on the example above, if you have a whole bunch of macros that everyone uses (perhaps everyone needs to have a way to attack, to defend, and to take and heal damage), you can create a single set of macros that everyone simply calls, rather than duplicating every macro on every token, every time you need a new token on the map.

So, for example, you may want to build a "library" of macros to handle your game (whatever game it happens to be), and then create a single set of macros on your tokens that do nothing but call macros in the library.

You'll note that it doesn't mean you have fewer macros overall - every token still needs a set of macros to call on the library; however, it does mean that your actual complex macros (the ones that took you a long time to write) are all in one place, and you only need to alter one copy in order to fix an error. If you'd copied the entire macro set to every token, you'd have to fix every single token one at a time to fix any mistakes you made.

Manipulating Other Tokens and Trusted Macros

Generally, when a token runs a macro, or calls a macro, the macro assumes that all properties and variables it needs to use apply to the token running the macro. So if Bork the Brave calls a macro in a macro library, that library macro is going to assume that it needs to do its thing on Bork the Brave.

However, sometimes Bork the Brave does not want this - maybe Bork the Brave just whacked a troll with his sword, and wants the damage to be applied to the troll (and, by extension, most definitely does not want the damage applied to himself!). He's going to want a macro that will affect the troll's token, not his own.

As it turns out, however, there are some things, as mentioned, that a regular old macro on a player token simply can't do. For instance, a macro on a player token can't go and determine what an NPC token's properties are. It's simply not permitted to access another token. I think you'll agree this is a good way to go - you may not want players being able to see property values on an NPC. Furthermore, a player token macro can't change values on another token. Nobody wants the players to be able to, for instance, reduce an enemy's armor value to zero just before making an attack.

But still, we want to be able to do some things to other tokens, right? In response to that, the concept of trusted macros was developed. Trusted macros are simply macros that can perform certain functions unavailable to other macros, such as the functions that manipulate token properties other than the ones on the token who called the macro.