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… »