VariablesWML/How to use variables

WML Variables HowTo (or Descent into Darkness)

In this document, we shall try to explain WML variables and their use with some details. We’ll start under the burning sun of lawful ordinary use, but, step by step, we shall go deeper in the shadows of necromancy, exploring undocumented features and hidden pits as we may. The first part should be understandable by any beginner, but the last one most probably requires a good WML understanding.

Under the burning sun

Variable definitions

This section and the next one can be skipped if you already know what variables are and how to use them. Variables are some kind of container a programmer can use to store pieces of information (s)he needs to manipulate : numbers, names, sentences, and anything else. In most programming languages, variables must be declared before they can be used. Declaration is an instruction giving a name (used later to refer to the variable) and a type, which defines the kind of content of the variable (number, characters strings, and so on). Later in the program, instructions can be used to store and retrieve the content of the container, which is most often called the value of the variable. In WML, variables need no declaration and their value have no precise type¹⁾. This means a new variable will be created at the first time the programmer stores something in it. And that (s)he can store anything in it. Variables use memory, so it’s good practice to clear them when they’re not needed anymore. Variables names are freely chosen by the programmer with some restrictions. They should not be the name of a language instruction (keyword) or operator. In WML, you can use quite any name or sentence to name a variable, but you shouldn’t if you want to shun subtle problems. A classical rule is :

- variable name should begin with a letter

- variable names should only contain letters (not accented) and numbers and the underscore _ character.

No spaces, no accented letters, no special characters, no minus and plus signs, etc… Those names are always safe and correctly interpreted by the engine as variables names. Note that some special characters are forbidden in variable names: $ , . | {} [] = because they have a special meaning we shall see later. I would strongly suggest to avoid common tags names like “event” “side” and too long names like:

“name_of_the_guy_who_killed_the_orc_on_last_turn” which is not the same as:

“name_of_the_gyu_who_killed_the_orc_on_last_turn”, but it’s not really obvious at first glance.

It’s a common error to type wrongly a variable name: in WML this don’t rise any error message, but the variable will have no value, giving most probably what you don’t expect. Last but not least, variables names are case sensitive: in other words, ‘aVar’ is not the same as ‘avar’.

Variables creation and manipulation

Even if WML variables contents have no precise types.¹⁾, we shall discuss two kinds:

- variables holding a single value, like a number, a character string

- variables holding a compound value, i.e. a pack of single values.

They’re often called containers in the documentation. Simple variables are created using the tag [set_variable]:

[set_variable]
    name=simpleVariable
    value=36
[/set_variable]

The tag defines the name and the value of the variable.

Next, we can access the variable value using the variable name prefixed with a dollar sign $.

[modify_unit]
    [filter]
        id=$unit.id
    [/filter]
    moves=$simpleVariable
[/modify_unit]

This sets the moves of the unit to 36 since simpleVariable holds 36.

When the line is executed, the value 36 is substituted to $simpleVariable, so it works as if we wrote:

[modify_unit]
    [filter]
        id=$unit.id
    [/filter]
    moves=36
[/modify_unit]

Using the same tag, we can change the value of simpleVariable, or make some arithmetic (see the tag documentation for the whole list).

For example:

[set_variable]
    name=simpleVariable
    sub=30
[/set_variable]

will change the value to 6 of course. We can even set the variable to another value type:

[set_variable]
    name=simpleVariable
    value="Delfador the Great"
[/set_variable]

We shall not use [set_variable] tag anymore. Instead, we shall use the VARIABLE shortcut:

{VARIABLE simpleVariable "Delfador the Great"}

stands for:

[set_variable]
    name=simpleVariable
    value="Delfador the Great"
[/set_variable]

We shall not use the arithmetic variations of set_variable either. Instead we shall use the formulaAI syntax which is much more natural. Instead of:

[set_variable]
     name=simpleVariable
     value=35
[/set_variable]
[set_variable]
      name=simpleVariable
      add=$anotherVariable
[/set_variable]

we shall write:

[set_variable]
    name=simpleVariable
    value="$(35 + $anotherVariable)"
[/set_variable]

# or

{VARIABLE simpleVariable "$(35 + $anotherVariable)"}

The formulaAI syntax is easy to use, the important thing is to always put the formula in this sequence: “$( … here comes the formula … )” In other words, $simpleVariable can be written everywhere you want to use the value of simpleVariable. Clearing variables can be done using the [clear_variable] tag:

