CiF's macro tutorial

This is WORK IN PROGRESS. UNFINISHED. and it has no ETA. :-( FIXME

Creating a macro

What is a macro? It is nothing more than some chat lines stored ready to use again and again. So the traditional „Hello world!“ example would be just that:

  1. Create a new macro (either in campaign or global panel or on any token)
  2. Edit it.
  3. Write the text „Hello world!“ into it.
  4. If you execute this macro now it sends the text you entered to chat.

Note that text in maptool is treated as HTML. You can use html tags do formatting.

This is <b>bold</b> text and this is <i>italic</i><br>
New lines are possible too.


As in chat you can enter commands that are executed. Anything between brackets [] will be evaluated for commands.

I rolled a d6 and got [1d6].

There are many commands and the most complete docs for them is found in the wiki. Of course there are fundamental functions like *, -, +, /

Note that the so called slash command like /me /im /say, that you can use in chat, only work in the very first line of a macro - actually even only in the first executed macro if there will be run several in a chain. If you do any advanced type of macro writing its considered bad practice to use slash commands at all.


Everything inside a command is something maptool can evaluate to a value. If it cant evaluate it further it is added to the output.

There a two basic data type, strings and numbers. Strings are any pieces of text.

["This is a string"]
[1d6] will be evaluated to a number

There are two special cases.

First there is the empty string. Functions sometimes return nothing and this is usually represented as empty string. Note that this is a string and not a number (=0).

Second there are the boolean values true and false. In MT these are always represented by numbers. 0 is always false, anything not 0 is true - usually you use 1.

Roll options

Since this was (times ago) created to perform simple rolls sometimes such a block is called roll. At least it explains why the roll options are called roll options.

You can specify some things like the output behaviour by adding a option to the roll.

The syntax is

[option1, option2, ... optionN: command]

The most important options are the output options. A roll is shown depending on the presets of the running maptool client with or without a tooltip. This can ruin your carefully designed macro.

So you can say in which way a command is shown. Most important ones are

R or result. This shows only the plain text.
H or hidden. This doesnt show any output at all.

There are much more roll options we will cover later.


Inside a macro you can store data and use it later again. A variable has always a name and you use it instead of its content.

Lets create a variable named roll and give it the value of 1d6. Then we multiply it by 10 and add another 1d6 (so rolling a d66).

[H: roll = 1d6]
[H: roll = roll * 10]
[H: roll = roll + 1d6]
You rolled d66 = [R: roll]

After the macro ended all variables are discarded, their values lost. We'll learn later which ways there are to get a value stored for use in another macro.

Token Context

Many functions are related to tokens. To use this maptool must know which token you mean when you execute the macro - or which token is used in context of that macro.

If a macro is placed on a token this token is it. If its a campaign or global macro it would be the impersonated token. If there is no impersonated token than the macro has no token context.

You can set up a macro in a way that the selected token should be used as token contect. For that you have to check the „Apply to Selected Tokens“ checkbox in the macro editor.

There are ways to change the token context with macro code. First there is the token roll option that changes the token context for a given command. Then there is the switchToken function that changes the token context for the remainder of the macro.

To change the context with code you need to have token id (a unique identifier) or the tokens name. There are many functions the give you the ids of different sets of tokens, like the selected ones, all pcs, all visible and so on.

Many functions accept a tokenId as parameter, so you dont have to change the token context at all.

[r: getName()] rolled a d6 = [r: 1d6].

Complex data type


Property lists






Flow control









Calling other macros

Macro roll option

User defined functions


maptool/macrotutorial.txt · Zuletzt geändert: 2011/10/23 11:34 von CoveredInFish
CC Attribution-Noncommercial-Share Alike 3.0 Unported Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0