The Battle for Wesnoth Wiki - User contributions [en]

BuildingUnits

2009-10-03T22:45:15Z

Solsword: /* Distributing your unit */

Making new units is fairly easy. Unit configuration files are plain text files that you can edit with any editor such as Notepad, TextEdit, gedit, pico, vi, emacs, etc. You will need to become familiar with [[UnitTypeWML|WML]] in order to make a new unit. This page contains a more in-depth discussion of Unit WML syntax and will walk you through the creation of a new unit and discuss how you can use it in-game.

== Recommended procedure ==
The easiest way to make a new unit is to copy and paste an existing unit, then modify it. Navigate to the game's data/units directory and copy any unit. When you are editing the unit, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game. For complete reference on unit properties see [[UnitTypeWML]].

Most of a unit's properties are self-explanatory to anyone who has played Battle for Wesnoth for very long, and the tags in the WML files are brief but descriptive. It is recommended that you try editing by yourself before consulting the guide. Otherwise, you may find the guide confusing.

== Using your new unit ==
Any unit in the game's existing data/units/*/ directories (you can't just add a new directory to data/units/) or ''[[EditingWesnoth#Where_is_my_user_data_directory.3F|userdata]]''/data/ will be recognized by the game. If you only want to use it once or twice as a special unit, that's all you need to do. However, just because you made a new unit does NOT mean that it can be recruited. Each scenario and multiplayer era has a specific recruit list. If your unit is not on the list, you can't recruit it. This means you need to modify the ''recruit='' key in the appropriate configuration file. [[BuildingMultiplayer]] describes different ways you do this for multiplayer. To add a unit to a campaign, read about scenarios, sides, and recruit lists in [[BuildingScenarios]].

== Distributing your unit ==

Note: for people using 1.7 and later, this section is out-of-date. Mainly, the campaigns/ directory is now called add-ons, but also the syntax for the main .cfg and .pbl files has changed: put _main.cfg '''inside''' your add-on directory, and put _server.pbl inside as well. Also, use ~ instead of @ for includes.

If you made a single unit, post it on the [http://www.wesnoth.org/forum forum]. If you made a whole group of units, you can make them into a multiplayer faction or you can upload a unit pack.

If you want to make a faction, follow the instructions in the [[BuildingFactions]] article. You should create a new era and add your units as one of the factions. You will not be able to add your units to any era that ships with the game.

If you want to make a unit pack, the procedure is easier. Unit packs are distributed for campaign writers who want to use your units in their campaigns/eras. They download your unit pack and copy/paste the units and images into their campaign/era.
* Navigate to the ''userdata''/data/campaigns directory. Everything from now on will occur relative to here. The era we'll use as an example will be called MyUnitPack
* Create a text file called MyUnitPack.cfg. Add the following lines:
# #define USE_MYUNITS #<- replace MYUNITS with something descriptive
# #enddef
# #ifdef USE_MYUNITS #<- replace MYUNITS with something descriptive
# {@campaigns/MyUnitPack/}
# #endif
:* These lines are commented out (with the #). That way when the unit pack ships it won't affect the game. If someone wants the game to be able to see these units, he can uncomment those lines and it will work. However, this usually causes problems in multiplayer (you will be using units no one else has), but it can be fun for campaigns.
:* NOTE: the commenting/uncommenting trick will only work if the units branch off of an existing unit. Custom L1 units will NOT show up in game automatically without editing another configuration file somewhere (scenario config file or multiplayer.cfg)
* Create another text file called MyUnitPack.pbl. (See [[PblWML]] for more details about *.pbl files.) Add the following lines to it:
author="''your name''"
icon="''any image file in the game's ./images directory''"
version="1.0"
title="My Awesome Unit Pack"
description="New race of lizard men."
* Create a folder called MyUnitPack. Navigate to it.
* Create two subdirectories: units and images. Place your unit cfg files and artwork into those subdirectories
* Create a text file called MyUnitPack.cfg (or another name of your choosing). Add the following lines:
[binary_path]
path=data/campaigns/MyUnitPack
[/binary_path]
[+units]
{@campaigns/MyUnitPack/units}
[/units]
* You should be ready to distribute your unit pack on the campaign server now
* PLEASE change the names to something unique before you publish

== Unit WML discussion ==

As of 1.6, unit definitions are enclosed in '''[unit_type]''' tags.

This section only provides some tips and pointers in making a unit. Feel free to add pointers of your own. For the full, current, complete WML reference on what to put in your [unit], see and frequently revisit [[UnitTypeWML|The Unit WML reference page]].
* The first attribute of a unit is the '''id''' attribute, which is a unique identifier for the unit. As value of the '''type''' attribute for these units, the '''id''' key is used. (See [[BuildingScenarios]]).
* When referencing the unit in a '''type''' key, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the key won't work. If you can't recruit in a scenario, it's probably because you have a typo in one of the unit ids and the '''recruit''' key was invalidated.
* It also has a '''name''' key, which is the (translatable) name of the unit, and is displayed on the Status Table when a unit of this type is selected. It does not need to be unique (but it helps).
* Do not set movement to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.

* See [[BuildingScenariosIntermediate]] for more information on attacks.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]
* [[Team_Color_Shifting]]

{{Create}}

BuildingUnits

2009-10-03T22:42:24Z

Solsword: /* Using your new unit */

Making new units is fairly easy. Unit configuration files are plain text files that you can edit with any editor such as Notepad, TextEdit, gedit, pico, vi, emacs, etc. You will need to become familiar with [[UnitTypeWML|WML]] in order to make a new unit. This page contains a more in-depth discussion of Unit WML syntax and will walk you through the creation of a new unit and discuss how you can use it in-game.

== Recommended procedure ==
The easiest way to make a new unit is to copy and paste an existing unit, then modify it. Navigate to the game's data/units directory and copy any unit. When you are editing the unit, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game. For complete reference on unit properties see [[UnitTypeWML]].

Most of a unit's properties are self-explanatory to anyone who has played Battle for Wesnoth for very long, and the tags in the WML files are brief but descriptive. It is recommended that you try editing by yourself before consulting the guide. Otherwise, you may find the guide confusing.

== Using your new unit ==
Any unit in the game's existing data/units/*/ directories (you can't just add a new directory to data/units/) or ''[[EditingWesnoth#Where_is_my_user_data_directory.3F|userdata]]''/data/ will be recognized by the game. If you only want to use it once or twice as a special unit, that's all you need to do. However, just because you made a new unit does NOT mean that it can be recruited. Each scenario and multiplayer era has a specific recruit list. If your unit is not on the list, you can't recruit it. This means you need to modify the ''recruit='' key in the appropriate configuration file. [[BuildingMultiplayer]] describes different ways you do this for multiplayer. To add a unit to a campaign, read about scenarios, sides, and recruit lists in [[BuildingScenarios]].

== Distributing your unit ==
If you made a single unit, post it on the [http://www.wesnoth.org/forum forum]. If you made a whole group of units, you can make them into a multiplayer faction or you can upload a unit pack.

If you want to make a faction, follow the instructions in the [[BuildingFactions]] article. You should create a new era and add your units as one of the factions. You will not be able to add your units to any era that ships with the game.

If you want to make a unit pack, the procedure is easier. Unit packs are distributed for campaign writers who want to use your units in their campaigns/eras. They download your unit pack and copy/paste the units and images into their campaign/era.
* Navigate to the ''userdata''/data/campaigns directory. Everything from now on will occur relative to here. The era we'll use as an example will be called MyUnitPack
* Create a text file called MyUnitPack.cfg. Add the following lines:
# #define USE_MYUNITS #<- replace MYUNITS with something descriptive
# #enddef
# #ifdef USE_MYUNITS #<- replace MYUNITS with something descriptive
# {@campaigns/MyUnitPack/}
# #endif
:* These lines are commented out (with the #). That way when the unit pack ships it won't affect the game. If someone wants the game to be able to see these units, he can uncomment those lines and it will work. However, this usually causes problems in multiplayer (you will be using units no one else has), but it can be fun for campaigns.
:* NOTE: the commenting/uncommenting trick will only work if the units branch off of an existing unit. Custom L1 units will NOT show up in game automatically without editing another configuration file somewhere (scenario config file or multiplayer.cfg)
* Create another text file called MyUnitPack.pbl. (See [[PblWML]] for more details about *.pbl files.) Add the following lines to it:
author="''your name''"
icon="''any image file in the game's ./images directory''"
version="1.0"
title="My Awesome Unit Pack"
description="New race of lizard men."
* Create a folder called MyUnitPack. Navigate to it.
* Create two subdirectories: units and images. Place your unit cfg files and artwork into those subdirectories
* Create a text file called MyUnitPack.cfg (or another name of your choosing). Add the following lines:
[binary_path]
path=data/campaigns/MyUnitPack
[/binary_path]
[+units]
{@campaigns/MyUnitPack/units}
[/units]
* You should be ready to distribute your unit pack on the campaign server now
* PLEASE change the names to something unique before you publish

== Unit WML discussion ==

As of 1.6, unit definitions are enclosed in '''[unit_type]''' tags.

This section only provides some tips and pointers in making a unit. Feel free to add pointers of your own. For the full, current, complete WML reference on what to put in your [unit], see and frequently revisit [[UnitTypeWML|The Unit WML reference page]].
* The first attribute of a unit is the '''id''' attribute, which is a unique identifier for the unit. As value of the '''type''' attribute for these units, the '''id''' key is used. (See [[BuildingScenarios]]).
* When referencing the unit in a '''type''' key, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the key won't work. If you can't recruit in a scenario, it's probably because you have a typo in one of the unit ids and the '''recruit''' key was invalidated.
* It also has a '''name''' key, which is the (translatable) name of the unit, and is displayed on the Status Table when a unit of this type is selected. It does not need to be unique (but it helps).
* Do not set movement to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.

* See [[BuildingScenariosIntermediate]] for more information on attacks.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]
* [[Team_Color_Shifting]]

{{Create}}

WML Abilities

2009-09-30T01:06:41Z

Solsword: Updated Charm to 1.7.x syntax

Remember that you must include the WML ability code in every scenario where you intend them to work. Or include them in the unit file inside the [unit_type] tag.

Some abilities require macros from [[WML_Utilities|Utilities]].

=== Knockback ===

When a unit is hit with a ''knockback'' attack, it is immediately pushed one hex away from the attacker, at which point the combat ends. Exception: units in villages can't be knocked out of them.

Examples that give ''knockback'' for every Drake Glider on their slam attack, and for the Shock Trooper named Jane:
{KNOCKBACK (type=Drake Glider) slam}
{KNOCKBACK description=Jane mace}

Requires the macro ''OPPOSITE_SIDE''.

#define KNOCKBACK FILTER WEAPON
[event]
name=attacker_hits
first_time_only=no

[filter]
{FILTER}
[/filter]

[special_filter]
weapon={WEAPON}
[/special_filter]

[sound]
name=ghoul-hit.wav
[/sound]

{OPPOSITE_SIDE $x2 $y2 $x1 $y1 target_hex}

[store_locations]
x,y=$x2,$y2
terrain=AaBbDeLptUVvYZ
variable=defender_in_village
[/store_locations]
[if]
[have_unit]
x,y=$target_hex.x,$target_hex.y
[/have_unit]
[else]
{IF_VAR defender_in_village.length not_equals 1 (
[then]
{STORE_UNIT_VAR x,y=$x2,$y2 side side_of_defender}

[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$target_hex.x,$target_hex.y
[/teleport]

[capture_village]
side=$side_of_defender
x,y=$target_hex.x,$target_hex.y
[/capture_village]

{CLEAR_VARIABLE side_of_defender}
[/then]
)}
[/else]
[/if]

{CLEAR_VARIABLE target_hex}
{CLEAR_VARIABLE defender_in_village}
[/event]
#enddef

=== Charm ===

When a unit is hit with a ''charm'' attack, it instantly jumps to the attacker's side, and returns to it's original side at the beginning of that side's turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

#define CHARM FILTER WEAPON
[event]
name=attacker_hits
first_time_only=no

[filter]
{FILTER}
[/filter]

[special_filter]
weapon={WEAPON}
[/special_filter]

{STORE_UNIT_VAR x,y=$x1,$y1 side charmer_side}
{STORE_UNIT_VAR x,y=$x2,$y2 side charmed_side}

{IF_VAR charmer_side not_equals $charmed_side (
[then]
{MODIFY_UNIT x,y=$x2,$y2 variables.real_side $charmed_side}
{MODIFY_UNIT x,y=$x2,$y2 side $charmer_side}
{MODIFY_UNIT x,y=$x2,$y2 moves 1}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}

{VARIABLE_OP varname format "side_$charmed_side|_units_charmed"}
{VARIABLE $varname yes}

{CLEAR_VARIABLE varname}
[/then]
)}

{CLEAR_VARIABLE charmer_side}
{CLEAR_VARIABLE charmed_side}
[/event]

[event]
name=side turn
first_time_only=no

{VARIABLE_OP this_side_charmed to_variable "side_$side_number|_units_charmed"}

{IF_VAR this_side_charmed equals yes (
[then]
[store_unit]
[filter]
[not]
side=$side_number
[/not]
[/filter]

variable=possibly_charmed
kill=no
[/store_unit]

{FOREACH possibly_charmed i}
{VARIABLE_OP real_side format "0$possibly_charmed[$i].variables.real_side"}

{IF_VAR real_side not_equals "0" (
[then]
{IF_VAR side_number equals $possibly_charmed[$i].variables.real_side (
[then]
{CLEAR_VARIABLE possibly_charmed[$i].variables.real_side}
{VARIABLE possibly_charmed[$i].side $side_number}

[unstore_unit]
variable=possibly_charmed[$i]
find_vacant=no
[/unstore_unit]
[/then]
)}
[/then]
)}
{NEXT i}

{CLEAR_VARIABLE possibly_charmed}
[/then]
)}
[/event]
#enddef

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit that has bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

{MODIFY_UNIT x,y=$x2,$y2 moves 0}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}
[/event]
#enddef

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special sucessfully hits an enemy unit, it gains a certain amount of gold - say 10.

To do this, use this code:

#define WEAPON_SPECIAL_PICKPOCKET
[damage]
id=pickpocket
name="Pickpocket"
description="When used offensively, this attack gives 10 gold to the attacker on every successful hit."
multiply=1
[/damage]
#enddef

Then put this event in your scenario:

[event]
name=attacker_hits
first_time_only=no
[filter]
side=$side_number
canrecruit=yes
[/filter]
[special_filter]
weapon=pickpocket gloves
[/special_filter]
[gold]
side=$side_number
amount=10
[/gold]
[/event]

Then give the unit you want to have the "pickpocket" special something like this:

[object]
silent=yes
[effect]
apply_to=new_attack
name=pickpocket gloves
type=impact
range=melee
damage=3
number=3
[specials]
{WEAPON_SPECIAL_PICKPOCKET}
[/specials]
[/effect]
[/object]

===Soultaker===

Any unit with this ability will gain an additional point of damage per strike every time it kills an enemy. Coder(s) unknown, made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=19&t=20100).

To give a unit the ability, place the following in any .cfg file loaded by the campaign or era:

#define ABILITY_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "Soultaker:
This unit gains an additional point added to its maximum damage whenever it kills a living unit."
[/dummy]

[/abilities]
[event]
name=die
first_time_only=no
[filter]
[not]
[wml_filter]
[status]
not_living="yes"
[/status]
[/wml_filter]
[/not]
[/filter]

[filter_second]
ability=soultaker
[/filter_second]

[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
find_vacant=no
[/unstore_unit]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
range=melee
increase_damage=1
increase=1
[/effect]
[/object]
[/event]

[+abilities]
#enddef

And the following in the unit's [abilities] tag:

{ABILITY_SOULTAKER}

===Charm (Type 2)===

An attack special. If the attack hits, and the target is level 0 or 1, the target is converted to the attacker's side. However, if it misses, the attacker is converted to the defender's side. Maintainer is krotop, using 1.4.X syntax, made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=21&t=22539)

Edit: Updated to 1.7.x syntax (maybe 1.6 compatible?) by solsword. See page history for the old version.

#textdomain wesnoth-tkotss

#define ABILITY_CHARM WEAPON
# dummy ability, defining the ability id for the next filters
[dummy]
id=charm_attack
[/dummy]

[/abilities]

# event that creates a variable at the beginning of the fight to check if the attacker hit at least once by the end.
[event]
name=attack
first_time_only=no

[filter]
ability=charm_attack
[/filter]
[filter_attack]
name={WEAPON}
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=no
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}

{DEBUG "Charm setup"}
[/event]

# event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no

[filter]
ability=charm_attack
[/filter]
[filter_attack]
name={WEAPON}
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}

{DEBUG "Charm hit"}
[/event]

# event that shifts a unit to the other side
# if the defending unit
# - was not lvl1 or lvl0
# - and was not a recruiting unit
# - and was a not a "non-living" creature
# then :
# -> if the attacker missed all attacks, it goes to the defender side.
# -> if the attacker hit once at least, the defender goes to the attacker side.
[event]
name=attack_end
first_time_only=no

[filter]
ability=charm_attack
[/filter]
[filter_attack]
name={WEAPON}
[/filter_attack]
[filter_second]
canrecruit=no
[and]
level=0
[or]
level=1
[/or]
[/and]
[and]
[not]
[filter_wml]
[status]
not_living=yes
[/status]
[/filter_wml]
[/not]
[/and]
[/filter_second]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=charmer
mode=append
[/store_unit]

[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=charmed
mode=append
[/store_unit]

[if]
[variable]
name=charmer.variables.charm_has_worked
equals=no
[/variable]
[then]
[set_variable]
name=charmer.side
value=$charmed.side
[/set_variable]
[/then]
[else]
[set_variable]
name=charmed.side
value=$charmer.side
[/set_variable]
[/else]
[/if]

[unstore_unit]
variable=charmer
[/unstore_unit]
[unstore_unit]
variable=charmed
[/unstore_unit]

{CLEAR_VARIABLE charmer}
{CLEAR_VARIABLE charmed}

{DEBUG "Charm resolution"}
[/event]

[+abilities]

#enddef

#define WEAPON_SPECIAL_CHARM
# dummy weapon special used to describe the effect to the user

[damage]
id=weapon_charm
name= _ "charm"
name_inactive= _ "charm"
description= _ "Charm :
Turns a living level 1 or level 0 unit to your side. Beware if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an ennemy leader or a non-living creature."
description_inactive= _ "Charm :
Turns a living level 1 or level 0 unit to your side. Beware if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an ennemy leader or a non-living creature."
apply_to=opponent
[/damage]

#enddef

== Works ==

Unit with ability ''works'' will produce 1 gold per turn.

Put this macro into you code before the last piece of code.
<pre>
#define ABILITY_WORKS
[leadership]
value=0
id=peasant_works
cumulative=no
name="works"
description= _ "Works:
This unit produces 1 gold per turn."
[/leadership]
#enddef
</pre>

Put this event into your code.
<pre>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
#your filter here... for example type=Peasant
[/filter]
variable=worker
kill=no
[/store_unit]

{FOREACH worker i}

[gold]
side=$side_number
amount=1
[/gold]
[unstore_unit]
variable=worker[$i]
text="1"
red,green,blue=255,255,0
[/unstore_unit]

{NEXT i}

{CLEAR_VARIABLE worker}
[/event]
</pre>

And give the unit the ability like this
<pre>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</pre>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have.
#define WEAPON_SPECIAL_MIND_FLAY
[damage]
id=mind_flay
name="Mind Flay"
description="When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
multiply=1
[/damage]
#enddef

Include these events into your scenario.
[event]
name=attack
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP second_unit.experience add -$hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
find_vacant=no
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
find_vacant=no
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]

Note: In dev version substitute "name=" instead of "weapon=".

== Initiative ==

Initiative is an aura ability. Much like Leadership, it effects adjacent allies but not the unit itself.

#define AURA_INITIATIVE TYPE
[dummy]
id=initiative
name= _ "initiative"
description= _ "Initiative:
Adjacent allies are granted Firststrike with all weapons."
[/dummy]
[/abilities]
[event]
name=attack
first_time_only=no

[filter]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]

{FOREACH unit.attack i}
{VARIABLE unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}

[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack
first_time_only=no

[filter_second]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter_second]

{FOREACH second_unit.attack i}
{VARIABLE second_unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}

[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no

[filter]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter]

{FOREACH unit.attack i}
{CLEAR_VARIABLE unit.attack[$i].specials.firststrike}
{NEXT i}

[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no

[filter_second]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter_second]

{FOREACH second_unit.attack i}
{CLEAR_VARIABLE second_unit.attack[$i].specials.firststrike}
{NEXT i}

[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[+abilities]
#enddef

A WML filter may be added instead of the type if you want some units of that type to not have the ability.

== Blitz ==

Blitz is an aura ability. Much like Leadership, it effects adjacent allies but not the unit itself.

#define AURA_BLITZ TYPE
[dummy]
id=blitz
name= _ "blitz"
description= _ "Blitz:
Allies that start their turn adjacent to this unit are granted Skirmisher for that turn."
[/dummy]
[/abilities]
[event]
name=side turn
first_time_only=no

[store_unit]
[filter]

[wml_filter]
blitzed=1
[/wml_filter]
[/filter]
variable=blitz_refresh
[/store_unit]

{FOREACH blitz_refresh i}
{CLEAR_VARIABLE blitz_refresh[$i].abilities.skirmisher}
{VARIABLE blitz_refresh[$i].blitzed 0}
[unstore_unit]
variable=blitz_refresh[$i]
[/unstore_unit]
{NEXT i}

[store_unit]
[filter]
side=$side_number
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]
variable=blitzed
[/store_unit]

{FOREACH blitzed i}
[if]
[variable]
name=blitzed[$i].abilities.skirmisher.id
not_equals="skirmisher"
[/variable]
[then]
{VARIABLE blitzed[$i].blitzed 1}
{VARIABLE blitzed[$i].abilities.skirmisher.id skirmisher}
{VARIABLE blitzed[$i].abilities.skirmisher.name "skirmisher"}
{VARIABLE blitzed[$i].abilities.skirmisher.description "Skirmisher:
This unit is skilled in moving past enemies quickly, and ignores all enemy Zones of Control."}
[unstore_unit]
variable=blitzed[$i]
[/unstore_unit]
[/then]
[/if]
{NEXT i}
[/event]
[+abilities]
#enddef

A WML filter may be added instead of the type if you want some units of that type to not have the ability.

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

WML Musical Moods

2009-09-29T06:50:43Z

Solsword:

Macros for grouping existing music (as of 1.7.x) and for changing playlists or playing random songs immediately.

#define MOOD_BATTLE
[music]
name=legends_of_the_north.ogg
append=no
ms_before=8000
[/music]
[music]
name=battle.ogg
append=yes
ms_before=8000
[/music]
[music]
name=frantic.ogg
append=yes
ms_before=8000
[/music]
[music]
name=suspense.ogg
append=yes
ms_before=8000
[/music]
[music]
name=the_dangerous_symphony.ogg
append=yes
ms_before=8000
[/music]
[music]
name=casualties_of_war.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define MOOD_EPIC
[music]
name=vengeful.ogg
append=no
ms_before=8000
[/music]
[music]
name=frantic.ogg
append=yes
ms_before=8000
[/music]
[music]
name=the_city_falls.ogg
append=yes
ms_before=8000
[/music]
[music]
name=siege_of_laurelmor.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define MOOD_CALM
[music]
name=traveling_minstrels.ogg
append=no
ms_before=8000
[/music]
[music]
name=elf-land.ogg
append=yes
ms_before=8000
[/music]
[music]
name=love_theme.ogg
append=yes
ms_before=8000
[/music]
[music]
name=sad.ogg
append=yes
ms_before=8000
[/music]
[music]
name=wanderer.ogg
append=yes
ms_before=8000
[/music]
[music]
name=journeys_end.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define MOOD_HUSHED
[music]
name=revelation.ogg
append=no
ms_before=8000
[/music]
[music]
name=underground.ogg
append=yes
ms_before=8000
[/music]
[music]
name=the_deep_path.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define MOOD_SAD
[music]
name=the_king_is_dead.ogg
append=no
ms_before=8000
[/music]
[music]
name=elvish-theme.ogg
append=yes
ms_before=8000
[/music]
[music]
name=transience.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define MOOD_DOOM
[music]
name=knalgan_theme.ogg
append=no
ms_before=8000
[/music]
[music]
name=northerners.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define MOOD_NORMAL
[music]
name=breaking_the_chains.ogg
append=no
ms_before=8000
[/music]
[music]
name=heroes_rite.ogg
append=yes
ms_before=8000
[/music]
[music]
name=knolls.ogg
append=yes
ms_before=8000
[/music]
[music]
name=loyalists.ogg
append=yes
ms_before=8000
[/music]
[music]
name=nunc_dimittis.ogg
append=yes
ms_before=8000
[/music]
[music]
name=into_the_shadows.ogg
append=yes
ms_before=8000
[/music]
[music]
name=northern_mountains.ogg
append=yes
ms_before=8000
[/music]
#enddef

#define SHHHH
[music]
name=silence.ogg
append=no
ms_before=0
[/music]
#enddef

#define CUE_EPIC
{RANDOM 0,1,2,3,4}
[switch]
variable=random
[case]
value=0
[music]
name=vengeful.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=1
[music]
name=frantic.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=2
[music]
name=the_city_falls.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=3
[music]
name=the_dangerous_symphony.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=4
[music]
name=siege_of_laurelmor.ogg
append=yes
ms_before=8000
[/music]
[/case]
[/switch]
[clear_variable]
name=random
[/clear_variable]
#enddef

#define CUE_DOOM
{RANDOM 0,1}
[switch]
variable=random
[case]
value=0
[music]
name=knalgan_theme.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=1
[music]
name=northerners.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[/switch]
[clear_variable]
name=random
[/clear_variable]
#enddef

#define CUE_ELVES
[music]
name=elf-land.ogg
play_once=yes
immediate=yes
[/music]
#enddef

#define CUE_SILENCE
[music]
name=silence.ogg
play_once=yes
immediate=yes
[/music]
#enddef

#define CUE_BATTLE
{RANDOM 0,1,2,3,4}
[switch]
variable=random
[case]
value=0
[music]
name=legends_of_the_north.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=1
[music]
name=vengeful.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=2
[music]
name=frantic.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=3
[music]
name=the_dangerous_symphony.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=4
[music]
name=casualties_of_war.ogg
append=yes
ms_before=8000
[/music]
[/case]
[/switch]
[clear_variable]
name=random
[/clear_variable]
#enddef

#define CUE_SAD
{RANDOM 0,1,2}
[switch]
variable=random
[case]
value=0
[music]
name=elvish-theme.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=1
[music]
name=the_king_is_dead.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[case]
value=2
[music]
name=transience.ogg
play_once=yes
immediate=yes
[/music]
[/case]
[/switch]
[clear_variable]
name=random
[/clear_variable]
#enddef

#define CUE_DEFEAT
[music]
name=defeat.ogg
play_once=yes
immediate=yes
[/music]
#enddef

#define CUE_VICTORY
[music]
name=victory2.ogg
play_once=yes
immediate=yes
[/music]
#enddef

#define VICTORY_AND_DEFEAT_MUSIC
[event]
name=victory
{SHHHH}
{CUE_VICTORY}
[/event]
[event]
name=defeat
{SHHHH}
{CUE_DEFEAT}
[/event]
#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

CutsceneWML

2009-09-29T06:50:15Z

Solsword:

WML for cutscenes, including a fixed fake movement macro (for cases where the destination contains a unit) and macros for defining dialogue for units that activates when a "main character" stops south of them.

==== Fake Movement ====

#define MOVE_TO FILTER X Y CONDITION
# Moves a unit to an empty space near (X, Y) (or to (X, Y) if possible).
# Ignores zones of control. Just like MOVE_UNIT, except doesn't glitch the
# movement animation when X,Y is occupied. The destination will satisfy
# CONDITION (a standard location filter), even if (X, Y) doesn't.
[store_unit]
variable=move_to_units
[filter]
{FILTER}
[and]
[not]
x=recall
[/not]
[/and]
[/filter]
[/store_unit]
{FOREACH move_to_units move_to_units_index}
[set_variable]
name=move_to_id
to_variable=move_to_units[$move_to_units_index].id
[/set_variable]
[store_unit]
variable=move_to_unit
[filter]
id=$move_to_id
[/filter]
[/store_unit]
# Get the starting x and y values:
[set_variable]
name=start_x
to_variable=move_to_unit.x
[/set_variable]
[set_variable]
name=start_y
to_variable=move_to_unit.y
[/set_variable]
# Find an open space near the destination:
{FIND_NEARBY ([not]
[filter]
[/filter]
[/not]
[and]
{CONDITION}
[/and]) {X} {Y} 30}
# Set real coordinates and end position:
[set_variable]
name=move_to_unit.x
to_variable=nearby_locations[0].x
[/set_variable]
[set_variable]
name=move_to_unit.y
to_variable=nearby_locations[0].y
[/set_variable]
[clear_variable]
name=nearby_locations
[/clear_variable]
[hide_unit]
x,y=move_to_unit.x,move_to_unit.y
[/hide_unit]
[set_variable]
name=end_x
to_variable=move_to_unit.x
[/set_variable]
[set_variable]
name=end_y
to_variable=move_to_unit.y
[/set_variable]
# Determine new facing for the unit:
[set_variable]
name=move_to_unit.facing
format=$(if(start_x < end_x, se, sw))
[/set_variable]
# Scroll to the old location:
[scroll_to]
x=$start_x
y=$start_y
[/scroll_to]
# Erase the old unit:
[kill]
id=$move_to_id
animate=no
fire_event=no
[/kill]
# Move the fake unit:
[move_unit_fake]
type=$move_to_unit.type
gender=$move_to_unit.gender
variation=$move_to_unit.variation
side=$move_to_unit.side
x=$start_x,$end_x
y=$start_y,$end_y
[/move_unit_fake]
# Place the real unit:
[unstore_unit]
variable=move_to_unit
find_vacant=yes
[/unstore_unit]
[redraw]
[/redraw]
{NEXT move_to_units_index}
[clear_variable]
name=move_to_units, move_to_unit, move_to_id, start_x, start_y, end_x, end_y
[/clear_variable]
#enddef

==== Move to a point and then go to the recall list ====

#define EXIT_STAGE_RECALL FILTER X Y
# Moves a unit matching the filter to X,Y, at which point it takes them
# off of the map and puts them on the recall list. Doesn't work for more
# than one unit at once.
{MOVE_TO {FILTER} {X} {Y} ()}
[store_unit]
variable=exit_stage_recall_unit
kill=yes
[filter]
{FILTER}
[/filter]
[/store_unit]
[unstore_unit]
variable=exit_stage_recall_unit
x,y=recall,recall
[/unstore_unit]
[clear_variable]
name=exit_stage_recall_unit
[/clear_variable]
#enddef

==== Give a unit unlimited movement ====

#define SET_UNLIMITED_MOVEMENT FILTER
# Useful for story-only situations, this macro defines an event that
# replenishes a unit's movement whenever that unit moves.
[event]
name=moveto
first_time_only=no
[filter]
{FILTER}
[/filter]
[store_unit]
kill=no
variable=temp
[filter]
{FILTER}
[/filter]
[/store_unit]
[set_variable]
name=temp.moves
to_variable=temp.max_moves
[/set_variable]
[unstore_unit]
find_vacant=no
variable=temp
[/unstore_unit]
[clear_variable]
name=temp
[/clear_variable]
[/event]
#enddef

==== Set up dialogue-based interaction ====

#define ENABLE_INTERACTION
# Sets up events to handle unit interaction. See the SET_MAIN_CHARACTER and
# UNIT_MESSAGE macros...
[event]
name=trigger_dialogue
first_time_only=no
[switch]
variable=second_unit.variables.dialogue.type
[case]
value=message
{M id=$second_unit.id $second_unit.variables.dialogue.message}
[if]
[variable]
name=second_unit.variables.dialogue.response
not_equals=$null
[/variable]
[then]
{M id=$unit.id $second_unit.variables.dialogue.response}
[/then]
[/if]
[if]
[variable]
name=second_unit.variables.dialogue.event
not_equals=$null
[/variable]
[then]
[fire_event]
name=$second_unit.variables.dialogue.event
[primary_unit]
id=$unit.id
[/primary_unit]
[secondary_unit]
id=$second_unit.id
[/secondary_unit]
[/fire_event]
[/then]
[/if]
[/case]
[case]
value=option
[message]
id=$second_unit.id
message=$second_unit.variables.dialogue.message
[option]
message=$second_unit.variables.dialogue.option1
[command]
[if]
[variable]
name=second_unit.variables.dialogue.event1
not_equals=$null
[/variable]
[then]
[fire_event]
name=$second_unit.variables.dialogue.event1
[primary_unit]
id=$unit.id
[/primary_unit]
[secondary_unit]
id=$second_unit.id
[/secondary_unit]
[/fire_event]
[/then]
[/if]
[/command]
[/option]
[option]
message=$second_unit.variables.dialogue.option2
[command]
[if]
[variable]
name=second_unit.variables.dialogue.event2
not_equals=$null
[/variable]
[then]
[fire_event]
name=$second_unit.variables.dialogue.event2
[primary_unit]
id=$unit.id
[/primary_unit]
[secondary_unit]
id=$second_unit.id
[/secondary_unit]
[/fire_event]
[/then]
[/if]
[/command]
[/option]
[/message]
[/case]
# Note: silent failure on unknown type is intentional.
[/switch]
[/event]
#enddef

==== Set the main character ====

#define SET_MAIN_CHARACTER FILTER
# Sets the filtered unit as the "main character" allowing them to talk to
# units that have an appropriate 'dialogue' variable. Interaction is
# triggered when the filtered unit moves to a space drectly south of a unit
# with dialogue. Note that the ENABLE_INTERACTION macro must be present in
# order for this macro to work. See also the UNIT_MESSAGE and UNIT_OPTION
# macros.
[event]
name=moveto
first_time_only=no
[filter]
{FILTER}
[and]
[filter_adjacent]
count=1
adjacent=n
[variable]
name=this_unit.variables.dialogue.type
not_equals=$null
[/variable]
[/filter_adjacent]
[/and]
[/filter]
[fire_event]
name=trigger_dialogue
[primary_unit]
{FILTER}
[/primary_unit]
[secondary_unit]
[filter_adjacent]
count=1
adjacent=s
{FILTER}
[/filter_adjacent]
[/secondary_unit]
[/fire_event]
[/event]
#enddef

==== Set dialogue for a unit ====

#define UNIT_MESSAGE MESSAGE RESPONSE EVENT
# Defines dialogue for a unit. When the main character (see the
# SET_MAIN_CHARACTER macro) triggers interaction with this unit, the
# message MESSAGE will be displayed, and the triggering unit will respond
# with RESPONSE, after which EVENT will be fired with the triggering unit
# as the primary unit and this unit as the secondary unit. Note that this
# macro should be placed within a [variables] tag inside of a [unit] tag.
[dialogue]
type=message
message={MESSAGE}
response={RESPONSE}
event={EVENT}
[/dialogue]
#enddef

#define SET_UNIT_MESSAGE FILTER MESSAGE RESPONSE EVENT
# Works just like the UNIT_MESSAGE macro, except that it takes a FILTER
# argument and applies the message to the all units matching the filter.
# UNIT_MESSAGE can only be used during unit creation, and must be placed
# within a [variables] tag. SET_UNIT_MESSAGE, on the other hand, can be
# used anywhere.
{SET_PROPERTY ({FILTER}) (variables.dialogue.type) ("message")}
{SET_PROPERTY ({FILTER}) (variables.dialogue.message) ({MESSAGE})}
{SET_PROPERTY ({FILTER}) (variables.dialogue.response) ({RESPONSE})}
{SET_PROPERTY ({FILTER}) (variables.dialogue.event) ({EVENT})}
#enddef

==== Set dialogue for a unit, including a two-option question ====

#define UNIT_OPTION MESSAGE OPTION1 OPTION2 EVENT1 EVENT2
# Defines dialogue for a unit that includes a choice to present to the
# player. When the main character (see the SET_MAIN_CHARACTER macro)
# triggers interaction with this unit, the message MESSAGE will be
# displayed, along with the options OPTION1 and OPTION2. Depending on which
# option the player chooses, either EVENT1 or EVENT2 will then be fired
# with the triggering unit as the primary unit and this unit as the
# secondary unit. Note that this macro should be placed within a
# [variables] tag inside of a [unit] tag.
[dialogue]
type=option
message={MESSAGE}
option1={OPTION1}
option2={OPTION2}
event1={EVENT1}
event2={EVENT2}
[/dialogue]
#enddef

#define SET_UNIT_OPTION FILTER MESSAGE OPTION1 OPTION2 EVENT1 EVENT2
# Works just like the UNIT_OPTION macro, except that it takes a FILTER
# argument and applies the message to all units matching the filter.
# UNIT_OPTION can only be used during unit creation, and must be placed
# within a [variables] tag. SET_UNIT_OPTION, on the other hand, can be
# used anywhere.
{SET_PROPERTY ({FILTER}) (variables.dialogue.type) ("option")}
{SET_PROPERTY ({FILTER}) (variables.dialogue.message) ({MESSAGE})}
{SET_PROPERTY ({FILTER}) (variables.dialogue.option1) ({OPTION1})}
{SET_PROPERTY ({FILTER}) (variables.dialogue.option2) ({OPTION2})}
{SET_PROPERTY ({FILTER}) (variables.dialogue.event1) ({EVENT1})}
{SET_PROPERTY ({FILTER}) (variables.dialogue.event2) ({EVENT2})}
#enddef

==== Clear unit dialogue ====

#define CLEAR_UNIT_DIALOGUE FILTER
# Removes any dialogue that is assigned to units matching the given filter,
# including both messages and options.
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.type)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.message)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.response)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.option1)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.option2)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.event)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.event1)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue.event2)}
{CLEAR_PROPERTY ({FILTER}) (variables.dialogue)}
#enddef

==== Assign a role to a recalled unit with various back-ups ====

#define FILL_ROLE_RECALL SIDE ROLE FILTER BACKUP_FILTER TYPE X Y
# Recalls the first unit on side SIDE matching FILTER and assigns it the
# role ROLE. If no such unit exists, it tries to find a unit that matches
# the given BACKUP_FILTER on SIDE's recall list, and if it can't, it tries
# to find any unit on side SIDE's recall list. If SIDE has no units on its
# recall list, a unit is spawned of type TYPE to fill the role. If the role
# is already filled, this does nothing. If the given location is
# unavailable, the nearest empty location will be used.
[if]
[have_unit]
side={SIDE}
x,y={X},{Y}
[/have_unit]
[then]
{FIND_NEARBY ([not]
[filter]
[/filter]
[/not]) {X} {Y} 30}
[set_variable]
name=fill_role_recall_target_x
to_variable=nearby_locations[0].x
[/set_variable]
[set_variable]
name=fill_role_recall_target_y
to_variable=nearby_locations[0].y
[/set_variable]
[clear_variable]
name=nearby_locations
[/clear_variable]
[/then]
[else]
[set_variable]
name=fill_role_recall_target_x
value={X}
[/set_variable]
[set_variable]
name=fill_role_recall_target_y
value={Y}
[/set_variable]
[/else]
[/if]
[if]
[not]
[have_unit]
side={SIDE}
role={ROLE}
[/have_unit]
[/not]
[then]
[recall]
show=no
side={SIDE}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
{FILTER}
[/recall]
[role]
role={ROLE}
side={SIDE}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
{FILTER}
[/role]
[/then]
[/if]
[if]
[not]
[have_unit]
side={SIDE}
role={ROLE}
[/have_unit]
[/not]
[then]
[recall]
show=no
side={SIDE}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
{BACKUP_FILTER}
[/recall]
[role]
role={ROLE}
side={SIDE}
{BACKUP_FILTER}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
[/role]
[/then]
[/if]
[if]
[not]
[have_unit]
side={SIDE}
role={ROLE}
[/have_unit]
[/not]
[then]
[recall]
show=no
side={SIDE}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
[/recall]
[role]
role={ROLE}
side={SIDE}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
[/role]
[/then]
[/if]
[if]
[not]
[have_unit]
side={SIDE}
role={ROLE}
[/have_unit]
[/not]
[then]
[unit]
side={SIDE}
type={TYPE}
x,y=$fill_role_recall_target_x,$fill_role_recall_target_y
generate_name=yes
random_gender=yes
random_traits=yes
role={ROLE}
[/unit]
[/then]
[/if]
[clear_variable]
name=fill_role_recall_target_x,fill_role_recall_target_y
[/clear_variable]
#enddef

==== Assign a group of roles to several units with backups ====

#define ASSIGN_ROLES ROLES DESIRED_ROLE_FILTER BACKUP_ROLE_FILTER
# Fills several roles at once from the pool of units specified by
# DESIRED_ROLE_FILTER, using units that match BACKUP_ROLE_FILTER if
# necessary. ROLES should be an ordered, comma-separated list of roles to
# fill. If not enough units match among both the DESIRED and BACKUP
# filters, not all of the roles will be assigned. The main advantage of
# ASSIGN_ROLES over [role] tags is that you don't have to use a bunch of
# [not] role= [/not] statements to ensure that each unit gets one role.
[set_variables]
name=roles_to_assign
[split]
list={ROLES}
key=value
separator=,
remove_empty=yes
[/split]
[/set_variables]
[set_variable]
name=role_assignment_index
value=0
[/set_variable]
[set_variable]
name=done_assigning_roles
value=no
[/set_variable]
[store_unit]
variable=primary_role_candidates
[filter]
{DESIRED_ROLE_FILTER}
[/filter]
[/store_unit]
[set_variable]
name=role_candidate_index
value=0
[/set_variable]
[while]
[variable]
name=done_assigning_roles
boolean_equals=no
[/variable]
[and]
[variable]
name=role_candidate_index
less_than=$primary_role_candidates.length
[/variable]
[/and]
[do]
# Assign a role:
[role]
role=$roles_to_assign[$($role_assignment_index)].value
id=$primary_role_candidates[$($role_candidate_index)].id
[/role]
# Increment loop variables:
[set_variable]
name=role_assignment_index
add=1
[/set_variable]
[set_variable]
name=role_candidate_index
add=1
[/set_variable]
# Check the break condition:
[if]
[not]
[variable]
name=role_assignment_index
less_than=$roles_to_assign.length
[/variable]
[/not]
[then]
[set_variable]
name=done_assigning_roles
value=yes
[/set_variable]
[/then]
[/if]
[/do]
[/while]
# Use backups if necessary:
[if]
[variable]
name=done_assigning_roles
boolean_equals=no
[/variable]
[then]
[store_unit]
variable=secondary_role_candidates
[filter]
{BACKUP_ROLE_FILTER}
[/filter]
[/store_unit]
[set_variable]
name=role_candidate_index
value=0
[/set_variable]
[while]
[variable]
name=done_assigning_roles
boolean_equals=no
[/variable]
[and]
[variable]
name=role_candidate_index
less_than=$secondary_role_candidates.length
[/variable]
[/and]
[do]
# Assign a role:
[role]
role=$roles_to_assign[$($role_assignment_index)].value
id=$secondary_role_candidates[$($role_candidate_index)].id
[/role]
# Increment loop variables:
[set_variable]
name=role_assignment_index
add=1
[/set_variable]
[set_variable]
name=role_candidate_index
add=1
[/set_variable]
# Check the break condition:
[if]
[not]
[variable]
name=role_assignment_index
less_than=$roles_to_assign.length
[/variable]
[/not]
[then]
[set_variable]
name=done_assigning_roles
value=yes
[/set_variable]
[/then]
[/if]
[/do]
[/while]
[/then]
[/if]
[clear_variable]
name=roles_to_assign, role_assignment_index, primary_role_candidates, secondary_role_candidates, role_candidate_index, done_assigning_roles
[/clear_variable]
#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

UsefulWMLFragments

2009-09-29T06:42:37Z

Solsword: /* Campaign Tools */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.
*[[AlternateToDWML]]: Macros for alternate time-of-day schemes, including per-hour time-of-day.

==== RPG Tools ====
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
*[[CutsceneWML]]: Fixed MOVE_TO event (uses FIND_NEARBY from [[WML Utilities]]), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.

==== Music Tools ====
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

UsefulWMLFragments

2009-09-29T06:41:21Z

Solsword: /* RPG Tools */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.

==== RPG Tools ====
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
*[[CutsceneWML]]: Fixed MOVE_TO event (uses FIND_NEARBY from [[WML Utilities]]), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.

==== Music Tools ====
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

CutsceneWML

2009-09-29T06:39:02Z

Solsword: Initial copy of the page macros

UsefulWMLFragments

2009-09-29T06:28:00Z

Solsword: /* RPG Tools */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.

=== RPG Tools ===
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
*[[CutsceneWML]]: Fixed MOVE_TO event (uses FIND_NEARBY from [[WML Utilities]]), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.

==== Music Tools ====
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

UsefulWMLFragments

2009-09-29T06:27:35Z

Solsword: /* Campaign Tools */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.

=== RPG Tools ===
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
*[[CutsceneWML]]: Fixed MOVE_TO event (uses FIND_NEARBY), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.

==== Music Tools ====
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

UsefulWMLFragments

2009-09-29T06:19:51Z

Solsword: /* Logic Structure Macros */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.

==== Music Tools ====
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Map Tools ====
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

WML Utilities

2009-09-29T06:19:14Z

Solsword: Added search macro

== Filter by Terrain ==

# Check whethers or not the terrain in the given coordinates is of the given
# type or types. Filtering by terrain isn't possible directly.
#
# You can use it for example like this:
#
# [event]
# name=moveto
# first_time_only=no
#
# {IF_TERRAIN $x1 $y1 Gg,Gs^Fp,Mm (
# [then]
# {DEBUG_MSG "Stepped on grassland, forest or mountains!"}
# [/then]
# )}
# [/event] 
#define IF_TERRAIN X Y TERRAIN CONTENTS
[store_locations]
x={X}
y={Y}
terrain={TERRAIN}
variable=IF_TERRAIN_temp
[/store_locations] 
[if]
[variable]
name=IF_TERRAIN_temp.length
not_equals=0
[/variable] 
{CONTENTS}
[/if] 
{CLEAR_VARIABLE IF_TERRAIN_temp}
#enddef

==Iterate==

# You can iterate through a range of numbers with this macro. The CONTENTS
# are repeated with every iteration, and you can use the VAR variable to
# insert the number of the current step into each iteration. Note that
# when using this, you must iterate from a smaller number to the bigger
# number, because the increment is always 1.
#
# Example that spawns a row of skeletons into the coordinates (4,5),
# (5,5), (6,5), (7,5), (8,5) and (9,5):
#
# {ITERATE 4 9 i (
# [unit]
# type=Skeleton
# x=$i
# y=5
# [/unit]
# )} 
#define ITERATE FROM TO VAR CONTENTS
{VARIABLE {VAR} {FROM}} 
[while]
[variable]
name={VAR}
less_than_equal_to={TO}
[/variable] 
[do]
{CONTENTS} 
{VARIABLE_OP {VAR} add 1}
[/do]
[/while]
#enddef

== Adding unit overlays with a filter instead of (x,y) ==

# UNIT_OVERLAY adds an overlay to a unit, taking in a standard filter
#
# Example that gives all spearmen a book:
# {UNIT_OVERLAY type=Spearman items/book1.png}

#define UNIT_OVERLAY FILTER IMG
[store_unit]
[filter]
{FILTER}
[/filter]
variable=UNIT_OVERLAY_store
kill=no
[/store_unit]
{FOREACH UNIT_OVERLAY_store UNIT_OVERLAY_i}
{VARIABLE_OP UNIT_OVERLAY_tempx format $UNIT_OVERLAY_store[$UNIT_OVERLAY_i].x}
{VARIABLE_OP UNIT_OVERLAY_tempy format $UNIT_OVERLAY_store[$UNIT_OVERLAY_i].y}
[unit_overlay]
x=$UNIT_OVERLAY_tempx
y=$UNIT_OVERLAY_tempy
image={IMG}
[/unit_overlay]
{NEXT UNIT_OVERLAY_i}
{CLEAR_VARIABLE UNIT_OVERLAY_store}
#enddef

== Determining opposite coordinates ==

# Using this, you can determine the coordinates on the "opposite side" of a
# central hex, relative to another hex adjacent to it. What this really means
# is illustrated below:
# __ __ __
# __/ \__ __/2 \__ __/ \__
# / \__/1 \ / \__/ \ /2 \__/ \ C: central point
# \__/C \__/ \__/C \__/ \__/C \__/ 1: the hex to "mirror"
# /2 \__/ \ / \__/ \ / \__/1 \ 2: the result
# \__/ \__/ \__/1 \__/ \__/ \__/
# \__/ \__/ \__/
#
# The coordinates of the central point are given in {CENTER_X} and {CENTER_Y},
# and the coordinates of hex 1 in {X} and {Y}. The coordinates of hex 2 are
# then stored in {VAR}, which will have member variables x and y.
#
# Note that this uses the IF macro given earlier on this page. 
#define OPPOSITE_SIDE CENTER_X CENTER_Y X Y VAR
{VARIABLE x_odd {X}} 
{VARIABLE_OP x_odd modulo 2} 
{VARIABLE c_x {CENTER_X}}
{VARIABLE c_y {CENTER_Y}}
{VARIABLE s_x {X}}
{VARIABLE s_y {Y}} 
{VARIABLE result_x {CENTER_X}}
{VARIABLE result_y {CENTER_Y}} 
{IF_VAR s_x greater_than $c_x (
[then]
{VARIABLE_OP result_x add -1}
[/then]
)} 
{IF_VAR s_x less_than $c_x (
[then]
{VARIABLE_OP result_x add 1}
[/then]
)} 
{IF_VAR s_x equals $c_x (
[then]
{IF_VAR s_y less_than $c_y (
[then]
{VARIABLE_OP result_y add 1}
[/then]
)} 
{IF_VAR s_y greater_than $c_y (
[then]
{VARIABLE_OP result_y add -1}
[/then]
)}
[/then]
)} 
{IF_VAR x_odd equals 1 (
[then]
{IF_VAR s_y equals $c_y (
[then]
{VARIABLE_OP result_y add 1}
[/then]
)}
[/then] 
[else]
{IF_VAR s_y equals $c_y (
[then]
{VARIABLE_OP result_y add -1}
[/then]
)}
[/else]
)}
{VARIABLE {VAR}.x $result_x}
{VARIABLE {VAR}.y $result_y} 
{CLEAR_VARIABLE c_x}
{CLEAR_VARIABLE c_y}
{CLEAR_VARIABLE s_x}
{CLEAR_VARIABLE s_y}
{CLEAR_VARIABLE result_x}
{CLEAR_VARIABLE result_y}
{CLEAR_VARIABLE x_odd}
#enddef

== Find nearest hex(es) ==

#define FIND_NEARBY FILTER X Y LIMIT
# Does a search for a nearby location that matches the given filter.
# Basically just looks for such a location with increasing radius until it
# finds at least one. This is sadly inefficient, but implementing BFS in
# WML is... difficult. Once LIMIT is reached, the entire map is searched.
# This macro creates the 'nearby_locations' and 'nearby_distance'
# variables, which can be used to access a list of locations found and the
# distance to those locations, respectively. They should eventually be
# cleared, which can be accomplished using the CLEANUP_SEARCH macro.
[clear_variable]
name=nearby_locations
[/clear_variable]
[set_variable]
name=nearby_distance
value=0
[/set_variable]
[while]
[not]
[variable]
name=nearby_locations.length
greater_than=0
[/variable]
[/not]
[and]
[variable]
name=nearby_distance
less_than={LIMIT}
[/variable]
[/and]
[do]
{DEBUG "Searching depth $nearby_distance around ({X}, {Y})..."}
[store_locations]
variable=nearby_locations
{FILTER}
[and]
x,y={X},{Y}
radius=$nearby_distance
[/and]
[/store_locations]
{DEBUG "...found $nearby_locations.length locations."}
[set_variable]
name=nearby_distance
add=1
[/set_variable]
[/do]
[/while]
[if]
[variable]
name=nearby_locations.length
equals=0
[/variable]
[then]
[store_locations]
variable=nearby_locations
{FILTER}
[/store_locations]
[/then]
[/if]
#enddef

#define CLEANUP_SEARCH
# Clears variables involved in searching (the FIND_NEARBY macro). Put this
# in your name=victory,defeat tag to clean up if you use FIND_NEARBY within
# a scenario.
[clear_variable]
name=nearby_locations, nearby_distance
[/clear_variable]
#enddef

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

UsefulWMLFragments

2009-09-29T06:17:21Z

Solsword: /* Music Tools */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates.

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.

==== Music Tools ====
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Map Tools ====
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

WML Musical Moods

2009-09-29T06:16:38Z

Solsword: Added the moods macros.

UsefulWMLFragments

2009-09-29T06:13:34Z

Solsword: /* Campaign Tools */

== Useful WML Fragments ==

Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Some things '''not''' to do here:
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
* Don't add macros that are trivial syntax shortcuts.
* Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

=== Logic Structure Macros ===
*[[WML Utilities]]: Macros to assist other macros. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates.

=== Campaign Tools ===
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.

=== Music Tools ===
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

==== Map Tools ====
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.

==== Unit Tools ====
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.

==== Item Tools ====
*[[DroppableItem]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.

=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme. Store Reachable Locations.

=== Templates ===
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)

== See Also ==

* [[ReferenceWML]]

[[Category: UsefulWMLFragments|*]]

AbilitiesWML

2009-09-29T05:31:59Z

Solsword: /* The [specials] tag */

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials, but by convention only one weapon special should be assigned to any given attack.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
Any other name is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. '''Note:''' a dummy ability must have an id for the name and description to display.

=== Common keys and tags for every ability ===

* '''name''': the name of the ability.
* '''name_inactive''': the name of the ability when inactive.
* '''description''': the description of the ability.
* '''description_inactive''': the description of the ability when inactive.
* '''affect_self''': if equal to 'yes', the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect allies in the specified adjacent hexes.
* '''affect_enemies''': if equal to 'yes', the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''[adjacent_description]''': contains all four of the above keys, which are used when an adjacent unit receives the ability.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* '''[affect_adjacent]''': each adjacent unit that does not match this filter will not receive its effects.
** '''adjacent''': a comma seperated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''.
** '''[filter]''': a [[StandardUnitFilter]].
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. This value '''must''' be set in order for [resistance] to function.
* '''add''': adds to resistance.
* '''multiply''': multiplies resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.

=== Extra keys used by the ''[illuminates]'' ability ===

* '''value''': the percentage bonus to lawful units.
* '''max_value''': the maximum percentage bonus given.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Macros for common abilities ===

* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[damage]''': modifies the damage of a weapon
* '''[attacks]''': modifies the number of attacks of a weapon
* '''[chance_to_hit]''': modifies the chance to hit of a weapon
* '''[slow]'''
* '''[poison]'''
* '''[stones]''' ('''[petrifies]''' in recent versions.
* '''[berserk]'''
* '''[firststrike]'''
* '''[drains]'''
* '''[plague]'''
Any other name is valid, but will result in an special that does nothing but report it's there.

=== Common keys and tags for every weapon special ===

* '''name''': the name of the special.
* '''name_inactive''': the name of the special when inactive.
* '''description''': the description of the special.
* '''description_inactive''': the description of the special when inactive.
* '''value''': the value to be used. Applies to '''[damage]''', '''[attacks]''', '''[chance_to_hit]''' and '''[berserk]''' (the maximum number of combat rounds).
* '''add''' the number to add to the base value.
* '''multiply''': same as '''value''', except that this multiplies the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''type''': only usable in '''[plague]''', where it defines the unit type to be spawned on kill.
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both'''. Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': [[StandardUnitFilter]], which takes an extra key '''adjacent''', which is used to specify which adjacent hexes to filter on. '''adjacent''' is a comma seperated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''.
* '''[filter_adjacent_location]''': like [filter_adjacent], except that it filters on the locations rather than the units.
* '''[filter_self]''': the special will only be active if the owner matches this filter.
** '''[filter_weapon]''': a standard weapon filter.
* '''[filter_opponent]''': the special will only be active if the opponent matches this [[StandardUnitFilter]].
** '''[filter_weapon]''': a standard weapon filter.
* '''[filter_attacker]''': the special will only be active if the attacker matches this filter.
** '''[filter_weapon]''': a standard weapon filter.
* '''[filter_defender]''' the special will only be active if the defender matches this filter.
** '''[filter_weapon]''': a standard weapon filter.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc.

=== Macros for common weapon specials ===

* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

EventWML

2009-09-25T23:31:18Z

Solsword: Sighted event warning

{{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 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.

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.

'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''

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.''

==== Predefined 'name' Key Values ====

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).

; preload {{DevFeature}}
: 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 whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, 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.

; 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.

; turn refresh
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

; turn ''X''
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.

; time over
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])

; enemies defeated
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.

; 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]])

; 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]])

Filters 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]]

; 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. ''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 other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.) (Double note: it also appears that the sighted event in more recent versions of the game (1.6 and 1.7, maybe?) does not fire on enemy turns. That is, it only fires for units that become visible as a result of the motion of another unit, not for units that move into the vision of an enemy. This event is also buggy in general... it's usually better to use a moveto event with a [filter_vision] tag than to use a sighted event (and note that the combination of the two can achieve something like the old sighted event)).

; attack
: Triggers when the primary unit attacks the secondary unit.

; 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.

; stone
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.

; die
: Triggers when the primary unit is killed by the secondary unit.

; 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.

; recruit
: Triggers when the primary unit is recruited. (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 but before it is displayed.

; recall
: Triggers after a unit is recalled.

; prerecall
: Triggers when a unit is recalled but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit.

; post advance
: Triggers just after the primary unit has advanced to another unit.

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, 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.''

=== 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.

=== 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 every time the criteria are met instead of only the first time.

==== [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 for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and other filter keys, see [[FilterWML]].
:* '''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 secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [event] ====
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].

==== 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 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

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 ==

It is only possible to use [message] with input and random numbers in events that are synchronous. This limitation is caused because that WML requires data from remote hosts which is only available after network synchronisation.

List of event that are synchronous:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
* events fired from WML event handler that is synchronous
* new turn {{DevFeature}}
* side turn {{DevFeature}}
* turn X {{DevFeature}}
* turn refresh {{DevFeature}}

There is also event that are synchronous if fired by engine but they can be fired by wml tags too from non-synchronous event. So when you are using them you must be extra careful. For example [unsotre_unit] unit may trigger unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

It is perfectly possible (and, in fact, useful) to have multiple events with the same predefined name and thus the same trigger condition. However, it is not defined what order such events will fire in, so you need to code so the order
will not matter.

Because of the above, 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.

== 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 the turn 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]

This 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, this example is identical to the first two, in that it will display the turn 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]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

TeamColoring

2009-09-17T04:40:59Z

Solsword: Update to reflect the realities of the current TeamColorizer

If you're an artist, or if you want to use a Wesnoth sprite as your avatar in the forums, or for whatever reason you want to produce a team-colored copy of a Wesnoth sprite without actually running Wesnoth (and probably having to cut the sprite out of a background), there are two easy tools to accomplish this:

* TeamColorizer - This is a Python script included with Wesnoth that does an '''inaccurate''' teamcoloring: it uses a slightly different algorithm than the one used in-game. However, it allows you to use any color that you want, even colors that aren't normal team colors. You just need to do a bit of trickery.
* wesnoth-tc - This is a C++ program, written by Shadowmaster from the forums. It even has a GUI written for Macs. It uses the same algorithm as the Wesnoth engine.

== TeamColorizer ==

The TeamColorizer included with Wesnoth is at data/core/tools/unit_tree/TeamColorizer. Internally, it's used to produce the red sprites found on http://units.wesnoth.org. However, you can use it to color any image red. It's a command-line program, so first you'll need to open up a command line (either Start->Run and then type "cmd" in Windows, or use Terminal on a Mac; if you run something else you should know how to do this already). Next, you need to find two things: Python, and the TeamColorizer. You don't have to do this in the shell. Python is likely to be at
C:\Python<#>\Python.exe
or something like that, where <#> is the version, and will be something like '25' for 2.5, '26' for 2.6, etc. You actually don't need this step on a Mac. Next, you have to find the TeamColorizer, and this one you have to do in the shell, by typing
cd <directory>
and then either 'ls' or 'dir' depending on whether you're on Windows ('dir') or on something else. The directory you want is data/core/tools/unit_tree relative to the [http://www.wesnoth.org/wiki/EditingWesnoth#Where_is_my_game_data_directory.3F Wesnoth data directory]. Once you're there, type
python TeamColorizer <input_image> <output_image>
where <input_image> and <output_image> are the '''full''' paths to the input image and desired output image, respectively. If you don't want to worry about where the images are, you can just copy the image you want to use into the same directory as the TeamColorizer for simplicity. Note that the output image will also appear in the same directory as the TeamColorizer unless you give it a different path. If you want, you can copy the whole TeamColorizer somewhere else for convenience. A quick example of what you might do:
C:\> cd C:\Progra~1\Wesnoth\data\tools\unit_tree
C:\Program Files\Wesnoth\data\tools\unit_tree> C:\Python25\Python.exe TeamColorizer C:\my_image.png out.png
on Windows, or
cd /usr/local/share/wesnoth/data/tools/unit_tree
./TeamColorizer ~/Desktop/in.png ~/Desktop/out.png
on a Mac (although that Wesnoth path might not be the same as yours...).

Note: these are pretty bad and technical instructions... especially the Windows side. Please revise them if you've got a better way of explaining things. Maybe you could just create a shortcut with the arguments in it in Windows and that would be simpler? (In fact, I'm not even sure if the Windows instructions are correct!)