[clear_variable]
    name=simpleVariable
[/clear_variable]

# or using the following macro to delete more than one variable {CLEAR_VARIABLE simpleVariable,anotherOne,count} ²⁾

Containers

What is a container? It is a variable holding more than a simple value. A good example is the unit variable created automatically in moveto and attack events. It contains the full description of a unit, not only its name and its id. Containers are useful to store related values in a pack. All these different values are called “members” of the created container. Instead of writing this:

{VARIABLE heroName "Delfador"}
{VARIABLE heroGold 250}
{VARIABLE heroFame 127}
{VARIABLE heroFullName "Delfador the Great"}

we can pack all this in a “hero” variable using [set_variables] (mark the ‘s’)

[set_variables]
    name=hero
    [value]
        name="Delfador"
        gold=250
        fame=127
        fullName="Delfador the Great"
    [/value]
[/set_variables]

Then, to get the values stored in the container, we shall use the $ sign as before, but appending the member name and a dot:³⁾

$hero.name -> Delfador
$hero.gold -> 250

And if we want to change a value, the “gold” member for instance:

[set_variable]
    name=hero.gold
    add=100
[/set_variable]

It’s important to note that here, we changed the “gold” member as if it was a single variable whose name is “hero.gold”. We can also clear a member of the container in the same way:

{CLEAR_VARIABLE hero.fullName}

This will delete the fullName member permanently. Note it will not only clear the value, but clear the member itself. Clearing the value would be:

{VARIABLE hero.fullName ""}

Can we add later a member to an existing container ? Yes, it can be done:

{VARIABLE hero.hasStaff yes}

this creates the member hasStaff and set it to yes.

A glance into the pit

All this will be clearer if we take a look at the way variables are stored. Opening a savegame with a text editor, we should find a part like this one:

[replay_start]  
    id=""
    [variables]  
        damage_inflicted=18
        heal_amount=10  
        side_number=1  
        turn_number=26  
        x1=8  
        x2=0  
        y1=8  
        y2=0  
        simpleVariable=35  
        [hero]  
            name="Delfador"  
            gold=250  
            fame=127  
            fullName="Delfador the Great"  
        [/hero]  
        ...  

Here are our variables ! We can see simple ones are a pair name/value separated with an equal sign.⁴⁾

Container are stored in a WML block whose name is the variable name. Actually, it’s just like folders and files on your hard disk. Each name/value pair is like a file, and other tags like folders. This explains the syntax used: set_variable and clear_variable operate on name/value pairs, and you use the dot to specify the path to the line you want to create or modify, for example hero.name. Using set_variable creates a line if it exists not. So we can use it to add lines to the hero container using hero.something name, just as we can add a new line at the first level. Now, we can understand better what a container is. It’s a WML block, just as an ordinary tag, and can hold any valid WML content. Look at this:

[set_variables]  
    name=aVar  
    [value]  
        name=capture
        first_time_only=no  
        [filter]  
            side=3  
            type=orc           
        [/filter]  
        [set_variable]  
            name=tmp  
            rand=1..2  
        [/set_variable]  
    [/value]  
[/set_variables]                    

This is perfectly valid and creates this container variable:

[aVar]  
    name=capture  
    first_time_only=no  
    [filter]  
        side=3  
        type=orc  
    [/filter]  
    [set_variable]  
        name=tmp  
        rand=1..2  
    [/set_variable]  
[/aVar]                                                    

We can modify members in the sub blocks too, using the full path to them, separated with dots. For instance:

{VARIABLE aVar.set_variable.rand “1..5”}  

or

{VARIABLE aVar.filter.side 2}.  

Capito ?

We can delete members, values or even whole blocks in the same way:

{CLEAR_VARIABLE aVar.filter.type}

will remove the key ‘type’ in the filter block:

[aVar]  
    name=capture  
    first_time_only=no  
    [filter]  
        side=3  
    [/filter]  
    [set_variable]  
        name=tmp  
        rand=1..2  
    [/set_variable]  
[/aVar]  
 
{CLEAR_VARIABLE aVar.filter } will remove the whole filter block:  
 
[aVar]  
    name=capture  
    first_time_only=no  
    [set_variable]  
        name=tmp  
        rand=1..2  
    [/set_variable]  
