Introduction to Macro Writing

What is a Macro?

As mentioned in the Token Macros page, a macro is simply a way to automate a task in MapTool. Essentially, macros are scripts that are read by a parser, which interprets them and ensures that the right parts are processed in the right way (for instance, ensuring that a command to add two numbers together is processed as a macro command, and not simply text to put into the chat window).

Macros started off small in MapTool, but at this point, the macro scripting language has become a very full-featured set of commands and functions that can perform nearly any operation you can imagine!

From here on out, macro will, obviously, refer to a collection of commands that are grouped together to automate a task, macro command will refer to any particular command or function you use in a macro, and the macro language will mean the whole collection of commands, functions, and operations you can use whenever you write macros.

Also, you might hear about things like Library Tokens, and calling one macro from another macro, and stuff like that. These things are possible, but we won't deal with them here. For this guide, the only macros we'll talk about are triggered by clicking a button on the appropriate Macro Panel, and only affect the tokens they run on.

Why Would I Use Them?

There's nothing requiring you to use macros at all when you use MapTool. Remember, the core purpose of MapTool is to share a map with your friends, and play games (read the Introduction to Mapping and the Introduction to Game Hosting to learn how to make and share maps with your gaming groups), and MapTool gives you everything you need to do that: maps, tokens, and a chat system that lets you chat in- and out-of-character, roll dice, and take on the roles of whatever character you are playing.

However, there's a lot more that can be done with MapTool, if you're interested in learning a little bit about the macro capabilities. For example, if you want to click a button that will automatically roll 1d20 and add a modifier to it, it's possible to create a macro for that. If you want to change your hit points after getting hurt, you can write a macro to do that.

And this tutorial will show you how!

Where are these "Macros"

Macros are associated with various parts of the MapTool interface and the objects in it. It turns out that there are three places a macro can "reside," so to speak:

Token Macros

The first, and most common place, is for a macro to reside on a token. Token macros are associated with the token on which they are created, and will travel around with that token as long as you let them.

Token macros are only directly accessible to the people who own the token, so if you don't own the token, you won't be able to click (or even see!) the button for that macro.

Campaign Macros

Campaign Macros are macros that aren't linked to a specific token in a campaign, but to the campaign as a whole. These macros work in almost every respect exactly like a token macro, except that:

1. You don't have to select a token to see the macros
2. Anyone can access them and run them

Campaign Macros are quite useful for the GM and for the Players to handle common functions - in fact, if you set up a common task as a campaign macro, then you only need to make one copy of it (instead of making copies on every token that needs it).

Global Macros

Global Macros aren't linked to a token or a campaign - instead, they are macros that are linked with your copy of MapTool. These macros are not visible to anyone else who connects to your game.

This is a good place to put macros for tasks you don't want other people seeing - like information you want to show to players only when you decide; or tasks you want to perform on your NPCs but you don't want PCs to be able to do.

The Macro Panels

With all this talk about macros and locations and especially the macro "buttons," you are probably wondering - where are these buttons? You'll find macro buttons on one of the 4 macro panels that appear in MapTool.

Selection and Impersonated Panels

There are two panels that deal directly with token macros: Selection, and Impersonated.

The Selection panel will show buttons for all of the macros that are currently residing on the token you have selected (you select tokens by clicking on them with the mouse). Each of these buttons runs a particular group of macro commands.

The Impersonated panel shows buttons for the macros on the token you are impersonating. Impersonating a token is a way to "assume the token's persona" - when you chat, text will appear as if the token was speaking, and so forth. It is possible to impersonate one token, and select another, so make sure you know what panel you're looking at!

Campaign Panel

This panel shows all of the macros currently set up for the Campaign. Remember, these are visible to everybody.

Global Panel

This panel contains the Global Macros you've set up. Remember, these are only visible to you.

Creating a Macro

Macro creation is a three-step procedure (though those three steps can contain multitudes!):

1. Right-click on the panel where you want the macro to appear (either one of the token panels, the Campaign panel, or the Global panel) and select Add New Macro. A gray button with the label (new) will appear.

2. Right-click on the button, and select Edit.

3. Enter your macro code, give it a name, and hit OK. There! You've created a macro!

Writing Macros

But wait...what do you mean, "macro code?"

As I said, those three steps can contain a huge amount of details, steps, tips, tricks, victories, failures, frustrations, and sometimes, hollering and gnashing of teeth. So, we'll take a step back and look at some very simple macros in a step-by-step fashion.

If you want to see what some advanced macros can look like, there are plenty of tutorials and how-tos on this wiki to read through. For now, though, we'll do some simple, but useful, macro coding.

Roll for Initiative

The simplest macros are no more than text, which is output to the chat window. In effect, a macro containing text (in fact, all macros) just send a string of commands to the chat window where it is read and interpreted.

Most programming languages start off with the classic "Hello World!" program, so this guide is not going to do that. Instead, let's do something a bit more RPG: create the dreaded "Roll for Initiative!" message!

1. Select the Campaign Panel.

2. Right-click on it, and create a new macro.

3. Right-click on the new macro button, and click Edit.

4. In the Label field, enter "Roll for Initiative!"

5. Leave the Group and Sort Prefix fields blank.

6. In the Command field, type

Roll for Initiative!

7. Click OK.

8. When you're done, you'll see that the button has changed - it now says Roll for Initiative! on it, and when you click it, lo and behold, the text "Roll for Initiative!" appears in the chat window.

