1. It is placed at the beginning of a macro command
2. It is followed by a colon
   1. If more than one roll option is used, they are separated by commas, and the last one is followed by a colon
3. After the colon, you place the operation you want to do every time the loop runs

[count(repetitions): command]

[c(repetitions): command]

• The [count():] option itself - without the option, we wouldn't need this tutorial, right?
• repetitions: this is the value that tells [count():] how many times to repeat command
• command: this is the actual macro command you want count to do over and over again.

1. [h:attackBonus = 7]

3. Toxic Cloud: [count(numAttacks): 1d20+attackBonus]

• Line 1 sets a value for attackBonus, to be used later.
• Line 3 sends the text "Toxic Cloud: " to chat, and then, begins the Count Loop. Since numAttacks is undeclared, MapTool will prompt you for a value before it can start the loop. Once you enter that value, the count loop will process the calculation of 1d20+attackBonus that many times, sending the result to chat each time, and separating each result with a comma.

Toxic Cloud: 17, 19, 12, 8

1. [h:attackBonus = 7]

3. Toxic Cloud vs:<br>

5. [c(numAttacks, "<br>"),CODE:

6. {

7.    [attack = 1d20+attackBonus]

8.    [damage = 1d6 + 2]

9.    Target [r:roll.count]: Attack [r:attack]; [damage] damage.

10. }]

• Line 1 still just sets attackBonus to 7, so we can use it later.
• Line 3 outputs "Toxic Cloud vs:
  " to chat (the <br> part sends a line break to chat, meaning that the next output will start on the line below the words "Toxic Cloud vs:")
• Line 4 starts a more complex Count Loop. First off, we used the abbreviation for "count", which is just c. We left numAttacks as is, but added a second argument - in this case, a different "separator." All loops in MapTool macros have a default separator, which is the comma. However, you don't always want to separate your results with a comma, right? In this situation, we want to separate them with a line break, so each result is on its own line in chat. So, we put the new separator in - an HTML line break character, or <br>.
• Line 4 also uses the CODE roll option, which is discussed in Introduction to Macro Branching, and lets us do multiple operations as a single group.
• Line 6 sets the variable attack to the sum of attackBonus and 1d20.
• Line 7 sets the variable damage to the sum of 1d6+2.
• Line 8 is a combination of text and variables, which are output to chat. Note that the variable roll.count is in there, which will be replaced with whatever iteration the loop happens to be on.
• Line 9 closes the CODE block, and the whole command.

Toxic Cloud vs:
Target 1: Attack 17; 6 damage.
Target 2: Attack 12; 5 damage.
Target 3: Attack 19; 7 damage.
Target 4: Attack 10; 3 damage.

[while(condition): command]

• [while():]: of course, we need to add the roll option itself
• condition: this is the comparison that we make, to see if the loop needs to stop - it can be any of the logical comparisons we've discussed already (such as, loops < 10 or numDice > 5 or anything you can think of).
• command: the macro command (or commands, if you use the CODE option) to run each time the loop goes 'round.

• A character has a machine gun with 30 rounds of ammunition
• They may fire one to six rounds for every action
• If their attack roll of 1d20 is greater than 15, they may make another attack; otherwise, they must end their turn. They always get at least 1 attack, though.

So what we need to do is repeat the operation until either the weapon runs out of ammo, or they roll less than a 15 on their attack. Here's how that macro would look:

1. [h:ammo = 30]

2. [h:hit = 1]

4. [while(ammo > 0 && hit == 1, "<br>"),CODE:

5. {

6.   [h:attackRoll = 1d20]

7.   [h:ammoSpent = 1d6]

8.   [h,if(attackRoll > 15): hit = 1; hit = 0]

9.   [h:ammo = ammo - ammoSpent]

10.   Your first attack expends [r:ammoSpent] rounds, and [if(hit==1, "hits.", "misses.")] You have [r:ammo] rounds remaining.

11. }]

13. [if(hit==0): "Your turn ends because you missed a target."]

14. [if(ammo==0): "Your turn ends because you are out of ammo."]