So now you have a red copy of your image. Hooray! What about other colors? There's currently a patch being considered that will make this bit a little easier (this editor will be honest and admit that eir the one that submitted the patch) but for now, you have to edit the TeamColorizer file. Open it with wordpad, textmate, or whatever text editor you normally use. Look near the top for a place where it says:
team_red = 255
team_green = 0
team_blue = 0
or something like that. Simply change the red, green, and blue values to your desired color and run the script again. For reference, the Wesnoth team colors are listed in data/core/team-colors.cfg, although because of the difference in algorithm, using the "average color" listed in that file may produce more washed-out variants; try using the "flag color", or some combination of the two.

== wesnoth-tc ==

If you want to use wesnoth-tc, read up on it on its [http://www.wesnoth.org/forum/viewtopic.php?f=9&t=22859 forum thread]. The thread has information on usage and a link to download the source, as well as information on the Mac GUI. Feel free to post more instructions here if you use it and feel like sharing any insights you gain.

Create Art

2009-09-17T04:29:37Z

Solsword: /* Sprite Art */

{| style="float:right; margin-left:1em;"
|__TOC__
|}

== Getting Started ==

=== General Information ===

Graphic artists usually meet on the [http://www.wesnoth.org/forum/viewforum.php?f=9 artwork development forum] or on the [http://www.wesnoth.org/forum/viewforum.php?f=18 restricted art development forum]. The former is a great place to post and discuss new and current Wesnoth art and graphics, and the latter to see what the art development team is working on.

Unit and terrain art is stored in the portable network graphics (PNG) format. Each frame of a unit animation, and each variation of a terrain is stored as a separate .png file in the "images" subdirectory of wesnoth, and generally these files will be 72 x 72 pixels (the size of Wesnoth's basic hexagonal tile) with an alpha channel (a part of the file that indicates how transparent each pixel is). When creating your own images, you can test them without overwriting any game data by putting them in your userdata directory (see [[EditingWesnoth]] for details on Wesnoth's directory structure). The game also supports JPEG images, though these are better suited for story art.

To edit these graphics, you'll need some program capable of creating PNGs - some of the programs in the following list are free, open-source software, and will do the job nicely: [[Art Programs]]

If you need some inspiration, we have a [[GraphicLibrary|Graphics Library]] which collects art posted on the forum. You can use this for ideas, and as a scrap heap for different parts of unit images (a technique described [[Give Your Hero A Personality|here]]).

=== Roadmap ===
A list of what's being done and what needs doing:
* '''[[Tiles Status]]''' - a roadmap/plan of sorts for future work on terrain tiles
* [http://www.wesnoth.org/forum/viewtopic.php?t=2014 A list] of current work that needs to be done with sprites.

== Art Tutorials ==

These are a work-in-progress, and describe both how to make art fit into wesnoth's style, as well as giving some considerable tips on drawing in general. Especially useful is the [[External Tutorials]] page which lists a large number of art tutorials available on the web.

=== General Art and Computer Graphics ===
* [[Using the Levels Adjustment]] - making scanned pencil drawings ''not'' look washed out.
* [[Extending dynamic range]] - The Grooviest (so far) tutorial about extending the dynamic range of images and how this technique can be used to make better scans of pencil drawings.
* [[Scanning with camera]] - How to transfer real-life art to computer using a digital camera instead of a scanner.
* [[How to Anti-Alias Sprite Art]] - A means of removing the jagged edges on pixel lines
* [[Art Supplies]] - What physical items you need to do larger cell-shaded art like that of Jetryl/Jormungadr/et al
* [[Inking With Pencils|Computer Inking a Sketch]] - Info from Jason Lutes on his portrait workflow
* [[Scaling Digital Images]] - how to properly resize an image on a computer
* [[How to Shade]] - at attempt at tackling a very complicated topic
* [[Cartography for Wesnoth|How to make Wesnoth-style Maps ]] - Kestenvarn's tricks of the trade
* [[Designing weapons and armour]] - Advice from zookeeper on designing realistic weapons for your characters
* [[Portrait Tutorial]] - a guide on how to draw unit/character portraits by Kitty.
* Sgt. Groovy's vector workshop - tips and tricks for drawing with Inkscape
** [[Z-order tricks]] - few methods for faking overlapping shapes
** [[Variable-width strokes]] - how to make the strokes vary in width, like being drawn with a flat-tipped pen — no tablet needed!
** [[Shaped gradients with Gaussian blur]] - how to make gradients in other shapes than linear or radial
** [[Smooth shading in vector]] - the basic vector techniques for smooth shading, employing Gaussian blur and clipping/masking
** [[Vector Inking]] - vector techniques, including mouse-only, for inking your sketches
** [[Making portrait art in vector]] - a complete tutorial for making Wesnoth unit portraits in vector graphics.

=== [[Terrain|Terrain Graphics]] ===

The following is information specific to drawing terrain for Wesnoth. Read Frame's "Tiles Tutorial" for a good overview of how terrain graphics work.

* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in wesnoth, and how they interact with adjacent tiles.
* [[How To Make Seamless Tiles]] - The tutorial is aimed at Photoshop users, but the technique is similar with The GIMP.
* [[Seamless Tiles Using Inkscape]] - This tutorial teaches a method for making seamless hex tiles in vector craphics (to be rendered in raster).
* [[Turning Square Tiles into Hex]] - Nifty tricks for transforming square (or any rectangle) shaped seamless tiles into hexagon seamless tiles.
* [[CastleTutorial|Castle Tutorial]] - A description of how Wesnoth's castle tiles work (needs updating, but useful nonetheless)
* [[MultiHexTutorial|Multi-Hex Tiling Tutorial]] - A description of how multi-hex tiles work.
* [[Editing Castles]] - Instructions for how to make/edit castles (and other corner-based terrains) using yobbo's GIMP script.

These describe the system used to specify how terrains behave in game:
* [[TerrainCodesWML]] - A list of the letters used to represent terrain types.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml Ayin's Terrain Graphics document] - If you really, ''really'' need to get technical, this describes the terrain graphics WML system in depth.

=== Sprite Art ===
The following are different tutorials about sprite work compiled by various wesnoth sprite artists. These will give you the most specific-to-wesnoth information about making sprites, and are well worth a read.

* [[Creating Unit Art]] - a list of specifications you will need to match.
* [[Give Your Hero A Personality]] - tricks for editing existing images, including some clip art.
* [[Basic Animation Tutorial]] - or "How to Animate Sprites for Dummies," covering the basic theory, and all of the mistakes to avoid.
* [[Team Color Shifting]] - how to create art that uses our new team color system.
* [[TeamColoring]] - how to automatically team-color sprites to see what they look like in various colors.
* [[Creating Shadows Under Units]] - how we create the shadows for the units in-game
* [[Making Bow Animations]] - the current standard for how we want bow animations to work
* [[Rotate Pixel Art Without Blurring]]
* [[Creating a scratch built sprite]] - an attempt to show some ways creating a sprite from scratch
* [[How to create motion blurs]] - a simple explanation on how to create attack animation weapon blurs
* [[FrankenPacks]] - a quick and dirty way to create sprites for [[WesnothAcronyms|UMC]]

=== External Tutorials ===
The following page contains dozens of links to tutorials covering all manner of artwork, including sprite art. These were not made by wesnoth artists, but should prove very useful for general instruction.

* [[External Tutorials]]

== See Also ==
* [[Create]]
* [[EditingWesnoth]]
* [[GraphicLibrary]] - Lots of usercontributed graphics (most should be GPL'ed)
* [[Project]]
* [http://wesnoth.dbzer0.com/blog/wpg2 External Graphic Library] - A project to better organize the art of Wesnoth.

[[Category:Art Tutorials]]

Team Color Shifting

2009-09-17T04:27:48Z

Solsword: Link to the new TeamColoring wiki page

by Richard Kettering (Jetryl)

:Note: if you're interested in actually changing the color of a sprite that has already had this technique applied to it (i.e. automatically changing the magenta in a sprite to blue or red), see the [[TeamColoring]] page instead.

Wesnoth's sprites are only drawn in one color, but in an actual game, all of our unit's clothing will change color to the color of whatever team they're on. We call this "team color" shifting. Any team color shifting system needs a way of indicating which areas of the graphic are to be changed in color. Ours solves this by selecting a certain, specific range of colors, and shifting the pixels whenever they are that source color in the unit image. In our system, this can be done with any set of colors that you choose, on a per-unit basis. However, we've got a shortcut for one set of colors, magenta. We picked a color that because it would stick out like a sore thumb; it's not an 'earthtone', and isn't commonly seen in nature.

It's not just any magenta; it has to be from the following, very specific set:
http://www.wesnoth.org/wiki-images/tutorial/team-color/colorswatch.png

Also, it won't show up on a unit unless they have this line in their unitname.cfg file:
{MAGENTA_IS_THE_TEAM_COLOR}

You'll need to have some costume element on the unit which can be designated as the team-colored piece of their outfit; It's best to design units around having this. The easiest way to designate this, is to define a new layer in a capable program (photoshop, gimp, etc), overlaid on the rest of the image, in which you draw with our special values of magenta.

'''Time-Saving Tips:'''

If units are drawn with a small color set, as used in traditional sprite art, you can use a properly-set paint-bucket tool to replace all instances of a given color. You'll want to set it to be non-contiguous, non-antialiased and to have a tolerance of 0 (presumably, you also want it to fill based on "all layers" - these settings are based on Photoshop, and the Gimp is likely similar).

If you're working on a sprite which isn't strictly pixel art (e.g. which doesn't have a tiny set of unique RGB values), you're not out of luck at all. Simply take the same paint-bucket tool with the same settings, and crank the tolerance up to about 20-30. The paint-bucket will then affect all of those similar, subtle gradations in shade which were achieved with the paintbrush tool, replacing them all with a single color. Use this with progressively lighter shades, and you'll fill in 90% of the target area, after which it is trivial to fill the holes left behind with a pencil tool.

Also, if you'd like a sane representation of what the final colors will look like, you can shift this separate team-color layer in your graphics application by using a '''temporary''' hue/saturation filter on that layer (I use +40 to the hue on the magenta colors to give a red hue similar but '''not''' identical to the one which the game uses).

It is often easiest to simply sample the colors from a unit to which already has team colors on it.

'''Screenshots:'''

This is a screenshot of what a unit would look like if it were drawn directly, without the special pixels:

http://www.wesnoth.org/wiki-images/tutorial/team-color/tcpatch_off.png

This is a screenshot of the team-colored pixels in a separate photoshop layer:

http://www.wesnoth.org/wiki-images/tutorial/team-color/tcpatch_alone.png

And this is what the combined image looks like, which will get mixed-down into a single PNG file:

http://www.wesnoth.org/wiki-images/tutorial/team-color/tcpatch_on.png

'''WML How To: '''

We've defined a WML macro to specify a set of magenta colors, as seen in the previous palette. To use this, you simply sample the color with your graphics program's eyedropper tool, and then draw with it. The macro is used just like the flag_rgb business - you simply insert the following in your unit .cfg file (for reference, the macro itself is defined in utils.cfg):
{MAGENTA_IS_THE_TEAM_COLOR}

Note that these shift ONLY the precise RGB values given - do not confuse color with hue, because every specific shade - every specific instance with a different luminosity and saturation value - must be specified separately.

The game will shift the color set to one of the team colors; in doing so it will completely overrun the saturation of the original color. It will change the hue to that of the team, and shift the luminosity as well. The coloration you give is set in terms of relative luminosity - the entire patch may be bright or dark depending on which team the unit is on. Also note that the first color specified is special, because it is treated as the median value, and will be assigned the precise luminosity value of the team color. Anything brighter than it will be brighter than the team color, anything darker will be darker.

''' design errata for nerds/game-designers: '''
E.g. "Why we did it the way we did." There are a number of other ways to do this, but this was what we settled on. A different option might have been to use special grayscale image maps to indicate what to change, they would have basically doubled the number of images used by the game. Alternately, we could have done some bizarre wizardry with graphics files, and included something like an alpha-channel to indicate which pixels to change; we decided against this because that would break the huge advantage of using a very standard format like PNG, which is that everyone can easily grab a program to edit it. Design nitpickers will notice one minor disadvantage in how we did it. The colors which get shifted away are inaccessible for direct use; but because they're such a small set of colors, and because they were chosen to be "unusual" colors (rather than common ones like earthtones), it's unlikely that not being able to use these specific RGB values would ever be a problem.

== See Also ==
* [[Create]]
* [[Art Tutorials]]
* [[TeamColoring]]

[[Category: Art Tutorials]]

Team Color Shifting

2009-09-17T04:24:29Z

Solsword: /* See Also */

by Richard Kettering (Jetryl)

Wesnoth's sprites are only drawn in one color, but in an actual game, all of our unit's clothing will change color to the color of whatever team they're on. We call this "team color" shifting. Any team color shifting system needs a way of indicating which areas of the graphic are to be changed in color. Ours solves this by selecting a certain, specific range of colors, and shifting the pixels whenever they are that source color in the unit image. In our system, this can be done with any set of colors that you choose, on a per-unit basis. However, we've got a shortcut for one set of colors, magenta. We picked a color that because it would stick out like a sore thumb; it's not an 'earthtone', and isn't commonly seen in nature.

It's not just any magenta; it has to be from the following, very specific set:
http://www.wesnoth.org/wiki-images/tutorial/team-color/colorswatch.png

Also, it won't show up on a unit unless they have this line in their unitname.cfg file:
{MAGENTA_IS_THE_TEAM_COLOR}

You'll need to have some costume element on the unit which can be designated as the team-colored piece of their outfit; It's best to design units around having this. The easiest way to designate this, is to define a new layer in a capable program (photoshop, gimp, etc), overlaid on the rest of the image, in which you draw with our special values of magenta.

'''Time-Saving Tips:'''

If units are drawn with a small color set, as used in traditional sprite art, you can use a properly-set paint-bucket tool to replace all instances of a given color. You'll want to set it to be non-contiguous, non-antialiased and to have a tolerance of 0 (presumably, you also want it to fill based on "all layers" - these settings are based on Photoshop, and the Gimp is likely similar).

If you're working on a sprite which isn't strictly pixel art (e.g. which doesn't have a tiny set of unique RGB values), you're not out of luck at all. Simply take the same paint-bucket tool with the same settings, and crank the tolerance up to about 20-30. The paint-bucket will then affect all of those similar, subtle gradations in shade which were achieved with the paintbrush tool, replacing them all with a single color. Use this with progressively lighter shades, and you'll fill in 90% of the target area, after which it is trivial to fill the holes left behind with a pencil tool.

Also, if you'd like a sane representation of what the final colors will look like, you can shift this separate team-color layer in your graphics application by using a '''temporary''' hue/saturation filter on that layer (I use +40 to the hue on the magenta colors to give a red hue similar but '''not''' identical to the one which the game uses).

It is often easiest to simply sample the colors from a unit to which already has team colors on it.

'''Screenshots:'''

This is a screenshot of what a unit would look like if it were drawn directly, without the special pixels:

http://www.wesnoth.org/wiki-images/tutorial/team-color/tcpatch_off.png

This is a screenshot of the team-colored pixels in a separate photoshop layer:

http://www.wesnoth.org/wiki-images/tutorial/team-color/tcpatch_alone.png

And this is what the combined image looks like, which will get mixed-down into a single PNG file:

http://www.wesnoth.org/wiki-images/tutorial/team-color/tcpatch_on.png

'''WML How To: '''

We've defined a WML macro to specify a set of magenta colors, as seen in the previous palette. To use this, you simply sample the color with your graphics program's eyedropper tool, and then draw with it. The macro is used just like the flag_rgb business - you simply insert the following in your unit .cfg file (for reference, the macro itself is defined in utils.cfg):
{MAGENTA_IS_THE_TEAM_COLOR}

Note that these shift ONLY the precise RGB values given - do not confuse color with hue, because every specific shade - every specific instance with a different luminosity and saturation value - must be specified separately.

The game will shift the color set to one of the team colors; in doing so it will completely overrun the saturation of the original color. It will change the hue to that of the team, and shift the luminosity as well. The coloration you give is set in terms of relative luminosity - the entire patch may be bright or dark depending on which team the unit is on. Also note that the first color specified is special, because it is treated as the median value, and will be assigned the precise luminosity value of the team color. Anything brighter than it will be brighter than the team color, anything darker will be darker.

''' design errata for nerds/game-designers: '''
E.g. "Why we did it the way we did." There are a number of other ways to do this, but this was what we settled on. A different option might have been to use special grayscale image maps to indicate what to change, they would have basically doubled the number of images used by the game. Alternately, we could have done some bizarre wizardry with graphics files, and included something like an alpha-channel to indicate which pixels to change; we decided against this because that would break the huge advantage of using a very standard format like PNG, which is that everyone can easily grab a program to edit it. Design nitpickers will notice one minor disadvantage in how we did it. The colors which get shifted away are inaccessible for direct use; but because they're such a small set of colors, and because they were chosen to be "unusual" colors (rather than common ones like earthtones), it's unlikely that not being able to use these specific RGB values would ever be a problem.

== See Also ==
* [[Create]]
* [[Art Tutorials]]
* [[TeamColoring]]

[[Category: Art Tutorials]]

TeamColoring

2009-09-17T04:23:58Z

Solsword: Instructions for using the built-in teamcoloring script.

If you're an artist, or if you want to use a Wesnoth sprite as your avatar in the forums, or for whatever reason you want to produce a team-colored copy of a Wesnoth sprite without actually running Wesnoth (and probably having to cut the sprite out of a background), there are two easy tools to accomplish this:

* TeamColorizer - This is a Python script included with Wesnoth that does an '''inaccurate''' teamcoloring: it uses a slightly different algorithm than the one used in-game. However, it allows you to use any color that you want, even colors that aren't normal team colors. You just need to do a bit of trickery.
* wesnoth-tc - This is a C++ program, written by Shadowmaster from the forums. It even has a GUI written for Macs. It uses the same algorithm as the Wesnoth engine.

== TeamColorizer ==

The TeamColorizer included with Wesnoth is at data/core/tools/unit_tree/TeamColorizer. Internally, it's used to produce the red sprites found on http://units.wesnoth.org. However, you can use it to color any image red. It's a command-line program, so first you'll need to open up a command line (either Start->Run and then type "cmd" in Windows, or use Terminal on a Mac; if you run something else you should know how to do this already). Next, you need to find two things: Python, and the TeamColorizer. You don't have to do this in the shell. Python is likely to be at
C:\Python<#>\Python.exe
or something like that, where <#> is the version, and will be something like '25' for 2.5, '26' for 2.6, etc. You actually don't need this step on a Mac. Next, you have to find the TeamColorizer, and this one you have to do in the shell, by typing
cd <directory>
and then either 'ls' or 'dir' depending on whether you're on Windows ('dir') or on something else. The directory you want is data/core/tools/unit_tree relative to the [http://www.wesnoth.org/wiki/EditingWesnoth#Where_is_my_game_data_directory.3F Wesnoth data directory]. Once you're there, type
python TeamColorizer -h
and press enter. The program should print a help message, giving you instructions, follow these, and you can get teamcolored images. If the instructions are difficult to follow: You'll wind up using a command like
python TeamColorizer --color=red my_image.png output_image.png
If you don't want to worry about where the images are, you can just copy the image you want to use into the same directory as the TeamColorizer for simplicity. Note that the output image will also appear in the same directory as the TeamColorizer. If you want, you can copy the TeamColorizer somewhere else for convenience.

Note: these are pretty bad and technical instructions... especially the Windows side. Please revise them if you've got a better way of explaining things. Maybe you could just create a shortcut with the arguments in it in Windows and that would be simpler?

Note 2: On a Mac or other Unix machine, you should be able to use
./TeamColorizer ...
in place of
python TeamColorizer ...
and for those happy to deal with paths a lot, there's no reason not to do
./path/to/teamcolorizer/TeamColorizer ...

== wesnoth-tc ==

If you want to use wesnoth-tc, read up on it on its [http://www.wesnoth.org/forum/viewtopic.php?f=9&t=22859 forum thread]. The thread has information on usage and a link to download the source, as well as information on the Mac GUI. Feel free to post more instructions here if you use it and feel like sharing any insights you gain.

BuildingMaps

2009-09-13T19:11:38Z

Solsword: Made the intro text into a short summary and made the tone less familiar

A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data"). There are two ways to use this rectangle in a file: as a stand-alone map, or within a scenario. The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it.

== Wesnoth map data format ==

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

* A map starts with a header with the following keys
** usage, this is map for a 'map' and 'mask' for an overlay mask
** border_size, the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== Creating a map ==

This is not the Matrix. You do not need to look at encoded maps. Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, although if you run into trouble, go ahead and ask for help on the [http://www.wesnoth.org/forum forum].

Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

== So now what? ==

You've created an awesome map with the [[WesnothMapEditor]] and you're ready to test it out. But how can you do this? It's actually quite simple.

==== Stand-alone maps ====

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into your custom maps folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear at the top of the map choices dialog.

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

==== The map_data key ====

There's another way to use map data. The data for the map can be placed directly inside of a ''map_data'' tag in a '''[scenario]''' tag (see [[ScenarioWML]]). An example of map data encoded directly in a file might look like this:
map_data="border_size=1
usage=map

Gg, Ke, Gg, Gg
Gg, Ce, Ce, Gg"

Keep in mind that it's almost always more useful to have a separate map file that you reference in a scenario than putting the data directly into the scenario (not least because the editor works on such separate map files). To use a saved map file in a campaign, you have to include the map data like this:

map_data="{@editor/''map_filename''}"

Note that @editor here means that the map should be found in the '''''userdata''/editor/maps/''' directory. You need to specify something else if your map is in another location (for example, in a campaign, the maps should go into their own folder). The [[ScenarioWML]], [[BuildingCampaignsTheCampaignFile]] and [[PreprocessorRef]] pages all contain more detailed information about how this works.

== Discussion: Scenario File vs Standalone ==

Campaign writers can't write campaigns without scenarios, so campaigns will always use the ''map_data'' key, either with the raw data in quotes or a preprocessor symbol {} pointing to the standalone file.

Multiplayer mapmakers, however, '''have a choice'''. If you want to place an object or unit on the map, you must create a scenario file starting with the '''[multiplayer]''' tag and containing the ''map_data'' key therein. You lose the simplicity of the standalone map file, but you gain tremendous power. Not only can you add units and objects, you can set allies, experience modifiers, add a map description, and add custom events (among other things). The question, "How do I place an object on the map with the map editor" is such a common question that I am sorry this information is buried so deeply here. But, now that you know you can seek out an example of a multiplayer map scenario file to use as an example. The game comes with many maps of each type. Check out [[BuildingMultiplayer]] for more information.

== See Also ==

* [[Create]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[BuildingScenariosShroudData]]
* [[TerrainCodesWML]]

{{Create}}

BuildingMaps

2009-09-13T19:07:34Z

Solsword: /* So now what? */

This is all you need to know about maps:

# A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data")
# There are two ways to save this rectangle in a file

Seriously now, here are the details.

== Wesnoth map data format ==

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

* A map starts with a header with the following keys
** usage, this is map for a 'map' and 'mask' for an overlay mask
** border_size, the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== Creating a map ==

This is not the Matrix. You do not need to look at encoded maps. Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, although if you run into trouble, go ahead and ask for help on the [http://www.wesnoth.org/forum forum].

Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

== So now what? ==

You've created an awesome map with the [[WesnothMapEditor]] and you're ready to test it out. But how can you do this? It's actually quite simple.

==== Stand-alone maps ====

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into your custom maps folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear at the top of the map choices dialog.

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

==== The map_data key ====

There's another way to use map data. The data for the map can be placed directly inside of a ''map_data'' tag in a '''[scenario]''' tag (see [[ScenarioWML]]). An example of map data encoded directly in a file might look like this:
map_data="border_size=1
usage=map

Gg, Ke, Gg, Gg
Gg, Ce, Ce, Gg"

Keep in mind that it's almost always more useful to have a separate map file that you reference in a scenario than putting the data directly into the scenario (not least because the editor works on such separate map files). To use a saved map file in a campaign, you have to include the map data like this:

map_data="{@editor/''map_filename''}"

Note that @editor here means that the map should be found in the '''''userdata''/editor/maps/''' directory. You need to specify something else if your map is in another location (for example, in a campaign, the maps should go into their own folder). The [[ScenarioWML]], [[BuildingCampaignsTheCampaignFile]] and [[PreprocessorRef]] pages all contain more detailed information about how this works.

== Discussion: Scenario File vs Standalone ==

Campaign writers can't write campaigns without scenarios, so campaigns will always use the ''map_data'' key, either with the raw data in quotes or a preprocessor symbol {} pointing to the standalone file.

Multiplayer mapmakers, however, '''have a choice'''. If you want to place an object or unit on the map, you must create a scenario file starting with the '''[multiplayer]''' tag and containing the ''map_data'' key therein. You lose the simplicity of the standalone map file, but you gain tremendous power. Not only can you add units and objects, you can set allies, experience modifiers, add a map description, and add custom events (among other things). The question, "How do I place an object on the map with the map editor" is such a common question that I am sorry this information is buried so deeply here. But, now that you know you can seek out an example of a multiplayer map scenario file to use as an example. The game comes with many maps of each type. Check out [[BuildingMultiplayer]] for more information.

== See Also ==

* [[Create]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[BuildingScenariosShroudData]]
* [[TerrainCodesWML]]

{{Create}}

BuildingMaps

2009-09-13T05:02:24Z

Solsword: Made more accessible and removed some old information

This is all you need to know about maps:

# A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data")
# There are two ways to save this rectangle in a file

Seriously now, here are the details.

== Wesnoth map data format ==

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

* A map starts with a header with the following keys
** usage, this is map for a 'map' and 'mask' for an overlay mask
** border_size, the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== Creating a map ==

This is not the Matrix. You do not need to look at encoded maps. Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, although if you run into trouble, go ahead and ask for help on the [http://www.wesnoth.org/forum forum].

Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

== So now what? ==

You've created an awesome map with the [[WesnothMapEditor]] and you're ready to test it out. But how can you do this? It's actually quite simple.

==== Stand-alone maps ====

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into your custom maps folder (which should be the default place to save things in the editor, so really all you should need to do is save it). Then, when you launch the game and host a multiplayer game, the map should appear at the top of the map choices dialog. Simple, eh?

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

==== The map_data key ====

There's another way to use map data. The data for the map can be placed directly inside of a ''map_data'' tag in a '''[scenario]''' tag (see [[ScenarioWML]]). An example of map data encoded directly in a file might look like this:
map_data="border_size=1
usage=map

Gg, Ke, Gg, Gg
Gg, Ce, Ce, Gg"

Keep in mind that it's almost always more useful to have a separate map file that you reference in a scenario than putting the data directly into the scenario (not least because the editor works on such separate map files). If you have a saved map file that you want to use in your campaign, you'll have to include the map data like this:

map_data="{@editor/''map_filename''}"

Note that @editor here means that the map should be found in the '''''userdata''/editor/maps/''' directory. You'll need to specify something else if your map is in another location (for example, in a campaign, the maps should go into their own folder). The [[ScenarioWML]], [[BuildingCampaignsTheCampaignFile]] and [[PreprocessorRef]] pages all contain more detailed information about hos this works and how it should be done.

== Discussion: Scenario File vs Standalone ==

Campaign writers can't write campaigns without scenarios, so campaigns will always use the ''map_data'' key, either with the raw data in quotes or a preprocessor symbol {} pointing to the standalone file.

Multiplayer mapmakers, however, '''have a choice'''. If you want to place an object or unit on the map, you must create a scenario file starting with the '''[multiplayer]''' tag and containing the ''map_data'' key therein. You lose the simplicity of the standalone map file, but you gain tremendous power. Not only can you add units and objects, you can set allies, experience modifiers, add a map description, and add custom events (among other things). The question, "How do I place an object on the map with the map editor" is such a common question that I am sorry this information is buried so deeply here. But, now that you know you can seek out an example of a multiplayer map scenario file to use as an example. The game comes with many maps of each type. Check out [[BuildingMultiplayer]] for more information.

== See Also ==

* [[Create]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[BuildingScenariosShroudData]]
* [[TerrainCodesWML]]

{{Create}}

BuildingMaps

2009-09-13T04:57:11Z

Solsword: Clarified how to use map data

This is all you need to know about maps:

# A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data")
# There are two ways to save this rectangle in a file

Seriously now, here are the details.

== Wesnoth map data format ==

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

* A map starts with a header with the following keys
** usage, this is map for a 'map' and 'mask' for an overlay mask
** border_size, the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== Creating a map ==

This is not the Matrix. You do not need to look at encoded maps. The source code and most binary distributions come with the official graphical map editor. When compiling from source, remember to use the ''--enable-editor'' option when configuring, otherwise the map editor won't be compiled. Using the map editor tends to be straightforward, judging from the feedback received from novice mapmakers. However, if you do encounter problems locating or using the editor, please ask for help on the [http://www.wesnoth.org/forum forum].

After the map is created, you may find it easier to make small tweaks by editing the textual map data directly.

Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]

== So now what? ==

You've created an awesome map with the [[WesnothMapEditor]] and you're ready to test it out. But how can you do this? It's actually quite simple.

==== Stand-alone maps ====

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into your custom maps folder (which should be the default place to save things in the editor, so really all you should need to do is save it). Then, when you launch the game and host a multiplayer game, the map should appear at the top of the map choices dialog. Simple, eh?

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

==== The map_data key ====

There's another way to use map data. The data for the map can be placed directly inside of a ''map_data'' tag in a '''[scenario]''' tag (see [[ScenarioWML]]). An example of map data encoded directly in a file might look like this:
map_data="border_size=1
usage=map

Gg, Ke, Gg, Gg
Gg, Ce, Ce, Gg"

Keep in mind that it's almost always more useful to have a separate map file that you reference in a scenario than putting the data directly into the scenario (not least because the editor works on such separate map files). If you have a saved map file that you want to use in your campaign, you'll have to include the map data like this:

map_data="{@editor/''map_filename''}"

Note that @editor here means that the map should be found in the '''''userdata''/editor/maps/''' directory. You'll need to specify something else if your map is in another location (for example, in a campaign, the maps should go into their own folder). The [[ScenarioWML]], [[BuildingCampaignsTheCampaignFile]] and [[PreprocessorRef]] pages all contain more detailed information about hos this works and how it should be done.

== Discussion: Scenario File vs Standalone ==

Campaign writers can't write campaigns without scenarios, so campaigns will always use the ''map_data'' key, either with the raw data in quotes or a preprocessor symbol {} pointing to the standalone file.

Multiplayer mapmakers, however, '''have a choice'''. If you want to place an object or unit on the map, you must create a scenario file starting with the '''[multiplayer]''' tag and containing the ''map_data'' key therein. You lose the simplicity of the standalone map file, but you gain tremendous power. Not only can you add units and objects, you can set allies, experience modifiers, add a map description, and add custom events (among other things). The question, "How do I place an object on the map with the map editor" is such a common question that I am sorry this information is buried so deeply here. But, now that you know you can seek out an example of a multiplayer map scenario file to use as an example. The game comes with many maps of each type. Check out [[BuildingMultiplayer]] for more information.

== See Also ==

* [[Create]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[BuildingScenariosShroudData]]
* [[TerrainCodesWML]]

{{Create}}

StandardLocationFilter

2009-02-05T05:35:30Z

Solsword: Added an in-depth clarification of how radius= works.

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering on locations. 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).
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''': a [[StandardUnitFilter]]; if present a unit must also be there
* '''owner_side''': the side of the owner, if this location is an owned village.
* '''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 ([http://www.wesnoth.org/wiki/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"

==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.

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.
[[Category: WML Reference]]

EventWML

2009-02-04T12:25:31Z

Solsword: Fixed extra ' after moveto

{{WML Tags}}
== The [event] tag ==

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of 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 definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

Keys and tags that describe when the event should trigger:
* '''name''': this is not like a normal 'name' key. It is a basic description of when the event will trigger. {{DevFeature}} '''name''' can accept a list of commas separated descriptions for which the event must be triggered. Example: '''name= attacker_misses, defender_misses'''. Note that unless you use ''first_time_only=no'', the event will fire only once, not once for each listed type.
* '''prestart''': the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start'''.
* '''start''': this event triggers after the map is shown but before the scenario begins
* '''new turn''': this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, 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.
* '''side turn''': this event 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.
* '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* '''turn X''': (for X some number) this event triggers at the start of turn ''X''. ''X'' cannot be 1.
* '''time over''': this event triggers on turn ''turns''. (''turns'' is specified in [scenario])
* '''enemies defeated''': this event triggers when all units with '''canrecruit=yes''' (i.e. all leaders) not allied with side 1 are killed.
* '''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]])
* '''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]])
* '''ai turn''': is 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.

Filters 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]]

* '''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.
* '''sighted''': this event triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)
* '''attack''': this event triggers when the primary unit attacks the secondary unit.
* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the attacker.
* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.
* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the defender.
* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.
* '''attack_end''': is similar to '''attack''', but is instead triggered after the fight, not before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.
* '''stone''': this event triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).
* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.
* '''die''': this event triggers when the primary unit is killed by the secondary unit.
* '''capture''': this event 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.
* '''recruit''': this event triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.
* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.
* '''advance''': this event triggers just before the primary unit is going to advance to another unit.
* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.
* '''select''': triggers when the primary unit is selected. ''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.''
* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.
* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.
* {{DevFeature}} other events with a custom name may be invoked from [fire_event]
* {{DevFeature}} '''consider attack''': triggers before the attack dialog is displayed.
* {{DevFeature}} '''unconsider attack''': triggers when canceling out of the attack dialog.

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 other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.

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]

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. Default is '''yes'''.
* '''[filter]''': the event will only trigger if the primary unit matches this filter.
** [[StandardUnitFilter]]: selection criteria
* '''[filter_second]''': is like [filter], but for the secondary unit.
** [[StandardUnitFilter]]: selection criteria
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack] and [filter_second_attack])
** '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')
** {{DevFeature}} '''range''': the ranged of the weapon used.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all 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

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 1 special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is created when the nested event is encountered (when executing the contents of the event). For example, you could create a portal that opens on turn 10. The outer event executes on turn 10, creating the nested moveto event, which executes when a player steps on a certain spot. An equivalent way of doing this would be to 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.