[/aVar] 

This example is rather confusing because this variable looks much more like a piece of code than data (and it’s part of the content of an event, of course). But, if you want to follow us to the deeper of darkness, you should already face this ominous truth: data and code are not separated in WML, and it’s possible to modify the code with data manipulation instructions. Fortunately with some limits. Actually, you can only modify from WML what can be put into a variable: units, locations, and some code blocks, but you can’t directly access to scenario level.

A more usual example is the unit container. Moveto events create a unit variable holding the full description of the moving unit. When pushed in your torture room (the ‘unit’ variable) you’re allowed to access any field of the unit. Exact composition of a unit block can be fetched in a savegame or with :inspect in debug mode. It’s rather complex. Here is an example (many lines have been deleted, particularly animations):

[unit]  
    flying=yes  
    gender="female"  
    hitpoints=26  
    id="Lestiviel"  
    image="units/elves-wood/shaman.png"  
    max_experience=26  
    max_hitpoints=26  
    max_moves=5  
    moves=5  
    name=_"Lestiviel"  
    overlays="misc/hero-icon.png"  
    profile="portraits/Lestiviel-y.png"  
    race="elf"  
    [attack]  
        damage=3  
        description=_"staff"  
        icon="attacks/druidstaff.png"  
        name="staff"  
        number=2  
        range="melee"  
        type="impact"  
    [/attack]  
    [attack]  
        damage=3  
        description=_"entangle"  
        name="entangle"  
        number=2  
        range="ranged"  
        type="impact"  
        [specials]  
            [slow]  
                description=_"Slow:"  
                id="slow"  
                name=_"slows"  
            [/slow]  
        [/specials]  
    [/attack]  
    [modifications]  
        [trait]  
            description=_"Zero upkeep"  
            female_name=_"female^loyal"  
            id="loyal"  
            male_name=_"loyal"  
            [effect]  
                apply_to="loyal"  
            [/effect]  
        [/trait]  
        [trait]  
            female_name=_"female^intelligent"  
            id="intelligent"  
            male_name=_"intelligent"  
            [effect]  
                apply_to="max_experience"  
                increase="-20%"  
            [/effect]  
        [/trait]  
    [/modifications]  
[/unit]

Here we have a problem: this unit has two attack blocks and two traits blocks. How can we access them ? Writing only $unit.attack.name can’t be correct since we have two blocks. We have here our first example of arrays. Arrays are lists of WML blocks sharing the same name (here attack or modifications.trait). The blocks in arrays are implicitly numbered in the order they are written, and we can use this index to state which one we want:

$unit.attack[0].name -> "staff"  
$unit.attack[1].name -> "entangle"  
       
$unit.modifications.trait[0].id -> "loyal"  
$unit.modifications.trait[1].id -> "intelligent"

Mark indexes begins with 0. So, can we modify the value of the intelligent trait using VARIABLE ? Yes, just do it:

{VARIABLE $unit.modifications.trait[1].increase "-50%"}

Does this modification apply to the unit ? Not immediately. You should use [unstore_unit] first to pull them out of your torture room, and then… well, it works for some values, but not all of them. There is an automatic healing process at work and some unit properties are overwritten when [unstore_unit] happens, but the variable itself is really changed. You can verify this using :inspect.

More with arrays

Arrays can be created using the [set_variables] tag. In it, we can repeat the [value][/value] block at will, and this will create a container array:

[set_variables]  
    name=heroes  
    [value]  
        name="Delfador"  
        gold=250  
        fame=127  
        fullName="Delfador the Great"  
    [/value]  
    [value]  
        name="Konrad"  
        gold=125  
        fame=10  
        fullName="Konrad the Heir"  
    [/value]  
    [value]  
        name="Lisar"  
        gold=1258  
        fame=250  
        fullName="Princess Lisar"  
    [/value]  
[/set_variables]  

This will create three [heroes] blocks numbered from 0 to 2.

[heroes]  
    name="Delfador"  
    gold=250  
    fame=127  
    fullName="Delfador the Great"  
[/heroes]  
[heroes]  
    name="Konrad"  
    gold=125  
    fame=10  
    fullName="Konrad the Heir"  
[/heroes]  
[heroes]  
    name="Lisar"  
    gold=1258  
    fame=250  
    fullName="Princess Lisar"  
