The Battle for Wesnoth Wiki - User contributions [en]

AiWML

2011-02-06T14:52:46Z

Kapoue II: /* the [ai] tag */

{{WML Tags}}
== For the info about new ai syntax, see==
[[Customizing_AI_in_Wesnoth_1.8]]

== AI phases ==

When the AI does its turn, it has several 'phases'.
In debug mode, these phases are shown in the upper-left corner.

=== Combat phase ===
It decides who is in range to attack, and whether it's worth attacking them

=== Healing phase ===
It locates injured units and sees if they can be moved to villages to heal

=== Village capturing phase ===
It locates units, and sees if they are in range of villages which they can capture

=== Retreating phase ===
It sees if any units are in grave danger/hopelessly outnumbered, and if they are, it retreats them

=== Movement/targeting phase ===
It decides upon 'targets', assigns those targets values, and moves units toward targets based on how easy it is to get to the targets, and how valuable the targets are.

== the [ai] tag ==

The [ai] tag is used inside a [side] tag, and it's contents define how the AI controlling that side acts. You can use multiple [ai] tags and have them apply during different turns or times of day, for example to set an undead side's caution higher and aggression lower during the day, or to boost the aggressiveness of a side when they receive reinforcements on a specific turn.

The following key/tags can be used in an '''[ai]''' tag:
* '''time_of_day''': (string) the time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in data/core/macros/schedules.cfg (See [[TimeWML]]).

* '''turns''': (string) during which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes(-) and commas(,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game comes with only ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or outside [ai] tags inside the [side] tag.

* '''aggression'''=0.5: (double) (value ranged from -infinity to 1.0 ) This key affects how an AI player will fight.
** In the following formulas of type ''X - Y = Z'', X is always 1 and Z is the value that aggression should be set to: aggression=Z.
** It determines how an AI considers the difference between its units and its opponents by taking the value ''1 - AI unit value in proportion to opponent unit value''. ('Unit value' here means that the AI weights its decision on the chance to kill a unit or be killed, using a combination of its own units.) So, to make an AI which considers its units worthless, i.e. only cares about how much damage attacks inflict, set aggression at ''1 - 0 = 1.0''. This is the highest meaningful value for aggression; although it is insane, it is used on many HttT levels. If an AI set on this value can inflict 1 damage and take 0, or inflict 2 damage and take 20 himself, he'll take the latter option. To make an AI which considers its units equally as valuable as its opponent's, i.e. only attacks if he feels he can inflict more damage than he receives, set aggression at ''1 - 1 = 0.0''.
** Although an AI which considers its opponent's units worthless is impossible under this scheme, an AI which, for example, considers its units twice as valuable as its opponent's can be represented by aggression ''1 - 2 = -1.0''.
** The default is ''1 - 1/2 = 0.5'', which means the AI is content with dealing only half the damage to his opponent of that which he himself takes.
** Or to put this whole thing into context, agression=1.0. means it will deal the maximum possible damage, agression=-10000000000000000.0. means it will never attack unless it will recieve no damage in exchange.

* '''attack_depth'''=5: (int) a number from 1 to 6. This is how many units will be thought about to attack a single unit. If the attack is completed, the AI on another round of thinking may still decide to attack that unit again with other units. Note that in battles, a unit usually can't be attacked from all six sides anyway, so any high attack_depth will be about the same. If attack_depth is low, the AI won't want to attack unwounded units very much, because it doesn't think it can kill them in the attack.

* '''[avoid]'''="": Makes the AI avoid a specific location or unit.
** ''x'', ''y'' standard coordinates- A location for the AI to avoid moving to. The AI will never move a unit to this location except for trying to move its leader to a keep. Either coordinate may be a range; ranges are interpreted in the usual way as areas, in this case to be avoided.
** [[StandardLocationFilter]] A set of locations for the AI to avoid moving to. {{DevFeature}}

* '''caution'''=0.25: (double) A number 0.0 or higher that affects how cautious the AI is in various ways. If it is higher, the AI will want to retreat more (especially to a better defensive terrain), it will dislike moving out of a defensive terrain to attack more, and, if grouping is enabled, it forms bigger groups to protect from enemies when going to a target.
** Considering a retreat will be skipped (during the retreat phase) if caution is set to 0 or lower. If caution is greater than 0, there will be an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat will take place, if caution * their_power > our_power There is also a terrain factor involved if the attacker is not on optimal terrain, but i'll skip this here for simplicity. So let's say the AI has its default caution of 0.25. Then the enemy forces have to be 4 times as strong at least before the unit will retreat. For a caution of 1, as soon as the enemy is considered to be stronger, the unit will retreat.
** Caution is also considered within the attack analysis to evaluate the rating of attacks. The mathematics for that is rather complicated, so let's just state that the caution value directly and proportionally influences a value for reducing the rating of an attack. A caution of 0 will have no influence (the rating won't be reduced at all).
** If grouping for the AI is enabled and the path to move the group along is considered to be dangerous, caution will have an influence, too. "Dangerous" mainly means there is a possibility for the best attacker of a primary target to be severely harmed, for example if he can be killed by enemies if not protected. In that case, the AI will compare our group with the enemy and based on the result move forward or not. "Group", from what i understood, means every unit of that side, including the leader. So it's not really a coherent group necessarily. Our side is rated which is mainly the sum of maximum damage * defense modifiers for every unit. Then this is compared to the enemy strength by determining a relation of both. A value of 1 means both sides have equal strength. Higher values indicate our side is stronger, lower values likewise. The formula for deciding if a group moves on is: our_strength / their_strength > 0.5 + caution So if caution is 0.5, our side needs to be at least as strong as the enemy. If it is 0, we go on, even if the enemy is up to twice as strong as we are. Setting caution to 1.5 means we need to be at least twice as strong to have the group keep moving.
** Caution also influences putting units onto villages. However, i haven't understood the code well enough yet to make backed up statements about it. Probably it's an estimation about how exposed a unit will be on that village, based on how many damage the enemy can do to it.
** Caution often won't influence the AI if the leader is involved, because for many actions it is hardcoded with a value of 2.0.

