The Battle for Wesnoth Wiki - User contributions [en]

Advanced Optimisations and Hacks

2026-02-20T01:12:28Z

Sapient:

From time to time, especially if working with some advanced WML, you will come to need things that WML does not support. And you might be in a bad need to do that. This isn't a tricky of using WML, it is actually doing what the developers didn't plan to support. I have mostly used it to write much more effective codes at the cost of low understandability.

Note: This article was written supposing that you are skilled with WML. It is expected that you know most WML tags, comprehend the contents of save files and have good understanding of variables and variable arrays in WML (not all of them are required by each of these). It is also assuming that you've read Dunno's article about [[Wml_optimisation]], and did these things before trying ''these'' optimisations.

== Many common events in scenarios ==
This trick is useful if your (multiple) scenarios contain a lot of common WML. This happens if your campaign adds some additional functionality, like inventories. It might be also useful if you are using repetitive macros that fire the same events. Or when you need to add event-based weapon specials with [object]s and therefore need to insert these events into all scenarios and not into the unit via macros using unbalanced WML (which is not recommended). It might be even useful if you have a lot of death message events.

The problem that comes from using the same WML events in many scenario is that they are preprocessed and loaded into RAM once for each scenario, and it can be dozens of times, resulting in huge RAM consumption and annoying loading times. This tricks inserts in through a unit so that it is loaded only once. Its downside is that prestart events can't be loaded this way, but start events can set up pretty much anything, they are fired before you see the scenario.