That is macro writing at its most basic: you enter some text in the macro, and that text is read by the parser and sent to the chat window when you press the button.

Something More Interesting

"Roll for Initiative," though scary when your GM utters it, is not all that interesting a macro. You probably thought, "why wouldn't I just type that in chat?" And in fact, the answer is, "you probably would."

So let's do something more interesting, and more in keeping with why we're using MapTool in the first place (after all, we're not here to write programs - we're here to play games).

Now we're going to add some macro commands to the macro, in addition to just plain text. Macro commands are special instructions that, when read by the parser, tell it to do something more than just print text in the chat window, like roll some dice or calculate a value.

Macro commands must always be enclosed in square brackets (e.g, [macro command]) or curly braces (e.g., {macro command}). Enclosing them in this fashion is what clues the parser in that a command is coming - otherwise, it will treat the command just like any other text, and print it in chat.

Roll Some Dice

This is a simple macro that's going to automatically roll some dice, and add a number to that roll, before displaying the whole thing in the chat window.

1. Create a new macro (this can be created anywhere you like - on a token, in the campaign panel, or in the global panel), and open the edit dialog.

2. In the Label field, call the macro something like "Attack Roll" or "Dice Roll"

3. In the Command area, enter:

My attack roll is [1d20+7]!

4. Click OK.

Now, you should see a button labeled with whatever you chose in Step 2, above. When you click it, you'll see something like the following appear in chat:

Chris: My attack roll is 8!

What has happened is that MapTool read through the contents of the macro, and when it got to the section [1d20+7], it knew to:

1. Roll a 20-sided die (or, in reality, choose a random number between 1 and 20), and
2. Add 7 to that result, and
3. Display the results in the chat window, inserted into the text in the right place

You'll see that the number 8 has a gray background. If you hover over that number, a "tooltip" will pop up showing how that number was reached. In this case, I managed to roll a 1 on the 1d20 (bummer! a critical fumble!)

Also, you probably won't see the name "Chris", unless your name happens to be Chris. That part of the chat output is just indicates who "said" that particular bit of text; if it was a token, it would have the token's picture and name instead of boring old "Chris."

More than Just Numbers

Macro commands can work with numbers and with text -- you can manipulate strings (that is, collections of alphanumeric characters) as well using the MapTool macro language. Say, for instance, you wanted to roll your attack, but wanted to enter the name of your target so that it showed up in chat.

What you can do is edit your Attack Roll macro to look like this:

My attack roll against [target] is [1d20+7]!

When you run this macro, though, suddenly a window pops up in your face demanding a "Value For target." What happened?

Well, when MapTool looked at that macro, it saw a macro command that just says [target]. MapTool assumes that any word inside a macro command that is not enclosed in quotes is actually the name of a variable (in other words, a value that might change).

MapTool also noted that nowhere in that macro do we say what the variable target happens to equal. Since MapTool has no way of knowing what target should be, it asks! If you type a name, number, or pretty much anything in that popup window, MapTool will take that information, assign it to the variable target, and finish the macro.

Go ahead and type "Nasty Orcses" (you can leave off the quotes) in the box, and hit OK. You should see in the chat window something like

Chris: My attack roll against Nasty Orcses is 23!

Once again, the parser read through the text and macro commands you put inside the macro, and in the places where a macro command was indicated (by the square brackets, remember), MapTool substituted the appropriate information.

Stepping Up Our Game

The examples above show very basic macro use: printing text to the chat window at the click of a button; making a simple dice roll inside a macro; and even getting some simple input from the user in order to complete a macro.

Now, let's step it up: we'll play with some formatting options, change token properties, and look at some basic looping (doing the same thing over and over again) and branching (doing different things based on some condition or situation).

Formatting Options

Macro output (like any chat output) can be formatted using basic HTML tags, as well as some options built into MapTool. We'll first look at the HTML briefly, and then at a couple Roll Formatting Options.

Expanded Rolls

In MapTool 1.3.b54, the default way to output the result of a dice roll or calculation is just to print out the total or final value. So if you rolled 1d20+7, what will appear in chat is just the final result, with the tooltip (remember when you hovered your mouse over the number) showing the mathematical breakdown.

If you wish, you can instruct MapTool to print out the full math breakdown for a roll too, by using a Roll Formatting Option - specifically, the Expanded Roll.

Think of a formatting option as a switch telling MapTool how to treat the results of a roll. To get the expanded form, edit your attack roll macro to show:

My attack roll against [target] is [e:1d20+7]!

Then, when you run it, you'll get something like this in the chat:

My attack roll against Nasty Orcses is « 1d20+7 = 1 + 7 = 8 »!

Now you can see the full breakdown of your roll.

Result-Only Rolls

But what if you don't want anyone to be able to see the breakdown? So far, both options still let everyone see the actual roll. For this, you use the Result Roll option. Edit your macro to look like this:

My attack roll against [target] is [r:1d20+7]!

And your output will look like this:

My attack roll against Nasty Orcses is 11!

Note that there's no gray background behind the number 11, and you can't get a tooltip if you hover over it. The Results Roll option strips out the special formatting, giving you just the plain text. If you wanted to get rid of the highlight behind the words "Nasty Orcses," you can just change the macro to:

My attack roll against [r:target] is [r:1d20+7]!

And the name of the target will be shown without any special highlighting.

To be continued Rumble 21:36, 1 April 2009 (UTC)