Example:

[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]

Variable substitution for a nested event can happen either when the event is spawned, or when it is triggered. This is controlled with the key ''delayed_variable_substitution'' (default yes). Consider the following two examples:

# This makes the message display the turn on which the moveto happens,
# because the variable substitution for the moveto event will be done
# when the event triggers.

[event]
name=turn 2

[event]
name=moveto
delayed_variable_substitution=yes

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

# This makes the message on moveto always display as "Turn 2", because
# the variable substitution is done when the moveto event is spawned,
# not when it eventually triggers.

[event]
name=turn 2

[event]
name=moveto
delayed_variable_substitution=no

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Another way to mark an individual variable to be substituted later (when the event is triggered) is to write it as "$|var" instead of the normal "$var". By combining this with delayed_variable_substitution=no you can have some variables in the nested event be substituted immediately when the event is spawned and some variables substituted when the event triggers.

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

InterfaceActionsWML

2009-02-03T00:59:48Z

Solsword: Clarified language of [hide_unit] tag: you can have multiple hidden units, but you have to use multiple [hide_unit] tags to achieve this.

{{WML Tags}}
== Interface actions ==

Interface actions are actions that do not have an effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: the unit whose profile and name are displayed. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit description or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': zero or more '''[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** ''message'' (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_chars''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* note that '''[option]''' and '''[text_input]''' can only be used in moveto events in MP, otherwise they cause OOS

Text formatting options for '''[message]'''. These can also be used in unit names (user_description), objectives, and such.
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
It can also be used to overwrite the starting objectives mid-scenario.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code. '''{SET_OBJECTIVES}''', '''{VICTORY_CONDITION}''' and '''{DEFEAT_CONDITION}'''. There are all used together. For more information look [http://www.wesnoth.org/misc/macro-reference.xhtml here]

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.

== Other interface tags ==

The following tags are also action tags:
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
** '''x''', '''y''': the location to place the item.
** '''image''': the image (in ''images/'' as .png) to place on the hex.
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex.
** '''team_name''' {{DevFeature}}: name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
** '''visible_in_fog''' {{DevFeature}}: whether the item should be visible through fog or not. Default yes.
* '''[removeitem]''': removes any graphical items on a given hex
** '''x''', '''y''': the hex to remove items off
** '''image''' {{DevFeature}} if specified, only removes the given image item
* '''[print]''': displays a message across the screen. The message will disappear after a certain time.
** '''text''': (translatable) the text to display.
** '''size''': (default=12) the pointsize of the font to use
** '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
** '''type''': the type of the unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''[hide_unit]''': makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
* '''[unhide_unit]''': stops the currently hidden unit from being hidden.
* '''[scroll]''': Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
** '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''[scroll_to]''': Scroll to a given hex
** '''x''', '''y''': the hex to scroll to
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[scroll_to_unit]''' Scroll to a given unit
** [[StandardUnitFilter]]
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[sound]''': Plays a sound
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
** '''repeat''': repeats the sound for a specified additional number of times (default=0)
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
** '''id''': a unique identification key of the sound source
** '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
** '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
** '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
** '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged/shrouded
** '''x,y''': a [[StandardLocationFilter]] for the locations associated with the sound source
** {{DevFeature}}
*** '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
*** '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
*** '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)
* '''[remove_sound_source]''': Removes a previously defined sound source.
** '''id''': the identification key of the sound source to remove
* '''[music]''': Switches to playing different music
** '''name''': the filename of the music to play (in ''music/'' as .ogg)
** see [[MusicListWML]] for the correct syntax
* '''[colour_adjust]''': tints the colour of the screen.
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each colour
* '''[delay]''': pauses the game
** '''time''': the time to pause in milliseconds
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around
** '''x''', '''y''': the location of the unit to overlay on
** '''image''': the image to place on the unit
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit
** '''x''', '''y''': the location of the unit to remove an overlay from
** '''image''': the image to remove from the unit
* '''[animate_unit]''': uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)
** '''flag''': the key to find the good custom animation in the unit description see the '''[extra_anim]''' description in [[AnimationWML]] Standar anims can be triggered with the following keywors ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
** '''[filter]''': a [[StandardUnitFilter]] see [[FilterWML]] by default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate
** '''[primary_attack]''': if this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation
** '''[secondary_attack]''': same for the second attack
** '''hits''': the hit type to filter unit on
** '''text''': a text to hover during the animation
** '''red''': red value for the text color
** '''green''': green value for the text color
** '''blue''': blue value for the text color
** '''with_bars''': whether to display the status bars or not.
** '''[animate]''': a sub block with the same syntax as the '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously
** '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated
* '''[label]''' places a label on the map.
** '''x''', '''y''': the location of the label
** '''text''': what the label should say
** '''team_name''': if specified, the label will only be visible to the given team.
** '''visible_in_fog''' {{DevFeature}}: whether the label should be visible through fog or not. Default yes.
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
** '''message''': the message to show.
* '''[debug_message]''': outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. Information is actually output depending on the minimum severity (''log level'') for the '''notifs''' log domain. {{DevFeature}} This tag is deprecated since 1.5.8, and the '''notifs''' log domain has been removed.
** '''message''': the message to show
** '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.
* '''[wml_message]''' {{DevFeature}}: in 1.5.7+svn/1.5.8 and later, this replaces [debug_message] and works identically, except that the log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{TREMOR}''' Creates a tremor like screenshake
** {{DevFeature}} This macro has been deprecated in favor of '''{QUAKE <soundfile>}'''. Thus, it is equivalent to '''{QUAKE (rumble.ogg)}''', although '''cave-in.ogg''' has been added as a much better alternative for most situations.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2009-01-30T00:51:13Z

Solsword: Added dev version exception to the remove_shroud note

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''carryover_report''' {{DevFeature}}: whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
** '''save''' {{DevFeature}}: whether a start-of-scenario save should be created for the next scenario, the default is save=yes.
** '''linger_mode''' {{DevFeature}}: whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''' {{DevFeature}}: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''' {{DevFeature}}: if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
** '''music''' {{DevFeature}}: (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
** '''end_text''' {{DevFeature}}: Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
** '''end_text_duration''' {{DevFeature}}: Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].
** {{Short Note:Predefined Macro|GENERIC_UNIT}}
** {{DevFeature}} '''to_variable''': spawn directly into a variable instead of on the map.
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
** '''clear_shroud''': should shroud be cleared on arrival
** '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
** {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.
** {{DevFeature}} '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
** {{DevFeature}} '''x''' ,'''y''': override unit location
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
** {{DevFeature}} '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. {{DevFeature}} 'last breath' events are also fired.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
** Note: '''[remove_shroud]''' doesnt't accept all of the standard location filters. In particular '''[filter]''' to remove shroud around units doesn't work, and radius may not either. To remove shroud around a group of units, you can temporarily switch the sides of the units using '''[store_unit]''', '''[set_variable]''', and then '''[unstore_unit]''' (do the '''[set_variable]''' and '''[unstore_unit]''' twice each, once to switch sides, and once to switch back). Just make sure you call '''[redraw]''' while the unit's side is switched to update shroud. Also make sure to use ''kill=no'' for the store and then ''find_vacant=no'' for the unstores.
** {{DevFeature}}: '''[remove_shroud]''' accepts a full standard location filter.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* '''[heal_unit]''' {{DevFeature}}: heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.
* '''[time_area]''' {{DevFeature}}: how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
** [[StandardLocationFilter]]: the locations to affect.
** [[TimeWML]]: the new schedule.
** '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. See below.
** '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
** {{DevFeature}}: in Wesnoth 1.5.9 and later, '''id''' may be a comma-separated list for removing time areas. It is not allowed, however, for inserting time areas; only the first id is taken into account in that case.

* '''[end_turn]''' {{DevFeature}}: end the current side's turn.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EventWML

2009-01-21T22:26:54Z

Solsword: /* The [event] tag */

{{WML Tags}}
== The [event] tag ==

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of 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 definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

Keys and tags that describe when the event should trigger:
* '''name''': this is not like a normal 'name' key. It is a basic description of when the event will trigger. {{DevFeature}} '''name''' can accept a list of commas separated descriptions for which the event must be triggered. Example: '''name= attacker_misses, defender_misses'''. Note that unless you use ''first_time_only=no'', the event will fire only once, not once for each listed type.
* '''prestart''': the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start'''.
* '''start''': this event triggers after the map is shown but before the scenario begins
* '''new turn''': this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, 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.
* '''side turn''': this event 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.
* '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* '''turn X''': (for X some number) this event triggers at the start of turn ''X''. ''X'' cannot be 1.
* '''time over''': this event triggers on turn ''turns''. (''turns'' is specified in [scenario])
* '''enemies defeated''': this event triggers when all units with '''canrecruit=yes''' (i.e. all leaders) not allied with side 1 are killed.
* '''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]])
* '''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]])
* '''ai turn''': is 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.

Filters 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]]

* '''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.
* '''sighted''': this event triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)
* '''attack''': this event triggers when the primary unit attacks the secondary_unit.
* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the attacker.
* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.
* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the defender.
* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.
* '''attack_end''': is similar to '''attack''', but is instead triggered after the fight, not before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.
* '''stone''': this event triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).
* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.
* '''die''': this event triggers when the primary unit is killed by the secondary unit.
* '''capture''': this event 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.
* '''recruit''': this event triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.
* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.
* '''advance''': this event triggers just before the primary unit is going to advance to another unit.
* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.
* '''select''': triggers when the primary unit is selected. ''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.''
* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.
* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.
* {{DevFeature}} other events with a custom name may be invoked from [fire_event]
* {{DevFeature}} '''consider attack''': triggers before the attack dialog is displayed.
* {{DevFeature}} '''unconsider attack''': triggers when canceling out of the attack dialog.

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 other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.

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]

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. Default is '''yes'''.
* '''[filter]''': the event will only trigger if the primary unit matches this filter.
** [[StandardUnitFilter]]: selection criteria
* '''[filter_second]''': is like [filter], but for the secondary unit.
** [[StandardUnitFilter]]: selection criteria
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack] and [filter_second_attack])
** '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')
** {{DevFeature}} '''range''': the ranged of the weapon used.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all 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

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 1 special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is created when the nested event is encountered (when executing the contents of the event). For example, you could create a portal that opens on turn 10. The outer event executes on turn 10, creating the nested moveto event, which executes when a player steps on a certain spot. An equivalent way of doing this would be to 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.