* '''grouping'''="offensive": (string) how the AI should try to group units
** '''offensive''': Makes the AI try to group units together before attacking.
** '''defensive''': Makes the AI group units together very conservatively, and only advances much beyond its castle if it has overwhelming force.
** '''no''': Makes the AI not use grouping behaviour. This is what it used to be like.

* '''leader_aggression'''="-4.0": exactly as aggression, but for units which can recruit.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location (as in the goal of The Elves Besieged).
** '''x''', '''y''': the location for the AI to move its leader to

* '''leader_value'''=3: (double) A number 0 or higher which determines how much the AI targets enemy leaders.

* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double) a number higher than 0.0. Tells AI to force the leader to move to a keep if it has enough gold to recruit the given number of units. If set to 0.0, moving to recruit is disabled.

* '''passive_leader'''=no: (bool) if 'yes' the AI leader will never move or attack, except to obey [leader_goal]s.

* '''passive_leader_shares_keep'''=no: (bool) {{DevFeature}} if 'yes', sets passive_leader=yes, but the AI leader will move 1 hex from the keep to share keep with allied players (if they can reach keep next turn), and will return to keep to recruit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: the way these parameters work, is to target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader' on the units.

* '''[protect_location]'''="": gives the AI a location to protect. Note that the AI will NOT station any units around the location, it will only send units to attack any enemy units that come within the guarding radius of the target.
** ''x'', ''y'' standard coordinates. These indicate the location the AI is protecting,
** '''radius''': indicates the radius around it to protect (0 indicates a single hex)
** '''value''': indicates the importance of protecting this location

* '''[protect_unit]'''="": gives the AI a set of units to protect. Note once again that the AI will not place units around the unit if there are no enemies nearby.
** [[StandardUnitFilter]]: The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': indicates the radius around it to protect (0 indicates a single hex)
** '''value''': indicates the importance of protecting this unit

* '''recruitment_ignore_bad_movement'''=no: (bool) if 'yes', the AI will not analyse the terrain to see if the unit is suitable for it.

* '''recruitment_ignore_bad_combat'''=no: (bool) if 'yes', the AI will not analyse the units the enemy has fielded to see if the unit is suitable for fighting them.

* '''recruitment_pattern'''="": (string) This key takes a comma separated list containing the usages defined in the recruitable units. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The AI considers all units with the specified usage(s) so make sure the units you want recruited are really covered by the pattern or use an empty pattern to have all available units considered regardless of usage. The usage is listed in the unit type config files. (See data/core/units/ for mainline units; See also [[UnitTypeWML]])
** For example, "recruitment_pattern=fighter,fighter,archer" means, the AI will recruit twice as many fighters as archers, and not recruit scouts (other than scouts for capturing villages, who are recruited independently), healers or mixed fighters.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village targets for scouts by this value.