Deprecated: {{DevFeature1.13|2}} added the [[ModificationWML#The_.5Bresource.5D_toplevel_tag|[resource]]] tag, which provides a non-hacky way to do this, and also supports prestart events. [[WML_Abilities]] shows how these combine with unit abilities.

First, create a dummy unit like this:
[unit_type]
id=Event Loader #It can be different, but it is assumed in the following code that it will be 'Event Loader',
#if you name it differently, you will have to rename it in the rest of the code!
alignment=neutral
advances_to=null
cost=1
hide_help=true
do_not_list=yes
{GLOBAL_EVENTS_LIST}
[/unit_type]
The {GLOBAL_EVENTS_LIST} macro contains all the events you want to insert into all scenarios. This thick is only useful if the list is very long. Example (too short to be worth using this hack, but it is a working example):
#define GLOBAL_EVENTS_LIST
[event]
# This events gives traits to all ally/enemy leaders (single player is expected)
name=start
[store_unit]
canrecruit=yes
[not]
side=1
[/not]
variable=leaders
kill=yes
[/store_unit]
{FOREACH leaders i}
[unit]
id=$leaders[$i].id
name=$leaders[$i].name
gender=$leaders[$i].gender
x=$leaders[$i].x
y=$leaders[$i].y
side=$leaders[$i].side
random_traits=yes
canrecruit=yes
[/unit]
{NEXT i}
{CLEAR_VARIABLE leaders}
[/event]
[event]
# This makes petrification last only for a single turn
name=turn refresh
first_time_only=no
[modify_unit]
[filter]
side=$side_number
[filter_wml]
[status]
petrified=yes
[/status]
[/filter_wml]
[/filter]
[status]
petrified=no
[/status]
[/modify_unit]
[/event]
#enddef

Now, we need to add the events in the unit into the scenario. It is trivial. Keep on mind that it means that only start events can be loaded this way, prestart events will be loaded, but will never be fired. It is useful to wrap it in a macro so that only one line makes it load. Because it disappears in prestart, it does not clear shroud for the player.
#define GLOBAL_EVENTS
[event]
name=prestart
[unit]
type=Event Loader
side=1
x,y=1,1
[/unit]
[kill]
type=Event Loader
animate=no
[/kill]
[/event]
#enddef
This should be placed in all events. If you need to control your events with some variables it will check, it might be useful to use them as arguments for this macro and set them in the event.

There is also a way to do it without touching the scenarios at all, but its use in multiplayer is severely limited. It is based on lua, which is always executed when the scenario is loaded (even if it is in the middle from a save file, because lua environment isn't saved), and can be later accessed only by defining new WML tags or event hooks. Placing this into your _main (inside the campaign's #ifdef wraps, to avoid hacking other campaigns!).
#ifdef CAMPAIGN_YOUR_AWESOME_CAMPAIGN
[lua]
code = <<
local helper = wesnoth.require "lua/helper.lua"
-- We need to check whether the events were loaded in this scenario
local events_loaded = wesnoth.get_variable( "events_loaded" )
if events_loaded ~= true then
wesnoth.set_variable("events_loaded", true)
-- We don't want this code to believe that the events were loaded because
-- the variable recording that they are saved remains from previous scenario
wesnoth.wml_actions.event{
name="victory" ,
{ "clear_variable", {
name="events_loaded"
} }
}
-- And now we do WML action itself
wesnoth.wml_actions.unit{ type = "Event Loader" , side = 1, x = 1, y = 1}
wesnoth.wml_actions.kill{ type = "Event Loader", animate = false}
end
>>
[/lua]
#endif

== Getting rid of AMLA clutter ==
This is almost required when a unit has too many AMLA options. Because of AMLA, the unit's can become extremely long, and the game will keep reading through it again and again and again and again, resulting in visible FPS drops when the unit is on the screen. If there are more units like this, it will get even more painful, because the save files will become excessively large, needing seconds to be created.

The trick is based on the fact that units' AMLA is irrelevant all the time, and is used only when it advances. Because of it, you can somehow remove all the [advancement] tags from the unit for most of the time. This is easier said than done, though. The number 1 problem is that if you classically store the unit, remove the [advancement] tags simply with {CLEAR_VARIABLE stored_unit.advancement} and unstore it, it will do ''nothing at all''. When a unit is unstored, [advancement]s are read from the unit_type, and not from the actual variable! There are alternatives to [unstore_unit], simplest of them is [insert_tag] with name=unit (which does almost the same, but for example doesn't check if the unit has enough experience to advance). But here comes another bummer - many WML tags' lua implementations use unstore_unit (harm_unit, transform_unit and modify_unit), and even if we simply avoided using them, unstore_unit is too useful to avoid using it (and refactoring the whole code).

There is a solution, of course. You can create an additional unit_type. One unit_type that is played all the time and has only one dummy AMLA (because we want it to show the experience bar and advance to nothing, I will call it dummy_amla), usable really a lot of times, and then another unit_type, let's call it advancing_unit_type, that uses the first unit_type as base unit, but contains all the AMLA options we want. Then we create events to transform between the unit types when advancing. This has some odd consequences, but they can be exploited.

Unfortunately, when I discovered the secrets behind this and wrote about them, the developers decided that it wasn't the intended behaviour and changed it in wesnoth 1.11.1 (and it is changed in all later versions of the 1.11 branch). There are four more problems to face - first is that when a unit advances, it shows the advancement window before the advance event is fired, second is that all changes done to the unit in an advance event are discarded, third is that there is no way to make the player choose an advancement if it isn't his turn ([unstore_unit] chooses a random one even in singleplayer and I think this wasn't fixed yet) and the fourth one is that if the advancing is activated by [unstore_unit], it may call the advance and post advance events again (it somehow doesn't loop, fortunately).

I am not writing the exact code because it would be too long and chaotic, but writing a pseudocode describes the steps.

Note: recreate unit means using the [unit] tag with all relevant properties of the unit that is sort of unstored by this, like name, id, location, canrecruit, gender, experience, unrenamable etc, as well as modifications, variables and status via insert_tag - it is similar to unstore, but will recalculate its other properties like attacks, damage, maximum hitpoints, resistances, abilities and so on.

The advance event:
if unit.advancement.id=dummy_amla then
# now we know if the unit has to be transformed or not
if unit.side=$side_number
# if it isn't the units' turn, we will deal with it later
kill unit fire_event=no animate=no
full_heal, clear_statuses
set_variable amla_processing yes
set_variables advancing_store unit
else
clear_statuses
# edit the unit so that it is created with the new unit_type and advancements and thrown right into a variable
set_variable unit.type advancing_$unit_type
set_variable unit.to_variable advancing_store
# recreate it with a new unit_type
recreate_unit variable=unit to_variable=advancing_store
unstore_unit advancing_store find_vacant=no
store_unit x,y=$x1,$y1 variable=advancing_store
recreate_unit variable=advancing_store to_variable=advancing_store
# clean up some stuff
set_variables advancing_store.modifications unit.modifications
set_variable advancing_store.experience unit.experience
set_variable advancing_store.achieved_amla yes
end
#ifver WESNOTH_VERSION >= 1.11.1
fire_event post advance on the unit
#endif
end

The post advance event basically just unstores the unit from the advancing_store variable. Expanding it with more things you might need should be done here (it may cause problems that might have different solutions before and after 1.11.1).

If implemented correctly, it does what is it supposed to do, but more problems come - we haven't solved advancing if it is not the unit's turn. It will have to be delayed until the start of the unit's turn. These units were marked by setting their variable named amla_processing to yes. At turn refresh, fire the following event on all that side's units that have that variable set to yes. Pseudocode again:
[event]
name=respecialisation
first_time_only=no
# count how many times it has taken the dummy_amla
set_variable times_advanced 0
foreach unit.modifications.advance
if unit.modifications.advance.id=dummy_amla
variable_op times_advanced add 1
end
repeat this as many times as the number in times_advanced is
variable_op unit.experience $unit.max_experience
clear_variable unit.variables.amla_processing
set_variable unit.type
set_variable unit.type advancing_$unit_type
recreate_unit variable=unit to_variable=advancing_store
unstore_unit advancing_store find_vacant=no
store_unit x,y=$x1,$y1 variable=advancing_store
recreate_unit variable=advancing_store to_variable=advancing_store
end
# you might want to fire the post advance event here
[/event]

== Handling many non-disjunctive possibilities ==
Sometimes, especially when working with inventories, you will come to need this. You have 100 possible items (or they might be something else if not used to create an inventory). You want the game to choose one when they are dropping and you want to show exactly those the unit currently has in a message's options (to let the player manipulate them). Some manipulation would require a huge [switch] and another one would require countless [show_if] tags. This can be done very comfortably if you use a variable as a database.

The database variable is just created with something like this:
[set_variables]
name=items
[value]
[object]
name= _ "Leather Armour"
required_strength=20
image=items/armour-leather.png
description= _ "This armour makes the user 20% more resistant to damage."
[effect]
apply_to=resistance
[resistances]
replace=false
impact=-20
blade=-20
pierce=-20
[/resistances]
[/effect]
[/object]
[object]
name= _ "Chain Armour"
required_strength=20
image=items/armour-chain.png
description= _ "This armour makes the user 30% more resistant to damage, but slows down slightly."
[effect]
apply_to=resistance
[resistances]
replace=false
impact=-30
blade=-30
pierce=-30
[/resistances]
[/effect]
[effect]
apply_to=movement
add=-1
[/effect]
[/object]
[object]
name= _ "Steel Plate Armour"
required_strength=20
image=items/armour-plate.png
description= _ "This armour makes the user 40% more resistant to damage, but slows down."
[effect]
apply_to=resistance
[resistances]
replace=false
impact=-40
blade=-40
pierce=-40
[/resistances]
[/effect]
[effect]
apply_to=movement
add=-2
[/effect]
[/object]
#... This would be useless if there were only 3 of them
[/value]
[/set_variables]

To randomly drop one of them, just choose a random number between 0 and 2 like {SET_VARIABLE rand rand 0..2}, then draw the picture $items.object[$rand].image and then create a moveto event (nested event with delayed_variable_substitution=no) on that hex that if a player steps on it, a it sets a variable informing about the item type being picked and fires a pickup event on that unit. The pickup event is fireable more than once, and basically does this:
[insert_tag]
name=object
variable=items.object[$item_type_being_picked]
[/insert_tag]

When the inventory is viewed, we can avoid having to use [show_if] for all possible items, we just read what is inside the unit (or look it up in the items variable array). The message can be composed in a variable and then asked via insert_tag.
{CLEAR_VARIABLE message}
{VARIABLE message.message "Which item do you want to manipulate?"}
{FOREACH unit.modifications.object i}
[set_variables]
name=message.option[$message.option.length]
[value]
message="&$unit.modifications.object[$i].image $unit.modifications.object[$i].name|:
$unit.modifications.object[$i].description"
[command]
[set_variables]
name=item_chosen
to_variable=unit.modifications.object[$i]
[/set_variables]
[/command]
[/value]
[/set_variables]
{NEXT i}
[insert_tag]
name=message
variable=message
[/insert_tag]
Then the properties of the object chosen will be in a variable named item_chosen.

== Hacking events into other campaigns ==
{{DevFeature1.13|2}} deprecatd since Wesnoth 1.13 supports sp [modification]s

This is the most dangerous trick, but it lets you make an add-on that mods the game - you can easily give inventories to mainline campaigns (without editing them at all), remove all randomness from campaigns, create a dungeonmaster kit for multiplayer survivals (without editing these survivals), change the general balance... possibilities are unlimited.

It is wholly based on the repetitive scenario events optimisation mentioned above in this article. It allows you to add events into scenarios, without actually editing the scenarios. If you don't protect it by any #ifdef, it will affect all scenarios! This is usually the best way to get kicked in the butt by other add-on writers, but in this case, you'll have to make it carefully and with the knowledge that it will affect all scenarios in all campaigns (or just some, you can wrap it in #ifndef MULTIPLAYER if you want it to be singleplayer-only).

Like before, we place these events into a unit_type, and create and kill at at the beginning of the scenario. If done by lua in _main, it will be inserted in any case.
[unit_type]
id=Event Loader #It can be different, but it is assumed in the following code that it will be 'Event Loader',
#if you name it differently, you will have to rename it in the rest of the code!
#It's however suggested to name it differently to avoid conflicts with other add-ons of a similar type
alignment=neutral
advances_to=null
cost=1
hide_help=true
do_not_list=yes
{GLOBAL_EVENTS_LIST} # This is your magical collection of events. Should be mostly start, prerecruit and turn refresh events.
[/unit_type]

Then insert it using lua.
[lua]
code = <<
local helper = wesnoth.require "lua/helper.lua"
-- We need to check whether the events were loaded in this scenario
local events_loaded = wesnoth.get_variable( "events_loaded" )
if events_loaded ~= true then
wesnoth.set_variable("events_loaded", true)
-- We don't want this code to believe that the events were loaded because
-- the variable recording that they are saved remains from previous scenario
wesnoth.wml_actions.event{
name="victory" ,
{ "clear_variable", {
name="events_loaded"
} }
}
-- And now we do WML action itself
wesnoth.wml_actions.unit{ type = "Event Loader" , side = 1, x = 1, y = 1}
wesnoth.wml_actions.kill{ type = "Event Loader", animate = false}
end
>>
[/lua]

An add-on named No Randomness mod uses this, although it is entirely written in lua, you might want to see it to know more possible combinations around customising the mod, but it will require you to know lua.

[[Category:WML_Tips]]

VariablesWML

2026-02-20T00:25:18Z

Sapient: remove false "not possible" claim, improve language

{{Template:WML Tags}}
Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign or scenario unless explicitly cleared.
Variable names can contain only alphanumerics and underscores and are case-sensitive. Though technically permitted, it is recommended not to use an underscore as the first character of a variable name.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* [[#Assigning Variables|'''Assigning to a variable''']]: stores a value in the variable, either creating a new variable or modifying a variable that already exists.
* [[#Reading Variables|'''Querying a variable''']]: retrieves the last value stored in the variable (usually returning an empty string if no value was stored).
* [[#Clearing Variables|'''Clearing a variable''']]: makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games.

== Kinds of Variables ==
=== Scalar ===
A scalar variable can store a single string, number, or boolean value.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([[SyntaxWML#Special_Attribute_Values|Special Attribute Values]]).

=== Container ===
A container variable can store any number of scalar variables, as well as nested containers. There are tags to assign specific information, for instance [store_side]. To refer to a variable <code>bar</code> stored in a container <code>foo</code> you would write <code>foo.bar</code>.

=== Array ===
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

Arrays are indexed from 0, which means that if <code>foo</code> is the name of an array, <code>foo[0]</code> is the full name of its first container variable, <code>foo[1]</code> the full name of its second, and so on.

For an array variable, <code>foo.length</code> is the special variable that always stores the number of containers in the array <code>foo</code>. Hence, if the value stored in <code>foo.length</code> is 18, the last container in the array would be <code>foo[17]</code>.

If you try to query an array as if it were a container, then it will simply use the first index. Thus <code>$foo.bar</code> would be the same as <code>$foo[0].bar</code>. An explicit index inside an array is also considered a container.

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <code>foo[3]</code> as if it were a scalar one is illegal; instead, you would use <code>foo[3].value</code> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a save of a game that contains such variables will fail with a WML error.)

=== Global ===

Most WML variables are global variables, and unless they are explicitly cleared, they will continue to exist across all events and scenarios until a campaign ends. Variables created with '''[set_variable]''', '''[set_variables]''', or any of the [store_something] styled WML tags such as '''[store_unit]''' may all used to create or modify global variables. Likewise, [[#Variable Substitution|variable substitution]] and the '''[variable]''' conditional tag may be used to read global variables.

=== Unit ===

Unit variables may be stored on a specific unit in a special '''variables''' child container. That means that, if desired, every unit could have a variable with the same name, and it wouldn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Unit variables can be read after storing a unit then can be created by setting data in the '''variables''' child container and unstoring the unit. A one-step way of creating unit variables is possible with '''[modify_unit]''', but to read the variables you still usually need to use '''[store_unit]'''. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardUnitFilter]] or [[AbilitiesWML]]) and the '''[filter_wml][variables]''' tag in [[StandardUnitFilter]], or as mentioned you can use '''[store_unit]''' to copy the unit along with all its variables into a global variable which can then be accessed normally – for example with a unit stored to the variable <code>my_unit</code>, you could access the scalar unit variable <code>my_stamina</code> as <code>$my_unit.variables.my_stamina</code>.

If modifying unit variables after storing the unit, always remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.

An example of how you can filter on a unit variable in [[StandardUnitFilter]]:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Side ===

Side variables are stored on a specific side. That means that, if desired, every side could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Side variables can be created with '''[modify_side]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardSideFilter]]), or you can use '''[store_side]''' to copy the side along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_side</code>, then you could access the scalar side variable <code>wood_amount</code> as <code>$my_side.variables.wood_amount</code>.

Since there is no '''[unstore_side]''' tag, don't modify the variables in a stored side. Instead, use [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]] for the changes to be kept.

== Assigning Variables ==

Variables can be created and modified using [[ActionWML]] or [[LuaAPI/wml#wml.variables|Lua]]. There are several ways to do this:

* The '''[set_variable]''' tag can assign or modify a scalar variable using a wide variety of operations.
* The '''[set_variables]''' tag can assign or modify a container or array variable using a wide variety of operations.
* The '''[variables]''' tag can be used to set up a large number of variables all at once.
* The '''{VARIABLE}''' macro can assign a new scalar variable with a given value.
* The '''{VARIABLE_OP}''' macro can modify an existing scalar variable using a wide variety of operations.
* There are several ways to assign variables from Lua. They won't be covered here, however.

=== The [set_variable] tag ===

The '''[[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]''' tag can be directly used as ActionWML to work with global variables, or it can be placed in the '''[modify_unit]''' or '''[modify_side]''' ActionWML tags to work with unit or side variables, respectively. See the documentation of these tags for details.

=== The [set_variables] tag ===

As of 1.18.0, the '''[[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]''' tag can only be used as ActionWML. Support for placing it in '''[modify_unit]''' and '''[modify_side]''' is planned. See the documentation of these tags for details.

=== The [variables] tag ===

Unlike the others, the '''[variables]''' tag cannot be directly used as ActionWML. It can be used in a number of other places, however:

* Placed in a scenario tag to assign initial global variables at scenario start.
* Placed in a '''[side]''' tag to assign initial side variables at scenario start.
* Placed in a '''[unit]''' tag to assign initial unit variables when the unit is spawned.
* Placed in '''[leader]''' with the same meaning as in '''[unit]'''.
* Placed in '''[modify_unit]''' and '''[modify_side]''' ActionWML to adjust the values of several variables at once using "merge mode" (see '''[set_variables]''' documentation for the explanation of how this works).
* Seen in saved games to describe the current value of each variable when the game was saved.

When using the '''[variables]''' tag, a scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

== Reading Variables ==

Variables can be queried in a variety of ways, including substitutions, [[ConditionalWML]], [[Wesnoth Formula Language]], and Lua. The Lua methods won't be covered here, however.

=== Conditionals ===

Variables may be compared by using '''[variable]''' within an [if] or [while] tag. The '''{VARIABLE_CONDITIONAL}''' macro can also be used for this purpose. For more information, please refer to [[ConditionalActionsWML]].

=== Filters ===

In [[StandardUnitFilter|unit filters]], the '''[variables]''' tag can be used in '''[filter_wml]''' to check the value of unit variables, respectively.

Both unit filters and [[StandardSideFilter|side filters]] also support querying variables via WFL. The details of how this works is not covered here, however.

=== Variable Substitution ===

When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.

In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.

Variable substitutions (and also formula substitutions, see [[SyntaxWML#formula substitution|here]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.

For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substitute in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

The most common use-case for this is using a scalar variable to index an array variable, for example <code>$houses[$n].title</code>. In cases where substitution will occur more than once, such as a nested event, it can also be used to delay substitution to the second phase by simply adding a pipe directly after the dollar sign. The first round of substitution will remove the pipe and stop there (moving on to the next substitution left of it, if any), and then the second round of substitution will detect the variable and replace it.

Here's a more complete example:

<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute values are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
* The value of '''literal=''' inside [set_variable]
* The contents of '''[literal]''' inside [set_variables]
* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, when used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).

=== [insert_tag] ===

The '''[insert_tag]''' tag inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form.

This works in any tag that permits sub-tags and supports variable substitution. That means that, like variable substitution, it will ''not'' work in places that use [[#Literal Mode|literal mode]].

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': The name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

Here's an example of its use:

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== Clearing Variables ==

This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]]. It can also be done from Lua.

Like '''[set_variable]''', the '''[clear_variable]''' tag can either be used as ActionWML or placed inside '''[modify_unit]''' or '''[modify_side]'''.

== Automatically Stored Variables ==
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once one of their attributes is accessed for the first time. This means that one can sometimes get incorrect results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

== Variable Usage Examples ==
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Tutorial ==

* [[/How_to_use_variables|How to use variables]]

VariablesWML

2026-02-20T00:06:54Z

Sapient: /* Global */

{{Template:WML Tags}}
Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign or scenario unless explicitly cleared.
Variable names can contain only alphanumerics and underscores and are case-sensitive. Though technically permitted, it is recommended not to use an underscore as the first character of a variable name.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* [[#Assigning Variables|'''Assigning to a variable''']]: stores a value in the variable, either creating a new variable or modifying a variable that already exists.
* [[#Reading Variables|'''Querying a variable''']]: retrieves the last value stored in the variable (usually returning an empty string if no value was stored).
* [[#Clearing Variables|'''Clearing a variable''']]: makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games.

== Kinds of Variables ==
=== Scalar ===
A scalar variable can store a single string, number, or boolean value.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([[SyntaxWML#Special_Attribute_Values|Special Attribute Values]]).

=== Container ===
A container variable can store any number of scalar variables, as well as nested containers. There are tags to assign specific information, for instance [store_side]. To refer to a variable <code>bar</code> stored in a container <code>foo</code> you would write <code>foo.bar</code>.

=== Array ===
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

Arrays are indexed from 0, which means that if <code>foo</code> is the name of an array, <code>foo[0]</code> is the full name of its first container variable, <code>foo[1]</code> the full name of its second, and so on.

For an array variable, <code>foo.length</code> is the special variable that always stores the number of containers in the array <code>foo</code>. Hence, if the value stored in <code>foo.length</code> is 18, the last container in the array would be <code>foo[17]</code>.

If you try to query an array as if it were a container, then it will simply use the first index. Thus <code>$foo.bar</code> would be the same as <code>$foo[0].bar</code>. An explicit index inside an array is also considered a container.

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <code>foo[3]</code> as if it were a scalar one is illegal; instead, you would use <code>foo[3].value</code> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a save of a game that contains such variables will fail with a WML error.)

=== Global ===

Most WML variables are global variables, and unless they are explicitly cleared, they will continue to exist across all events and scenarios until a campaign ends. Variables created with '''[set_variable]''', '''[set_variables]''', or any of the [store_something] styled WML tags such as '''[store_unit]''' may all used to create or modify global variables. Likewise, [[#Variable Substitution|variable substitution]] and the '''[variable]''' conditional tag may be used to read global variables.

=== Unit ===

Unit variables are stored on a specific unit. That means that, if desired, every unit could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Unit variables can be created with '''[modify_unit]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardUnitFilter]] or [[AbilitiesWML]]) and the '''[filter_wml][variables]''' tag in [[StandardUnitFilter]], or you can use '''[store_unit]''' to copy the unit along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_unit</code>, then you could access the scalar unit variable <code>stamina</code> as <code>$my_unit.variables.stamina</code>.

If modifying unit variables after storing the unit, remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.

An example of how you can filter on a unit variable in [[StandardUnitFilter]]:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Side ===

Side variables are stored on a specific side. That means that, if desired, every side could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Side variables can be created with '''[modify_side]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardSideFilter]]), or you can use '''[store_side]''' to copy the side along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_side</code>, then you could access the scalar side variable <code>wood_amount</code> as <code>$my_side.variables.wood_amount</code>.

Since there is no '''[unstore_side]''' tag, don't modify the variables in a stored side. Instead, use [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]] for the changes to be kept.

== Assigning Variables ==

Variables can be created and modified using [[ActionWML]] or [[LuaAPI/wml#wml.variables|Lua]]. There are several ways to do this:

* The '''[set_variable]''' tag can assign or modify a scalar variable using a wide variety of operations.
* The '''[set_variables]''' tag can assign or modify a container or array variable using a wide variety of operations.
* The '''[variables]''' tag can be used to set up a large number of variables all at once.
* The '''{VARIABLE}''' macro can assign a new scalar variable with a given value.
* The '''{VARIABLE_OP}''' macro can modify an existing scalar variable using a wide variety of operations.
* There are several ways to assign variables from Lua. They won't be covered here, however.

=== The [set_variable] tag ===

The '''[[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]''' tag can be directly used as ActionWML to work with global variables, or it can be placed in the '''[modify_unit]''' or '''[modify_side]''' ActionWML tags to work with unit or side variables, respectively. See the documentation of these tags for details.

=== The [set_variables] tag ===

As of 1.18.0, the '''[[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]''' tag can only be used as ActionWML. Support for placing it in '''[modify_unit]''' and '''[modify_side]''' is planned. See the documentation of these tags for details.

=== The [variables] tag ===

Unlike the others, the '''[variables]''' tag cannot be directly used as ActionWML. It can be used in a number of other places, however:

* Placed in a scenario tag to assign initial global variables at scenario start.
* Placed in a '''[side]''' tag to assign initial side variables at scenario start.
* Placed in a '''[unit]''' tag to assign initial unit variables when the unit is spawned.
* Placed in '''[leader]''' with the same meaning as in '''[unit]'''.
* Placed in '''[modify_unit]''' and '''[modify_side]''' ActionWML to adjust the values of several variables at once using "merge mode" (see '''[set_variables]''' documentation for the explanation of how this works).
* Seen in saved games to describe the current value of each variable when the game was saved.

When using the '''[variables]''' tag, a scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

== Reading Variables ==

Variables can be queried in a variety of ways, including substitutions, [[ConditionalWML]], [[Wesnoth Formula Language]], and Lua. The Lua methods won't be covered here, however.

=== Conditionals ===

Variables may be compared by using '''[variable]''' within an [if] or [while] tag. The '''{VARIABLE_CONDITIONAL}''' macro can also be used for this purpose. For more information, please refer to [[ConditionalActionsWML]].

=== Filters ===

In [[StandardUnitFilter|unit filters]], the '''[variables]''' tag can be used in '''[filter_wml]''' to check the value of unit variables, respectively.

Both unit filters and [[StandardSideFilter|side filters]] also support querying variables via WFL. The details of how this works is not covered here, however.

=== Variable Substitution ===

When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.

In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.

Variable substitutions (and also formula substitutions, see [[SyntaxWML#formula substitution|here]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.

For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substitute in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

The most common use-case for this is using a scalar variable to index an array variable, for example <code>$houses[$n].title</code>. In cases where substitution will occur more than once, such as a nested event, it can also be used to delay substitution to the second phase by simply adding a pipe directly after the dollar sign. The first round of substitution will remove the pipe and stop there (moving on to the next substitution left of it, if any), and then the second round of substitution will detect the variable and replace it.

Here's a more complete example:

<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute values are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
* The value of '''literal=''' inside [set_variable]
* The contents of '''[literal]''' inside [set_variables]
* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, when used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).

=== [insert_tag] ===

The '''[insert_tag]''' tag inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form.

This works in any tag that permits sub-tags and supports variable substitution. That means that, like variable substitution, it will ''not'' work in places that use [[#Literal Mode|literal mode]].

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': The name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

Here's an example of its use:

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== Clearing Variables ==

This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]]. It can also be done from Lua.

Like '''[set_variable]''', the '''[clear_variable]''' tag can either be used as ActionWML or placed inside '''[modify_unit]''' or '''[modify_side]'''.

== Automatically Stored Variables ==
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once one of their attributes is accessed for the first time. This means that one can sometimes get incorrect results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

== Variable Usage Examples ==
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Tutorial ==

* [[/How_to_use_variables|How to use variables]]

VariablesWML

2026-02-20T00:05:59Z

Sapient: Not "always"

{{Template:WML Tags}}
Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign or scenario unless explicitly cleared.
Variable names can contain only alphanumerics and underscores and are case-sensitive. Though technically permitted, it is recommended not to use an underscore as the first character of a variable name.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* [[#Assigning Variables|'''Assigning to a variable''']]: stores a value in the variable, either creating a new variable or modifying a variable that already exists.
* [[#Reading Variables|'''Querying a variable''']]: retrieves the last value stored in the variable (usually returning an empty string if no value was stored).
* [[#Clearing Variables|'''Clearing a variable''']]: makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games.

== Kinds of Variables ==
=== Scalar ===
A scalar variable can store a single string, number, or boolean value.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([[SyntaxWML#Special_Attribute_Values|Special Attribute Values]]).

=== Container ===
A container variable can store any number of scalar variables, as well as nested containers. There are tags to assign specific information, for instance [store_side]. To refer to a variable <code>bar</code> stored in a container <code>foo</code> you would write <code>foo.bar</code>.

=== Array ===
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

Arrays are indexed from 0, which means that if <code>foo</code> is the name of an array, <code>foo[0]</code> is the full name of its first container variable, <code>foo[1]</code> the full name of its second, and so on.

For an array variable, <code>foo.length</code> is the special variable that always stores the number of containers in the array <code>foo</code>. Hence, if the value stored in <code>foo.length</code> is 18, the last container in the array would be <code>foo[17]</code>.

If you try to query an array as if it were a container, then it will simply use the first index. Thus <code>$foo.bar</code> would be the same as <code>$foo[0].bar</code>. An explicit index inside an array is also considered a container.

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <code>foo[3]</code> as if it were a scalar one is illegal; instead, you would use <code>foo[3].value</code> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a save of a game that contains such variables will fail with a WML error.)

=== Global ===

Most WML variables are global variables and unless they are explicitly cleared, they will continue to exist across all events and scenarios until a campaign ends. Variables created with '''[set_variable]''', '''[set_variables]''', or any of the [store_something] styled WML tags such as '''[store_unit]''' may all used to create or modify global variables. Likewise, [[#Variable Substitution|variable substitution]] and the '''[variable]''' conditional tag may be used to read global variables.

=== Unit ===

Unit variables are stored on a specific unit. That means that, if desired, every unit could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Unit variables can be created with '''[modify_unit]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardUnitFilter]] or [[AbilitiesWML]]) and the '''[filter_wml][variables]''' tag in [[StandardUnitFilter]], or you can use '''[store_unit]''' to copy the unit along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_unit</code>, then you could access the scalar unit variable <code>stamina</code> as <code>$my_unit.variables.stamina</code>.

If modifying unit variables after storing the unit, remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.

An example of how you can filter on a unit variable in [[StandardUnitFilter]]:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Side ===

Side variables are stored on a specific side. That means that, if desired, every side could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Side variables can be created with '''[modify_side]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardSideFilter]]), or you can use '''[store_side]''' to copy the side along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_side</code>, then you could access the scalar side variable <code>wood_amount</code> as <code>$my_side.variables.wood_amount</code>.

Since there is no '''[unstore_side]''' tag, don't modify the variables in a stored side. Instead, use [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]] for the changes to be kept.

== Assigning Variables ==

Variables can be created and modified using [[ActionWML]] or [[LuaAPI/wml#wml.variables|Lua]]. There are several ways to do this:

* The '''[set_variable]''' tag can assign or modify a scalar variable using a wide variety of operations.
* The '''[set_variables]''' tag can assign or modify a container or array variable using a wide variety of operations.
* The '''[variables]''' tag can be used to set up a large number of variables all at once.
* The '''{VARIABLE}''' macro can assign a new scalar variable with a given value.
* The '''{VARIABLE_OP}''' macro can modify an existing scalar variable using a wide variety of operations.
* There are several ways to assign variables from Lua. They won't be covered here, however.

=== The [set_variable] tag ===

The '''[[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]''' tag can be directly used as ActionWML to work with global variables, or it can be placed in the '''[modify_unit]''' or '''[modify_side]''' ActionWML tags to work with unit or side variables, respectively. See the documentation of these tags for details.

=== The [set_variables] tag ===

As of 1.18.0, the '''[[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]''' tag can only be used as ActionWML. Support for placing it in '''[modify_unit]''' and '''[modify_side]''' is planned. See the documentation of these tags for details.

=== The [variables] tag ===

Unlike the others, the '''[variables]''' tag cannot be directly used as ActionWML. It can be used in a number of other places, however:

* Placed in a scenario tag to assign initial global variables at scenario start.
* Placed in a '''[side]''' tag to assign initial side variables at scenario start.
* Placed in a '''[unit]''' tag to assign initial unit variables when the unit is spawned.
* Placed in '''[leader]''' with the same meaning as in '''[unit]'''.
* Placed in '''[modify_unit]''' and '''[modify_side]''' ActionWML to adjust the values of several variables at once using "merge mode" (see '''[set_variables]''' documentation for the explanation of how this works).
* Seen in saved games to describe the current value of each variable when the game was saved.

When using the '''[variables]''' tag, a scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

== Reading Variables ==

Variables can be queried in a variety of ways, including substitutions, [[ConditionalWML]], [[Wesnoth Formula Language]], and Lua. The Lua methods won't be covered here, however.

=== Conditionals ===

Variables may be compared by using '''[variable]''' within an [if] or [while] tag. The '''{VARIABLE_CONDITIONAL}''' macro can also be used for this purpose. For more information, please refer to [[ConditionalActionsWML]].

=== Filters ===

In [[StandardUnitFilter|unit filters]], the '''[variables]''' tag can be used in '''[filter_wml]''' to check the value of unit variables, respectively.

Both unit filters and [[StandardSideFilter|side filters]] also support querying variables via WFL. The details of how this works is not covered here, however.

=== Variable Substitution ===

When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.

In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.

Variable substitutions (and also formula substitutions, see [[SyntaxWML#formula substitution|here]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.

For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substitute in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

The most common use-case for this is using a scalar variable to index an array variable, for example <code>$houses[$n].title</code>. In cases where substitution will occur more than once, such as a nested event, it can also be used to delay substitution to the second phase by simply adding a pipe directly after the dollar sign. The first round of substitution will remove the pipe and stop there (moving on to the next substitution left of it, if any), and then the second round of substitution will detect the variable and replace it.

Here's a more complete example:

<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute values are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
* The value of '''literal=''' inside [set_variable]
* The contents of '''[literal]''' inside [set_variables]
* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, when used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).

=== [insert_tag] ===

The '''[insert_tag]''' tag inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form.

This works in any tag that permits sub-tags and supports variable substitution. That means that, like variable substitution, it will ''not'' work in places that use [[#Literal Mode|literal mode]].

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': The name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

Here's an example of its use:

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== Clearing Variables ==

This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]]. It can also be done from Lua.

Like '''[set_variable]''', the '''[clear_variable]''' tag can either be used as ActionWML or placed inside '''[modify_unit]''' or '''[modify_side]'''.

== Automatically Stored Variables ==
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once one of their attributes is accessed for the first time. This means that one can sometimes get incorrect results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

== Variable Usage Examples ==
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Tutorial ==

* [[/How_to_use_variables|How to use variables]]

VariablesWML

2026-02-19T23:48:50Z

Sapient: irrelevant information... numeric variable names are inadvisable

{{Template:WML Tags}}
Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign or scenario unless explicitly cleared.
Variable names can contain only alphanumerics and underscores and are case-sensitive. Though technically permitted, it is recommended not to use an underscore as the first character of a variable name.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* [[#Assigning Variables|'''Assigning to a variable''']]: stores a value in the variable, either creating a new variable or modifying a variable that already exists.
* [[#Reading Variables|'''Querying a variable''']]: retrieves the last value stored in the variable (usually returning an empty string if no value was stored).
* [[#Clearing Variables|'''Clearing a variable''']]: makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games.

== Kinds of Variables ==
=== Scalar ===
A scalar variable can store a single string, number, or boolean value.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([[SyntaxWML#Special_Attribute_Values|Special Attribute Values]]).

=== Container ===
A container variable can store any number of scalar variables, as well as nested containers. There are tags to assign specific information, for instance [store_side]. To refer to a variable <code>bar</code> stored in a container <code>foo</code> you would write <code>foo.bar</code>.

=== Array ===
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

Arrays are indexed from 0, which means that if <code>foo</code> is the name of an array, <code>foo[0]</code> is the full name of its first container variable, <code>foo[1]</code> the full name of its second, and so on.

For an array variable, <code>foo.length</code> is the special variable that always stores the number of containers in the array <code>foo</code>. Hence, if the value stored in <code>foo.length</code> is 18, the last container in the array would be <code>foo[17]</code>.

If you try to query an array as if it were a container, then it will simply use the first index. Thus <code>$foo.bar</code> would be the same as <code>$foo[0].bar</code>. An explicit index inside an array is also considered a container.

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <code>foo[3]</code> as if it were a scalar one is illegal; instead, you would use <code>foo[3].value</code> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a save of a game that contains such variables will fail with a WML error.)

=== Global ===

Most variables are global variables – they exist in the global scope. Variables created with '''[set_variable]''', '''[set_variables]''', or any of the '''[store_something]''' styled WML tags are all global variables, and [[#Variable Substitution|variable substitution]] and the '''[variable]''' conditional tag only read global variables.

=== Unit ===

Unit variables are stored on a specific unit. That means that, if desired, every unit could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Unit variables can be created with '''[modify_unit]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardUnitFilter]] or [[AbilitiesWML]]) and the '''[filter_wml][variables]''' tag in [[StandardUnitFilter]], or you can use '''[store_unit]''' to copy the unit along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_unit</code>, then you could access the scalar unit variable <code>stamina</code> as <code>$my_unit.variables.stamina</code>.

If modifying unit variables after storing the unit, remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.

An example of how you can filter on a unit variable in [[StandardUnitFilter]]:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Side ===

Side variables are stored on a specific side. That means that, if desired, every side could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Side variables can be created with '''[modify_side]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardSideFilter]]), or you can use '''[store_side]''' to copy the side along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_side</code>, then you could access the scalar side variable <code>wood_amount</code> as <code>$my_side.variables.wood_amount</code>.

Since there is no '''[unstore_side]''' tag, don't modify the variables in a stored side. Instead, use [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]] for the changes to be kept.

== Assigning Variables ==

Variables can be created and modified using [[ActionWML]] or [[LuaAPI/wml#wml.variables|Lua]]. There are several ways to do this:

* The '''[set_variable]''' tag can assign or modify a scalar variable using a wide variety of operations.
* The '''[set_variables]''' tag can assign or modify a container or array variable using a wide variety of operations.
* The '''[variables]''' tag can be used to set up a large number of variables all at once.
* The '''{VARIABLE}''' macro can assign a new scalar variable with a given value.
* The '''{VARIABLE_OP}''' macro can modify an existing scalar variable using a wide variety of operations.
* There are several ways to assign variables from Lua. They won't be covered here, however.

=== The [set_variable] tag ===

The '''[[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]''' tag can be directly used as ActionWML to work with global variables, or it can be placed in the '''[modify_unit]''' or '''[modify_side]''' ActionWML tags to work with unit or side variables, respectively. See the documentation of these tags for details.

=== The [set_variables] tag ===

As of 1.18.0, the '''[[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]''' tag can only be used as ActionWML. Support for placing it in '''[modify_unit]''' and '''[modify_side]''' is planned. See the documentation of these tags for details.

=== The [variables] tag ===

Unlike the others, the '''[variables]''' tag cannot be directly used as ActionWML. It can be used in a number of other places, however:

* Placed in a scenario tag to assign initial global variables at scenario start.
* Placed in a '''[side]''' tag to assign initial side variables at scenario start.
* Placed in a '''[unit]''' tag to assign initial unit variables when the unit is spawned.
* Placed in '''[leader]''' with the same meaning as in '''[unit]'''.
* Placed in '''[modify_unit]''' and '''[modify_side]''' ActionWML to adjust the values of several variables at once using "merge mode" (see '''[set_variables]''' documentation for the explanation of how this works).
* Seen in saved games to describe the current value of each variable when the game was saved.

When using the '''[variables]''' tag, a scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

== Reading Variables ==

Variables can be queried in a variety of ways, including substitutions, [[ConditionalWML]], [[Wesnoth Formula Language]], and Lua. The Lua methods won't be covered here, however.

=== Conditionals ===

Variables may be compared by using '''[variable]''' within an [if] or [while] tag. The '''{VARIABLE_CONDITIONAL}''' macro can also be used for this purpose. For more information, please refer to [[ConditionalActionsWML]].

=== Filters ===

In [[StandardUnitFilter|unit filters]], the '''[variables]''' tag can be used in '''[filter_wml]''' to check the value of unit variables, respectively.

Both unit filters and [[StandardSideFilter|side filters]] also support querying variables via WFL. The details of how this works is not covered here, however.

=== Variable Substitution ===

When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.

In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.

Variable substitutions (and also formula substitutions, see [[SyntaxWML#formula substitution|here]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.

For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substitute in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

The most common use-case for this is using a scalar variable to index an array variable, for example <code>$houses[$n].title</code>. In cases where substitution will occur more than once, such as a nested event, it can also be used to delay substitution to the second phase by simply adding a pipe directly after the dollar sign. The first round of substitution will remove the pipe and stop there (moving on to the next substitution left of it, if any), and then the second round of substitution will detect the variable and replace it.

Here's a more complete example:

<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute values are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
* The value of '''literal=''' inside [set_variable]
* The contents of '''[literal]''' inside [set_variables]
* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, when used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).

=== [insert_tag] ===

The '''[insert_tag]''' tag inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form.

This works in any tag that permits sub-tags and supports variable substitution. That means that, like variable substitution, it will ''not'' work in places that use [[#Literal Mode|literal mode]].

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': The name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

Here's an example of its use:

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== Clearing Variables ==

This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]]. It can also be done from Lua.

Like '''[set_variable]''', the '''[clear_variable]''' tag can either be used as ActionWML or placed inside '''[modify_unit]''' or '''[modify_side]'''.

== Automatically Stored Variables ==
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once one of their attributes is accessed for the first time. This means that one can sometimes get incorrect results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

== Variable Usage Examples ==
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Tutorial ==

* [[/How_to_use_variables|How to use variables]]

VariablesWML

2026-02-13T17:46:14Z

Sapient: there is no boolean_value key in set_variable

{{Template:WML Tags}}
Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign or scenario unless explicitly cleared.
Variable names can contain only alphanumerics and underscores and are case-sensitive. Though technically permitted, it is recommended not to use an underscore as the first character of a variable name.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* [[#Assigning Variables|'''Assigning to a variable''']]: stores a value in the variable, either creating a new variable or modifying a variable that already exists.
* [[#Reading Variables|'''Querying a variable''']]: retrieves the last value stored in the variable (usually returning an empty string if no value was stored).
* [[#Clearing Variables|'''Clearing a variable''']]: makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games.

== Kinds of Variables ==
=== Scalar ===
A scalar variable can store a single string, number, or boolean value.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([[SyntaxWML#Special_Attribute_Values|Special Attribute Values]]).

=== Container ===
A container variable can store any number of scalar variables, as well as nested containers. There are tags to assign specific information, for instance [store_side]. To refer to a variable <code>bar</code> stored in a container <code>foo</code> you would write <code>foo.bar</code>. This works even if one of the variable names is entirely numeric.

=== Array ===
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

Arrays are indexed from 0, which means that if <code>foo</code> is the name of an array, <code>foo[0]</code> is the full name of its first container variable, <code>foo[1]</code> the full name of its second, and so on.

For an array variable, <code>foo.length</code> is the special variable that always stores the number of containers in the array <code>foo</code>. Hence, if the value stored in <code>foo.length</code> is 18, the last container in the array would be <code>foo[17]</code>.

If you try to query an array as if it were a container, then it will simply use the first index. Thus <code>$foo.bar</code> would be the same as <code>$foo[0].bar</code>. An explicit index inside an array is also considered a container.

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <code>foo[3]</code> as if it were a scalar one is illegal; instead, you would use <code>foo[3].value</code> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a save of a game that contains such variables will fail with a WML error.)

=== Global ===

Most variables are global variables – they exist in the global scope. Variables created with '''[set_variable]''', '''[set_variables]''', or any of the '''[store_something]''' styled WML tags are all global variables, and [[#Variable Substitution|variable substitution]] and the '''[variable]''' conditional tag only read global variables.

=== Unit ===

Unit variables are stored on a specific unit. That means that, if desired, every unit could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Unit variables can be created with '''[modify_unit]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardUnitFilter]] or [[AbilitiesWML]]) and the '''[filter_wml][variables]''' tag in [[StandardUnitFilter]], or you can use '''[store_unit]''' to copy the unit along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_unit</code>, then you could access the scalar unit variable <code>stamina</code> as <code>$my_unit.variables.stamina</code>.

If modifying unit variables after storing the unit, remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.

An example of how you can filter on a unit variable in [[StandardUnitFilter]]:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Side ===

Side variables are stored on a specific side. That means that, if desired, every side could have a variable with the same name, and it doesn't conflict with a global variable of the same name. Note that they are not global only in the sense that they are "namespaced" and not in the sense that they cannot be accessed globally.

Side variables can be created with '''[modify_side]''', but there is currently no way to read them directly in WML. You can read them from [[Wesnoth Formula Language|formulas]] (eg in [[StandardSideFilter]]), or you can use '''[store_side]''' to copy the side along with all its variables into a global variable which can then be accessed normally – if you call the variable <code>my_side</code>, then you could access the scalar side variable <code>wood_amount</code> as <code>$my_side.variables.wood_amount</code>.

Since there is no '''[unstore_side]''' tag, don't modify the variables in a stored side. Instead, use [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]] for the changes to be kept.

== Assigning Variables ==

Variables can be created and modified using [[ActionWML]] or [[LuaAPI/wml#wml.variables|Lua]]. There are several ways to do this:

* The '''[set_variable]''' tag can assign or modify a scalar variable using a wide variety of operations.
* The '''[set_variables]''' tag can assign or modify a container or array variable using a wide variety of operations.
* The '''[variables]''' tag can be used to set up a large number of variables all at once.
* The '''{VARIABLE}''' macro can assign a new scalar variable with a given value.
* The '''{VARIABLE_OP}''' macro can modify an existing scalar variable using a wide variety of operations.
* There are several ways to assign variables from Lua. They won't be covered here, however.

=== The [set_variable] tag ===

The '''[[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]''' tag can be directly used as ActionWML to work with global variables, or it can be placed in the '''[modify_unit]''' or '''[modify_side]''' ActionWML tags to work with unit or side variables, respectively. See the documentation of these tags for details.

=== The [set_variables] tag ===

As of 1.18.0, the '''[[InternalActionsWML#.5Bset_variables.5D|[set_variables]]]''' tag can only be used as ActionWML. Support for placing it in '''[modify_unit]''' and '''[modify_side]''' is planned. See the documentation of these tags for details.

=== The [variables] tag ===

Unlike the others, the '''[variables]''' tag cannot be directly used as ActionWML. It can be used in a number of other places, however:

* Placed in a scenario tag to assign initial global variables at scenario start.
* Placed in a '''[side]''' tag to assign initial side variables at scenario start.
* Placed in a '''[unit]''' tag to assign initial unit variables when the unit is spawned.
* Placed in '''[leader]''' with the same meaning as in '''[unit]'''.
* Placed in '''[modify_unit]''' and '''[modify_side]''' ActionWML to adjust the values of several variables at once using "merge mode" (see '''[set_variables]''' documentation for the explanation of how this works).
* Seen in saved games to describe the current value of each variable when the game was saved.

When using the '''[variables]''' tag, a scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

== Reading Variables ==

Variables can be queried in a variety of ways, including substitutions, [[ConditionalWML]], [[Wesnoth Formula Language]], and Lua. The Lua methods won't be covered here, however.

=== Conditionals ===

Variables may be compared by using '''[variable]''' within an [if] or [while] tag. The '''{VARIABLE_CONDITIONAL}''' macro can also be used for this purpose. For more information, please refer to [[ConditionalActionsWML]].

=== Filters ===

In [[StandardUnitFilter|unit filters]], the '''[variables]''' tag can be used in '''[filter_wml]''' to check the value of unit variables, respectively.

Both unit filters and [[StandardSideFilter|side filters]] also support querying variables via WFL. The details of how this works is not covered here, however.

=== Variable Substitution ===

When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.

In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.

Variable substitutions (and also formula substitutions, see [[SyntaxWML#formula substitution|here]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.

For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substitute in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

The most common use-case for this is using a scalar variable to index an array variable, for example <code>$houses[$n].title</code>. In cases where substitution will occur more than once, such as a nested event, it can also be used to delay substitution to the second phase by simply adding a pipe directly after the dollar sign. The first round of substitution will remove the pipe and stop there (moving on to the next substitution left of it, if any), and then the second round of substitution will detect the variable and replace it.

Here's a more complete example:

<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute values are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
* The value of '''literal=''' inside [set_variable]
* The contents of '''[literal]''' inside [set_variables]
* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, when used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).

=== [insert_tag] ===

The '''[insert_tag]''' tag inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form.

This works in any tag that permits sub-tags and supports variable substitution. That means that, like variable substitution, it will ''not'' work in places that use [[#Literal Mode|literal mode]].

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': The name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

Here's an example of its use:

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== Clearing Variables ==

This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]]. It can also be done from Lua.

Like '''[set_variable]''', the '''[clear_variable]''' tag can either be used as ActionWML or placed inside '''[modify_unit]''' or '''[modify_side]'''.

== Automatically Stored Variables ==
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once one of their attributes is accessed for the first time. This means that one can sometimes get incorrect results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

== Variable Usage Examples ==
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Tutorial ==

* [[/How_to_use_variables|How to use variables]]

WML for Complete Beginners: Chapter 5

2026-02-13T16:12:52Z

Sapient:

{{Translations}}<div style="float:right">{{:WML for Complete Beginners}}</div>

==Interlude: Testing your WML==

Having completed chapter 4, the game should be able to load your campaign. The next chapter will make your campaign more interesting, but already it's worth regularly loading the campaign in the game - at some stage you'll make some typos, and the earlier you notice that it's broken the less code you'll have to read to find the bug.

To make the game notice changes to the WML files, either press F5 on the title screen, or start the game from the command line with the ''--nocache'' option.

There are various [[Maintenance tools]] which can help with checking for errors. {{DevFeature1.15|?}} There will be a lot of work on a new tool, described in the [[ValidationFAQ]]; however as of 1.15.5 it's not user-friendly yet.

==Chapter 5: Events==

Let's walk through an average morning. When your alarm clock goes off, you wake up. You go downstairs and put some bread in the toaster for breakfast. When the toaster pops, you butter the toast and eat it. When you have eaten breakfast, you go outside and wait for the schoolbus to arrive. When the bus arrives, you get on it. When it stops at your destination, you get off of the bus.

Notice that you do everything “when” something else happens. These are all “events”. The alarm going off caused you to wake up. The toaster popping causes you to butter the toast and eat it. Finishing breakfast go outside. The bus stopping causes you to get on or off. These are all like events in WML.

To give you examples of the real thing, i.e. playing Wesnoth: When you move somewhere, it’s an event. When you attack somebody, it’s an event. When you are hit, it’s an event. When a new turn starts, it’s an event. When you kill, or get killed, these are too - obviously – events.

It’s up to your decisions, which of these events you want to “catch”, to make them a turning point in the storyline.

The syntax for writing an event goes like this:
<syntaxhighlight lang=wml>
[event]
name=name_of_the_event
#do something
[/event]
</syntaxhighlight>

As mentioned before, there are quite a few events available to you in WML. Of these, the most commonly used are the ''prestart'' event, the ''start'' event, and the ''moveto'' event. In our example here we shall also mention the ''last breath'' event, the ''die'' event, and the ''time over'' event.

====Common Events====

Now, I'm not going to supply you with an exhaustive list of every kind of predefined event and what each does, that's what the [[EventWML]] page is for. I will, however, provide you with a list of the most frequently used predefined events and what they do, since we will be using these events in our campaign scenarios later on.

====The "prestart" Event====

:This event fires before anything is shown on the screen for your scenario. This event is commonly used to recall loyal heroes for the player and to create loyal defenders. Anything you want to happen before the user can even see the map goes within this event. Think of it this way: everthing in the prestart event is done during the loading-screen before the scenario begins. To create this event, we use the following WML:
<syntaxhighlight lang=wml>
[event]
name=prestart
#do stuff here
[/event]
</syntaxhighlight>
:The prestart event does not require any additional keys (besides name=prestart) in order to function. However, we will not use this event in our sample scenario.

====The "start" Event====

:The "start" event fires after the user can see the map and the screen, but before the user can actually do anything. To declare a start event, simply use
<syntaxhighlight lang=wml>
name=start
</syntaxhighlight>

*'''Objectives'''
A common use of the start event is to declare the objectives (The little window you can access by pressing CTRL + J) for the scenario.

One very important distinction here: The [objectives] tag only serves to display the objectives at the start of the scenario, NOT to program them into the game logic. The actual logic of defining the defeat/win outcome is written into other events, using the [endlevel] tag, as we shall see later. Now, back to the initial display of the objectives.

Declaring the objectives is done using two tags: [objectives] and [objective] like this:
<syntaxhighlight lang=wml>
[event]
name=start
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
</syntaxhighlight>

:Notice how the [objectives] tag encloses all the [objective] tags. Basically the [objectives] tag tells WML that you are going to start declaring objectives for the scenario, which are then represented by [objective] tags. Notice that the [objective] tag has two keys
<syntaxhighlight lang=wml>
description= _ "Describe the Objective Here"
condition= #put either "win" or "lose" here--win objectives are grouped together in green and lose objectives are grouped together in red.
</syntaxhighlight>

*'''[message]'''
Of course, the start event is also a good place to create an initial dialogue. This is done using the [message] tag. This tag has two keys:
<syntaxhighlight lang=wml>
speaker=
message= _ ""
</syntaxhighlight>
The speaker tag contains the id of the unit who is going to talk. Remember in the last chapter how I gave our example leader an id of 'MyLeader'? Well, now he's going to give a short speech:
<syntaxhighlight lang=wml>
speaker=MyLeader
</syntaxhighlight>
The message key represents what the speaker is actually going to say. This should be marked translatable:
<syntaxhighlight lang=wml>
message= _ "I see the orcs!"
</syntaxhighlight>

I'm going to put this (and another) message into our example start event:
<syntaxhighlight lang=wml>
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
</syntaxhighlight>

While it doesn't matter to WML where you put events, it is good form to put them below the [side] tags so that others can read your WML more easily:
<syntaxhighlight lang=wml>
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[/objectives]
[/event]
[/scenario]
</syntaxhighlight>

====The "moveto" Event====
As you might have guesses, the "moveto" event covers when a unit moves. This event triggers after any unit moves and matches a given [filter]. What is this '[filter]' you ask? Let's take a quick look:
*'''[filter]'''
The [filter] tag tells WML to apply this event only to units which match the filter. For example, what if I wanted to run my moveto event only when side 1 moves a unit onto hex 1,1? In that case, I would use:
<syntaxhighlight lang=wml>
[filter]
side=1
x,y=1,1
[/filter]
</syntaxhighlight>
Simple, huh? Other common keys for a filter tag include:
<syntaxhighlight lang=wml>
id=MyLeader #id of a specific unit, such as our leader.
type="Elvish Shaman" #only Elvish Shamans would pass this filter.
</syntaxhighlight>
To learn more about [filter]s, check out [[FilterWML]].
Now we could add a very simple moveto event to our example scenario:
<syntaxhighlight lang=wml>
[event]
name=moveto
first_time_only=no
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
</syntaxhighlight>
"But you added a new key without explaining it...I'm confused!" Hang in there, I'm just getting to explaining that first_time_only key.
*'''first_time_only'''
The "first_time_only" key has two possible values "yes" and "no". This key is actually present in every event, even if you don't type it in. In that case, it contains a value of "yes" (this is also called a ''default value''). If first_time_only="yes", the event will only run the first time its conditions are met. In our example, this means that only the ''first'' unit to move onto hex 1,1 will announce his presence to the world. If, however, first_time_only="no" then ''every'' time a unit moves onto hex 1,1 will cause it to speak. This is what the example event does.
====The "time over" Event====
This event fires after all turns have run out. It is usually used to give a brief message before causing the player to lose the scenario. By the way, forcing a win/loss using WML is accomplished like this:
<syntaxhighlight lang=wml>
[endlevel]
result=victory #or result=defeat to force a loss.
[/endlevel]
</syntaxhighlight>
A rather typical time over event would look like this:
<syntaxhighlight lang=wml>
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]
</syntaxhighlight>

===="last breath" and "die" Events====
These two events are very similar. Both events trigger when a unit (specified by [filter], known as 'unit') is killed by another unit (can be specified by [filter_second], known as 'second_unit'). However there is one, crucial difference. "last breath" occurs ''before'' a unit's death-animation is shown (before the unit visibly dies, but has <= 0 hitpoints) whereas "die" occurs ''immediately after'' the unit's death-animation. As a result, use "last breath" when you want the dying unit to give a last-breath message, and "die" for anything which occurs as a result of that death. Here is an example of using both of these events. See if you can figure out what exactly is happening:
<syntaxhighlight lang=wml>
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
</syntaxhighlight>

These two events fire every time ''side 1'' kills one of ''side 2'''s units. When these events fire, here is what the player will see: "Take that!" -> "Hah! You missed!" -> Death animation -> "Wrong!"

====Nested Events====
Have you ever wondered what would happen if you did this (pseudocode example):
<syntaxhighlight lang=wml>
[event]
name=event1
# ...
[event]
name=event2
# ...
[/event]
[/event]
</syntaxhighlight>
This is called ''nesting'' events because one event is "nested" inside the other. What happens here is that when event1 is triggered, in addition to whatever else event1 does, event2 is created. This prevents event2 from occurring before event1. Suppose we wanted to display a message after defeating the enemy leader (id=EnemyLeader) and moving our leader (id=MyLeader) to the enemy's keep (x,y=20,7). We could do that like this:
<syntaxhighlight lang=wml>
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[event]
name=moveto
[filter]
id=MyLeader
x,y=20,7
[/filter]
[message]
speaker=unit
message= _ "Haha! I captured the enemy keep!"
[/message]
[/event]
[/event]
</syntaxhighlight>
*'''Further Information'''
For more information on events, how to write them, and how they work, go to the page on [[EventWML]].

I'm going to insert a few of these sample events into our example scenario (and write a new "die" event for the enemy leader), which now looks like:
<syntaxhighlight lang=wml>
#textdomain wesnoth-my_first_campaign
[scenario]
id=my_first_scenario
next_scenario=null
name=_"My First Scenario."
map_data="{~add-ons/my_first_campaign/maps/my_first_map.map}"
turns=30
[side]
side=1
controller=human
team_name="good"
user_team_name= _ "My Team"
id=MyLeader
name= _ "My Leader's Name"
type="Elvish Ranger"
unrenameable=yes
canrecruit=yes
recruit="Elvish Fighter, Elvish Archer, Elvish Shaman"
gold=100
[/side]
[side]
side=2
controller=ai
team_name="bad"
user_team_name= _ "Bad Guys"
id="EnemyLeader"
name= _ "My Villain"
type= "Orcish Warrior"
unrenameable=yes
canrecruit=yes
recruit="Orcish Grunt, Orcish Archer, Orcish Assassin, Wolf Rider"
gold=100
[/side]
[event]
name=start
[message]
speaker=MyLeader
message= _ "I see the orcs!"
[/message]
[message]
speaker=EnemyLeader
message= _ "Grrrr!"
[/message]
[objectives]
[objective]
description= _ "Defeat the enemy leader"
condition="win"
[/objective]
[objective]
description= _ "Death of your leader"
condition="lose"
[/objective]
[objective]
description= _ "Turns run out"
condition="lose"
[/objective]
[/objectives]
[/event]
[event]
name=moveto
first_time_only="no"
[filter]
side=1
x,y=1,1
[/filter]
[message]
speaker=unit #unit means the unit triggering this event--in this case the guy who just moved
message= _ "Look at me! I'm on hex 1,1!"
[/message]
[/event]
[event]
name="last breath"
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Take that!"
[/message]
[message]
speaker=unit
message= _ "Hah! You missed!"
[/message]
[/event]
[event]
name=die
first_time_only=no
[filter]
side=2
[/filter]
[filter_second]
side=1
[/filter_second]
[message]
speaker=second_unit
message= _ "Wrong!"
[/message]
[/event]
[event]
name=die
[filter]
id=EnemyLeader
[/filter]
[message]
speaker=second_unit
message= _ "Yeah! I killed him!"
[/message]
[endlevel]
result=victory
[/endlevel]
[/event]
[event]
name=time over
[message]
speaker=MyLeader
message= _ "I give up. This is taking too long..."
[/message]
[endlevel]
result=defeat
[/endlevel]
[/event]
[/scenario]
</syntaxhighlight>
Congratulations! You have now written your first functional scenario! Go, give it a try! Play it! When you're ready to keep going, head to the next chapter.

{{Navigation|[[WML for Complete Beginners: Chapter 4|'''Chapter 4''' Creating Your First Scenario]]|[[WML for Complete Beginners: Chapter 6|'''Chapter 6''' Custom Units]]}}

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Introduction

2026-02-13T15:48:52Z

Sapient: /* Introduction */

{{Translations}}<div style="float:right">{{:WML for Complete Beginners}}</div>

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding out before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML. In addition, some very helpful people have worked on supporting WML in [https://forums.wesnoth.org/viewtopic.php?f=21&t=13799 certain tools].

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without being required to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

===Ready to Get Started?===

When you are ready, head on over to chapter 1 and let's get started!

{{Navigation|<nowiki>----</nowiki>|[[WML for Complete Beginners: Chapter 1|'''Chapter 1''' Syntax]]}}

[[Category:WML_Tutorials]]
[[Category:WML_for_Complete_Beginners]]

SyntaxWML

2021-06-30T09:01:09Z

Sapient: Undo revision 65551 as it distracts from the concept being explained and was unclear

{{Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break without quotes would otherwise end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped – without quotes, all leading and trailing spaces would be removed, and internal runs of spaces would be replaced by a single space. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data. See [[TranslationsWML]] and [[GettextForWesnothDevelopers]] for more information.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign unless explicitly cleared.
Variable names should contain only alphanumerics and underscores, and the first character of the name should not be an underscore.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a unit filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in unit filters).

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by a pound sign (<code>#</code>) unless in double quotes. Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

Specially-formatted comments are frequently used to give commands to the Wesnoth [[MaintenanceTools|maintenance tools]] to suppress false positives and enhance their coverage, as well as for adding explanatory comments for [[GettextForWesnothDevelopers#Marking_up_strings_in_WML|translatable strings]].

== Tutorial ==

* [[VariablesWML/How_to_use_variables|How to use variables]]

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

InternalActionsWML

2021-06-30T08:54:10Z

Sapient: /* [unsynced] */ closing tag typo

{{WML Tags}}

Part of [[ActionWML]], Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.

== Variable Actions ==

These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

=== [set_variable] ===

The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.

* '''name''': the name of the variable to manipulate

* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])

* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollar signs.

* '''to_variable''': set the variable to the value of the given variable, e.g. 'to_variable=temp' would be equivalent to 'value=$temp'.

* '''add''': add the given amount to the variable.

* '''sub''': subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. The result is a float. To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.

* '''divide''': divide the variable by the given number. The result is a float. Wesnoth 1.9 and later no longer uses integer division. Use a second tag with round=floor if you relied on this.

* '''modulo''': returns the remainder of a division.

* '''abs''': Returns the absolute value of the variable.

* '''root''': Use '''root=square''' to calculate the square root. {{DevFeature1.15|0}} Also supports '''root=cube''' and arbitrary integer roots.

* '''power''': Raise the variable to some power.

* '''rand''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'rand=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'rand=3..5'. You may combine these, e.g. 'rand=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. If a number or item is repeated, it is sampled more frequently as appropriate. See [[MultiplayerContent]] for more info on the MP case. Using rand= will automatically result in the current action being non undoable. Ignoring possible [allow_undo].

* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).

* '''[join]''' joins an array of strings to create a textual list
** '''variable''': name of the array
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to connect the elements
** '''remove_empty''': whether to ignore empty elements

* '''ipart''': Assigns the integer part (the part to the left of the decimal point) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the decimal point) of the referenced variable.

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.
**'''round=trunc''': {{DevFeature1.15|0}} Rounds towards zero; this is the same operation as '''ipart''', but operating on the value already contained in the variable rather than the value assigned to the key.

* '''min''', '''max''': {{DevFeature1.15|9}} Specify a comma-separated list of numbers; either the smallest or largest number in the list will be assigned to the variable.

* '''reverse=yes''': {{DevFeature1.15|9}} Reverses the string value of the variable. For example, "delfador" becomes "rodafled".

* '''formula''': Calculate the new value of the variable from a [[Wesnoth_Formula_Language|WFL]] formula operating on the old value. This is similar to using the '''$(...)''' syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

=== [set_variables] ===

Manipulates a WML array or container

* '''name''': the name of the array or container to manipulate

* '''mode''': one of the following values:
** ''replace'': will clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''. Attributes in '''[value]''' will overwrite any existing already in '''name'''. Tags in '''[value]''' modify the corresponding tag of the original value of '''name''', so for example the first '''[attack]''' tag in '''[value]''' would modify the first '''[attack]''' tag of '''name''' rather than appending a new '''[attack]''' tag. A few special syntaxes are supported:
*** ''__remove=yes'': When used in a subtag, causes the corresponding subtag in '''name''' to be deleted rather than merged. Deletion happens after any other subtags have been merged.
*** ''add_to_xxx'': Adds its integer value to the integer value of '''xxx''' in '''name''', and sets '''xxx''' in '''name''' to the result. {{DevFeature1.13|8}} Now adds as real numbers rather than integers.
*** ''concat_to_xxx'': {{DevFeature1.13|8}} Similar to '''add_to_xxx''', but does string concatenation instead of numerical addition.
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

* '''to_variable''': data will be set to the given array

* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags

*'''[split]''' splits a textual list into an array which will then be set to data
** '''list''': textual list to split
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to separate the elements
** '''remove_empty''': whether to ignore empty elements

{{DevFeature1.13|4}} You can now mix '''[value]''', '''[literal]''', and '''[split]''' in the same '''[set_variables]''' tag. They will be processed in order of appearance. Multiple instances of [split] are also supported now.

=== Capturing Game Data ===

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

==== [store_gold] ====

Stores a side's gold into a variable.

* '''[[StandardSideFilter]]''': The first matching side's gold will be stored in the variable "variable".
* '''variable''': (default='gold') the name of the variable to store the gold in

==== [store_locations] ====

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). The array will include any unreachable border hexes, if applicable.

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. By default, all locations on the map are stored.

* '''variable''': the name of the variable (array) into which to store the locations.

* '''mode''': {{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and locations which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and locations which match the filter will be added to the array after the existing elements.

==== [store_reachable_locations] ====

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). See note below for ''vision''.
* '''moves''': possible values ''current'' (default), ''max''. For ''movement'' and ''attack'', specifies whether to use the current or maximum movement points when calculating the range. Ignored for ''vision''.
* '''viewing_side''': If left unset then fog and shroud are ignored, hidden ambushers are not ignored, and the real reach of the units is stored. If set to a non-zero number, then the area stored for each unit matching the SUF is based on the information visible to that unit's side; it doesn't matter which non-zero number is given. Ignored completely for ''vision''.
* '''variable''': the name of the variable (array) into which to store the locations.

In 1.14 and before, the ''vision'' range is calculated as max movement range ignoring ZoC + 1 hex.

{{DevFeature1.15|12}} ''vision'' uses the same calculations as the fog and shroud, and handles:
* units with vision costs different to movement costs
* units whose vision points aren't the same as their max movement points
* jamming by enemy units

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to ''append'', the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.
'''Result'''

Variable will contain following members:
* '''color''': Team color used for ellipses, sprites, and flags. Will be one of the id's found in data/core/team-colors.cfg or a custom color defined by [[GameConfigWML#Color_Palettes|[color_range]]].
* '''controller''': Indicates type of player that control this side. ''Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''null''': If players assigns "Empty" to "Player/Type" in game lobby
* '''fog''': Indicates whether this side is affected by fog of war.
* '''gold''': The amount of gold the side has.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''team_name''': String representing the team's description.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''': {{DevFeature1.13|7}} When the side will be considered defeated. See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''faction''': {{DevFeature1.13|7}} id of the selected faction, string (multiplayer-only)
* '''faction_name''': {{DevFeature1.13|7}} Name of the selected faction, string (multiplayer-only)
* '''num_units''' {{DevFeature1.13|7}}: The number of units the side currently has on the map.
* '''num_villages''' {{DevFeature1.13|7}}: The number of villages the side currently controls.
* '''total_upkeep''' {{DevFeature1.13|7}}: The number of unit levels the side is currently supporting.
* '''expenses''' {{DevFeature1.13|7}}: The amount of gold the side is currently spending to support units.
* '''net_income''' {{DevFeature1.13|7}}: The income the side gains per turn after expenses.
* '''base_income''' {{DevFeature1.13|8}}: The income the side gains per turn (same as [side] income key)

* {{DevFeature1.13|7}} All other keys and tags of the side that are contained in [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] .__cfg

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

* [[StandardSideFilter]]: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
* '''variable''': (default='location'): the name of the variable to store the location in
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

==== [store_time_of_day] ====

Stores time of day information from the current scenario into a WML variable container.

* '''x, y''': Location to store the time for. [[DirectActionsWML#.5Btime_area.5D|Time areas]] matter; illumination does not. If this is omitted, the global (location-independent) time is stored.

* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].

* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

==== [store_turns] ====

Stores the turn limit (the maximum number of turns). If there is no limit, this stores ''-1''.

* '''variable''': (default='turns') the name of the variable in which to store the turn limit.

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample '''list of these tags and keys''' can be found at [[InternalActionsWMLUnitTags]].

If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file). One can also use the [[CommandMode|:inspect]] command or the [[InterfaceActionsWML#.5Binspect.5D|[inspect]]] tag to open a game-state inspector dialog, which can be used to view unit properties.

Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] to re-create the unit with the modified variables.

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] and [[ConditionalActionsWML#.5Bforeach.5D|[foreach]]].

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. The units will be stored in order of their internal ''underlying_id'' attribute, which is usually in creation order (but you normally should not depend on the order).

* '''variable''': the name of the variable into which to store the unit(s)

* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to ''append'', the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.

* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.

==== [store_unit_defense] ====

{{DevFeature1.13|9}}

{{DevFeature1.15|7}} Fixed, was broken in 1.15.3

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is. A footpad on castle has 70% defense, so this function stores the value 30.)

* StandardUnitFilter
* '''loc_x''', '''loc_y''': x and y of a valid map location. The terrain on this location will be used for the defense calculation.
* '''terrain''': The terrain code for which unit defense should be calculated. If '''terrain''' is specified, '''loc_x''' and '''loc_y''' are ignored.
* '''variable''': the name of the variable into which to store the defense. default: "terrain_defense"

==== [store_unit_defense_on] ====

{{DevFeature1.15|7}} Similar to [store_unit_defense], but stores the same number that would be shown in the UI. For example, a footpad on castle has 70% defense, so this stores the value 70.

Takes the same attributes as [store_unit_defense], and defaults to storing the value in "terrain_defense".

==== [store_unit_type] ====

Stores a unit type definition into a variable.

* '''type''': (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

* '''variable''': the name of the variable into which to store the unit type information (default "unit_type")

* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable. If mode is set to ''replace'', the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to ''append'', the variable will not be cleared, and the unit type will be added to the array after the existing elements.

==== [store_unit_type_ids] ====

* '''variable''': the name of the variable into which to store a comma-separated list of all unit type IDs including all from all loaded addons

==== [store_villages] ====

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.

Note: This differs from using [store_locations] only in that the hexes considered for match are restricted to those with villages (those whose terrain type has its 'gives_income' flag set to true), in the same way that use of either the 'owner_side' key or the '[filter_owner]' will. In fact, if either of these are present, [store_villages] and [store_locations] will behave identically.

* '''variable''': the name of the variable (array) into which to store the locations (default: "location")
* '''[[StandardLocationFilter]]''' tags and keys as arguments

==== [store_items] ====

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [[InterfaceActionsWML#.5Bitem.5D|[item]]] (depending on what was set during creating the item).

*'''variable''': name of the wml variable array to use (default "items")
*'''[[StandardLocationFilter]]''' keys as arguments: only items on locations matching this [[StandardLocationFilter]] will be stored
*'''item_name''': {{DevFeature1.15|0}} if given, only items created with a matching '''[item]name=''' will be stored. As of 1.15.0, this does not support comma-separated lists.

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

Gets the relative direction from one hex to another. This is an interface to the function wesnoth uses to decide how a unit will face while it is moving / attacking / defending.

* '''[source]''' x and y must describe a map location
* '''[destination]''' similar
* '''variable''' name of the variable to store string result in (one of 'n', 'nw', 'ne', 's', 'sw', 'se')
* '''mode''' optional. 0 is the default setting corresponding to default wesnoth implementation used in animations. 1 is an alternate "radially symmetric" mode. The default mode breaks ties in the direction of south, since this makes more units face the player directly on screen. The radially symmetric mode breaks ties in the direction of counter-clockwise, and might be more appropriate in some cases.

==== [find_path] ====

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path (including the starting hex).

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]]
*'''variable''': the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
*'''allow_multiple_turns''': default no, if yes also moves that require more than one turn will be calculated.
*'''check_visibility''': default no, if yes the path will not be computed if some hexes are not visible due to shroud.
*'''check_teleport''': default yes; if no, teleport won't be taken in account while computing path.
*'''check_zoc''': default yes; if no, unit ZOCs won't be considered while calculating the path.
*'''nearest_by''': {{DevFeature1.15|2}} possible values "movement_cost" (default), "steps", "hexes"; if the [destination] SLF matches multiple hexes, the one that would need the least movement points to reach may not be the one that's closest as measured by '''hexes''', or closest as measured by steps, from the starting point. This option chooses which measurement to prefer.

More detail about multiple destinations and the return structure is on [[FindPathExplanation]] (moved out of this page because it has an image in it).

This is the structure of the variable returned by [find_path]:
[path]
hexes = non-zero if a path was successfully found.
if the path is calculated to an impassable hex, or the move requires multiple turns
and allow_multiple_turns is no, its value will be 0.
from_x, from_y = location of the unit
to_x, to_y = destination
movement_cost = total movement cost required by unit to reach that hex
required_turns = total turns required by unit to reach that hex
[step]
x, y = location of the step
terrain = terrain of the step
movement_cost = movement cost required by unit to reach that hex
required_turns = turns required by unit to reach that hex
[/step]
[/path]

==== [unit_worth] ====
Takes only an inline [[StandardUnitFilter]] (only the first matching unit will be used for calculation) and outputs the following variables:
*''cost'', the current unit cost;
*''next_cost'', the cost of the most expensive advancement;
*''health'', the health of the unit in percentage;
*''experience'', current experience in percentage;
*''unit_worth'', how much the unit is worth.

Mainly used for internal AI checks, but one could in theory just do anything with it.

[event]
name=moveto
[unit_worth]
x,y=$x1,$y1
[/unit_worth]
[message]
id=$unit.id
message=_"I cost $cost gold, with $health|% of my hitpoints and $experience|% on the way to cost $next_cost|.
I am estimated to be worth $unit_worth"
[/message]
[clear_variable]
name=cost,next_cost,health,experience,unit_worth
[/clear_variable]
[/event]

=== [clear_variable] ===

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro [http://www.wesnoth.org/macro-reference.xhtml#CLEAR_VARIABLE CLEAR_VARIABLE] is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

* '''name''': the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
** If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, <code>{CLEAR_VARIABLE my_awesome_array[2]}</code> deletes <code>my_awesome_array[2]</code>, but then moves <code>my_awesome_array[3]</code> to <code>my_awesome_array[2]</code>, moves <code>my_awesome_array[4]</code> to <code>my_awesome_array[3]</code>, and so on until the end of the array.
** Note that <code>{CLEAR_VARIABLE my_awesome_array}</code> deletes the entire array, but <code>{CLEAR_VARIABLE my_awesome_array[0]}</code> deletes only the first container.

=== [sync_variable] ===

{{DevFeature1.13|0}}

Sets one or multiple variables to the same value as on all clients and also on replays, it uses the value from the currently active side.
* '''name''' the name of the variable to synchonize this can be a comma seperated list.

== Other Internal Actions ==

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

=== [fire_event] ===

Trigger a WML event (used often for [[EventWML#Custom_events|custom events]])

* '''name''': the name of event to trigger
** ''(Optional)'' {{DevFeature1.13|6}}

* '''id''': ''(Optional)'' the id of a single event to trigger {{DevFeature1.13|6}}

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.

* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.

=== [remove_event] ===
{{DevFeature1.13|0}} Removes the event with the specified id.

* '''id''': the id of the event to remove. May be a comma separated list.

=== [insert_tag] ===

Inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form. ([[#.5Binsert_tag.5D_Example|See Example]]).

Tag insertion is a special case in that it can be used in places where other ActionWML cannot be used. The basic rule is that anywhere that $variable syntax works, tag insertion will also work. In practice this means pretty much everywhere except directly within top-level scenario tags.

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': Name of the container variable which will have its value inserted into the tag. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

=== [role] ===

Tries to find a unit to assign a role to. This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.

* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

* '''search_recall_list''': {{DevFeature1.13|5}} whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. {{DevFeature1.13|6}} If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it.

* '''[else]''' {{DevFeature1.13|5}} ActionWML to execute if the game is unable to find a unit to assign the role to. For example, this could be used to create a new unit satisfying the role.

* '''[auto_recall]''' {{DevFeature1.13|6}} If present, and the role is assigned to a unit on the recall list, then that unit is recalled. Supports all unique keys of [[DirectActionsWML#.5Brecall.5D|[recall]]], but no [[StandardUnitFilter]].

* [[StandardUnitFilter]], do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

=== [random_placement] ===
{{DevFeature1.13|2}}

Selects randomly a given number of locations from a given set of locations and exectutes the given code for each of those locations.

* '''[filter_location]''': a [[StandardLocationFilter]].
* '''[command]''': contains ActionWml that is executed for each of the locations.
* '''num_items''': the number of locations that should be selected. There are several ways of specifying this:
** An integer, giving the exact number of locations to use. (Variable substitution is supported too.)
** {{DevFeature1.15|0}} A percentage, meaning that fraction of the total available spaces.
** {{DevFeature1.15|0}} A [[Wesnoth_Formula_Language|WFL]] formula. It has access to one variable, ''size'', which is the total number of available spaces. In order to identify it as a WFL formula, the entire expression must be enclosed in parentheses. (Do not use a '''$''', as that will cause it to see ''size'' as zero.)
** A Lua expression. As with a WFL expression, it can access the ''size'' variable. {{DevFeature1.15|0}} This is now deprecated.
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
* '''min_distance''': The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
* '''allow_less''': If yes, the tag will not show an error in case there were less than num_items locations available.

=== Flow control actions ===

{{DevFeature1.13|2}}

There are three actions that alter the flow of execution. They are '''[break]''', '''[continue]''', and '''[return]'''. All of them take no arguments.

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.
<syntaxhighlight lang=wml>
[event]
name=moveto
[fire_event]
name=return_please
[/fire_event]
[message]
message="Made it back"
[/message]
[/event]
[event]
name=return_please
[return][/return]
[/event]
</syntaxhighlight>

=== [unsynced] ===

{{DevFeature1.13|?}}

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example
<syntaxhighlight lang=wml>
[event]
name=moveto
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code
<syntaxhighlight lang=wml>
[event]
name=moveto
[unsynced]
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[/unsynced]
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

== Examples ==

=== Using [set_variables] to Create Arrays of WML ===

<syntaxhighlight lang=wml>
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
</syntaxhighlight>

This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.

=== [insert_tag] Example ===

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== See Also ==
* [[VariablesWML]]
* [[ActionWML]]
** [[ConditionalWML]]
** [[DirectActionsWML]]
** [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

SyntaxWML

2020-03-23T03:15:27Z

Sapient: to be or not to be

{{Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break without quotes would otherwise end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped – without quotes, all leading and trailing spaces would be removed, and internal runs of spaces would be replaced by a single space. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data. See [[TranslationsWML]] and [[GettextForWesnothDevelopers]] for more information.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign unless explicitly cleared.
Variable names should contain only alphanumerics and underscores, and the first character of the name should not be an underscore.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a unit filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in unit filters).

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

Specially-formatted comments are frequently used to give commands to the Wesnoth [[MaintenanceTools|maintenance tools]] to suppress false positives and enhance their coverage, as well as for adding explanatory comments for [[GettextForWesnothDevelopers#Marking_up_strings_in_WML|translatable strings]].

== Tutorial ==

* [[VariablesWML/How_to_use_variables|How to use variables]]

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SyntaxWML

2020-03-23T02:02:12Z

Sapient: minor grammar/clarity fixes

{{Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break without quotes would otherwise end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped – without quotes, all leading and trailing spaces would be removed, and internal runs of spaces would be replaced by a single space. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data. See [[TranslationsWML]] and [[GettextForWesnothDevelopers]] for more information.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign unless explicitly cleared.
Variable names should contain only alphanumerics and underscores, and the first character of the name should be not be an underscore.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a unit filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in unit filters).

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''owner_side''': inside a capture event, this contains the number of the previous owner (0 if previously unowned)
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

Specially-formatted comments are frequently used to give commands to the Wesnoth [[MaintenanceTools|maintenance tools]] to suppress false positives and enhance their coverage, as well as for adding explanatory comments for [[GettextForWesnothDevelopers#Marking_up_strings_in_WML|translatable strings]].

== Tutorial ==

* [[VariablesWML/How_to_use_variables|How to use variables]]

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Authoring tools

2018-07-18T19:22:38Z

Sapient: trackplacer bugs

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML. At present there is only one such tool: <tt>trackplacer</tt>.

== trackplacer ==

'''UPDATE: per Elvish_Hunter in [https://forums.wesnoth.org/viewtopic.php?f=21&t=48478&p=631121#p631121 this thread]:
'''<nowiki>"trackplacer is outdated (it requires the obsolete PyGTK toolkit, which doesn't run on Python 3) and terribly bugged (it doesn't run at all on Windows, for example)."</nowiki> Until it is fixed, you should use image editing software to find the X and Y coordinates to create each dot or cross manually.
-------------

'''trackplacer''' is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run '''trackplacer''', it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by '''trackplacer''' (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the '''trackplacer''' window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, '''trackplacer''' looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The '''Animate''' button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The '''Save''' button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The '''Properties''' button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of '''trackplacer'''. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to '''JOURNEY''').

The '''Tracks''' button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like '''JOURNEY_STAGE_1''', '''JOURNEY_STAGE_2''' and so on. '''JOURNEY_STAGE_1''' will draw the first stage in the 'new' color parts. '''JOURNEY_STAGE_2''' will draw the first stage in the 'old' color and the second stage in the 'new' one; '''JOURNEY_STAGE_3''' will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro '''JOURNEY_COMPLETE''' that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments
that look like this:

# trackplacer: tracks begin
# trackplacer: tracks end

'''trackplacer''' will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your ''journey.cfg'', looking like this:

<tt># trackplacer: <property>=<value></tt>

These set properties that '''trackplacer''' may use. At present there is only one such property: <tt>map</tt>, which records the name of the mapfile on which your track is laid. Don't remove this comment, '''trackplacer''' needs it.

'''trackplacer''' has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click '''Animate''' to refresh and slow down.

== CampSynt==

'''CampSynt''' is a tool to create a not so skeletal campaign as you can view in the help:

camp-synt -c -n -s [-s] -h [-h] -u [-u] -f -w

Warning: put underscores instead of spaces or include in double quotes (eg: a_string or "a string")
Warning: you can use long or short notations for options:
-c A_str is the same of -c "A str" and of --campaign=A_str and --campaign="A str"

OPTIONS:
-c Name_with_underscores or "Name in quotes". This option is mandatory.
-n Number of scenarios if not provided scenario's names via -s option
-s First_scenario [-s Second_scenario -s Third_scenario -s End]
one or more scenario names provided in sequential order
-h Hero_Name [-h Best_Friend -h My_Dog.Wolf]
one or more hero names to create and use in the story.
If the name contains a '.' (dot sign) everything following it is considerd as the type of that unit.
-u new_Unit [-u Another_one -u Last]
one or more new unit types to be included in the private units folder.
If the name contains two dot signs it will be splitted this way: new_unit_name, race, copied_from
like in: Farm_rebel.humans.Peasant
This need -w option properly set.
-f Force the rewrite of an existing file.
-w Wesnoth path (in double quotes if containing spaces) to access original units.
If this option is set and the path match 1.6 then the directory 'campaigns' is used instead of 'add-ons'.

EXAMPLES:
-c Camp_Name -n 3
-c Camp_Name -n 3 -f
-c Camp_Name -s Scenario_One -s Scenario_Two
-c Camp_Name -s Scenario_One -s Scenario_Two -h Hero_Name -u New_unit
-c Camp_Name -s One -s Two -h Hero_Name -h His_Friend -u New_unit -u New_Bowman
-c Camp_Name -s One -s Two -h Hero -h Friend.New_Bowman -u New_Bowman
-c Camp_Name -s One -s Two -h Hero.New_Bowman -u New_Bowman.humans.Peasant

campsynth is a perl script (with core modules usage only, suitable for most Linux systems and packed as exe for the enjoy of some other OS users). It was written based on 1.8.5 version of the game but can be also used with 1.6.x versions and was successfully tested with 1.9.5 (12 apr 2011). campsynth is located at the forum http://forum.wesnoth.org/viewtopic.php?f=8&t=29010

[[Category:Tools]]

StandardLocationFilter

2018-07-16T13:55:55Z

Sapient: /* Notes about Radius Usage */

{{WML Tags}}
__NOTOC__
From [[FilterWML]], this is the standard way of filtering on locations.
The term [[StandardLocationFilter]] means that the set of such keys and tags (see below) can appear at that point. Sometimes a [[StandardLocationFilter]] needs to be included in a [filter_location] tag. There are however many tags which accept the [[StandardLocationFilter]] directly as an argument such as [store_locations]. Generally, if the tag [filter_location] is not mentioned to be a possible subtag of the outer tag in question, then don't put it.

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, or neutral). Note: ''chaotic'', ''lawful'', and ''neutral''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [[#Filtering_Terrains|Filtering Terrains]]).
* '''x,y''': the same as in the unit filter; supports any range ([[StandardLocationFilter#Notes_about_Coordinate_Usage|notes]])
* '''location_id''': {{DevFeature1.13|?}} Matches a special location set in the map. This can also be a side number to match that side's starting location.
* '''area''': matches locations assigned to the [[DirectActionsWML#.5Btime_area.5D|[time_area]]] with the given id.
* '''include_borders''': {{DevFeature1.13|0}} whether the SLF will include border hexes or not. Will override the default behavior of the tag this appears in.
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes (which means a side can own that hex).
* '''[filter_vision]''': this tests whether or not the location is currently visible
** '''visible''': yes or no, default yes. "yes" filters for visible locations, "no" filters for invisible locations.
** '''respect_fog''': yes or no, default yes. "yes" filters for locations that are clear of both fog and shroud, "no" filters for locations that are clear of shroud.
** [[StandardSideFilter]] tags and keys as arguments. If there is *at least one* matching side which can see the location then the filter matches, and otherwise it fails to match.
*'''[filter_owner]''': If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([[StandardLocationFilter#Notes_about_Radius_Usage|notes]])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[#Directions|notes]])
* '''formula''': {{DevFeature1.13|5}} a [[Wesnoth Formula Language]] formula
* '''lua_function''': {{DevFeature1.13|5}} the name of a [[LuaWML|Lua]] function in the global environment that takes arguments <code>x, y</code> and returns true if the given location matches the filter. Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

==Notes about Coordinate Usage==

When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

While some locations should only be one hex (like the starting position of a unit),
others filter over multiple hexes.
The following syntax is used to filter over multiple hexes:

Dashes('''-''') are used to have the location be a range of hexes.
There must be values before and after the dash;
everything in between these numbers (inclusively) is part of the range.

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.
E.g. in order to specify multiple locations 1,4 and 2,5, use:

<syntaxhighlight lang='wml'>
[tag]
x=1,2
y=4,5
[/tag]
</syntaxhighlight>

Note: although the ordering of locations in a list generally does not matter,
the action '''[move_unit_fake]''' takes in a list of hexes,
and moves an image onto each of those hexes in order.

==Notes about Radius Usage==
If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.

<syntaxhighlight lang='wml'>
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
</syntaxhighlight>

Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:

<syntaxhighlight lang='wml'>
[have_location]
x,y=15,23
radius=5 # oops... this time it won't work as expected
[not]
[filter]
[/filter]
[/not]
[have_location]
</syntaxhighlight>

will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.

== Directions ==

Some attributes expect a direction or list of directions. Valid base directions are n, ne, nw, s, se, sw, and there are three operators supported as well:

* To take the opposite direction, use - (eg -n is the same as s)
* {{DevFeature1.13|2}} To rotate clockwise, use :cw (eg n:cw is the same as ne)
* {{DevFeature1.13|2}} To rotate counterclockwise, use :ccw (eg n:ccw is the same as nw)

You can't apply multiple rotation operators - for example, "n:cw:ccw" is not a valid direction. If for some reason you really need multiple rotations, you can use parentheses (so, "(n:cw):ccw" is valid and is the same as n). Similarly, "--n" is not valid, but "-(-n)" is valid and is the same as n.

This syntax is mainly useful when used in conjunction with variable substitution in the adjacent key in [filter_adjacent_location] and in [filter_adjacent] (in [[StandardUnitFilter]]), but will work anywhere a direction is expected. For example, using [modify_unit] to change a unit's direction:

<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
# ... Whatever filter you need
[/filter]
facing=-$this_unit.facing
[/modify_unit]
</syntaxhighlight>

That will cause the matched units to turn around.

== Filtering Terrains ==

The '''terrain=''' key allows you to filter based on the terrain of a space, for example:

<syntaxhighlight lang='wml'>
[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]
</syntaxhighlight>

At some places the terrains can be filtered with a
match list. The list is a comma separated list and matching will stop
at the first matched [[TerrainCodesWML|terrain string]]. There's one special character
''!'' which inverts the meaning of a match. Terrain strings can
use the wildcard * to match zero or more following letters, characters
behind the * are not allowed and the result is undefined.

Example 1: 
ww* matches ww, www, wwW but not WWW 
!, ww returns false if ww found and true if not 
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.

Example 2: 
<nowiki>*</nowiki>^V* matches all village-terrain 
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).

For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].

== Tutorial ==
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

FancyAddonIcons

2018-05-17T02:47:40Z

Sapient: See Also

An add-on's icon is the first thing a player is going to look at when picking add-ons. A good add-on icon can attract many players, so it should not be neglected. However, custom images cannot be used, they will be seen only by people who have it installed, that usually means that the author will think it's correct, although it is not. Despite this limitation, there is a way to create quite cool add-on icons. It is called [[ImagePathFunctionWML]]. Another method that can be used is a [[DataURI]]

== Introduction ==
Of course, you can create a code like (careful, it is long!):
items/bonestack.png~BLIT(items/bonestack.png~CROP(20,0,52,52),0,20)~BLIT(items/bonestack.png~CROP(0,0,52,52),20,20)~BLIT(items/burial.png~CROP(20,0,52,72),0,0)~BLIT(items/burial.png~CROP(0,0,52,62),20,10)~BLIT(units/undead-skeletal/archer-die2-6.png~CROP(10,0,62,62)~RC(magenta>black),0,10)~BLIT(units/orcs/sovereign-lead-2.png~RC(magenta>black))~BLIT(items/burial.png~CROP(0,0,62,52),10,20)

But testing this will be very tedious and annoying, reloading the entire add-on to view it somewhere, or even uploading it to test it every time. To make this easier, download an add-on named ''Image loading tester'', it will help you a lot with this. The add-on is absolutely minimalistic, and has no obvious effect anywhere. To use it, either execute this WML chunk:
[lua]
code=<<wesnoth.image_test()>>
[/lua]

Or activate the debug mode (:debug in [[CommandMode]]), and use this command:
lua wesnoth.image_test()
The second option is probably more convenient.

A window will show up, there will be a text box and two buttons. Type your image code into the text box and click on the Show button (or hit Enter instead). This way, you will be able to verify it very quickly. It is recommended to do this while running wesnoth from command prompt (on Windows) or Terminal (on Linux), it will notice you about some errors in your code (on Windows, you can also read stderr.txt afterwards).

Because the code on a single line possibly with many nested brackets is almost unreadable for humans, it is recommended to write it in a text file with indentation and new lines, then to use Find&Replace to remove all tabs, spaces and new lines and paste it into the text box. I will use indented codes later, for better readability, and it will be necessary to remove all spaces and new lines from it or copying the version when it is already removed bellow it if you want to try it out.

To understand better the numeric values that look like just made up to fit, you might want to learn the coordinates needed in an image editor like GIMP.

It is also recommended to use wesnoth 1.12 or later wesnoth 1.11, 1.10 tends to randomly crash when copying stuff from the textbox and that annoys a lot, even if it happens only sometimes. I have written the examples to work with these versions.

Now, you can verify your codes easily, and you can progress to the next step.

== Step by step tutorial ==
Let us think about creating an add-on image for a campaign where elves attack undead. It would consist of an Elvish Hero chopping undead to pieces, supported by spells of an Elvish Sorceress behind him. We will create an image for it in several steps. Try out each one of them to see what is changed.

'''1.''' Image showing an Elvish Hero in an attacking position is units/elves-wood/hero-melee-3.png. So we start with it:
units/elves-wood/hero-melee-3.png

'''2.''' Nothing interesting so far. Let us add a skeleton he is slashing. The image units/undead-skeletal/skeleton/skeleton-se-melee3.png is in a good fighting position, also exposing his belly to our hero. We will use the ~BLIT function of [[ImagePathFunctionWML]] to add him to the picture. Now we have:
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png
)
Note that the new lines and indentation are added only for readability, it will not work in game, you'll have to remove all new lines and breaks. Here it is without indents:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png)

'''3.''' However, they are quite in an awkward position. We will need to add some offset to the skeleton. ~BLIT accepts two additional arguments that mean the offset of the image. However, it would not fit on the image then (this prints an error message into the command line, Termina or stderr.txt), so we need to crop it. The ~CROP function accepts four arguments, the first two are the coordinates where the selected part of the image should start (pixels to the right first, pixels down second), the second two is the desired size of the result (width and height respectively). In this case, we start cropping on the top left corner, therefore the first two coordinates will be 0 and 0. The offset will be 20,20 (pixels to left first, pixels down second), so we need the resolution of the image to be 52x52 (original is 72x72, we subtract 20 from both numbers). The four arguments of crop will be therefore 0,0,52,52, and the two additional arguments of ~BLIT will be 20,20. Together, it should look like this:
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(0,0,52,52)
,20,20)
Or without indentation:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(0,0,52,52),20,20)

'''4.''' Now, the skeleton needs to be headed differently, because he isn't attacking the hero. The ~FLIP function is designed for this. Use ~FLIP(horizontal) for this. We will also need to adjust the offset in CROP and BLIT, because it would look bad:
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,47)~FL(horizontal)
,40,20)
Or without indentation:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,47)~FL(horizontal),40,20)

'''5.''' However, we want the skeleton to be chopped in half by the Hero's sword. We can do this by placing two conveniently cropped images of skeleton one above another.
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)
,40,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal)
,40,47)
Or without indentation:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal),40,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal),40,47)

'''6.''' We want our heroes to be also teamcoloured, so we can change the default colour (magenta) to some other colour. The colours you can change it to can be found in the data/core/team_colors.cfg file. The colours are changed using the ~RC function. Because our heroes are good and the undead are bad, let's team-colour the undead black and the heroes white.
units/elves-wood/hero-melee-3.png~RC(magenta>white)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal)~RC(magenta>black)
,40,47)
Or without indentation:
units/elves-wood/hero-melee-3.png~RC(magenta>white)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal)~RC(magenta>black),40,47)

'''7.''' Now, we want to add the Sorceress casting a spell to the background. She should be behind the Elvish Hero, and she should have an offset, but that can be done by cropping. To make sure that she won't be hid behind the Hero too badly, the hero and the skeleton will have to be offset too. Because we need an image of dimensions 72x72 as background, and a cropped Sorceress does not have such dimensions, we will have to use misc/blank-hex.png as background (it is a blank image) and place the sorceress on it. The offsets were adjusted to make it look better.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(15,10,57,62),0,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

'''8.''' Now, we need to add some halo to her, she is casting a spell, no? A suitable halo can be halo/elven/faerie-fire-halo4.png, let's use it. Its resolution is 96x96, that is quite awkward because it is larger than our image, but we can crop it easily.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52)
,0,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62),0,0)~BLIT(halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52),0,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

'''9.''' Now, to add the homing missile of the spell. halo/elven/ice-halo3.png looks convenient. Placing it on the image together with a skeleton that would be the victim of this spell is analogical to things done previously.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52)
,0,0)
~BLIT(
units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black)
,30,0)
~BLIT(
halo/elven/ice-halo3.png~CROP(0,20,62,52)
,10,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62),0,0)~BLIT(halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52),0,0)~BLIT(halo/elven/ice-halo3.png~CROP(0,20,62,52),10,0)~BLIT(units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black),30,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

'''10.''' We might colourise the skeleton blue, to make him appear frozen. There are two functions for this, ~CS and ~GS. ~GS removes all colour, transforming all colours into shades of gray. ~CS is used to change the colour, it accepts three arguments, the change to the red colour, the change to the green colour and the change to the blue colour. Negative numbers (from -1 to -255) mean removing the colour from all pixels (respecting transparency), so ~CS(0,-255,-255) will remove all colours except red, so that only the red part of the light will remain. Positive numbers (from 1 to 255) will add the colour to all pixels (unless invisible), so ~CS(255,0,0) will set the red fraction of the colour to maximum. ~CS(255,-255,-255) will remove all colours but red, and add a maximum of red everywhere, creating a single-colour image. To create the effect of frozen, we first use ~GS and then we use ~CS to make it bluer.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52)
,0,0)
~BLIT(
units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black)~GS()~CS(50,50,150)
,30,0)
~BLIT(
halo/elven/ice-halo3.png~CROP(0,20,62,52)
,10,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62),0,0)~BLIT(halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52),0,0)~BLIT(units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black)~GS()~CS(50,50,150),30,0)~BLIT(halo/elven/ice-halo3.png~CROP(0,20,62,52),10,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

Now, we are done with this image.

== More examples ==
Here are more examples of stuff you can do using these methods. They don't contain precise information how it is done, but it should be clear if you have read the tutorial.

=== The Spellsword ===
The purpose of this example is to show the usage of the opacity ~O function. When called on magical halo, it can be used to make the halo partially before and partially behind the unit (place the image there twice with 50% opacity, once under him, once above him). It can be also used to create motion blur.

halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%)
~BLIT(
units/elves-wood/high-lord-attack-sword-2.png~CROP(6,6,66,66)~O(25%)~RC(magenta>blue)
)
~BLIT(
units/elves-wood/high-lord-attack-sword-2.png~CROP(3,3,69,69)~O(50%)~RC(magenta>blue)
)
~BLIT(
units/elves-wood/high-lord-attack-sword-2.png~RC(magenta>blue)
)
~BLIT(
halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%)
)
~BLIT(
halo/elven/faerie-fire-halo3.png~CROP(0,5,57,72)
,15,0)
Without indentation:
halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%)~BLIT(units/elves-wood/high-lord-attack-sword-2.png~CROP(6,6,66,66)~O(25%)~RC(magenta>blue))~BLIT(units/elves-wood/high-lord-attack-sword-2.png~CROP(3,3,69,69)~O(50%)~RC(magenta>blue))~BLIT(units/elves-wood/high-lord-attack-sword-2.png~RC(magenta>blue))~BLIT(halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%))~BLIT(halo/elven/faerie-fire-halo3.png~CROP(0,5,57,72),15,0)

=== Zorro ===
The purpose of this example is to show that some body parts can be taken from the original body (provided that they can be selected easily), modified and placed back. Or placed on to different place. Or to a completely different sprite.

units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)
~BLIT(
units/human-loyalists/master-at-arms-crossbow-2.png~CROP(2,27,18,14)~FL(horiz)
,48,27)
~BLIT(
units/human-outlaws/assassin-throwknife1.png~CROP(29,17,11,13)~RC(magenta>black)
,26,21)
~BLIT(
halo/misc/leadership-flare-7.png~CROP(0,5,46,67)
,26,0)
~BLIT(
halo/misc/leadership-flare-6.png~CROP(33,7,39,65)
,0,0)
~BLIT(
units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)~CROP(20,11,20,17)~CS(-100,-100,-100)
,20,11)
Without indentation:
units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)~BLIT(units/human-loyalists/master-at-arms-crossbow-2.png~CROP(2,27,18,14)~FL(horiz),48,27)~BLIT(units/human-outlaws/assassin-throwknife1.png~CROP(29,17,11,13)~RC(magenta>black),26,21)~BLIT(halo/misc/leadership-flare-7.png~CROP(0,5,46,67),26,0)~BLIT(halo/misc/leadership-flare-6.png~CROP(33,7,39,65),0,0)~BLIT(units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)~CROP(20,11,20,17)~CS(-100,-100,-100),20,11)

=== Lich Wars ===
The purpose of this is to show how can text be used in the graphics. It mostly revolves around the misc/font8x8.png file (it is not in core, but in another images folder belonging to the game, next to the data folder that contains the core folder; using it causes no trouble).

misc/blank-hex.png
~BLIT(
units/undead-skeletal/deathblade-dying-2.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62)~O(50%)
,10,10)
~BLIT(
units/undead-skeletal/deathblade-dying-1.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62)
,10,10)
~BLIT(
units/undead-necromancers/ancient-lich-melee.png~RC(magenta>red)~CROP(20,10,52,62)
)
~BLIT(
halo/undead/black-magic-3.png~FL(vert)~CROP(15,40,72,60)~O(70%)
)
~BLIT(
misc/blank-hex.png
~BLIT(
misc/font8x8.png~CROP(39,33,8,8)
,16,56)
~BLIT(
misc/font8x8.png~CROP(16,32,8,8)
,24,56)
~BLIT(
misc/font8x8.png~CROP(47,24,8,8)
,32,56)
~BLIT(
misc/font8x8.png~CROP(8,33,8,8)
,40,56)
~BLIT(
misc/font8x8.png~CROP(48,41,8,8)
,16,64)
~BLIT(
misc/font8x8.png~CROP(32,25,8,8)
,24,64)
~BLIT(
misc/font8x8.png~CROP(8,40,8,8)
,32,64)
~BLIT(
misc/font8x8.png~CROP(16,41,8,8)
,40,64)
~CS(-255,0,-255)
)
Without indentation:
misc/blank-hex.png~BLIT(units/undead-skeletal/deathblade-dying-2.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62)~O(50%),10,10)~BLIT(units/undead-skeletal/deathblade-dying-1.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62),10,10)~BLIT(units/undead-necromancers/ancient-lich-melee.png~RC(magenta>red)~CROP(20,10,52,62))~BLIT(halo/undead/black-magic-3.png~FL(vert)~CROP(15,40,72,60)~O(70%))~BLIT(misc/blank-hex.png~BLIT(misc/font8x8.png~CROP(39,33,8,8),16,56)~BLIT(misc/font8x8.png~CROP(16,32,8,8),24,56)~BLIT(misc/font8x8.png~CROP(47,24,8,8),32,56)~BLIT(misc/font8x8.png~CROP(8,33,8,8),40,56)~BLIT(misc/font8x8.png~CROP(48,41,8,8),16,64)~BLIT(misc/font8x8.png~CROP(32,25,8,8),24,64)~BLIT(misc/font8x8.png~CROP(8,40,8,8),32,64)~BLIT(misc/font8x8.png~CROP(16,41,8,8),40,64)~CS(-255,0,-255))

== See Also ==

* [[ImagePathFunctionWML]] - The reference for the functions used here
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string

[[Category:WML_Tips]]

ImagePathFunctions

2018-05-17T02:44:16Z

Sapient: /* See Also */

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, and 1.12 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White Function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale Function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative Function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch Function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

=== RC: Re-Color Function ===
May be used to change some colors in an image.

'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia Function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap Function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color Function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip Function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate Function ===
May be used to rotate an image by a multiple of 90 degrees.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear intorpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-and-paste ==

=== BLIT: Blit Function ===
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

=== CROP: Crop Function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== MASK: Mask Function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===
Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== DARKEN: Overlay function ===
{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Overlay function ===
{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== CHAN: General function ===

{{DevFeature1.13|?}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel.

'''~CHAN(formula, formula, formula)'''

=== NOP: Null function ===
Does nothing.

'''~NOP()'''

== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string

[[Category:WML Reference]]

SyntaxWML

2018-04-29T18:37:12Z

Sapient: /* Automatically Stored Variables */ teleport_unit

{{Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data. See to [[TranslationsWML]] for more information.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string.

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign unless explicitly cleared.
Variable name should contain only alphanumerics and underscores, and the first character should be non-underscore.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a unit filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in unit filters).

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''teleport_unit''': inside the [[AbilitiesWML#Extra_tags_used_by_the_.5Bteleport.5D_ability|[tunnel]]] tag used by a teleport ability, this is the unit with that ability

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

== Tutorial ==

* [[VariablesWML/How_to_use_variables|How to use variables]]

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SyntaxWML

2018-04-25T07:51:59Z

Sapient: /* Variables */ putting a regular expression here was not increasing anyone's understanding

{{Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data. See to [[TranslationsWML]] for more information.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string.

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name. Once created, a variable persists until the end of a campaign unless explicitly cleared.
Variable name should contain only alphanumerics and underscores, and the first character should be non-underscore.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
* In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a unit filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in unit filters).

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

== Tutorial ==

* [[VariablesWML/How_to_use_variables|How to use variables]]

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

WML for Complete Beginners: Chapter 1

2017-12-16T21:14:30Z

Sapient: /* Attributes */

{{Translations}}

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
grocery_store
::as is this:
bread

::If a standard string is more than one simple identifier, it is better for it to be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to be one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll discuss Variable Manipulation in chapter 7). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level_3_tagset]
level_4_attribute=value
[/level_3_tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 1

2017-12-16T20:53:27Z

Sapient: /* Attributes */

{{Translations}}

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
grocery_store
::as is this:
bread

::If a standard string is more than one simple identifier, it is better for it to be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to be one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level_3_tagset]
level_4_attribute=value
[/level_3_tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

Geography of Wesnoth

2017-09-05T19:12:53Z

Sapient: /* Delfador's Memoirs */

{{Translations}}
== Irdya ==

The name of the world in which the kingdom of Wesnoth is situated is "Irdya". This term is , however, only rarely used in the era depicted by the main map. People normally just say "the world" or, poetically, "the wide green world".

== Wesnoth and Surrounding Lands ==

[https://github.com/wesnoth/wesnoth/blob/master/data/core/images/maps/wesnoth.png https://github.com/wesnoth/wesnoth/blob/master/data/core/images/maps/wesnoth.png]

This map is current for approximately YW 450. Named cities were founded during the Golden Age of Wesnoth and have thus have existed for at least 200 years.

Place names in '''bold''' are marked on the main map.

* Major features:
** '''The Great Ocean''': Lies to the west of the continent and all rivers eventually flow to it.
** The '''Bay of Pearls''': The Elensefar Peninsula in the North and the '''Isle of Alduin''' in the southwest separate this from the Great Ocean. This is where human refugees from the Green Isle first landed in 1YW.
** '''Isle of Alduin''': Inhabited island off the west coast of the Great Continent. Home of the Great Academy of Magic and a traditional center of magecraft.
** '''The Three Sisters''': Group of three islands north-northwest of Alduin. The nearest is individually known as the Isle of the Damned and has an evil reputation.
** '''The Great River''': Runs east to west on the main map, unmarked.
** '''Ford of Abez''': Easternmost point at which the Great River can be crossed without ships. A traditional invasion route for armies crossing in either direction.
** '''River Weldyn''': Tributary running north from the '''Dulatus Hills''' to the '''Great River'''.
** River Aethen: River running from the '''Dulatus Hills''' to the '''Great Ocean''' through the '''Aethenwood'''.
** '''The Heart Mountains''': the major mountain range surrounding '''Lake Vrug'''.

=== Wesnoth ===
The Kingdom of Wesnoth is located in the north-central portion of the Great Continent. Most of the mainline campaigns revolve around it. It is bounded on the map by the '''Great River''' to the north, the shore of the '''Great Ocean''' to the west, the Aethenwood to the southwest, and the '''Bitter Swamp''' to the southeast (lower right corner of the main map).

Over the '''River Aethen''', south of '''Fort Tahn''', is a Wesnothian frontier region. It is bounded to the south (off-map) by dense woods of which the '''Aethenwood''' may be considered a northernmost extension.

* Notable cities:
** '''Weldyn''': The capital of Wesnoth.
** '''Aldril''': City lying on the Bay of Pearls.
** '''Blackwater Port''': City lying south of the Bay of Pearls.
** '''Carcyn''': Located between the Grey Woods and the Great River.
** '''Dan'Tonk''': Wesnoth's largest city, located in the center of the country, just west and north of Weldyn.
** '''Soradoc''': The northernmost border outpost of Wesnoth, controls the confluence of the Weldyn River and the Great River.
** '''Fort Tahn''': The southernmost border outpost, controls the north/south road crossing the River Aethen.
** '''Tath''': Important fort city north of Dan'Tonk, exerts control over the wilderness country around the east of the Brown Hills and north to the '''Ford of Abez'''.

* Notable land features:
** '''Gryphon Mountain''': Home of the fabled Gryphons
** '''Ford of Abez''': Shallow part of the Great River, it is usually controlled by Wesnothian forces
** '''Weldyn River''': It branches from the Great River and goes south
** Great Central Plain: Area bounded by Weldyn, Dan'Tonk, and Fort Tahn, this plain is Wesnoth's bread basket and home to most of its population
** '''Dulatus Hills''': These rolling hills bordering the Great Central Plain provide much of Wesnoth's livestock and agriculture
** Brown Hills: Wasteland surrounding Gryphon Mountain that is not well-populated and occasionally very dangerous.
** Horse Plains: Region of rolling plains just south of the '''Great River''', bounded by '''Glyn's Forest''' to the west and the '''River Weldyn''' to the east; the southern reach merges into the Central Plain. Home of the powerful Clans; the best horses in Wesnoth are bred here.
** '''Estmark Hills''': Largish range rising south of the Great River and east of the Weldyn River. The northernmost portion, nearest the '''River Weldyn''', has at various times been settled by Wesnothians, but the Kingdom's control is tenuous at best and banditry is common.
** '''Glyn's Forest''': Sometimes known as the Royal Forest, named for one of Haldric II's sons
** '''Grey Woods''': Large forest in the heart of the wilds of Wesnoth, located between Carcyn and Aldril and generally considered to be haunted
** Green Swamp: Large swamp in the heart of the wilds of Wesnoth, south of Aldril. (Not shown on the main map.)

=== Southwest Elven Lands ===
The Wood Elves are separate from those of the north, and have only intermittent relations with them and most other countries. Its borders are the Green Swamp to the northeast, the desert (not shown) to the south, and the Ocean to the west.
* Notable cities
** None known
* Notable land features:
** '''Aethen Forest''': The largest southern forest, it extends far to the southwest - much farther than is charted - and is home to elves

=== Elensefar ===
'''Elensefar''' is at times a province of Wesnoth, at times an independent country, and at times in a treaty federation with Wesnoth. Its borders are the Great River to the north, a loosely defined line with Wesnoth to the east, the Bay of Pearls to the south, and the ocean to the west. More information is found in the [[Timeline of Wesnoth|historical narrative]] of Wesnoth.

* Notable cities:
** '''Elensefar''': The capital, located on an island in the Great River delta
** '''Carcyn''': City on the Wesnoth-Elensefar border, disputed with Wesnoth
* Notable land features:
** '''Great River''': It is very wide at this point, and only ships can cross it.

=== Northlands ===

There is no government of the Northlands. Various groups of orcs, dwarves, barbarian men and even elves populate the region. The northern and eastern borders are not defined, the southern border is the '''Great River''', and the western border is the '''Great Ocean'''.

* Notable cities:
** '''Glamdrol''': An Orcish tribal capital
** '''Romyr''': Another Orcish tribal capital
** '''Wesmere''': The location of the Ka'lian - the Elvish Council
** Dwarven Doors: A mixed human/dwarven town in the region of Knalga in the southern Heart Mountains. A major trade center.
** Dallben and Delwyn: Human villages originally built by settlers who crossed the Great River during Wesnoth's Golden Age expansion. Now abandoned. The forested area northeast of '''Elensefar''', where these villages were located, was named the Annuvin province by men but was known by the elves as Wesmere.

* Notable land features:
** '''Heart Mountains''': A virtually impassable barrier between the river country and the Northern Plains.
** Heartfangs: the particularly forbidding stretch of high peaks southwest of '''Lake Vrug''' and north of the '''Forest of Wesmere'''. The most inhospitable and dangerous portion of the '''Heart Mountains'''; only hermits, madmen, and mages live there.
** '''Swamp of Dread''': a very large bog located between the '''Heart Mountains''' and the '''Great River'''. A notoriously dangerous place.
** '''Lake Vrug''': A large mountain lake whose river carves the only pathway through the Northern Mountains
** '''Arkan-thoria''': The river than comes out of Lake Vrug. This is the elvish name; among humans it is called Longlier.
** '''River Listra''': The south-running tributary of the Great River into which the '''Arkan-thoria''' empties.
** '''Lintanir Forest''': The southernmost portion of the Great Northern Forest, a gigantic wood whose eastern and northern boundaries are known only the elves. Their capitol, Elensiria, has only seldom been visited by humans.
** '''Great River''': The origin of this river is somewhere in the east of the northern lands

==== Wesmere====
The location of the Ka'lian - the Elvish Council in the Eastern part of the forest. The river Telfar flows through the forest. The Kal'ian is on an island in the Telfar. The River Telfar is crossed by the Northern Shallows, the Ford of Alyas, the Ford of Tifranur and the North Bridge. Villages surrounding the Ka'lian are named Telionath, Arthen, Arryn, Illissa, Viricon, Tireas, Essarn, Valcathra, Aelion, Elendor, Erethean. Other areas near the Ka'lian are Brightleaf Wood, Telfar Green (an opening in the forest), Dancer’s Green (an opening in the forest), Karmarth Hills, Westwind Wood (possibly the foothills of the Heart Mountains to the north east of Wesmere), Southwind Wood. East and outside are the forest are the villages of Dallben and Delwyn.

== Far North ==

[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Son_Of_The_Black_Eye/images/maps/sotbe.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Son_Of_The_Black_Eye/images/maps/sotbe.png]

Cold, harsh, and inaccessible, the Far North is the ancestral home of the Orcish Clannate. It lies north of the Heart Mountains, which the Orcs call the Haggid-Dargor and claim (without merit) as their own. To the east lie the Unaligned Tribes of the Wild Steppe, who fell out of the control of the Clannate, instead roaming with wild human barbarians and clashing with the High Elves of the North Plains (known as North Elves in human lands). The High Elves themselves reside further east, where it is rumored they rule a vast kingdom.

* Notable cities:
** Barag Gor, a city home to the Orcish Council
** Bitok
** Borstep
** Castelfrang
** Farzi
** Festog
** Grisbi
** Lmarig
** Melmog
** Prestim
** Tirigaz
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Mountains of Haag
** Green Forest
** Silent Forest
** Forest of Thelien
** River Oumph
** River Bork
** Wild Steppe

===Area around Tirigaz===
Featured in [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water Dead Water].

[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Dead_Water/images/maps/dw.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Dead_Water/images/maps/dw.png]
* Notable cities:
** Tirigaz
** Jotha
**Agvorad
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Bilheld, a large island.
** A small island of coast of Bilheld

== The Southern Land ==
<tt>Where is this confirmed?</tt>

This is the land to the far south of wesnoth.
* Notable cities:
** Serrul: a peaceful city that excels at sea trade.
** Varrant: a prosperous trade city.
** Kesh: a powerful military city.
** Azen: capitol of the Azgar (a Expansionist clan with a strong military force)
* Notable land features:
** The Ashland Desert: a long and hot desert that leads to Wesnoth.

== The Green Isle ==
The geography features in [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth The Rise of Wesnoth]. In this place names are placed over the map below as overlays.
http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/campaigns/The_Rise_Of_Wesnoth/images/story/the_green_isle.png
=== Wesfolk Land ===
This is where the Wesfolk live, with their Lich overlords. The boundary between it and the Islefolk land is the hilly area running south-west to north-east. The Wesfolk land is in the north-west. Little is known about what happened to the island after Haldric left.
* Notable cities:
** Jevyan's Haven: The capital of the Wesfolk, where Jevyan reigned; presumably where the gates to orcland were opened
* Notable land features
** None. (its not a very detailed map, is it? :) )

=== Islefolk Land ===
This is where the Islefolk (Haldric's folk) live. The boundary is the same as that of the Wesfolk; the islefolk land is to the southeast.
* Notable cities:
** Blackmore: {??}
** Clearwater Port: {??}
** Southbay: {??}
* Notable land features:
** None. (see Wesfolk land)

== Campaign References ==

This section collates specific facts about geography asserted in the the text of mainline campaigns, implied by map dots (track) or by features on a battle map (map). It aims to be complete as to locations on the main map and identifiably adjacent to it. Two groups of off-map locations are confined to single campaigns, the Green Isle in ''The Rise of Wesnoth'' and the Far North in ''Son of the Black Eye''; those locations are not listed here.

=== Heir To The Throne ===

Konrad was raised in the '''Aethenwood''' (track, ''The Elves Besieged''). He returns to the mainland very near the location where Haldric the Great first landed in 1YW. (map, ''Bay of Pearls''). The fight with Muff Malal takes place on the peninsula north of the '''Bay of Pearls''' (track, ''Bay of Pearls''). The city of '''Elensefar''' is actually located on a large island in the mouth of the '''Great River''' (map, ''The Siege of Elensefar''). The crossroads fight takes place where the roads from '''Carcyn''', '''Dan'Tonk''' and '''Fort Tahn''' meet (track, ''Crossroads''). Konrad meets Li'sar on the road between '''Dan'Tonk''' and '''Carcyn''' (track, ''The Princess of Wesnoth''). Konrad fights undead in the Brown Hills southeast of '''Gryphon Mountain''' (track, ''Valley of Death''). The track for ''Gryphon Mountain'' unsurprisingly lands on the '''Gryphon Mountain''' map feature; equally unsurprisingly, the track for ''Ford of Abez'' lands on the '''Ford of Abez''' map feature.

North of the '''Great River''' this campaign is our basic textual evidence for several important features. The country around the easternmost tip of the '''Swamp of Dread''' is described as "abundant pine forests nestled in rolling foothills" (track and text, ''Northern Winter'') and, at least during the Turmoil of Asheviere, is inhabited by orcs. Dwarven Doors and Knalga are located in the center of the southern arm of the Heart Mountains, south-southeast of Lake Vrug (''The Dwarven Doors''). Lionel, the Lost General, is found in an orcish warren at the northern edge of the southern '''Heart Mountains''', north-northeast of Knalga and adjacent to the valley of the Arkan-thoria (''The Lost General''). Konrad re-encounters Li'sar north across that valley in the foothills of the northern '''Heart Mountains''' (track, ''Hasty Alliance''). The Scepter of Fire is found in those same foothills a bit further east and south, just north of the southernmost bend of the '''Arkan-thoria''' (''Scepter of Fire'').

Konrad's party travels southeast through the caverns, under the '''Arkan-thoria''', to just south of a northward bend of the river (''A Choice Must Be Made''). Kalenz says that this river is called 'Longlier' by men and 'Arkan-thoria' by the Elves. He further says that the homeland of his people lies to the east and north. Kalenz identifies their location at the easternmost edge of the southern '''Heart Mountains''' (track, ''Snow Plains'') as "...once the home of my people. We left here centuries ago" (text). In the next scenario, the North Elves are contacted at the confluence of the '''Arkan-thoria''' and the '''Listra''' (track, ''Home of the North Elves''). Konrad's party take refuge in Emetria, an Elven castle located just within the border of the southern lobe '''Lintanir Forest'''. ''The Elven Council'' takes place in the elven capital of Elensiria, location not specified.

Konrad crosses the '''Great River''' into Wesnoth just north of '''Soradoc''' (''Return to Wesnoth''). The country between the Elven forests and the river is inhabited by, among other things, "hermit mages" (text). He then crosses the river into the '''Estmark Hills''' hills east of the '''Weldyn River''' (track, ''Test of the Clans'').

Neither the '''Estmark Hills''', nor the '''Heart Mountains''', nor the swamp between them and the '''Great River''' are named in this campaign, but one scenario title refers to the latter as ''Swamp of Dread''.

Continuity problems: the map for 'The Princess of Wesnoth' is difficult to reconcile with the track location; the lake to the south should be large enough to show on the main map and is difficult to fit in a valley in the Brown Hills.
Likewise, the map for ''Home of the North Elves'' shows only an east-west river probably too small to be the '''Arkan-thoria''', and not the '''Listra''' that it should flow into.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:HttT#Labels map labels]

=== A Tale of Two Brothers ===

This campaign has a tracking map. In text, the village of Maghre is described as being in the "western reaches of Wesnoth" (''Rooting Out a Mage''). In ''The Chase'', the haunted forest is identified as the Grey Woods.

=== An Orcish Incursion ===

This campaign has a map and a journey track. No places are named other than '''Wesmere'''; the action takes place north and west of there. A pass that is bottleneck route through the northern mountains figures in the action.

=== The South Guard ===

This campaign takes place off the main map and has its own background map.

We know from it that the city of Westin is located southwest of '''Fort Tahn''' (track, ''Born To The Banner'') and is capital of the frontier province of Kerlath (text), also that the Aethenwood is to the west (text).

There is no map track after the second scenario. We learn that south of Westin , Kerlath is bounded by dense woods, "a bastion of the ancient heart forest of the Great Continent so dense and gloomy that even elves forbore from dwelling there."
(''Born to the Banner'') South of it an unspecified distance lies the elven Vale of Tears, and much further south of that the Black River, of which Etheliel says "No elf, still living, has crossed it."

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:TSG#Labels map labels]

=== Liberty ===

This campaign uses a modified version of the main Wesnoth map for tracking. The map shows the villages of Dallben and Delwyn, and some small patches of forest, between the forest of Wesmere and the ocean; also it labels the '''Grey Woods'''. Text (''The Raid'') identifies this as the province of Annuvin, a frontier area of Wesnoth. It is clear that '''Elensefar''' is the chief city of Annuvin.

Baldras and his party travel south to '''Elensefar''' (track, ''A Strategy of Hope''). From there they go upriver to '''Carcyn''' (track, ''Hide And Seek''), and south to the '''Grey Woods''' (track, ''The Grey Woods''), then south on the road to ''Aldril''. The campaign finishes at '''Halstead'''. In the Epilogue, there is a reference to villagers fleeing southwest to settle on the '''Three Sisters'''.

The scenario maps feature [http://wiki.wesnoth.org/CampaignDialogue:L#Labels map labels]

=== The Rise of Wesnoth ===

This campaign has its own tracking map for the Green Isle, which is our only actual source of information about the Green Isle's geography. The only Great Continent location of interest is the Ka'lian, which has the same location in the '''Forest of Wesmere''' that it does in other campaigns.

The lady Jessene uses the term "Old Continent" to describe the ancestral home of her people, and implies that it lies in "the far West".

=== The Legend of Wesmere ===
This campaign uses a [http://wiki.wesnoth.org/Geography_of_Wesnoth#LOW_Custom_Map modified version of the main Wesnoth map] for tracking. The map shows far fewer settlements with the notable addition of a castle settlement in the '''Swamp of Dread''', called '''Saurgrath''' (the location of ''The Saurian Treasury'').

The map track for ''Hostile Mountains'' shows Kalenz starting from the '''Lintanir Forest''' and moving across the easternmost '''Heart Mountains''' to a spot on the Arkan-thoria. They travel to '''Wesmere Forest''' (''The Ka'lian Under Attack''); the map tracking runs almost lengthwise through the '''Heart Mountains'''. The Ka'lian is near the northeast edge of '''Wesmere forest'''; the Elvish treasury is further west (track, ''The Elvish Treasury''). The Saurian treasury in the westernmost foothills of the '''Heart Mountains''' (track, ''The Saurian Treasury''); Kalenz and his men avoid the direct route from it back to Wesmere by going north from it and that they return via the eastern approaches to Wesmere. On the way, they re-encounter Olurf in the southeastern reaches of the '''Heart Mountains''' (''Acquaintance In Need''). They march back to the north edge of '''Wesmere Forest''' (track, ''Elves' Last Stand'').

In ''Council of Hard Choices'' we learn that the mage Crelanu lives in "the mountains of Thoria". The route north goes over the mountains to the "Arkan-thoria" (track: ''Bounty Hunters''), the name is confirmed in text. The mountains of Thoria themselves are just north of the valley of the '''Arkan-thoria''' (track, ''Cliffs of Thoria''). Crelanu's keep is well into the northern '''Heart Mountains''', right at the northern edge of the map (track, ''Battle of the Book'').

Kalenz and friends "return to the Ka'lian" (''News From The Front''); then to orcish forces are "encamped south of the '''Great River''', and have surrounded the fortified human settlement of Tath". The track for ''Breaking the Siege'' indicates that the killing of the Great Chief took place at the southeastern tip of the '''Heart Mountains''' and that ''Breaking the Siege'' takes place on the '''River Listra''', just north of the confluence with the '''Arkan-thoria'''.

The remaining scenarios convey no new information; the track points are all east of the '''River Listra''' between it and the '''Lintanir Forest'''.

Kalenz's home map has big water to the east. This has to be a lake off the NE corner of the main map, emptying into the main course of the Listra.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:LOW#Labels map labels]
====LOW Custom Map====
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png]

=== Eastern Invasion ===

This campaign has its own map, with the River Guard outposts shown, and a tracking map. The intro describes the location of the River Guard posts on "the near bank of the Weldyn", alludes to trouble in the Estmarks, and refers to "raiders from the great desert", location unspecified.

One path from ''An Unexpected Appearance'' leads west, the other east (text). But the western path forces Gweddry and his men to travel north, into "known forest country just south of the Great River" (text). On the other branch, Mal-Ravanal's capitol is in the '''Bitter Swamp''' (''Mal-Ravanal's Capitol''); the party flees "west and north" until they find a "low pass in the Estmarks, and [are] greatly relieved to see the valley of the Weldyn open before them." (text). In ''Undead Crossing'', Gweddry's party crosses the '''Great River''' to the north (text). One of the following scenarios is named '''Lake Vrug'''. In ''Drowned Plains'' the party goes south to the '''Great River''', crosses it, and Owaec announces that they have entered the Horse Plains. '''Weldyn''' is on the map of the final scenario.

The Orc kings stronghold map has [http://wiki.wesnoth.org/CampaignDialogue:EI#King_Dra-Nak.27s_City_.28labels.29 map labels]

=== The Hammer of Thursagan ===

This campaign has a tracking map. It begins at Knalga, and the heroes travel generally eastwards. There are no other specific geographical references in it, except to "the High Pass" about halfway between Knalga and Kal Kartha.

=== Descent Into Darkness ===

This campaign has a journey track, and a map on which the the "northern border town of Parthyn" (''Saving Parthyn'') appears. An eartly fight (''Orc War'') takes place near the river Longlier (the '''Arkan-thoria'''). This is denoted by a [http://wiki.wesnoth.org/CampaignDialogue:DID#Places_.28labels.29 map label]. Later in the campaign (''Return To Parthyn'') it is specified that Malin follows a trail south across the '''Great River''' and west to Parthyn. Part of the action (''A Small Favor'' and three sequels) takes place in the city of '''Tath'''.

=== Scepter of Fire ===

This campaign has a tracking map.
The campaign begins in "the foothills of Knalga" (text, ''A Bargain Is Struck'') when Haldric II rides north from there from the '''Ford of Abez'''. Rugnur looks for Thursagan in "the northern wastelands", which is near the coast north-northeast of Rumyr (''Searching for the Runecrafter''). Much of the rest of the campaign takes place in the old eastern mines just north of the Arkan-thoria; this is where the Scepter will be found in ''Heir To The Throne''. Alanin's running battle with the outriders takes place just north of the '''Ford of Abez''' (track, ''Outriding the Outriders'').

(Note: earlier versions of SoF were set in a completely different location in the far western foothills of the Heart Mountains. This was an error by some hapless chronicler.)

=== Son Of The Black Eye ===

This campaign takes place off the northern edge of the main map and has its own tracking map (see "The Far North") above. There is no reference to anywhere on the main map other than Dwarven Doors, and that does not indicate either distance or direction.

=== Dead Water ===

This campaign has a tracking map. It takes place on and near the coast of the Far North; the port city of Tirigaz, mentioned in '''Son of the Black-Eye''', is a locale of one scenario. We learn that one of the small islands off the coast is called Bilheld and is inhabited by drakes.

=== Secrets of the Ancients ===

This campaign has a tracking map. It begins at the Great Academy on Alduin.

=== Delfador's Memoirs ===

This campaign has a tracking map. Its scenario locations are in general well known from other campaigns. The campaign maps feature some [http://wiki.wesnoth.org/CampaignDialogue:DM#Places_.28labels.29 map labels]

=== Northern Rebirth ===

This campaign has a tracking map. It begins in Dwarven Doors. No distances or directions to places elsewhere in canon are indicated.

=== Under The Burning Suns ===

This campaign has no tracking map. It takes place long after the fall of Wesnoth and none of its locations can be clearly tied to anywhere in the main map.

== See Also ==

* [[Timeline of Wesnoth]]

[[Category:World of Wesnoth]]

EventWML

2017-07-26T15:11:30Z

Sapient: /* ai turn */

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Predefined Events Without Filters ====

These events do not take filter parameters (except [filter_condition] which works for all events).

===== preload =====

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

===== prestart =====

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== start =====

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== new turn =====

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

===== turn end =====

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

===== turn ''X'' end =====

Triggers at the end of turn ''X''.

===== side turn =====

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

===== ai turn =====

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event can break replays if it is used improperly. The ai turn event does not fire during replays. The intention is only to guide the AI to make choices (movements, attacks) which are then saved to the replay.''

===== turn refresh =====

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

===== turn ''X'' =====

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

===== side ''X'' turn ''Y'' =====

This event triggers at the start of turn ''Y'' of side X

===== side ''X'' turn =====

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn ''X'' =====

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side X turn Y refresh =====

This event triggers at the turn refresh for side X on turn Y

===== side ''X'' turn refresh =====

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== turn ''X'' refresh =====

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn end =====

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

===== time over =====

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

===== enemies defeated =====

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

===== victory =====

In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]]). This event is not synchonized in networked mp or in replays. The reason is that it is possible to have diffrent results in a mp game (one player wins so a '''victory''' event is fired on that client, other player loses so a '''defeat''' event is fired on his client)

===== defeat =====

In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]]). Like '''victory''', this event is not synchonized in networked mp or in replays.

==== Predefined Events With Filters ====

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

===== moveto =====

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

===== sighted =====

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away. You may want to use [filter_second] in order to restrict a sighted event in a single player scenario to only being triggered by the player and not by other non-allied sides.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

===== enter_hex =====

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== exit_hex =====

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== attack =====

Triggers when the primary unit attacks the secondary unit. Variables $weapon and $second_weapon contain weapons used for this attack by primary and secondary units respectively for all attack-related events (attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath).

===== attack end =====

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

===== attacker hits =====

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

===== attacker misses =====

Same as ''attacker hits'', but is triggered when the attacker misses.

===== defender hits =====

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

===== defender misses =====

Same as ''defender hits'', but is triggered when the defender misses.

===== petrified =====
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

===== last breath =====

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

===== die =====

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

===== capture =====

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

===== recruit =====

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

===== prerecruit =====

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

===== recall =====

Triggers after the primary unit is recalled (by the secondary unit).

===== prerecall =====

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

===== advance =====

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

===== pre advance =====

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

===== post advance =====

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

===== select =====

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

===== menu item ''X'' =====

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

===== unit placed {{DevFeature1.13|3}}=====

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit]
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
#The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

#This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

#And now a fire_event tag is used to trigger the previously defined event
[fire_event]
name=unit_recruited
[/fire_event]

#As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Whether to remove an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if yes, then the contents of the event are ignored and the event with the specified id is removed instead. {{DevFeature1.13|0}} May be a comma separated list.

[event]
id=id_of_event_to_remove
remove=yes
[/event]

Note: {{DevFeature1.13|0}} You can now use [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] instead (the [event] remove= syntax still works). It also accepts a comma separated list.

[remove_event]
id=id_of_event_to_remove
[/remove_event]

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]].

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
The following are not synced:
* select
* preload
* victory
* defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

VariablesWML/How to use variables

2017-05-10T10:11:57Z

Sapient: /* More with arrays */

== 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 type1). 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.[[In computering words, they are not '''strongly typed.'''|1)]], 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.|2)]]

==== 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:[[That’s why dots are forbidden in variable names : they are used to specify members.|3)]]
$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.[[That’s why = signs are forbidden in variables names : it corrupts savegames.|4)]]

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.
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[[Less easy because there is no macro for that.|5)]] 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[[It would be better if it exists… |6)]]. 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) [[You can minimize the risk using special key names like 'Pyro_level' instead of only 'level'… or write a feature request! |7)]] . 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

[[Category:WML_Reference]]
[[Category:WML_Tutorials]]

SyntaxWML

2017-05-10T02:48:54Z

Sapient: /* See Also */

{{SyntaxWML/Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable|translatable value]]'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name, which may contain only alphanumerics and underscores. Once created, a variable persists until the end of a campaign unless explicitly cleared.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

== Tutorial ==

* [[VariablesWML/How_to_use_variables|How to use variables]]

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Category:WML for Complete Beginners

2017-05-10T02:12:19Z

Sapient:

This category contains information on WML for complete beginners. To get started, head to [[WML for Complete Beginners: Introduction]].

[[Category:WML_Tutorials]]

Category:WML Tips

2017-05-10T02:10:52Z

Sapient:

This category is for pages that provide useful tips or advice regarding WML, without necessarily being reference material or WML fragments themselves.

== See Also ==
[[UsefulWMLFragments]]

[[Category:WML_Reference]]

WML for Complete Beginners: Introduction

2017-05-10T02:08:24Z

Sapient:

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Introduction|English]]
[[WML_for_Complete_Beginners:_Introduction/zh|简体中文]]
|}

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding out before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML. In addition, some very helpful people put together a program specifically designed to help you write WML, which you can find at [http://eclipse.wesnoth.org eclipse.wesnoth.org]

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without being required to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

===Ready to Get Started?===

When you are ready, head on over to [[WML for Complete Beginners: Chapter 1]] and let's get started!

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_Tutorials]]
[[Category:WML_for_Complete_Beginners]]

FilterWML/Examples - How to use Filter

2017-05-10T02:04:36Z

Sapient: /* Download as .pdf */

== WML Filtering ==

Filters are a very important part of WML language, and a fairly complex too for various
reasons. Here, we shall try to explain how to use them with more details than in the reference
wiki pages. But the goal is not to replace these pages, and we assume you have at least some
knowledge of the various WML filters, namely unit and location filters. The examples given
below aren’t always the best way to do things: the goal here is understanding filtering, not to
give a complete WML course.

=== Basics: How filters work. ===

Filtering is narrowing a set of objects to a result set using criteria. Let’s give an example :
given a set of cards, if one is asked to select the spades, (s)he will probably check the cards
one by one and create two stacks : one containing only the spades, and another containing the
unselected cards. This is a very simple filter, where the criterion is « this card has spades
colour » and the result set is a card stack.
The spades cards are said to ‘match’ the filter.
If next we’re asked to find the king of spades, most probably, we will not restart from the
beginning but only scan the spades stack to find the right card. This is an example of a two
criteria filter. In WML we would write something like:
[filter]
colour=spades
value=king
[/filter]
to describe the operation. Criteria are expressions evaluating to true or false. Is this card colour
spades ? That’s how we must read the sentence: ‘colour=spades’.
Now, stating both criteria must be met is not the only way to combine them:
[filter]
colour=spades,diamonds
value=king
[/filter]
The first expression will be true if a card colour is ‘spades OR diamonds’. It would make no
sense to state they should be ‘spades AND diamonds’, of course.
In many languages, you must specify how criteria combine using the special keywords ‘OR’
and ‘AND’. In WML, you can do so, but most often, you’re not required to do so. Writing
explicitly the logical operators would give something like:
[filter]
[and]
colour=spades
[or]
colour=diamonds
[/or]
[/and]

[and]
value=king
[/and]
[/filter]
or in natural speech: “is card (colour=spades OR colour=diamonds) AND value=king ?” Note
here the use of parentheses. As in algebra, they mean their content must be evaluated prior to
applying the last criterion.
'''[and]''' and '''[or]''' subtags are WML equivalents of parentheses. They are not mandatory (like in some other languages), and this is a cool feature, but can be misleading in complex filters.
The rule is:
* listed criteria are ''ANDed'', in other words, they must all be true for the object to match the filter.
* comma separated lists in a criterion are equivalent to ''ORed'' criteria. In other words, one only is enough for the object to match the filter.

'''There are some things important to note:'''

* A complex filter can always be split into simpler filters applied in chain, each filter taking as starting set the result set of the former one. In our example, we applied the filter « value=king » to the result set of filter « color=spades ». This is important when building or debugging filters, because complex ones can easily be reduced to a chain of simpler ones.

* Criteria order is not important from a logical point of view. We could have searched the kings first, obtaining the four kings in our result set, and the card of color spade next. The final result is the same. But in WML, for some reasons we shall study later, order can be important.

* Result sets can contain any number of objects. One can’t assume the result set of our filter will contain a single card ‘THE king of spades’. A human being would probably stop the search when finding a king of spades, but filters don’t. If our starting card packet is not a complete set (some cards were lost, a cheater introduced some more, or anything else), you’ll find one, none or many kings of spades. It’s a common error in WML to assume filters will select a single object.1)
* Any unit or location will match an empty filter like this one:
[event]
name=moveto
[filter]
[/filter]
…
[/event]
This event will be triggered on every move of every unit on the map.

________________________________________

:1) One can be sure only when filtering with ID’s because they are unique.

'''Here now are two versions of the same action, using filters and not.'''
[modify_unit]
[filter]
side=2
[not]
race=orc
[/not]
[/filter]
side=1
[/modify_unit]
This moves to side 1 all side 2 units except orcs. Please note how filter syntax is after all very close to natural speech. This is why we shall see a good way to design complex filters is writing an accurate sentence describing them first.
Using no filter (and assuming ‘all_units’ is an array containing all created units in a scenario) we could write :
{FOREACH all_units i}
[if]
[variable]
name= all_units[$i].side
equals=2
[/variable]
[and]
[variable]
name= all_units[$i].race
not_equals=orc
[/variable]
[/and]
[then]
[set_variable]
name= all_units[$i].side
value=1
[/set_variable]
[unstore_unit]
variable= all_units[$i]
[/unstore_unit]
[/then]
[/if]
{NEXT i}
Of course, the first version is much more concise. One should note:
* Filters are hidden loops2) fetching all elements of the starting set.
* Criteria composition is more explicit in the second version. We have here an [and] tag which is missing in the first one. It shows clearly both conditions must be met. In filters, the [and] tag is most often implicit, as we have already seen.
________________________________________

:2) Internally, it’s not always the case, but we’ve not to deal with internal implementations. Conceptually, filters can always be seen as hidden loops.

At this point, a question arises: where are the starting and result sets we talked about? They show nowhere. The reply is most often we don’t need to see them, because we don’t need to create result sets explicitly. We need to use them to specify actions targets or conditions. In the '''‘modify_unit’''' example, we apply the action « change side » to the result set of the filter and then need it no more.
The starting set is implicit too. Most of the time, it’s the larger available set of objects: e.g., all created units (sometimes including the recall list), or all hexes in the map. In the '''moveto''' event, it contains only the moving unit.
Once again, we are not saying these sets really exist in Wesnoth engine code. But this is an accurate model of how the filters work in WML.

=== Result sets and arrays. ===

A good way to explicitly get the result set is to use the '''‘store_...’''' tags. These actions create
arrays containing the result set of the filter they take as parameter. This is very useful in many ways. The common use is of course to store units and locations for some processing or later use. But one can use this to split complex filters and inspect intermediate results. The former '''‘modify_unit’''' example could be written as:
[store_unit]
variable=temp1
[filter]
side=2
[/filter]
[/store_unit]

[store_unit]
variable=temp2
[filter]
find_in=temp1
[not]
race=orc
[/not]
[/filter]
[/store_unit]

[modify_unit]
[filter]
find_in=temp2
[/filter]
side=1
[/modify_unit]
This trivial example shows not only how to debug complex filters (inspecting the content of ''temp1'' and ''temp2'' arrays), but how to specify a starting set with the '''‘find_in’''' key. Without it, the second '''‘store_unit’''' tag would store all units except orcs. With it, we ask to apply the filter to the content of ''temp1'' array only (all side 2 units). It’s like our card example where we selected the spades first and next the king(s) in the spades stack.
The '''‘find-in’''' key is really precious in many cases: often it’s easier to explicitly build an array containing the objects we want to select, than it is to create a complex filter to retrieve them.
For example, if we want dying units to drop weapons and other units to retrieve them, it can be very difficult to create a filter allowing to select locations where the weapons were dropped. Instead, we can build an array containing their locations (and other information as well). Since this array's members have x and y (sub-)members, the '''find_in''' key of a location filter can use it3). It would be:
# in the die event
[set_variables]
name=weapons
mode=append
[value]
x=$unit.x
y=$unit.y
… anything else, for instance the image name and item id.
[/value]
[/set_variables]

# drop item, etc…

# and in a moveto event
[event]
name=moveto
first_time_only=no
[filter]
side=1
[filter_location]
find_in=weapons
[/filter_location]
[/filter]
…

Let’s give another example.
The scenario’s map features three temples at 10,10 20,20 30,30.
We want to give some bonus gold to side 1 if any side 1 unit visits temple 1,2,3 exactly in that order.
Here is a solution using result sets arrays :
[event]
name=moveto
first_time_only=no
[filter]
side=1
x,y=10,10
[not]
find_in=temple_1
[/not]
[/filter]
[store_unit]
mode=append
variable=temple_1
[filter]
id=$unit.id
[/filter]
[/store_unit]
[/event]
In temple_1, we store all side 1 units visiting temple_1, but only once (that’s why the '''[not] find_in''' tag, because units can visit the temple more than once).

________________________________________

:3) It’s surprising because this array doesn’t contain locations, but it’s a feature, not a side effect.

[event]
name=moveto
first_time_only=no
[filter]
side=1
x,y=20,20
find_in=temple_1
[not]
find_in=temple_2
[/not]
[/filter]
[store_unit]
mode=append
variable=temple_2
[filter]
id=$unit.id
[/filter]
[/store_unit]
[/event]

This time, we store only units previously stored in temple_1 (= they already visited that temple).
Then the last event is obviously :
[event]
name=moveto
first_time_only=yes
[filter]
side=1
x,y=30,30
find_in=temple_2
[/filter]
[gold]
side=1
amount=1000
[/gold]
{CLEAR_VARIABLE temple_1,temple_2}
[/event]

=== Ordering and writing ===

We said earlier that criteria order is not significant. That's right from a theoretical point of view. But, for syntactic reasons and particularly because the radius key in location filters, this is not fully true in WML. Actually conditions are applied to candidate objects until one proves to be false or all conditions are checked. Then, if some condition proves to be false, remaining conditions are not evaluated (so if there's some radius there, it will not be executed). In some cases, this may be important. One can assume conditions are evaluated in the order they are found except logical operators (and, or, not) which are evaluated after other conditions. It’s very important to note that evaluation order of top level conditions (those not embedded in and/or/not tags) is undocumented, which means your code shouldn’t rely on it. On the contrary, and/or/not tags are always executed last, in the order they are written.

So in this example:
[filter]
has_weapon=sword
side=1
[or]
side=2
[/or]
gender=female
[/filter]
will be executed using this order:
[filter]
has_weapon=sword
side=1
gender=female
[or]
side=2
[/or]
[/filter]
One should be aware of this for some reasons:

'''⇒''' Clarity: your code will be easier to understand and to debug if you avoid meddling conditions, nested filters and logical blocks, and write them in the order in which they are evaluated.

'''⇒''' Performance.
Most of the time, performance is not an issue. But it can be if you have a lot of units and use '''[filter_wml]'''. More generally, it’s good programming practice to execute the more restrictive test first.
Consider this example:
[filter]
race=orc
x,y=16,22
[/filter]
The first condition will be evaluated on all units. But the second one will be evaluated on all orcs. If instead we write:
[filter]
x,y=16,22
race=orc
[/filter]
obviously, the second condition will be evaluated once at most, and filtering will be faster. (Strictly speaking, I should have wrapped the second condition in an '''and''' tag to force evaluation order).
Remember too that logical operators '''(and, or, not)''' are not mandatory, but are allowed. So one can use them for clarity's sake, or to force an evaluation order. It’s particularly important when using '''or''' tags.

In the example above one could expect the result set contains all women of sides 1 and 2 wielding a sword. But it contains actually all side 1 women wielding a sword plus all side 2 units.

Filters work actually as if top level criteria were enclosed in an implicit '''and''' tag: so we should read:
[filter]
[and] '''#implicit'''
has_weapon=sword
side=1
gender=female
[/and]
[or]
side=2
[/or]
[/filter]
and what we probably wanted is:
[filter]
has_weapon=sword
gender=female
[and]
side=1
[or]
side=2
[/or]
[/and]
[/filter]
Note that it could be written:
[filter]
[and]
has_weapon=sword
gender=female
[/and]
[and]
side=1
[or]
side=2
[/or]
[/and]
[/filter]
This syntax is correct and you can use it if you find it clearer.
Remembering this implicit '''and''' tag (and writing it explicitly at will) is very important to understand or design complex filters.

=== Writing complex filters. ===

Here are some guidelines one can use when writing complex filters. Suppose we want to set up some kind of disease aura harming units standing close to some villages. We shall start writing a sentence describing the feature.

'''We want to select units who:'''
'''Are enemy to side 1'''
'''stand on hexes which'''
'''are near to'''
'''villages'''
'''with side 1 units standing on it'''
Mark we put only one condition on each line to clearly separate them. Mark we sorted them, because some apply to units to be filtered, others to locations, and finally to other (enemy) units standing on locations. Next, we shall add logical operators and parenthesis to clearly specify what we want:
'''Units, who ('''
'''Are enemy to side 1 AND'''
'''stand on locations which ('''
'''( Are villages AND'''
'''have unit on it who ('''
'''Belongs to side 1'''
''')'''
''') OR'''
'''are adjacent to THOSE villages radius 3'''
''')'''
''')'''
Now, we are ready to start building the filter. Since we want units who… it shall be a unit filter. In the standard unit filter, there’s no condition directly allowing to state the unit is enemy to side 1. So we have to replace this with something valid in the SUF context. Using parenthesis to avoid errors, we can replace the condition with a side filter because it’s valid in unit filters.
'''Units, who ('''
'''(belongs to a side which ('''
'''is enemy to side 1) ) AND'''
'''stand on locations which ('''
'''( Are villages AND'''
'''have unit on it who ('''
'''Belongs to side 1'''
''')'''
''') OR'''
'''are adjacent to THOSE villages radius 3'''
''')'''
''')'''
Now we can write the filter. Here we do it step by step to show how the translation is rather straightforward and how our parenthesis match exactly the subtags.
[filter]
[filter_side]
[enemy_of]
side=1
[/enemy_of]
[/filter_side]
'''AND'''
'''stand on locations which ( # we start to filter locations there'''
'''( Are villages AND'''
'''have unit on it who ('''
'''Belongs to side 1'''
''')'''
''') OR'''
'''are adjacent to THOSE villages radius 3'''
''')'''
[/filter]

[filter]
[filter_side]
[enemy_of]
side=1
[/enemy_of]
[/filter_side]
[and]
[filter_location]
terrain=*^V*
'''AND'''
'''have unit on it who (# to unit filter again'''
'''Belongs to side 1'''
''')'''
radius=3 '''# radius is a special case, see below'''
[/filter_location]
[/and]
[/filter]

[filter]
[filter_side]
[enemy_of]
side=1
[/enemy_of]
[/filter_side]
[and]
[filter_location]
terrain=*^V*
[and]
[filter]
side=1
[/filter]
[/and]
radius=3 '''# radius is a special case, see below'''
[/filter_location]
[/and]
[/filter]
Here, we are done. The filter should work as it is, but it looks rather unusual because all these '''[and]''' blocks. Actually we can delete most of them using a simple rule: '''[and]''' tags are not needed when they contain one single criterion or a single block, (except if you want to set up an evaluation order). In our example, the '''filter_location''' block is alone in its '''and''' tag, and the embedded '''filter''' as well, so we can avoid those '''and''' tags and get finally:
[event]
name=moveto
first_time_only=no
[filter]
[filter_side]
[enemy_of]
side=1
[/enemy_of]
[/filter_side]
[filter_location]
terrain=*^V*
[filter]
side=1
[/filter]
radius=3
[/filter_location]
[/filter]
[harm_unit]
[filter]
id=$unit.id
[/filter]
amount=10
animate=yes
[/harm_unit]
[/event]

=== Filters uses: events actions and conditions. ===

Here, we shall deal with filter uses in WML. The language is not fully consistent, mainly to simplify its syntax, so some points can be misleading.
:'''Using in actions'''
Most actions take a filter as first parameter. The main difficulty here is to know if '''[filter]''' tags must be used or not. Actually, they’re used to avoid confusing keys and criteria when they have the same name4. For instance, the '''[kill]''' action needs a unit filter and has these keys:

* '''animate:''' if 'yes', displays the unit dying (fading away).
* '''fire_event:''' if 'yes', triggers any appropriate 'die' events (See EventWML). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a StandardUnitFilter as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter.

As we can see, none of these keys and tags are shared with unit filter keys and tags. This means the code parser needs no '''[filter]''' tag to know which key belongs to the filter and which to the action. But in the code, there’s no obvious distinction.

________________________________________

:4) Note there’s no specific top level tag for location filters.

[kill]
animate=yes '''# this belongs to the ‘kill’'''
id=BadGuy_101 '''# this belongs to the unit filter'''
[/kill]
is the correct syntax. Note a common error is to use a '''[filter]''' tag here. Since this tag is unknown in the context, it is ignored, so the kill action is applied to the starting set, i.e. all units (including the recall lists). Same with the '''filter_side''' tag which is not needed everywhere (in '''store_sides''' particularly).
Adversely, '''[modify_unit]''' obviously requires a '''[filter]''' tag, because all keys and criteria have the same name:
[modify_unit]
side=2
side=1
[/modify_unit]

This would make no sense of course because one can’t find if side 1 units must be put into side 2 or the contrary. Anyway, there is an exception: the '''[store_unit]''' tag requires a '''[filter]''' tag even if there is no '''‘variable’''' key in units description. Another special case is when using terrain action, because the key '''terrain''' is valid both in location filters and terrain action. Since there is no special tag to delimit location filters, one should write:
[terrain]
[and]
terrain=Wo* '''# here is the filter criterion'''
[/and]
terrain=Rr '''# and the new terrain'''
[/terrain]
The next example can be confusing:
[kill]'''# kill all units standing on deep water'''
animate=yes
[filter_location]
terrain=Wo
[/filter_location]
[/kill]
When reading the '''‘kill’''' tag documentation, one will not find any '''‘filter_location’''' or location filter entry. Does this means it’s an undocumented feature ? No. But the '''‘filter_location’''' belongs to the implicit '''‘filter’''' tag of the '''‘kill’''' action and is documented there. It’s kind of:
[kill]'''# kill all units standing on deep water'''
animate=yes
'''#'''[filter] '''we’re filtering units here, not locations'''
[filter_location]
terrain=Wo
[/filter_location]
'''#'''[/filter]
[/kill]

=== Using filters in conditions. ===

Filters can be used to create conditional expressions. They can be nested in '''[have_unit]''' or '''[have_location]''' tags or in nested filters. Here, the result set is not used directly, but its size must fall in the range defined by the '''‘count’''' key. This finally gives a Boolean result: true or false. So one can use them in '''[if] [show_if]''' conditional actions or in a '''[filter_condition]''' tag. They are widely used in nested filters too (see the special chapter on this).

Let’s give some examples:

[have_unit] '''# this piece of code evaluates to true when no more enemy leaders are alive'''
canrecruit=yes
[not]
side=1
[/not]
count=0
[/have_unit]

[have_location] '''# this one is true if at least 5 side 1 units stand on a village'''
terrain=*^V*
[filter]
side=1
[/filter]
count=5-1000
[/have_location]
Note we could also write this condition:
[have_unit]
side=1
[filter_location]
terrain=*^V*
[/filter_location]
count=5-1000
[/have_unit]
Note we could use a '''[store_unit]''' instead, testing the ''length'' property of the array:
[store_unit]
variable=temp
[filter]
side=1
[filter_location]
terrain=*^V*
[/filter_location]
[/filter]
[/store_unit]
#[if] or [filter_condition]
[variable]
name=temp.length
greater_than=4
[/variable]

=== Using filters in events. ===
In events, filters are always used in a conditional way, because they state if the event should fire or not. In any event, we can set '''[filter_condition]''' using '''have_unit''' or '''have_location''' (and a more ordinary variable condition, but this is off topic).
Some events use filters in a special way: '''moveto''' and '''attack''' events particularly. In them, the filtering apply not on all units as usual, but only on units involved in the event action: one unit only is moving at a time, two units only are involved in a fight. Then the event fires if and only if the involved unit(s) match the filter.
Note that one can use '''[filter]''' and '''[filter_condition]''' in the same moveto or attack event. Both conditions are then ANDed.

'''Filtering units'''

Criteria allowed to filter units (in standard unit filters) are listed below. First, the keys dealing with the unit properties (as usual, comma separated lists means conditions are ORed):
:'''id:''' ''can be a comma-separated list, every unit with one of these ids matches''
:'''type:''' ''can be a list of types''
:'''race:''' ''(Version 1.11 and later only: this can be a comma-separated list)''
:'''ability:''' ''unit has an ability with the given id (not name !)''
:'''side:''' ''the unit is on the given side (can be a list). One can use a [filter_side] instead''
:'''has_weapon:''' ''the unit has a weapon with the given name''
:'''canrecruit:''' ''yes if the unit can recruit (i.e. is a leader)''
:'''gender:''' ''female if the unit is female rather than the default of male''
:'''role:''' ''the unit has been assigned the given role''
:'''level:''' ''the level of the unit''
:'''defense:''' ''current defense of the unit on current tile''
:'''movement_cost:''' ''current movement cost of the unit on current tile''
:'''x,y:''' ''the position of the unit. (Ranges ? probably because it works in moveto events)''

Not all unit properties are listed here, but they can be used in a '''[filter_wml]''' sub-tag like this:
[filter_wml]
max_moves=7
[/filter_wml]

[filter_wml]
[status]
poisoned=yes
[/status]
[/filter_wml]
Some of them accept comma separated lists or ranges. Some not, but it also possible to use them more than once with '''[and]''' and '''[or]''' subtags. For instance :
[and]
race= elf
[or]
race= merman
[/or]
[/and]
Other sub tags are dealing with unit relationships:
:'''⇒''' The hex on which they stand: '''[filter_location]''' which contains a standard location filter.
:'''⇒''' The units adjacent to it: '''[filter_adjacent]''' which contains another standard unit filter
:'''⇒''' Their visible status relating to a particular side: '''[filter_vision]'''
These are nested filters ; or in other words, filters used to create conditions and not result sets (see earlier and later).

Custom functions returning a boolean:
:'''formula:''' FormulaAI like formula.
:'''lua_function:''' lua function

SUFs accept a '''find_in''' key too. As we saw earlier, this allows to restrict the starting set to the content of an array.

=== this_unit ===

This variable is a special variable defined only inside SUFs. Suppose we want to catch in a filter units at full health. We can use the '''hitpoints''', but the problem is we know not which value to use, because every unit type has its own:
[filter]
side=1
[filter_wml]
hitpoints=?
[/filter_wml]
[/filter]
This is why we could have the use of some way to specify the unit being fetched during the filtering.
[filter]
side=1
[filter_wml]
hitpoints=$this_unit.max_hitpoints
[/filter_wml]
[/filter]
This does the trick. The condition value will be updated according to unit properties before executing the check.

=== Filtering locations ===

'''find_in''': a location array specifying the starting set.

'''time_of_day''': one of lawful, chaotic, neutral or liminal.
'''time_of_day_id''': one or more from: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.

'''terrain''': comma separated list of terrains.
'''x,y''': the same as in the unit filter; supports any range.
'''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ terrain_type ] gives_income= parameter was set to yes (which means a side can own that hex).

'''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter

'''[filter]''' with a Standard Unit Filter as argument; if present a unit must also be there

'''radius''': this is not strictly speaking a criterion. It adds to the result set all hexes adjacent to a matching hex and is always applied last, when all criteria are checked. Remember the filtering process is a hidden loop where all candidates are fetched one by one. If a candidate match the filter, radius adds all adjacent hexes (matching the filter or not !). If it don't, it does nothing.
This is why this example doesn't work:
[filter] '''# this example doesn’t work !'''
side=1
[filter_location]
x,y=43,32
radius=5
[not]
x,y=43,32
[/not]
[/filter_location]
[/filter]
The coder here expected the radius action to be performed just after selecting the 43,32 hex, and the '''[not]''' criterion applied to this hex and it's adjacent radius 5 set. But '''radius''' is always applied last, even if written before some other conditions. So when using '''radius''', a good rule is to create the filter without it at first and to see if it can catch something. Here, it would give:
[filter]
side=1
[filter_location]
x,y=43,32
[not]
x,y=43,32
[/not]
[/filter_location]
[/filter]
which is clearly non sense because the two conditions are mutually exclusive.

The solution is to pack the conditions in two different filters:
[filter]
side=1
[filter_location]
x,y=43,32
radius=5
[/filter_location]
[and]
[filter_location]
[not]
x,y=43,32
[/not]
[/filter_location]
[/and]
[/filter]
or,
[filter]
side=1
[filter_location]
[and]
x,y=43,32
radius=5
[/and]
[not]
x,y=43,32
[/not]
[/filter_location]
[/filter]
or, since the x,y keys are defined in '''[filter]''' too, it can be:
[filter]
side=1
[filter_location]
x,y=43,32
radius=5
[/filter_location]
[not]
x,y=43,32
[/not]
[/filter]
This is why '''[filter_radius]''' is useful. As we said, radius adds hexes without checking any condition (except proximity of course). If we want to put a condition on hexes added with radius (and them only), we would use it as in next example. Here we want to select forested hexes near villages:
[filter_location]
terrain=*^V*
radius=3
[filter_radius]
terrain=*^F*
[/filter_radius]
[/filter_location]
But, this will not work exactly as in our previous example because radius extends outwards from matching locations one step at a time. Only the locations matching the '''filter_radius''' will be selected AND used to compute the next step. If there’s no forest hex near the village, the previous filter will return nothing, even if there are some forest hexes farther in the range.

Note this filter selects the village too ! If we want not, this should be:
[filter_location]
[and]
terrain=*^V*
radius=3
[filter_radius]
terrain=*^F*
[/filter_radius]
[/and]
[not]
terrain=*^V*
[/not]
[/filter_location]

=== Nested filters ===

Now, we are ready to study how to create nested filters, in other words, filters containing sub filters. In location or unit filters, the documentation says one can insert filters of various kind involving other objects. In this way, we can select unit adjacent to other units or standing on some terrains. Actually, they’re not exactly filters: they are conditions or criteria built on filters. In other words, they don’t produce a result set but are, like other criteria, expressions evaluating to true or false. That’s why many of them have additional keys, like '''‘count’''' (see the filter use in conditions).

We shall discuss this on examples.

=== Filter_adjacent. ===

In a unit filter, this allow to create criteria stating which units must be adjacent to the tested unit. In this example, we shall implement an ability named ‘escape’. Units having this ability can teleport elsewhere when surrounded by more than 3 enemies. We shall set a '''moveto''' event to watch the ‘surround’ event.
[event]
name=moveto
first_time_only=no
[filter]
'''# we could set some additional condition on the moving unit here'''
[filter_adjacent]
ability=escape '''# this part fetches the adjacent units, not the moving one.'''
is_enemy=yes
[/filter_adjacent] '''# this results to true if at least one unit is found.'''
[/filter]
…
[/event]
This will fire each time some enemy unit get close to our able unit. Note we have here not only a standard unit filter (the ability key), but special keys specifying relationships between units : the '''is_enemy key'''. Another special key is the '''‘count’''' key. It allows to specify how much adjacent units must be found. As far as the default is 1-6, we don’t need it here. But this means more than one able unit can be surrounded by a single move.
Now, we must add the ‘surrounded’ condition. Here, we shall use a new '''filter_adjacent''' tag, but applying to the able unit (not the moving one):
[event]
name=moveto
first_time_only=no
[filter]
[filter_adjacent]
ability=escape '''# this part filters the adjacent units, not the moving one.'''
[filter_adjacent]
is_enemy=yes '''# this part finds adjacent units to the able one.'''
count=4-6
[/filter_adjacent]
is_enemy=yes
[/filter_adjacent]
[/filter]
…
[/event]
Suppose we want now to apply one more condition for the ability to work : able unit must be adjacent to another unit sharing the same ability. We must use a new '''filter_adjacent''' tag, and since there is already one, use an '''‘and’''' tag to combine them.
[event]
name=moveto
first_time_only=no
[filter]
'''# we could set some additional condition here'''
[filter_adjacent]
ability=escape
[filter_adjacent]
is_enemy=yes
count=4-6
[/filter_adjacent]
[and]
[filter_adjacent]
ability=escape '''# these are the needed helpers'''
is_enemy=no
[/filter_adjacent]
[/and]
is_enemy=yes
[/filter_adjacent]
[/filter]
…
[/event]
Note you’ll find very few examples of such complex filters in events. Why ? It’s because we often need to catch the involved units to take some actions. In our example, we need not only to test if our able units are surrounded but make them teleport as well. As a result, the filtering process would probably be split in two, moving in the '''teleport''' filter the code which was in the '''filter_adjacent''' tag:
[event]
name=moveto
first_time_only=no
[filter]
'''# we could set some additional condition here'''
[filter_adjacent]
ability=escape
is_enemy=yes
'''# here was a block …'''
[/filter_adjacent]
[/filter]

[teleport]
[filter]
ability=escape
[filter_adjacent] '''# … which was just moved here ! '''
is_enemy=yes
count=4-6
[/filter_adjacent]
[and]
[filter_adjacent]
ability=escape '''# these are the needed helpers'''
is_enemy=no
#count=1-6 '''# since it’s the default, we don’t need this'''
[/filter_adjacent]
[/and]
[/filter]
…
[/teleport]
[/event]

=== Filter_location ===

Filter_location allows to specify on which hex the unit must be standing. Of course, since we already have x,y keys in the standard unit filter, we don’t need to set a filter location for that. Suppose our former ability should work only in forests. The '''filter_location''' is fitted for that.
[filter_location]
terrain=*^F*
[/filter_location]
Where shall we put it ? Certainly not at the first level of the filter: this would make the ability to work if the moving unit (the enemy) stands on forest. So the right place is in level 2 and 3 where we are dealing with the able units.
[event]
name=moveto
first_time_only=no
[filter]
'''# we could set some additional condition here'''
[filter_adjacent]
ability=escape
[filter_adjacent]
is_enemy=yes
count=4-6
[/filter_adjacent]
[and]
[filter_adjacent]
ability=escape '''# these are the needed helpers'''
is_enemy=no
[filter_location]
terrain=*^F*
[/filter_location]
[/filter_adjacent]
[/and]
[filter_location]
terrain=*^F*
[/filter_location]
is_enemy=yes
[/filter_adjacent]
[/filter]
…
[/event]

=== pitfalls ===

One thing to avoid designing filters is using redundant or mutually exclusive criteria. In other words, they specify a condition never or always met in any case. Let's give an example:
[filter]
side=1
[filter_adjacent]
side=1
is_enemy=yes
[/filter_adjacent]
[/filter]
It's pretty obvious this filter will always return an empty set because side 1 units can't be enemy to side 1. But this filter is valid and will raise no error ! Now, let's look at this one:
[filter]
side=1
[filter_adjacent]
side=2
is_enemy=yes
[/filter_adjacent]
[/filter]
Here, we can mark the '''is_enemy''' key is redundant because sides already define if the units are enemy or not. So, if side 1 and 2 are allied, the filter will always return an empty set. If they are not, it will always match, so the '''is_enemy''' criterion is useless. This filter:
[filter]
side=1
[filter_adjacent]
side=2
[/filter_adjacent]
[/filter]
will always return exactly the same result (except if sides configuration is modified during the scenario of course). Another example:
[filter]
type=Horseman,Knight
[filter_location]
terrain=M*
[/filter_location]
[/filter]
The result set will always be empty because these units can't walk on mountains. So, there's no need to use such a filter and it's most probably a design error.

Another common error is assuming a filter will always return a single unit or location. In conjunction with '''store_unit''' or '''store_locations''', the result set will be an array or a single variable:
[store_unit]
variable=temp
[filter]
… anything
[/filter]
[/store_unit]

[modify_unit]
[filter]
id=$temp.id
[/filter]
… something
[/modify_unit]
This will work only if the result set contains a single unit. Else, the temp.id will be taken from the first result, or empty if the result set was empty. Instead, one should use temp[$i].id in a FOREACH loop. Or better in this particular case: '''find_in'''=temp in the unit filter, because it handles correctly all the cases.

=== Download as .pdf ===
Wesnoth forum thread:
[http://forums.wesnoth.org/viewtopic.php?f=21&t=38583#p553139 (WMLFiltering.pdf.zip)]

For feedback please use the same thread.

[[Category: WML Reference]]
[[Category: WML Tutorials]]

Category:WML Tutorials

2017-05-10T02:01:12Z

Sapient: Created page with "Category:WML_Reference"

[[Category:WML_Reference]]

Category:WML Tips

2017-05-10T02:00:40Z

Sapient:

VariablesWML/How to use variables

2017-05-10T01:59:13Z

Sapient:

== 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 type1). 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.[[In computering words, they are not '''strongly typed.'''|1)]], 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.|2)]]

==== 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:[[That’s why dots are forbidden in variable names : they are used to specify members.|3)]]
$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.[[That’s why = signs are forbidden in variables names : it corrupts savegames.|4)]]

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.
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[[Less easy because there is no macro for that.|5)]] 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 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[[It would be better if it exists… |6)]]. 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) [[You can minimize the risk using special key names like 'Pyro_level' instead of only 'level'… or write a feature request! |7)]] . 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

[[Category:WML_Reference]]
[[Category:WML_Tutorials]]

VariablesWML/How to use variables

2017-05-10T01:57:19Z

Sapient: expanded arrays tutorial

== 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 type1). 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.[[In computering words, they are not '''strongly typed.'''|1)]], 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.|2)]]