[/heroes]

Arrays all have a special property named length. It holds the number of blocks in the array. So here:

$heroes.length -> 3   

$unit.modifications.trait.length -> 2

(from the previous ‘unit’ example)

Another way to create arrays is using [store_unit] and [store_locations] tags, or [set_variables] when using the split key to split a string.

All these arrays can be modified: we can add later a block or delete it. Deletion is done with the [clear_variable] tag:

{CLEAR_VARIABLE heroes[1]}  

This will delete the Konrad record. Please note that the array will be renumbered: so the Lisar record will now have the index 1.

Adding blocks can be done with [set_variables] using the additional key mode. By default, [set_variables] creates a new array (or container), erasing any previous variable with the same name. But, using one of the different modes allows to add new blocks in various places:

• replace: will clean the array name and replace it with given data, it’s the default.
• append: will append given data to the current array
• merge: will merge in the given data into name
• insert: will insert the given data at the index specified in the name attribute, such as

name=my_array[1].

Note that [store_unit] has also a mode key allowing to append more units blocks to an array.

You can place any kind of block in an array, but usually, it’s good practice to avoid meddling different kind of records (for instance units and locations). The reason is most often, arrays are fetched and manipulated in loops. Loops are much more easy to program when all records have the same structure. The FOREACH macro is most often used for this purpose. It takes an array name and a variable name as arguments. The variable will contain an index incremented by one on each step of the loop by the ending macro NEXT. For instance, we can summarize the wealth of our heroes with this code:

{FOREACH heroes index}  
    [set_variable]  
        name=tmp  
        add=$heroes[$index].gold  
    [/set_variable]  
{NEXT index}  

[message]  
    speaker=narrator  
    message="Team has $tmp gold."  
[/message]  

Here, we accumulate the gold amount of our heroes in the variable tmp. The loop will begin with index=0 and repeat the code inserted between FOREACH and NEXT, incrementing the value of index by one and will stop when index=heroes.length. FOREACH is easy to use, but one should be aware of two things:

- make sure you don’t use the index variable elsewhere: it shall be cleared at the end.

- when using such a loop to delete some records. For instance this:

{FOREACH heroes index}  
    [if]  
        [variable]  
            name=heroes[$index].name  
            equals="Konrad"  
        [/variable]  
        [then]  
            {CLEAR_VARIABLE heroes[$index]}  
        [/then]  
    [/if]  
{NEXT index}  

will not work exactly as expected. As we saw earlier, the array will be renumbered when the “Konrad” record is deleted. So the next record will take the “Konrad” index, and, since index is incremented at the end of the step, the record following “Konrad” will be skipped. The correct way to do this is fetching the array in reverse order⁵⁾ or decrementing the index after the deletion:

{FOREACH heroes index}  
    [if]  
        [variable]  
            name=heroes[$index].name  
            equals="Konrad"  
        [/variable]  
        [then]  
            {CLEAR_VARIABLE heroes[$index]}  
            [set_variable]  
                name=index  
                sub=1  
            [set_variable]  
        [/then]  
    [/if]  
{NEXT index}

First steps into darkness

Using simple strings in names

Consider this variable name:

heroes_$index  

How to understand this? At execution time, $index will be replaced with the value of the variable index⁶⁾. Suppose it contains 2, the variable used will then be heroes_2. Of course, it can be anything else, “Konrad” for instance. Then the variable will be heroes_Konrad.

Look at these macros:

#define LSB_STOREPERSO ID KILL  
    [store_unit]  
        [filter]  
            id=${ID}  
        [/filter]  
        variable=${ID}_back  
        kill={KILL}  
    [/store_unit]  
#enddef

#define LSB_RECALLPERSO ID XY  
    [unstore_unit]  
        variable=${ID}_back  
        find_vacant=yes  
        {XY}  
    [/unstore_unit]  
#enddef

They store and retrieve an unit using it’s ID to create the name of the variable. The unit ID is found in the variable whose name is given in the parameter ID. For instance, it can be unit.id in a moveto event:

[event]  
    name=moveto  
    # ... the filter will come here  
    {LSB_STOREPERSO unit.id yes} # the unit disappear  
    # but is stored in a variable named after its id,  
    # for instance "Konrad_back"  