Example:

[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]

Variable substitution for a nested event can happen either when the event is spawned, or when it is triggered. This is controlled with the key ''delayed_variable_substitution'' (default yes). Consider the following two examples:

# This makes the message display the turn on which the moveto happens,
# because the variable substitution for the moveto event will be done
# when the event triggers.

[event]
name=turn 2

[event]
name=moveto
delayed_variable_substitution=yes

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

# This makes the message on moveto always display as "Turn 2", because
# the variable substitution is done when the moveto event is spawned,
# not when it eventually triggers.

[event]
name=turn 2

[event]
name=moveto
delayed_variable_substitution=no

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Another way to mark an individual variable to be substituted later (when the event is triggered) is to write it as "$|var" instead of the normal "$var". By combining this with delayed_variable_substitution=no you can have some variables in the nested event be substituted immediately when the event is spawned and some variables substituted when the event triggers.

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2009-01-16T07:26:20Z

Solsword: /* Direct actions */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''carryover_report''' {{DevFeature}}: whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
** '''save''' {{DevFeature}}: whether a start-of-scenario save should be created for the next scenario, the default is save=yes.
** '''linger_mode''' {{DevFeature}}: whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''' {{DevFeature}}: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''' {{DevFeature}}: if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
** '''music''' {{DevFeature}}: (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
** '''end_text''' {{DevFeature}}: Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
** '''end_text_duration''' {{DevFeature}}: Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].
** {{Short Note:Predefined Macro|GENERIC_UNIT}}
** {{DevFeature}} '''to_variable''': spawn directly into a variable instead of on the map.
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
** '''clear_shroud''': should shroud be cleared on arrival
** '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
** {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.
** {{DevFeature}} '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
** {{DevFeature}} '''x''' ,'''y''': override unit location
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
** {{DevFeature}} '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. {{DevFeature}} 'last breath' events are also fired.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
** Note: '''[remove_shroud]''' doesnt't accept all of the standard location filters. In particular '''[filter]''' to remove shroud around units doesn't work, and radius may not either. To remove shroud around a group of units, you can temporarily switch the sides of the units using '''[store_unit]''', '''[set_variable]''', and then '''[unstore_unit]''' (do the '''[set_variable]''' and '''[unstore_unit]''' twice each, once to switch sides, and once to switch back). Just make sure you call '''[redraw]''' while the unit's side is switched to update shroud. Also make sure to use ''kill=no'' for the store and then ''find_vacant=no'' for the unstores.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* '''[heal_unit]''' {{DevFeature}}: heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.
* '''[time_area]''' {{DevFeature}}: changes the schedule in the given locations.
** [[StandardLocationFilter]]: the locations to affect.
** [[TimeWML]]: the new schedule.
* '''[end_turn]''' {{DevFeature}}: end the current side's turn.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]