View source for 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.

=== <u>Under the burning sun</u> ===


==== <u>Variable definitions</u> ====
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<sup>1)</sup>. 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’.


==== <u>Variables creation and manipulation</u> ====
Even if WML variables contents have no precise types.[[In computering words, they are not '''strongly typed.'''|<sup>1)</sup>]], 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} [[Please note the CLEAR_VARIABLE macro will not work if your variables names contain spaces or commas. It’s one good reason to avoid them.|<sup>2)</sup>]]


==== <u>Containers</u> ====
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:[[That’s why dots are forbidden in variable names : they are used to specify members.|<sup>3)</sup>]]
 $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.


=== <u>A glance into the pit</u> === 

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.[[That’s why = signs are forbidden in variables names : it corrupts savegames.|<sup>4)</sup>]]

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 <u>any valid WML content</u>. 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'''.  


==== <u>More with arrays</u> ====
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 <u>array will be renumbered</u>: 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, <u>the record following “Konrad” will be skipped</u>. The  
correct way to do this is fetching the array in reverse order[[Less easy because there is no macro for that.|<sup>5)</sup>]] 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}
=== <u>First steps into darkness</u> ===  

==== <u>Using simple strings in names</u> ==== 
Consider this variable name: 
 heroes_$index  
How to understand this? At execution time, '''$index''' will be replaced with the value of the  
variable index[[It would be better if it exists…  |<sup>6)</sup>]]. 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.

==== <u>Using variables strings in events names</u> ====  
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]

=== <u>Voodoo and black magics</u> ===  
« 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…  

==== <u>Existing blocks customization</u> ====  
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) [[You can minimize the risk using special key names like 'Pyro_level' instead of only 'level'… or write a feature request! |<sup>7)</sup>]] . 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.


==== <u>Passing “parameters” to an event</u> ====  
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.

==== <u>Dynamic code with insert_tag</u> ====
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