==== 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:[[That’s why dots are forbidden in variable names : they are used to specify members.|3)]]
$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.[[That’s why = signs are forbidden in variables names : it corrupts savegames.|4)]]

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.
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[[Less easy because there is no macro for that.|5)]] 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 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[[It would be better if it exists… |6)]]. 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) [[You can minimize the risk using special key names like 'Pyro_level' instead of only 'level'… or write a feature request! |7)]] . 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

[[Category:WML_Reference]]
[[Category:WML_Tutorial]]

StandardUnitFilter

2017-05-05T08:15:58Z

Sapient: /* See Also */

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The term [[StandardUnitFilter]] means that the set of such keys and tags (see below) can appear at that point. Often a [[StandardUnitFilter]] needs to be included in a [filter] tag. But many tags take the [[StandardUnitFilter]] directly as an argument, like [kill] and [have_unit]. See [[Special:WhatLinksHere/StandardUnitFilter]] for tags which can contain a StandardUnitFilter.

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given id. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this (see [[SingleUnitWML]]). id= can be a comma-separated list, every unit with one of these ids matches.
* '''speaker''': alias for id (no comma-separated list supported)
* '''type''': matches the unit's type name (can be a list of types)
* '''type_adv_tree''': {{DevFeature1.13|7}} matches the type name of the unit and all its advancements (can be a list)
* '''race''': the race of the unit type. This can be a comma-separated list; the unit's race must match one of the given races. Mainline races are listed in data/core/units.cfg 
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]
* '''ability_type''': {{DevFeature1.13|7}} unit has an ability with the given type (tag name) - eg, ''ability_type=heals'' will match a unit with any healing ability.
* '''status''': {{DevFeature1.13|0}} matches if the unit has the specified status active. This can be a comma-separated list, in which case the unit will match as long as it has one of the listed statuses active
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name {{DevFeature1.13|5}} Now deprecated
* '''[has_attack]''': {{DevFeature1.13|5}} the unit has a weapon matching the [[StandardWeaponFilter]]. If this is present, '''has_weapon''' is ignored.
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless it is also found stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes. When "yes", this matches units that are not obscured by fog or shroud, and that are not hiding (via the {{tag|AbilitiesWML|hides}} ability). When "no", this matches units that are obscured by fog or shroud, or that are hiding.
** [[StandardSideFilter]] tags and keys. Filter for who may be able to see (or not see) the unit. If there is *at least one* matching side which can see the unit then the filter matches, and otherwise it fails to match.
* '''[filter_wml]''': this is WML level filter for the unit. In it, you can filter on anything that is in the WML description of a unit. This description can be found in any savegame also in [[SingleUnitWML]]. If the filter encounters a nested '''[not]''' tag, the attributes and containers inside the tag should not match for the upper filter to match. Note: [filter_wml] is especially slow, unless it contains only a child [variables], which is used for matching variables stored inside the unit.
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''' with a StandardUnitFilter as argument; do not use a [filter] tag. If present the correct number of adjacent units must match this filter.
**'''StandardUnitFilter''' tags and keys
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[StandardLocationFilter#Directions|notes]])
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
** '''$other_unit''': {{DevFeature1.13|2}} Within [filter_adjacent], the special variable $other_unit refers to the filtered unit from the enclosing filter, while $this_unit refers (as with all StandardUnitFilters) to the unit being filtered on.
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
*'''[filter_side]''': The currently filtered unit's side must match this [[StandardSideFilter]] for the unit to match.
**[[StandardSideFilter]] tags and keys
* '''formula''': A formula using [[Wesnoth Formula Language]]. The <tt>self</tt> variable is set to the current $this_unit, and the formula should return a boolean. If it returns 0, the filter does not match. Otherwise, the filter does match. {{DevFeature1.13|5}} If the filter has a secondary unit, the formula can access it using the <code>other</code> variable.
* '''lua_function''': the name of a [[LuaWML|Lua]] function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter. {{DevFeature1.13|5}} Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''id''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:
[kill]
[not]
id=Gwiti Ha'atel
[/not]
[not]
id=Tanar
[/not]
[/kill]
:And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:
[kill]
id=Gwiti Ha'atel
[or]
id=Tanar
[/or]
[/kill]

== Tutorial ==

* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

StandardLocationFilter

2017-05-05T08:14:48Z

Sapient: /* See Also */

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering on locations.
The term [[StandardLocationFilter]] means that the set of such keys and tags (see below) can appear at that point. Sometimes a [[StandardLocationFilter]] needs to be included in a [filter_location] tag. There are however many tags which accept the [[StandardLocationFilter]] directly as an argument such as [store_locations]. Generally, if the tag [filter_location] is not mentioned to be a possible subtag of the outer tag in question, then don't put it.

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, or neutral). Note: ''chaotic'', ''lawful'', and ''neutral''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [[#Filtering_Terrains|Filtering Terrains]]).
* '''x,y''': the same as in the unit filter; supports any range ([[StandardLocationFilter#Notes_about_Coordinate_Usage|notes]])
* '''area''': matches locations assigned to the [[DirectActionsWML#.5Btime_area.5D|[time_area]]] with the given id.
* '''include_borders''': {{DevFeature1.13|0}} whether the SLF will include border hexes or not. Will override the default behavior of the tag this appears in.
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes (which means a side can own that hex).
* '''[filter_vision]''': this tests whether or not the location is currently visible
** '''visible''': yes or no, default yes. "yes" filters for visible locations, "no" filters for invisible locations.
** '''respect_fog''': yes or no, default yes. "yes" filters for locations that are clear of both fog and shroud, "no" filters for locations that are clear of shroud.
** [[StandardSideFilter]] tags and keys as arguments. If there is *at least one* matching side which can see the location then the filter matches, and otherwise it fails to match.
*'''[filter_owner]''': If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([[StandardLocationFilter#Notes_about_Radius_Usage|notes]])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[#Directions|notes]])
* '''formula''': {{DevFeature1.13|5}} a [[Wesnoth Formula Language]] formula
* '''lua_function''': {{DevFeature1.13|5}} the name of a [[LuaWML|Lua]] function in the global environment that takes arguments <code>x, y</code> and returns true if the given location matches the filter. Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

__NOTOC__

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

While some locations should only be one hex (like the starting position of a unit),
others filter over multiple hexes.
The following syntax is used to filter over multiple hexes:

Dashes('''-''') are used to have the location be a range of hexes.
There must be values before and after the dash;
everything in between these numbers (inclusively) is part of the range.

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.
E.g. in order to specify multiple locations 1,4 and 2,5, use:
[tag]
x=1,2
y=4,5
[/tag]
Note: although the ordering of locations in a list generally does not matter,
the action '''[move_unit_fake]''' takes in a list of hexes,
and moves an image onto each of those hexes in order.

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.

== Directions ==

Some attributes expect a direction or list of directions. Valid base directions are n, ne, nw, s, se, sw, and there are three operators supported as well:

* To take the opposite direction, use - (eg -n is the same as s)
* {{DevFeature1.13|2}} To rotate clockwise, use :cw (eg n:cw is the same as ne)
* {{DevFeature1.13|2}} To rotate counterclockwise, use :ccw (eg n:ccw is the same as nw)

You can't apply multiple rotation operators - for example, "n:cw:ccw" is not a valid direction. If for some reason you really need multiple rotations, you can use parentheses (so, "(n:cw):ccw" is valid and is the same as n). Similarly, "--n" is not valid, but "-(-n)" is valid and is the same as n.

This syntax is mainly useful when used in conjunction with variable substitution in the adjacent key in [filter_adjacent_location] and in [filter_adjacent] (in [[StandardUnitFilter]]), but will work anywhere a direction is expected. For example, using [modify_unit] to change a unit's direction:

[modify_unit]
[filter]
# ... Whatever filter you need
[/filter]
facing=-$this_unit.facing
[/modify_unit]

That will cause the matched units to turn around.

== Filtering Terrains ==

The '''terrain=''' key allows you to filter based on the terrain of a space, for example:

[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]

At some places the terrains can be filtered with a
match list. The list is a comma separated list and matching will stop
at the first matched [[TerrainCodesWML|terrain string]]. There's one special character
''!'' which inverts the meaning of a match. Terrain strings can
use the wildcard * to match zero or more following letters, characters
behind the * are not allowed and the result is undefined.

Example 1: 
ww* matches ww, www, wwW but not WWW 
!, ww returns false if ww found and true if not 
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.

Example 2: 
<nowiki>*</nowiki>^V* matches all village-terrain 
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).

For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].

== Tutorial ==
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

FilterWML

2017-05-05T08:12:30Z

Sapient: /* Filtering Tutorial */

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> or http://www.wesnoth.org/units/ to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special''': filter on the attack's special power. For values see [[AbilitiesWML]].
* '''number''': {{DevFeature1.13|5}} filter on number of attacks
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''viewing_side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''viewing_side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Tutorial ==
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

