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 Wesnoth_Formula_Language 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 Wesnoth_Formula_Language 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] (notice 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"

Note: 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.

Using arrays

Now that we understand containers (read the previous section if you skipped that), it's time to move on to 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.

(Version 1.13.2 and later only) This explanation of loops is still relevant, but it's now recommended to use the [for] or [foreach] tags instead of the FOREACH macro.

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}

More with arrays

Let's say we want our Trapper unit to be able to put traps all around the map. Each trap position is saved as a location, a container with x and y values, stored using [store_locations]. We have stored all our trap positions in this variable "trap_pos", but now we want to add another location where the Trapper is currently standing ($x1, $y1). How would we do that? Here is one simple way, using find_in:

[store_locations]
    x=$x1
    y=$y1
    [or]
        find_in=trap_pos
    [/or]
    variable=trap_pos
[/store_locations]

Continuing the example above, what if our Trapper had a change of heart, and now he wants to remove the trap where he is standing? He can easily remove that position from the "trap_pos" array, again by using find_in:

[store_locations]
    find_in=trap_pos
    [not]
        x=$x1
        y=$y1
    [/not]
    variable=trap_pos
[/store_locations]

Now the final piece is an event that will catch any unsuspecting unit who dares to step upon our well-placed traps:

[event]
    name=moveto
    first_time_only=no
    [filter]
        [filter_location]
            find_in=trap_pos
        [/filter_location]
    [/filter]
    # Boom! Gotcha
[/event]

The same find_in trick for growing and shrinking arrays of locations can also be used with arrays of units, using the find_in key of [store_unit].

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  
        variable=heroes  
    [/insert_tag]  
    [insert_tag]  
        name=value  
        variable=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]

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

[insert_tag]  
    name=harm_unit  
    variable=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  
        variable=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. Another way to avoid the early variable substitution is using the tag literal instead of value when creating the harmingCode variable:

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

Pay heed, 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):

# list unit objects  
#define LSB_LIST_UNIT_THINGS  
   {VARIABLE t_done no}  

    [while]  
        [variable]  
            name=t_done  
            equals=no  
        [/variable]  
        [do]  
            {CLEAR_VARIABLE t_menu}  
            {VARIABLE t_menu.message " Choose an item to drop:"}  
            {VARIABLE t_menu.speaker narrator}  
 
# here begins the objects listing. They are in the modifications block of the unit  
            {FOREACH unit.modifications.object nc}  
                # creates the option block with the name of the object  
                [set_variables]  
                    name=t_menu.option  
                    mode=append  
                       [value]  
                           message=$unit.modifications.object[$nc].name  
                           [command]  
                               # remove the object, or anything else  
                               {LSB_CLEAR_UNITOBJECT}  
                           [/command]  
                        [/value]              
                [/set_variables]  
            {NEXT nc}  

# this adds the “exit” option to the end of the list  
            {VARIABLE nc $t_menu.option.length}  
                [set_variables]  
                    name=t_menu.option  
                    mode=append  
                    [value]  
                        message="Exit."  
                        [command]  
                            {VARIABLE t_done yes}  
                        [/command]  
                    [/value]              
                [/set_variables]  

# this finally displays the list on screen and let the user choose  
                [insert_tag]  
                    name=message  
                    variable=t_menu  
                [/insert_tag]  
            [/do]  
        [/while]  
    {CLEAR_VARIABLE t_menu,nc}  
#enddef  

# this is an example of use: in a right-click menu item.  
    [set_menu_item]  
        id=LSB_drop  
        description="Drop items."  
        [show_if]  
            [variable]  
                name=unit.side  
                equals=1  
            [/variable]  
        [/show_if]  
        [command]  
            {LSB_LIST_UNIT_THINGS}  
        [/command]  
    [/set_menu_item]

Of course, you may want to list not all objects applied to a unit. It’s easy to do that adding a custom key to the objects you want to list, for instance droppable=yes, and testing if it is present before creating the option block.

Another example of code managing pickuppable items on the map. We first define those objects using macros. For instance, this one is the core Storm Trident with some additional keys. The [object] tag is missing in order to use this macro more easily in an [insert_tag].