* '''simple_targeting'''=no: (bool) When the AI decides what targets to move towards with which units, it considers all its units that can move, sequentially. For each unit, it decides what the best target for it to go towards is. If not 'yes', it will check if any other units would be better to go towards that target than the unit it is currently considering.

* '''support_villages'''=no: (bool) Trigger a code path that will try to protect those villages which are threatened by the enemy. This seems to cause the AI to just 'sit around' a lot, so it's only turned on if it's explicitly enabled.

* '''[target]'''="": Any number of [target] tags can be used to set a target for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get a target worth '2.0' as it is a target worth '1.0'.
** [[StandardUnitFilter]] Do not use a [filter] tag.
** value: A number greater than 0 (default=1) which determines how much the AI tries to kill all units which pass the filter.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to capture villages.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

== See Also ==
* [[AI_Module]]
* [[ReferenceWML]]
* [[Customizing_AI_in_Wesnoth_1.8]]

[[Category: WML Reference]]

AiWML

2011-02-06T14:47:50Z

Kapoue II: /* the [ai] tag */

{{WML Tags}}
== For the info about new ai syntax, see==
[[Customizing_AI_in_Wesnoth_1.8]]

== AI phases ==

When the AI does its turn, it has several 'phases'.
In debug mode, these phases are shown in the upper-left corner.

=== Combat phase ===
It decides who is in range to attack, and whether it's worth attacking them

=== Healing phase ===
It locates injured units and sees if they can be moved to villages to heal

=== Village capturing phase ===
It locates units, and sees if they are in range of villages which they can capture

=== Retreating phase ===
It sees if any units are in grave danger/hopelessly outnumbered, and if they are, it retreats them

=== Movement/targeting phase ===
It decides upon 'targets', assigns those targets values, and moves units toward targets based on how easy it is to get to the targets, and how valuable the targets are.

== the [ai] tag ==

The [ai] tag is used inside a [side] tag, and it's contents define how the AI controlling that side acts. You can use multiple [ai] tags and have them apply during different turns or times of day, for example to set an undead side's caution higher and aggression lower during the day, or to boost the aggressiveness of a side when they receive reinforcements on a specific turn.

The following key/tags can be used in an '''[ai]''' tag:
* '''time_of_day''': (string) the time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in data/core/macros/schedules.cfg (See [[TimeWML]]).