FilterWML

2017-05-05T08:11:31Z

Sapient: /* See Also */

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".
A common use for location filters is to check the terrain of a space.

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for attack filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name. See <code>data/units/</code> or http://www.wesnoth.org/units/ to find the name of a particular unit's attack.
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special''': filter on the attack's special power. For values see [[AbilitiesWML]].
* '''number''': {{DevFeature1.13|5}} filter on number of attacks
* '''parry''': {{DevFeature1.13|5}} filter on parry value
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]

'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''viewing_side'' and, when in a SUF, the unit is not hiding.
** '''no''': matches when the location is obscured by fog or shroud for the ''viewing_side'' or, when in a SUF, the unit is hiding.
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== Filtering Tutorial ==
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]

== See Also ==

* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SyntaxWML

2017-04-30T17:07:05Z

Sapient: /* Conditionals */ fix wrong sentence structure

{{SyntaxWML/Translations}}
{{WML Tags}}

The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].

== Tag and Attribute Structures ==

WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
</syntaxhighlight>

''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
<syntaxhighlight lang="wml">
[parent_tag]
key1=value1
[child_tag]
key2=value2
[/child_tag]
[/parent_tag]
</syntaxhighlight>

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.

''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.

=== Tag Amendment Syntax ===

Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
<syntaxhighlight lang="wml">
[tag]
key=value
[/tag]
[+tag]
key=value
[/tag]
</syntaxhighlight>

* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

=== Multiple Assignment Syntax ===

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
<syntaxhighlight lang="wml">
[tag]
key1,key2,key3=value1,value2,value3
[/tag]
</syntaxhighlight>
would be the same as:
<syntaxhighlight lang="wml">
[tag]
key1=value1
key2=value2
key3=value3
[/tag]
</syntaxhighlight>
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.

=== Special Attribute Values ===

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.
* '''key = _"value"''': a ''[[translatable|translatable value]]'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''

== Variables ==

Variables in WML are used to store data for later retrieval. Each variable is identified by its name, which may contain only alphanumerics and underscores. Once created, a variable persists until the end of a campaign unless explicitly cleared.

The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].

=== Kinds of Variables ===
==== Scalar ====
A scalar variable can store a single string or number.

<syntaxhighlight lang="wml">
[set_variable]
name=my_variable
value="sample value"
[/set_variable]
</syntaxhighlight>

The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).

==== Array ====
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
<syntaxhighlight lang="wml">
[set_variable]
name=my_awesome_array[0].x
value=10
[/set_variable]
[set_variable]
name=my_awesome_array[1].x
value=12
[/set_variable]
[set_variable]
name=my_awesome_array[2].x
value=14
[/set_variable]
</syntaxhighlight>

However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
<syntaxhighlight lang="wml">
[set_variables]
name=my_awesome_array
[value]
x=10
[/value]
[value]
x=12
[/value]
[value]
x=14
[/value]
[/set_variables]
</syntaxhighlight>

If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar

''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)

==== Container ====
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.

=== Conditionals ===
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].

=== Variable Substitution ===
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
<syntaxhighlight lang="wml">
[event]
name=turn 1
[set_variable]
name=my_variable
value= _ "Konrad"
[/set_variable]
[message]
speaker=Delfador
message= _ "Hello, $my_variable|... How are you?"
[/message]
[/event]
</syntaxhighlight>

The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.

When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.

In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.

{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.

==== Literal Mode ====

There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
* value of '''literal=''' inside [set_variable]
* contents of '''[literal]''' inside [set_variables]
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start

=== Automatically Stored Variables ===
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
* '''unit''': inside an event, this is the unit at $x1,$y1
* '''second_unit''': inside an event, this is the unit at $x2,$y2
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].

Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.

=== The [variables] tag ===

The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.

A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.

A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.

An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...

=== Storing variables inside units ===

Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
<syntaxhighlight lang="wml">
[filter]
[filter_wml]
[variables]
my_variable="test"
[/variables]
[/filter_wml]
[/filter]
</syntaxhighlight>

=== Variable Usage Examples ===
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
<syntaxhighlight lang="wml">
[variables]
attitude_of_elves=hate
attitude_of_dwarves=love
attitude_of_humans=like
current_opponent=elves
[/variables]
</syntaxhighlight>

Then,
<syntaxhighlight lang="wml">
[message]
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]
</syntaxhighlight>
displays the message
Oh, I see elves! They surely hate us!

Consider another game with variables
<syntaxhighlight lang="wml">
[variables]
our_side=1
their_side=2
[/variables]
</syntaxhighlight>
where side 1 has 75 gold, and side 2 50 gold. Then,
<syntaxhighlight lang="wml">
[store_side]
side=$our_side
variable=we
[/store_side]
[store_side]
side=$their_side
variable=they
[/store_side]
[message]
message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
[variable]
name=we.gold
greater_than=$they.gold
[/variable]
[then]
[message]
message=This should be easy!
[/message]
[/then]
[else]
[message]
message=This will not be easy!
[/message]
[/else]
[/if]
[clear_variable]
name=we
[/clear_variable]
[clear_variable]
name=they
[/clear_variable]
</syntaxhighlight>
displays the messages
We have 75 gold, they have 50 gold.
This should be easy!
If side 2 had 100 gold instead, the same code would display the messages
We have 75 gold, they have 100 gold.
This will not be easy!

The code
<syntaxhighlight lang="wml">
[store_unit]
[filter]
canrecruit=yes
side=1
[/filter]
variable=leader
[/store_unit]
[message]
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
name=leader
[/clear_variable]
</syntaxhighlight>
always displays a true sentence.

You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.

== Comments ==

Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

== See Also ==

* [[PreprocessorRef]]
* [[ConventionsWML]]
* [[SavefileWML]]
* [[ReferenceWML]]
* [[VariablesWML/How_to_use_variables|How to use variables]]

[[Category: WML Reference]]

WML for Complete Beginners: Chapter 11

2017-04-18T03:26:50Z

Sapient: add missing x,y to event filter

==Chapter 11: More Logic: Cases and Loops==

===Cases and the Switch Statement===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
x=14
y=30
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_number
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
variable=turn_number
[case]
value=1,2,3,4,5,6,7,8,9,10
# too soon
[/case]
[case]
value=11,12,13,14,15,16,17,18,19,20
# pick flower
[/case]
[else]
# too late
[/else]
[/switch]

===Loops===

I was a very messy child, much to the distress of my mother, who was the epitome of cleanliness and couldn't for the life of her understand how she could have raised such an untidy child as me. Occasionally she'd work up enough courage to venture into the land of chaos that was my room, and then she'd tell me not leave my room until it was picked up.

Okay, intimate family analogies aside, pay attention to how my mother told me to clean up my room: I was not to leave my room until it was clean. Whether or not the room was clean was the condition on which my permission to leave my room depended. So each time I put something away (which, more often then not, I did by stuffing the item under the bed), I would have to check to see that condition was met. If the room wasn't clean, then my mother's condition wasn't met and I had to keep cleaning. If the room was clean, then my mother's condition was met and I was free to leave my room.

Talk about basic parts of loops, variations of loops (do/while, etc.)

Go to Conclusion:
[[WML for Complete Beginners: Conclusion]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 10]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 11

2017-04-18T03:25:07Z

Sapient: no such variable turn_count

==Chapter 11: More Logic: Cases and Loops==

===Cases and the Switch Statement===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_number
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
variable=turn_number
[case]
value=1,2,3,4,5,6,7,8,9,10
# too soon
[/case]
[case]
value=11,12,13,14,15,16,17,18,19,20
# pick flower
[/case]
[else]
# too late
[/else]
[/switch]

===Loops===

I was a very messy child, much to the distress of my mother, who was the epitome of cleanliness and couldn't for the life of her understand how she could have raised such an untidy child as me. Occasionally she'd work up enough courage to venture into the land of chaos that was my room, and then she'd tell me not leave my room until it was picked up.

Okay, intimate family analogies aside, pay attention to how my mother told me to clean up my room: I was not to leave my room until it was clean. Whether or not the room was clean was the condition on which my permission to leave my room depended. So each time I put something away (which, more often then not, I did by stuffing the item under the bed), I would have to check to see that condition was met. If the room wasn't clean, then my mother's condition wasn't met and I had to keep cleaning. If the room was clean, then my mother's condition was met and I was free to leave my room.

Talk about basic parts of loops, variations of loops (do/while, etc.)

Go to Conclusion:
[[WML for Complete Beginners: Conclusion]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 10]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 11

2017-04-18T03:19:07Z

Sapient: fix the switch

==Chapter 11: More Logic: Cases and Loops==

===Cases and the Switch Statement===

Suppose you had a scenario in which the player must pick a flower by moving a unit to the coordinates 14,30 in order to win. But that's not all: the flower can only be picked after turn 10 and before turn 20 (so the flower can only be picked between turns 11 and 20). If the player tries to pick the flower before turn 11, the game tells him that the flower hasn't bloomed yet and that he or she needs to wait a while longer. If the player tries to pick the flower after turn 20, the game will display a message telling him or her that he or she waited too long, and now the flower is dead. How would you go about implementing this in WML?

Well, you could write something like this:

[event]
name=moveto
first_time_only=no
[filter]
side=1
[/filter]
[if]
[variable]
name=turn_number
less_than_equal_to=10
[/variable]
[then]
[message]
speaker=narrator
message= _ "The flower hasn't bloomed yet. Try coming back later."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=20
[/variable]
[then]
[message]
speaker=narrator
message= _ "You waited too long: the flower is dead now."
[/message]
[/then]
[/if]

[if]
[variable]
name=turn_number
greater_than=10
[/variable]
[and]
[variable]
name=turn_count
less_than_equal_to=20
[/variable]
[/and]
[then]
[message]
speaker=narrator
message= _ "You pick the flower."
[/message]
[/then]
[/if]

[/event]

but this is extremely lengthy and tedious to write and maintain. Wouldn't it be awesome if we had some simpler way to test multiple conditions without having to create an entire [if] codeblock for each condition?

Well, actually, there is an easier way to test for multiple conditions without having to wade through a quagmire of if codeblocks. This is done via the switch/case codeblock, which tests the value of a variable for multiple conditions, and determines the action performed as a result of that evaluation. The syntax of the switch/case codeblock goes thusly:

[switch]
variable=turn_number
[case]
value=1,2,3,4,5,6,7,8,9,10
# too soon
[/case]
[case]
value=11,12,13,14,15,16,17,18,19,20
# pick flower
[/case]
[else]
# too late
[/else]
[/switch]

===Loops===

I was a very messy child, much to the distress of my mother, who was the epitome of cleanliness and couldn't for the life of her understand how she could have raised such an untidy child as me. Occasionally she'd work up enough courage to venture into the land of chaos that was my room, and then she'd tell me not leave my room until it was picked up.

Okay, intimate family analogies aside, pay attention to how my mother told me to clean up my room: I was not to leave my room until it was clean. Whether or not the room was clean was the condition on which my permission to leave my room depended. So each time I put something away (which, more often then not, I did by stuffing the item under the bed), I would have to check to see that condition was met. If the room wasn't clean, then my mother's condition wasn't met and I had to keep cleaning. If the room was clean, then my mother's condition was met and I was free to leave my room.

Talk about basic parts of loops, variations of loops (do/while, etc.)

Go to Conclusion:
[[WML for Complete Beginners: Conclusion]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 10]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 10

2017-04-18T03:15:51Z

Sapient: /* Else */

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
# (condition)
[then]
# (do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
# (condition]
[then]
# (do something)
[/then]
[else]
# (do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
# the car door is open
[then]
# go over and shut it
[/then]
[else]
# do a backflip
[/else]
[/if]

Next Chapter:
[[WML for Complete Beginners: Chapter 11]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 9]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 10

2017-04-18T03:15:22Z

Sapient: /* If This, Then That */

==Chapter 10: Introduction to Logic==

===If This, Then That===

Suppose you went to the grocery store to get some food. You park you car in the parking lot and begin to walk towards the store, when suddenly you realize that you can't remember if you shut the car door or not after you got out. You turn around to see if the car door is open...

...and then what?

Well, if the car door is open, you know that you ''did'' forget to close it, so you go over and close it before you go into the grocery store. If the car door isn't open, there's no need for you to do anything, so you keep walking towards the store.

This kind of logic (called ''conditional'' logic) evaluates a condition and determines a reaction based on the state of that condition. In the example above, the condition is whether or not the car door is open. If it is open, then you go over and close it. If it isn't open, then you continue walking towards the store.

In WML you have a number of logical operations available to assess and react to conditions. The first one we will go over is the if/then operation. The syntax of this operations is:

[if]
# (condition)
[then]
# (do something)
[/then]
[/if]

===Else===

With the if clause, if the condition is true then we do something. But what if the condition isn't true? Well, in the examples above the WML engine doesn't have anything to do if the condition isn't true, so it just keeps running and doesn't do anything. However, it is possible to make the game perform a task if the condition isn't true, which is done by using the tagset [else]. The syntax is:

[if]
(condition]
[then]
(do something)
[/then]
[else]
(do something else)
[/else]
[/if]

Returning to the example of the car door, suppose that, before you turn around to check to see whether the door is open or not, you decide to go over and close the door if it is open, and if it isn't then you'll do a backflip to celebrate your genius before continuing your journey across the parking lot to the grocery store. In pseudocode:
[if]
the car door is open
[then]
go over and shut it
[/then]
[else]
do a backflip
[/else]
[/if]

Next Chapter:
[[WML for Complete Beginners: Chapter 11]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 9]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 8

2017-04-18T03:14:09Z

Sapient: rearrange sections

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Container Variables===

Container variables are variables that contain other variables within themselves. Just imagine how many variables you could create for information about one unit. There could be a variable my_leader_hitpoints, my_leader_name, my_leader_level, and so on. Instead of having all these different variables, wouldn't it be much easier if we could just put them all in one large box labeled "my_leader"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store other containers or even array variables.

===Array Variables===

You will typically encounter Array variables when you need to store all the units or locations on the map that meet certain criteria. That is outside the scope of this beginner's tutorial, but later you can consult the ReferenceWML documentation for [store_unit] and [store_locations] when you are ready to do that.

Here are some basic facts about Array Variables. Every Array has a length, which is the number of its containers. And these containers are all numbered starting at container zero.

Next Chapter:
[[WML for Complete Beginners: Chapter 9]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 7]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 8

2017-04-18T03:12:46Z

Sapient: /* Container Variables */

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

You will typically encounter Array variables when you need to store all the units or locations on the map that meet certain criteria. That is outside the scope of this beginner's tutorial, but later you can consult the ReferenceWML documentation for [store_unit] and [store_locations] when you are ready to do that.

Here are some basic facts about Array Variables. Every Array has a length, which is the number of its containers. And these containers are all numbered starting at container zero.

===Container Variables===

Container variables are variables that contain other variables within themselves. Just imagine how many variables you could create for information about one unit. There could be a variable my_leader_hitpoints, my_leader_name, my_leader_level, and so on. Instead of having all these different variables, wouldn't it be much easier if we could just put them all in one large box labeled "my_leader"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store other containers or even array variables.

Next Chapter:
[[WML for Complete Beginners: Chapter 9]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 7]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 8

2017-04-18T03:01:52Z

Sapient: /* Array Variables */

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

You will typically encounter Array variables when you need to store all the units or locations on the map that meet certain criteria. That is outside the scope of this beginner's tutorial, but later you can consult the ReferenceWML documentation for [store_unit] and [store_locations] when you are ready to do that.

Here are some basic facts about Array Variables. Every Array has a length, which is the number of its containers. And these containers are all numbered starting at container zero.

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

Next Chapter:
[[WML for Complete Beginners: Chapter 9]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 7]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 8

2017-04-18T02:56:20Z

Sapient: /* Array Variables */

==Chapter 8: Array, and Container Variables==

So far we have only discussed ''scalar variables'', i.e. variables that have only one value at any given time. Believe it or not, there are types of variables than can store more than one value simultaneously, or even other variables.

===Array Variables===

You will typically encounter Array variables when you need to store all the units or locations on the map that meet certain criteria. That is outside the scope of this beginner's tutorial, but later you can consult the ReferenceWML documentation for [store_unit] and [store_locations] when you are ready to do that.

===Container Variables===

Container variables are variables that contain other variables within themselves. Returning to the metaphor of boxes, let's say you had three small boxes, labeled "Apples", "Oranges", and "Pears", respectively. Instead of having to carry around three smaller boxes, wouldn't it be much easier if we could just put them all in one large box labeled "fruit"? Well, with container variables, you can!

Container variables are not restricted to containing scalar variables, however. They can also store array variables.

Next Chapter:
[[WML for Complete Beginners: Chapter 9]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 7]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2017-04-18T02:52:39Z

Sapient: /* Manipulating Variables */

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

You may have a counter variable to count the number of times an event happens. This variable will start at zero and go up by one every time the event happens. So how would you perform that basic math? It would look like this:

[set_variable]
name=counter
add=1
[/set_variable]

Next Chapter:
[[WML for Complete Beginners: Chapter 8]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 6]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 7

2017-04-18T02:45:37Z

Sapient: remove "clearing variables". it's not needed for a "complete beginner"

==Chapter 7: Introduction to Variables==

Now it's time to learn about “variables”. Variables contain things. They're a lot like boxes that you'd use when moving to a new home. You put things in the boxes, and then you label them so that you can find the right things when unpacking later.

Like attributes, every variable has a name and a value. The name of the variable is like the label on the box, and the variable's value is the thing that the variable (or box) contains.

For instance, you might put all of your dishes in a box and label it “dishes”. Similarly you might create a variable named “my_name” and put your name inside of it. Then if you wanted to find your name later, you could look in the variable called “my_name”.

===Creating Variables===
To create a variable, the following syntax is used:
[set_variable]
name=variable_name
value=variable_value
[/set_variable]

This creates a variable and assigns a name and value to it.

===Referencing Variables===

If you have ever taken basic algebra, you should know what substitution is. If you haven't, don't worry, I'll explain it.

Substitution basically allows you to substitute one thing for another thing, as long as both of those things are declared equal. For instance, let's say that x=7. Since they have been declared equal, if you were told to solve this problem:
x-3=
what would you do? Well, since x is equal to seven, you can just replace x with 7, which gives you:
7-3=
From there, it's easy to solve this problem.

What you just did was called substitution. You substituted 7 for x in the problem.

Returning the idea of the dishes stored in the box labeled "dishes". If your mother pointed at the box containing the dishes and said "get out the contents of the box labeled dishes", you understand that she wants you to get out the dishes from the box labeled "dishes", so you'd get out the dishes and give them to her. Now suppose you had a WML variable named "dishes_box" and the value of that variable was "dishes". If you tell the game that you want it to get the value of the variable named "dishes_box", it would give you the value "dishes". So what exactly do we need to do in order to tell the game to get the value of the "dishes_box" variable? This is where substitution comes in.

Suppose you wanted to have the narrator give a message telling the player the value of the variable "dishes_box". Here's how you would tell the game to do that in WML:

[message]
speaker=narrator
message= _ "The value of the dishes_box variable is: $dishes_box"
[/message]

By preceding the name of a variable with a dollar sign "$" you are telling the game that you want to substitute the value of that variable. So in-game the narrator would say, "The value of the dishes_box variable is: dishes"

Suppose you decided change the value of the "dishes_box" variable to "empty". Now the narrator will say in-game, "The value of the dishes_box variable is: empty"

===Manipulating Variables===

Next Chapter:
[[WML for Complete Beginners: Chapter 8]]

Previous Chapter:
[[WML for Complete Beginners: Chapter 6]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 1

2017-04-18T02:25:20Z

Sapient: illegal spaces in tag name

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Chapter_1|English]]
[[WML_for_Complete_Beginners:_Chapter_1/zh|简体中文]]
|}

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
grocery_store
::as is this:
bread

::If a standard string is more than one simple identifier, it is better for it to be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level_3_tagset]
level_4_attribute=value
[/level_3_tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 1

2017-04-18T02:23:51Z

Sapient: remove false requirement; clarify principle

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Chapter_1|English]]
[[WML_for_Complete_Beginners:_Chapter_1/zh|简体中文]]
|}

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
grocery_store
::as is this:
bread

::If a standard string is more than one simple identifier, it is better for it to be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]