[/event]  

The variables created using this code shouldn’t be confused with an array. They’re individual variables, even if they look more or less the same in the :inspect display. Particularly, they can’t be fetched using a FOREACH loop. But if this is not needed, one can find this better to create bi-dimensional arrays, particularly because distinct records are easier to identify in the :inspect display. In this code, we use quite the same system as above to create a bi-dimensional array to store boats and units on board. The unit ID (of the boat) is used to create the name of an array storing the units it contains, whose name is RF_$ID, for example RF_B1, RF_B2 and so on. So, in a moveto event of one of these boats, RF_$unit.id is the name of the array containing the crew. This code make them pop out.

{FOREACH RF_$unit.id| n}  
    [unstore_unit]  
        variable=RF_$unit.id|[$n]  
        x,y=$rft[0].x,$rft[0].y  
        find_vacant=yes  
    [/unstore_unit]                     
{NEXT n}

Fine, but here, the engine could have a problem: what is exactly RF_$unit.id[$n] ? It can be :

- the nth record of the array RF_$unit.id (if unit.id = B1, it would be RF_B1[$n])

- the simple variable named RF_$unit.id[$n], where the suffix is taken from $unit.id array.

That’s why the pipe character | is appended to the array name. It states the first case is the good one, or in other words, the array name is delimited between the $ sign and the pipe.

This is one way to create and use bi-dimensional arrays. But it’s possible to create real bi- dimensional array: they are arrays containing arrays (which could contain arrays as well, and so on… but will you really need that ?) Here is the way to do this. We shall use here our “heroes” array, and store it twice into a new created array:

[set_variables]  
    name=biDim  
    [insert_tag]  
        name=value  
        value=$heroes  
    [/insert_tag]  
    [insert_tag]  
        name=value  
        value=$heroes # of course it could be something different  
    [/insert_tag]  
[/set_variables]  

Insert_tag creates a new block whose tag is equal to its name key, so each insert_tag will create a block:

[value]  
    [heroes]  
        name="Delfador"  
        gold=250  
        fame=127  
        fullName="Delfador the Great"  
    [/heroes]  
    [heroes]  
        name="Konrad"  
        gold=125  
        fame=10  
        fullName="Konrad the Heir"  
    [/heroes]  
    [heroes]  
        name="Lisar"  
        gold=1258  
        fame=250  
        fullName="Princess Lisar"  
    [/heroes]  
[/value]  

Still with us? OK, now to access our heroes we shall use the ordinary syntax. For instance:

$biDim[0].heroes[1].name -> Konrad  
 

And of course, one can walk all the array using a nested FOREACH loop.

{FOREACH biDim i}  
    {FOREACH biDim[$i].heroes index}  
        [if]  
            [variable]  
                name=biDim[$i].heroes[$index].gold  
                less_than=100  
            [/variable]  
            [then]  
                [set_variable]  
                    name=biDim[$i].heroes[$index].gold  
                    add=100  
                [/set_variable]  
            [/then]  
        [/if]  
    {NEXT index}  
{NEXT i}  

This adds some gold to the purse of the poorest heroes of biDim array.

Using variables strings in events names

This syntax:

[event]  
    name=$myEvent  
    ...  
[/message]  

Is perfectly valid. Of course, myEvent should contain some valid event name, consistent with the event body. One use of this is to specify turn numbers. For instance:

[event]  
    name=turn $afterDark  
    ...  
[/event]

With this you can set afterDark in order to state when the event should fire (it must then contain a number or a string of the form side number). Even more useful is the way to fire an event some turn after another occurred. Suppose we want to raise a storm two turns after some hero visited a particular location. Then we shall write:

[event]  
    name=moveto  
    # ... the moveto filter will come here  

    [event]  
        name=turn "$($turn_number + 2)"  

        # start the storm  
    [/event]  
[/event]  

This will create the nested event and make it fire 2 turns later. It can be used with fire_event too. This code sets the variable myEvent according to the incomer type, then fires the corresponding event.

[switch]  
    name=unit.type  
    [case]  
        value=Elvish Sorceress  
        {VARIABLE myEvent storm}  
    [/case]  
    [case]  
        value=Troll Warrior  
        {VARIABLE myEvent monster}  
    [/case]  
    [case]  
        value=Mermaid Initiate  
        {VARIABLE myEvent flood}  
    [/case]  