* '''turns''': (string) during which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes(-) and commas(,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game comes with only ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or outside [ai] tags inside the [side] tag.

* '''aggression'''=0.5: (double) (value ranged from -infinity to 1.0 ) This key affects how an AI player will fight.
** In the following formulas of type ''X - Y = Z'', X is always 1 and Z is the value that aggression should be set to: aggression=Z.
** It determines how an AI considers the difference between its units and its opponents by taking the value ''1 - AI unit value in proportion to opponent unit value''. ('Unit value' here means that the AI weights its decision on the chance to kill a unit or be killed, using a combination of its own units.) So, to make an AI which considers its units worthless, i.e. only cares about how much damage attacks inflict, set aggression at ''1 - 0 = 1.0''. This is the highest meaningful value for aggression; although it is insane, it is used on many HttT levels. If an AI set on this value can inflict 1 damage and take 0, or inflict 2 damage and take 20 himself, he'll take the latter option. To make an AI which considers its units equally as valuable as its opponent's, i.e. only attacks if he feels he can inflict more damage than he receives, set aggression at ''1 - 1 = 0.0''.
** Although an AI which considers its opponent's units worthless is impossible under this scheme, an AI which, for example, considers its units twice as valuable as its opponent's can be represented by aggression ''1 - 2 = -1.0''.
** The default is ''1 - 1/2 = 0.5'', which means the AI is content with dealing only half the damage to his opponent of that which he himself takes.
** Or to put this whole thing into context, agression=1 means it will deal the maximum possible damage, agression=-10000000000000000 means it will never attack unless it will recieve no damage in exchange.

* '''attack_depth'''=5: (int) a number from 1 to 6. This is how many units will be thought about to attack a single unit. If the attack is completed, the AI on another round of thinking may still decide to attack that unit again with other units. Note that in battles, a unit usually can't be attacked from all six sides anyway, so any high attack_depth will be about the same. If attack_depth is low, the AI won't want to attack unwounded units very much, because it doesn't think it can kill them in the attack.

* '''[avoid]'''="": Makes the AI avoid a specific location or unit.
** ''x'', ''y'' standard coordinates- A location for the AI to avoid moving to. The AI will never move a unit to this location except for trying to move its leader to a keep. Either coordinate may be a range; ranges are interpreted in the usual way as areas, in this case to be avoided.
** [[StandardLocationFilter]] A set of locations for the AI to avoid moving to. {{DevFeature}}

* '''caution'''=0.25: (double) A number 0.0 or higher that affects how cautious the AI is in various ways. If it is higher, the AI will want to retreat more (especially to a better defensive terrain), it will dislike moving out of a defensive terrain to attack more, and, if grouping is enabled, it forms bigger groups to protect from enemies when going to a target.
** Considering a retreat will be skipped (during the retreat phase) if caution is set to 0 or lower. If caution is greater than 0, there will be an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat will take place, if caution * their_power > our_power There is also a terrain factor involved if the attacker is not on optimal terrain, but i'll skip this here for simplicity. So let's say the AI has its default caution of 0.25. Then the enemy forces have to be 4 times as strong at least before the unit will retreat. For a caution of 1, as soon as the enemy is considered to be stronger, the unit will retreat.
** Caution is also considered within the attack analysis to evaluate the rating of attacks. The mathematics for that is rather complicated, so let's just state that the caution value directly and proportionally influences a value for reducing the rating of an attack. A caution of 0 will have no influence (the rating won't be reduced at all).
** If grouping for the AI is enabled and the path to move the group along is considered to be dangerous, caution will have an influence, too. "Dangerous" mainly means there is a possibility for the best attacker of a primary target to be severely harmed, for example if he can be killed by enemies if not protected. In that case, the AI will compare our group with the enemy and based on the result move forward or not. "Group", from what i understood, means every unit of that side, including the leader. So it's not really a coherent group necessarily. Our side is rated which is mainly the sum of maximum damage * defense modifiers for every unit. Then this is compared to the enemy strength by determining a relation of both. A value of 1 means both sides have equal strength. Higher values indicate our side is stronger, lower values likewise. The formula for deciding if a group moves on is: our_strength / their_strength > 0.5 + caution So if caution is 0.5, our side needs to be at least as strong as the enemy. If it is 0, we go on, even if the enemy is up to twice as strong as we are. Setting caution to 1.5 means we need to be at least twice as strong to have the group keep moving.
** Caution also influences putting units onto villages. However, i haven't understood the code well enough yet to make backed up statements about it. Probably it's an estimation about how exposed a unit will be on that village, based on how many damage the enemy can do to it.
** Caution often won't influence the AI if the leader is involved, because for many actions it is hardcoded with a value of 2.0.

* '''grouping'''="offensive": (string) how the AI should try to group units
** '''offensive''': Makes the AI try to group units together before attacking.
** '''defensive''': Makes the AI group units together very conservatively, and only advances much beyond its castle if it has overwhelming force.
** '''no''': Makes the AI not use grouping behaviour. This is what it used to be like.

* '''leader_aggression'''="-4.0": exactly as aggression, but for units which can recruit.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location (as in the goal of The Elves Besieged).
** '''x''', '''y''': the location for the AI to move its leader to

* '''leader_value'''=3: (double) A number 0 or higher which determines how much the AI targets enemy leaders.

* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double) a number higher than 0.0. Tells AI to force the leader to move to a keep if it has enough gold to recruit the given number of units. If set to 0.0, moving to recruit is disabled.

* '''passive_leader'''=no: (bool) if 'yes' the AI leader will never move or attack, except to obey [leader_goal]s.

* '''passive_leader_shares_keep'''=no: (bool) {{DevFeature}} if 'yes', sets passive_leader=yes, but the AI leader will move 1 hex from the keep to share keep with allied players (if they can reach keep next turn), and will return to keep to recruit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: the way these parameters work, is to target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader' on the units.