• Line 1 and 2 set two important variables: ammo and hit. We set ammo to 30, per the assumptions above, and we set hit to 1, so that the character always gets at least one attack roll (if we didn't set hit to 1, the loop might stop before it started!).
• Line 4 is the start of the While Loop: we establish the loop, and give it a combined condition. We say that while ammo has a value greater than 30, and (remember, two ampersands is the logical operator "and") hit is equal to 1, the loop should go 'round. If either or both of those is not true, then the loop should stop. Also, we set the separator to <br>, so that a new line will be printed each time the loop runs.
• Lines 5 - 9 handle the actual loop processing. Note that in that loop, we make sure to set a new value for hit and ammo - this is critical. If you never change the variables that your conditions are based on, then your loop will never stop.

Your attack expends 6 rounds, and hits. You have 24 rounds remaining.
Your attack expends 2 rounds, and hits. You have 22 rounds remaining.
Your attack expends 3 rounds, and misses. You have 19 rounds remaining. Your turn ends because you missed a target.

• [for():]: as always, we need to actually put the roll option in there
• counter: this is the variable that will be used to count the iterations through the loop; typically people us a simple 1-letter variable in here, like x or i. For examples below, we'll use i.
• start: this is what the counter variable starts at (it can be zero, another variable, or any other numeric value)
• end: this is the value that ends the loop
  • In a loop where the counter variable is increasing - in other words, a loop with a positive stepsize - the loop runs as long as counter is less than end
  • In a loop where the counter variable is decreasing- in other words, a loop with a negative stepsize - the loop runs as long as counter is greater than end
• stepsize: this is how big the increment is for each iteration of the loop (for example, if you set stepsize to 2, then counter will increase by 2 ever iteration). The default stepsize is +1 (that is, by default, the counter variable increments by 1 each time the loop is processed).
• separator: like with [count():] and [while():], this is an optional separator to show between each output line from the loop; the default is a comma.

• The counter variable is i.
• The start value is 10
• The end value is 0
• The stepsize is -2 (the counter decrements by 2 every time the loop processes)

• theList is simply a string list variable containing four elements
• listCount() is a function that, when you put the name of a string list variable in it, will return the number of elements in the string list
• We create the beginning of an HTML table by using the <table> tag
• The [for():] loop here uses the counter variable i, which starts at 0, and counts up until it reaches numberOfRows. It increases by 1 each loop, and the default separator has been changed to "" so that no extraneous commas are printed to chat.
• Inside the loop, we concatenate the HTML tags for table rows and table cells around the function listGet(). This function will retrieve, from a string list variable, the value of the element that is at the position specified in the second argument. In this case, we say, "get from the variable theList the value of the element that's in the same position as i" - so that it starts with element 0 (all lists start at item 0 in MapTool) and each time we loop through, it gets the next element.
• At the end, we close the table with the appropriate HTML tag.

The [for():] loop structure lets you repeat a set of commands a specified number of times, with flexible beginning, ending, and steps. That looping method is applicable to many things, and can be looked at as a very "general" way to loop - it gives you lots of flexibility with where you start and end, and can be used for many operations.

However, frequently loops are used to go through a list of items that is already established, and it is kind of a pain to have to make sure to count each list, then assign the variables in a [for():] loop, and make sure you can figure out how the counter variable corresponds to the position of an item in a list. So, a different kind of for loop - one that handles most of that without bothering you about it - also exists. This one is called [foreach():].

In a [foreach():] loop, the looping structure is given two arguments: the name of a string list, and a variable. The variable takes on the value of each element in the list, in turn, as the looping structure iterates. That's a bit confusing, so first, let's look at the general structure of a [foreach():] loop:

• [foreach():]: once again, the roll option itself.
• item: this is the variable that takes on the value of each successive element in the list or property
• list: this is the string list you want the foreach() to work on
• command: the operation you want performed on each successive item in list

To explain that in plain English: assume for a moment that there you have the names of several targets (NPC tokens) that your character wants to attack at the same time. You need to make an attack roll against each target, which is equal to 1d20 + 7, but you have to roll separately for each target.

You could write out the attacks each time like this:

And so forth and so on. Not so bad if you have 3 targets. But what if you have 6? Or 12?

So instead, what if you created a single variable that was a list of the names of each target? Then, you can use the [foreach():] loop to go through the list one by one and let you make the roll with a very efficient little bit of code. [foreach():] may be a little hard to explain, but once you understand what it can do, you will see how useful it can be!

Now, let's jump to some examples.

This simple example will go through a string list, and list the value of each element in the list, from beginning to end.

In the above macro, we've created a [foreach():] loop that takes the list variable theList, and goes to each element in that list, and assigns the value of that element to the variable item. We've set the separator to the HTML code for a line break, and then -- after the colon -- instructed the macro to print the value of the variable item to the chat window.

The output of that macro looks like:

Do you see what happened there? The foreach() option went to each element in theList, said, "the variable item is now equal to the element," and then printed the value of item to chat.

Now, let's look at the example described in the beginning. Remember how we had those target names to attack? Here's how we'd do that:

[h:targetList = "Orc 1, Goblin 2, Orc 4, Zombie 17, Big Boss"]
 
[foreach(target, targetList, "<br>"),CODE:
{
   [h:attackRoll = 1d20+7]
   I attack [r:target] with an attack roll of [r:attackRoll]
}]

• The first line simply sets up the variable targetList, as discussed.
• The foreach loop goes through each element in targetList, assigning its value to the variable target. So, the first time through, target has the value of the first item in targetList - in other words, target is equal to Orc 1. The second time through, target equals the second item in the list, and so on.
• The [code():] roll option is used so we can execute multiple commands (and because it sometimes makes formatting the output a little easier)
• Inside the CODE brackets, we calculate a variable called attackRoll. This is recalculated on every loop, so it's different for each target.
• Finally, we generate some chat output, inserting the variable target and the variable attackRoll in the appropriate places.

The output of that macro, when sent to chat, looks like:

I attack Orc 1 with an attack roll of 12
I attack Goblin 2 with an attack roll of 11
I attack Orc 4 with an attack roll of 21
I attack Zombie 17 with an attack roll of 17
I attack Big Boss with an attack roll of 9

That about covers the looping basics for MapTool macros. The examples shown above are very simple, of course - just enough to show you how these work. But looping is incredibly useful for many applications in a MapTool macro, from generating multiple die rolls to building tables to editing token properties, so make sure to experiment with it.