[/switch]  

# --- somewhat later…  
[fire_event]  
    name=$myEvent  
[/fire_event]  

# ... of course, these events should be defined elsewhere  
[event]  
    name=storm  
    ...  
[/event]

[event]  
    name=monster  
    ...  
[/event]

[event]  
    name=flood  
    ...  
[/event]

Voodoo and black magics

« He who enters this place must quit all hopes… »

At this point, maybe you begin to suspect many things can be replaced with variables, including parts of the code itself. That’s true and interesting in some cases, but it should be

clear that using the features explained later creates code much more difficult to understand and to debug. You certainly shall discover that much more can be done than what we describe, but here, we shall restrain ourselves to some limits. Trespassing them is most often getting caught in mysterious traps, and most often, absolutely useless. In other words, you’re at risk to fall into deep darkness under heavy bugs attack. So take care…

Existing blocks customization

Since we can add members to existing containers, why not add some to documented containers like units or objects ? It’s perfectly possible, and finally harmless (You’re only are at risk your code become broken if the key name is used in further versions of Wesnoth) ⁷⁾ . WML just ignores what it knows nothing of. In units blocks, you have a special block named variables where you can add safely all what you want, but it’s common to find in campaigns additions to the status block. For instance:

{VARIABLE unit.status.isHero yes}

creates a new flag named isHero in unit status. Of course, the game engine will not display anything as it does with slow and poison status key, but you can use it in filters:

[event]  
    name=die  
    first_time_only=no  
    [filter_condition]  
        [variable]  
            name=unit.status.isHero  
            boolean_equals=yes  
        [/variable]  
    [/filter_condition]  
     …  
 

The same can be done in objects. In this object block, the programmer added two custom keys, category and price.

[object]  
    name= _ "Poisonous Bow"  
    image=items/bow.png  
    description= _ "This bow deals 20% more damage than other bows, it shots poisonned arrows to enemies and is also quicker."  
    category=bows  
    price=150  
    [effect]  
        apply_to=new_attack  
        name=longbow  
        type=pierce  
        range=ranged  
        damage=12  
        number=4
        movement_used=0  
        icon=attacks/bow-elven-magic.png  
        [specials]  
            {WEAPON_SPECIAL_POISON}  
        [/specials]  
    [/effect]  
[/object] 

And when this object is applied to an unit, the extra keys are not deleted or modified in any way.

Passing “parameters” to an event

The trick explained here is for use with the fire-event tag. As you know, this tag allows to trigger an event (custom or not) from another piece of code. Really useful for instance, when you don’t want to repeat the same code in many places. As the reference manual says, it can be used as some sort of subroutine call. Fine, but in programming languages, subroutines calls accept parameters for use of the subroutine, and fire_event don’t. Suppose we want to display a nice message which can be spoken by various units. Of course, we can use role or a global variable whoSpeaks to specify who is speaking. For instance:

[event]  
    name=nice_speech  
    [message]  
        speaker=$whoSpeaks  
        message=_"Vanish, foul messengers of Sauron…" # and so on…  
    [/message]  
[/event]  

We can fire this event with:

{VARIABLE whoSpeaks Gandalf} # or any other character  
[fire_event]  
     name=nice_speech  
[/fire_event]

But we would have to clear the whoSpeaks variable later. There is another way. In the fire_event tag documentation, one can find: [primary_attack]: Information passed to the primary attack filter and $weapon variable on the new event.

Of course, we have no attacker and no attack here, but what happens if we set something here  

like :

[fire_event]  
    name=nice_speech  
    [primary_attack]  
        whoSpeaks=Gandalf  
    [/primary_attack]  
[/fire_event]  

[event]  
    name=nice_speech  
    [message]  
        speaker=$weapon.whoSpeaks  
        message=_"Vanish, foul messengers of Sauron…" # and so on…  
    [/message]  
[/event]

Well, it pure voodoo but it works. Of course, one can pass anything in the primary_attack block, not only a single value. The block itself will be discarded when he event is finished, just like call parameters in subroutines.

Dynamic code with insert_tag

We have already seen a use of this tag above. Its effect is to insert at execution time a WML block contained in a variable. It is like a macro, but macro substitution occurs once when loading the code which makes a huge difference. With insert_tag, the variable used (i.e. the code executed) can change during the scenario. First step is creating a container holding the WML block you want to execute. For instance, this action:

[harm_unit]  
    [filter]  
        x,y=$x1,$y1  
    [/filter]  
    amount=10  
    animate=yes  
    kill=no  
[/harm_unit]   

The easiest way is to use a macro to define the block content:

#define BLOCK_CONTENT  
    [filter]  
        x,y=$x1,$y1  
    [/filter]  
    amount=10  
    animate=yes  
    kill=no  
#enddef  
   
    [set_variables]  
        name=harmingCode  
        [value]  
            {BLOCK_CONTENT}  
        [/value]  
    [/set_variables]  

Else, we should have to create the variable first, and then add the subtag in this way:

[set_variables]  
    name=harmingCode  
    [value]  
        amount=10  
        animate=yes  
        kill=no  
    [/value]  
[/set_variables]

[set_variables]  
    name=harmingCode.filter  
    [value]  
        x,y=$x1,$y1  
    [/value]  
[/set_variables]  

Mark we didn’t include the [harm_unit] tag. Then we can use insert_tag in this way:

[insert_tag]  
    name=harm_unit  
    value=$harmingCode  
[/insert_tag]  

This will produce exactly the original block above. Sometimes, it’s not very practical to define only the block content in the macro (maybe you would like to use it elsewhere, as an ordinary macro). Then you can specify the command tag in the insert_tag. This tag does nothing except creating blocks. Then it would be:

#define HARM_UNIT  
   [harm_unit]  
        [filter]  
            x,y=$x1,$y1  
        [/filter]  
        amount=10  
        animate=yes  
        kill=no  
    [/harm_unit]  
#enddef  

    [set_variables]  
         name=harmingCode  
         [value]  
             {HARM_UNIT}  
         [/value]  
    [/set_variables]  

    # --- somewhere else…  

    [insert_tag]  
        name=command  
        value=$harmingCode  
    [/insert_tag]

But… this code works not always. The reason is the $x1, $y1. They are replaced with their values when we create the harmingCode variable, which is not what we generally want. We want to use the values they hold when the insert_tag is executed (most often, it’s later), in other words, we want to delay their substitution. To mark these variables to be substituted later , we shall add a pipe character just after the dollar sign:

#define HARM_UNIT  
    [harm_unit]  
        [filter]  
            x,y=$|x1,$|y1  
        [/filter]  
        amount=10  
        animate=yes  
        kill=no  
    [/harm_unit]  
#enddef  

Then the code works. And the macro can be used in a normal way too. Mark insert_tag must be included in some action (event and so on). It works not at the scenario level for instance. As you can see, the insert_tag allows to do many things, but in our opinion, should be used scarcely. Here we shall show how it can be used to solve a common problem. Suppose we want to list the objects of a unit in a option message, let the user choose an object and remove it from the unit. This can be done with this kind of code:

[message]  
    message="Choose an item to drop"  
    speaker=narrator  
    [option]  
        message="Fabulous speed potion"  
        [show_if]  
            # here a conditional expression stating if the unit has  
            # the fabulous item.  
        [/show_if]  
        [command]  
            # ... drop the item  
        [/command]  
    [/option]  
        # more options blocks...                            
[/message]  

The show_if tag prevents the line to show if the unit has not the object. There are two problems with this code. First, the condition is not easy to write: the object list of the unit must be searched for that particular object. Next, the message block must have an option for each possible item. No problem if you have only a few, but when, like in some add-ons we shall name not, you have near one hundred… Here, we shall create dynamically a message block listing all the objects in the modification block of the unit. Thus, we don’t need the show_if tag et we want something like that:

[message]  
    message="Choose an item to drop"  
    speaker=narrator  
    [option]  
        message="Fabulous speed potion"  
        [command]  
            # ... drop the item  
        [/command]  
    [/option]  
    [option]  
        message="Amazing flashing bow"  
        [command]  
            # ... drop the item  
        [/command]  
        [/option]  
            # ... more options if more objects  
        [option]  
            message="Exit"  
        [command]  
            # ... exit the loop  
        [/command]  
    [/option]  
[/message]  

So we shall create dynamically this block in a container variable and next use insert_tag to execute it. The block itself is embedded in a loop which executes until the exit option is chosen (this sets the flag t_done):