* '''[protect_location]'''="": gives the AI a location to protect. Note that the AI will NOT station any units around the location, it will only send units to attack any enemy units that come within the guarding radius of the target.
** ''x'', ''y'' standard coordinates. These indicate the location the AI is protecting,
** '''radius''': indicates the radius around it to protect (0 indicates a single hex)
** '''value''': indicates the importance of protecting this location

* '''[protect_unit]'''="": gives the AI a set of units to protect. Note once again that the AI will not place units around the unit if there are no enemies nearby.
** [[StandardUnitFilter]]: The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': indicates the radius around it to protect (0 indicates a single hex)
** '''value''': indicates the importance of protecting this unit

* '''recruitment_ignore_bad_movement'''=no: (bool) if 'yes', the AI will not analyse the terrain to see if the unit is suitable for it.

* '''recruitment_ignore_bad_combat'''=no: (bool) if 'yes', the AI will not analyse the units the enemy has fielded to see if the unit is suitable for fighting them.

* '''recruitment_pattern'''="": (string) This key takes a comma separated list containing the usages defined in the recruitable units. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The AI considers all units with the specified usage(s) so make sure the units you want recruited are really covered by the pattern or use an empty pattern to have all available units considered regardless of usage. The usage is listed in the unit type config files. (See data/core/units/ for mainline units; See also [[UnitTypeWML]])
** For example, "recruitment_pattern=fighter,fighter,archer" means, the AI will recruit twice as many fighters as archers, and not recruit scouts (other than scouts for capturing villages, who are recruited independently), healers or mixed fighters.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village targets for scouts by this value.

* '''simple_targeting'''=no: (bool) When the AI decides what targets to move towards with which units, it considers all its units that can move, sequentially. For each unit, it decides what the best target for it to go towards is. If not 'yes', it will check if any other units would be better to go towards that target than the unit it is currently considering.

* '''support_villages'''=no: (bool) Trigger a code path that will try to protect those villages which are threatened by the enemy. This seems to cause the AI to just 'sit around' a lot, so it's only turned on if it's explicitly enabled.

* '''[target]'''="": Any number of [target] tags can be used to set a target for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get a target worth '2.0' as it is a target worth '1.0'.
** [[StandardUnitFilter]] Do not use a [filter] tag.
** value: A number greater than 0 (default=1) which determines how much the AI tries to kill all units which pass the filter.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to capture villages.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

== See Also ==
* [[AI_Module]]
* [[ReferenceWML]]
* [[Customizing_AI_in_Wesnoth_1.8]]

[[Category: WML Reference]]

InternalActionsWML

2010-12-12T09:54:38Z

Kapoue II: /* [set_variables] */

{{WML Tags}}

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

== Variable Actions ==

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

=== [set_variable] ===

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

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

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

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

* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.

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

* '''add''': add the given amount to the variable. To subtract, add a negative number.

* '''sub''' {{DevFeature}}: subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. Floating point values are not rounded.

* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.

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

* '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. {{DevFeature1.9}} random is deprecated, use rand instead.

* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''

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

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

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

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

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

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''ceil''': Rounds upward to the nearest integer.
**'''floor''': Rounds down to the nearest integer.

=== [set_variables] ===

Manipulates a WML array or container

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

* '''mode''': one of the following values:
** ''replace'': will clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

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

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

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

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

=== Capturing Game Data ===

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

==== [store_gold] ====

Stores a side's gold into a variable.

* '''side''': (default=1) the side for which the gold should be stored

* '''variable''': (default='gold') the name of the variable to store the gold in

==== [store_locations] ====

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

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.

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

==== [store_reachable_locations] {{DevFeature1.9}} ====

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

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). If ''vision'', stores the vision range (movement range ignoring Zone of Control + 1 hex).
* '''moves''': possible values ''current'' (default), ''max''. Specifies whether to use the current or maximum movement points when calculating the range.
* '''viewing_side''': (optional) the side whose vision to use when calculating the reach. This only has meaning in the presence of fog, shroud, or units with the ambush ability. If left out, then fog, shroud and ambushers are ignored and the real reach of the units is stored.
* '''variable''': the name of the variable (array) into which to store the locations.

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

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

==== [store_side] ====

Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour' (becomes 'color' in 1.9+), 'controller', 'village_gold' and 'recruit'.

* '''side''': the side whose information should be stored

* '''variable''': the name of the variable to store the information in

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)

* '''side''': the side whose starting location is to be stored

* '''variable''': (default='location'): the name of the variable to store the location in

==== [store_time_of_day] ====

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

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

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

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample list of these tags and keys can be found [[InternalActionsWMLUnitTags|here]]. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file).

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

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].''

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.

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

* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.

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

==== [store_villages] ====

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

* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.

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

* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.

=== [clear_variable] ===

This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.

* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.

== Other Internal Actions ==

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

=== [fire_event] ===

Trigger a WML event

* '''name''': the name of event to trigger

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

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

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

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

=== [insert_tag] ===

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

*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.

*'''variable''': Name of the variable which will have its value inserted into the tag.

=== [role] ===

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

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

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

== Examples ==

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

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

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

=== [insert_tag] Example ===

[event]
name=moveto

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

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

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]

This is effectively identical to:

[event]
name=moveto

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

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

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

EventWML

2010-12-09T07:56:05Z

Kapoue II: /* [filter_condition] */

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

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

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

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

'''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
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.
: '''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

; prestart
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; new turn
: Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

; turn end {{DevFeature1.9}}
: Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

; turn ''X'' end {{DevFeature1.9}}
: Triggers at the end of turn ''X''.

; side turn
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.
: '''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