# --- Object definition example, don’t include the [object] tag  
#define LSB_STORM_TRIDENT  
    name="storm trident"  
    image=items/storm-trident.png  
    duration=forever  
    description={RTN_USTR-6}  
    category=spears  
    level=2  
    [effect]  
        apply_to=new_attack  
        name="storm trident"  
        description="storm trident"  
        icon=attacks/lightning.png  
        type=fire  
        range=ranged  
        [specials]  
            {WEAPON_SPECIAL_MAGICAL}  
        [/specials]  
        damage=15  
        number=2  
    [/effect]  
 
    {LIGHTNING_ANIMATION "storm trident" 1}  
    {LIGHTNING_ANIMATION "storm trident" 2}  
    {LIGHTNING_ANIMATION "storm trident" 3}  
#enddef

At the beginning of the scenario or even the campaign, we define an object list containing all pickuppable items. Please note it’s the only place we need to modify when creating or deleting an object in our campaign. All the code needed to manage them is generic.

# --- shortcut to store an object into an array  
#define LSB_OBJINFO OBJ  
    [value]  
        {OBJ}  
    [/value]  
#enddef  
  
# This is the main objects list which must be created at first start: it creates an array with all pickuppable items and give them an uid.  
#define LSB_CREATEOBJECTS_LIST  
    [set_variables]  
        name=Objets  
        mode=replace  
        {LSB_OBJINFO {RTN_OBJ_TELNECKLACE} }  
        {LSB_OBJINFO {RTN_OBJ_AELTHRANK} }  
        {LSB_OBJINFO {LSB_GOLD} }  
        {LSB_OBJINFO {LSB_STORM_TRIDENT} }  
        # add more here at will  
    [/set_variables] 
 
    {FOREACH Objets i} # this adds an id to objects  
        [set_variable]  
            name=Objets[$i].uid  
            value=$i  
        [/set_variable]  
    {NEXT i}  
#enddef

Here a macro to drop objects on the map. Note the NUM parameter is the uid created before, not the full object itself. Of course, it can be a variable holding an uid.

#define LSB_DROP_OBJECT NUM X Y  
    [item] # place the item on the map  
         image=$Objets[{NUM}].image  
         x,y={X},{Y}  
    [/item]  
    [set_variables] # add it to the dropped objects list  
        name=D_Objets  
        mode=append  
        [value]  
             x={X}  
             y={Y}  
             code={NUM}  
        [/value]              
    [/set_variables]  
#enddef

At last, we can set up a moveto event to trigger the pick up dialog

#define LSB_GETOBJECT FILTER ID  
    [event]  
        name=moveto  
        id=GETOBJECT_{ID}  
        first_time_only=no  
        [filter]  
            [filter_location] # fires only if there is something on the map  
                find_in=D_Objets  
            [/filter_location]  
            {FILTER} # and for some units  
        [/filter]  

        {VARIABLE i $D_Objets.length}  
        [while] # maybe we have more than one object here  
            [variable]  
                name=i  
                greater_than=0  
            [/variable]  
            [do]  
                [set_variable]  
                    name=i  
                    sub=1  
                [/set_variable]  
                
# message  
                [if]  
                    [variable]  
                        name=D_Objets[$i].x  
                        equals=$x1  
                    [/variable]  
                    [variable]  
                        name=D_Objets[$i].y  
                        equals=$y1  
                    [/variable]  
                    [then]                         
                        [message]  
                            speaker=narrator  
                            message=_ "There is a $Objets[$D_Objets[$i].code].name on the ground. Should $unit.name take it ?"  
                            [option]  
                                message=_ "Take it"                                         
                                [command]                                     
                                    # --- give object to unit  
                                    [insert_tag]  
                                        name=object  
                                        variable=Objets[$D_Objets[$i].code]  
                                    [/insert_tag]  
                                             
                                    # --- clear the map  
                                    [remove_item]                                         
                                        image=$Objets[$D_Objets[$i].code].image  
                                        x,y=$unit.x,$unit.y                 
                                    [/remove_item]  
                                    {CLEAR_VARIABLE D_Objets[$i]}  
                                [/command]  
                            [/option]  
                            [option]  
                                message= _ "Leave it"  
                            [/option]  
                        [/message]  
                    [/then]
                [/if]  
            [/do]
        [/while]  
    [/event]  
#enddef