; 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''
: Triggers at the start of turn ''X''. It's the first side initialization event.
:Side initialization events go in the order of:
: 1) '''turn ''X'''''
:2) '''new turn'''
:3) '''side turn'''
:4) '''side ''X'' turn'''
:5) '''side turn ''X'''''
:6) '''side ''X'' turn ''Y'''''
:7) '''turn refresh'''
:8) '''side ''X'' turn refresh'''
:9) '''turn ''X'' refresh'''
:10) '''side ''X'' turn ''Y'' refresh'''

; side ''X'' turn ''Y''
: This event triggers at the start of turn ''Y'' of side X {{DevFeature}}

; side ''X'' turn
: This event triggers at the start of any turn of side X {{DevFeature}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn ''X''
: This event triggers at the start of any side on turn X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side X turn Y refresh
: This event triggers at the turn refresh for side X on turn Y {{DevFeature1.9}}

; side ''X'' turn refresh
: This event triggers at the turn refresh for side X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; turn ''X'' refresh
: This event triggers for any side at the refresh of turn X. {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn end {{DevFeature1.9}}
: Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:
:1) '''side turn end'''
:2) '''side ''X'' turn end'''
:3) '''side turn ''X'' end'''
:4) '''side ''X'' turn ''Y'' end'''
:5) '''turn end'''
:6) '''turn ''X'' end'''

; 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 (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

; 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 undo 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
: '''important: "sighted" events are very buggy in general, especially if "delay shroud updates" is set to "yes". Avoid using them despite of them being (still) used a lot in mainline.''' {{DevFeature1.9}}: It is currently tested whether the introduction of the "whiteboard" feature is accepted, making it possible to remove the "delay shroud updates" option which could in return make this event stable again.
: A '''sighted''' event is triggered when a fog or shroud is lifted from the primary ''unit''. This can happen when a ''second_unit'' moves to a nearby location and discovers the primary ''unit''. Alternatively, the ''second_unit'' might emerge "out of the mist" and be discovered simultaneously by all members of the enemy side: in this case, the ''second_unit'' is not set. (This is part of the sighted event's bugs.)

: '''Note:''' The sighted event is ''only'' triggered when a unit moves from one location to another. When the player moves to attack an enemy unit and, in the process, removes the fog/shroud over an enemy unit, the sighted event does ''not'' fire. This makes the sighted event unreliable: It may or may not fire, depending on the user actions. (This may be part of the sighted event's bugs.)

: '''Alternatives:''' It is sometimes possible to replace a sighted event by a moveto event with a [[StandardLocationFilter|location filter]] matching a nearby location. A [[FilterWML#Filtering_Vision|filter_vision]] filter may be useful in some cases.

; 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). In {{DevFeature}}, this event name is changed to "petrified".

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

; die
: Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.

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

==== [filter_condition] ====
: {{DevFeature1.9}}
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* True Condition Tags and Meta Condition Tags as described in [[ConditionalActionsWML]].
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

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

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
getting message options (etc) from the following events is not synchronized, except in the development version (1.9+svn):
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

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

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

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

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

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

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

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

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

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

[[Category: WML Reference]]