The Battle for Wesnoth Wiki - User contributions [en]

EventWML

2007-12-07T01:15:27Z

Death is undead: /* Nested events */

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

This tag is a subtag of [scenario] (or [unit] - see '''event''', [[UnitWML]]) which is used to describe a set of actions
which trigger at a certain point in the scenario.

keys and tags that describe when the event should trigger:
<ul><li> ''name'' this is not like a normal 'name' key. It is a basic description of when the event will trigger.
* ''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'' [[DevFeature|(1.3.8 or SVN trunk only)]] this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* ''turn ''X'''' 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=1''' (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 ''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 ''secondary_unit'' below). '' {{DevFeature}} These units are stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]] 

* ''moveto'' triggers after ''primary_unit'' moves. Typically this is used when ''primary_unit'' gets to a particular location and a filter for the location of ''primary_unit'' is included; remember that this is the location that ''primary_unit'' lands on, not the location it started on or any location it travels on.
* ''sighted'' this event triggers when ''primary_unit'' moves to a location where ''secondary_unit'' is in ''primary_unit'''s sight range. Works only in shroud or fog.
* ''attack'' this event triggers when ''primary_unit'' attacks ''secondary_unit''.
* ''attacker_hits'' this event triggers when the attacker (''primary_unit'') hits the defender (''secondary_unit'').
* ''attacker_misses''} same as ''attacker_hits'', but is triggered when the attacker misses.
* ''defender_hits'' this event triggers when the attacker (''primary_unit'') is hit in retaliation by the defender (''secondary_unit'').
* ''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 ''primary_unit'' is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by ''secondary_unit'' (''secondary_unit'' is the unit with the 'stones' ability.)
* ''pre_die'' this event triggers when ''primary_unit'' is killed by ''secondary_unit'', but before the death animation is triggered.
* ''die'' this event triggers when ''primary_unit'' is killed by ''secondary_unit''.
* ''capture'' this event triggers when ''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 ''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.)
* ''prerecruit'' {{DevFeature}} this event triggers when ''primary_unit'' is recruited, but before it is displayed.
* ''advance'' this event triggers just before ''primary_unit'' is going to advance to another unit.
* ''post_advance'' this event triggers just after ''primary_unit'' has advanced to another unit.
* ''select'' triggers when a 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.''
 
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. Note that '''[allow_undo]''' does not work within '''[if]''' tags, and that it causes out-of-sync errors in multiplayer games; check [[DirectActionsWML]] for the details.
</li></ul>

''Primary_unit'' can be referred to as '''unit''' and ''Secondary_unit'' can be referred to as '''second_unit''' in [message] tags. 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 ''primary_unit'' matches this filter.
** standard unit filter - attributes for [filter] are described in [[FilterWML]]
* '''[filter_second]''' is like [filter], but for ''secondary_unit''.
** standard unit filter
* '''[special_filter]''' and '''[special_filter_second]''' can be used to set some additional filtering criteria for ''primary_unit'' and ''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''.
** ''weapon'' the name of the weapon used.
** ''terrain'' the letter of the terrain the unit is on.

=== 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 outer event executes. 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 simple and elegant way to accomplish more complex tasks without resorting to excessive if statements.
Example:
[event]
name=turn 10 (example NOT NEEDED AS TURN 10)
[event]
name=moveto (example NOT NEEDED AS MOVETO)
[filter]
x,y= (put x,y)
[/filter]
[/event]
[/event]

~Matt Lazar (DEATH, DEATH_is_undead)

== See Also ==

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

[[Category: WML Reference]]

EventWML

2007-12-07T01:13:07Z

Death is undead1: /* Nested events */

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

This tag is a subtag of [scenario] (or [unit] - see '''event''', [[UnitWML]]) which is used to describe a set of actions
which trigger at a certain point in the scenario.

keys and tags that describe when the event should trigger:
<ul><li> ''name'' this is not like a normal 'name' key. It is a basic description of when the event will trigger.
* ''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'' [[DevFeature|(1.3.8 or SVN trunk only)]] this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* ''turn ''X'''' 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=1''' (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 ''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 ''secondary_unit'' below). '' {{DevFeature}} These units are stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]] 

* ''moveto'' triggers after ''primary_unit'' moves. Typically this is used when ''primary_unit'' gets to a particular location and a filter for the location of ''primary_unit'' is included; remember that this is the location that ''primary_unit'' lands on, not the location it started on or any location it travels on.
* ''sighted'' this event triggers when ''primary_unit'' moves to a location where ''secondary_unit'' is in ''primary_unit'''s sight range. Works only in shroud or fog.
* ''attack'' this event triggers when ''primary_unit'' attacks ''secondary_unit''.
* ''attacker_hits'' this event triggers when the attacker (''primary_unit'') hits the defender (''secondary_unit'').
* ''attacker_misses''} same as ''attacker_hits'', but is triggered when the attacker misses.
* ''defender_hits'' this event triggers when the attacker (''primary_unit'') is hit in retaliation by the defender (''secondary_unit'').
* ''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 ''primary_unit'' is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by ''secondary_unit'' (''secondary_unit'' is the unit with the 'stones' ability.)
* ''pre_die'' this event triggers when ''primary_unit'' is killed by ''secondary_unit'', but before the death animation is triggered.
* ''die'' this event triggers when ''primary_unit'' is killed by ''secondary_unit''.
* ''capture'' this event triggers when ''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 ''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.)
* ''prerecruit'' {{DevFeature}} this event triggers when ''primary_unit'' is recruited, but before it is displayed.
* ''advance'' this event triggers just before ''primary_unit'' is going to advance to another unit.
* ''post_advance'' this event triggers just after ''primary_unit'' has advanced to another unit.
* ''select'' triggers when a 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.''
 
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. Note that '''[allow_undo]''' does not work within '''[if]''' tags, and that it causes out-of-sync errors in multiplayer games; check [[DirectActionsWML]] for the details.
</li></ul>

''Primary_unit'' can be referred to as '''unit''' and ''Secondary_unit'' can be referred to as '''second_unit''' in [message] tags. 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 ''primary_unit'' matches this filter.
** standard unit filter - attributes for [filter] are described in [[FilterWML]]
* '''[filter_second]''' is like [filter], but for ''secondary_unit''.
** standard unit filter
* '''[special_filter]''' and '''[special_filter_second]''' can be used to set some additional filtering criteria for ''primary_unit'' and ''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''.
** ''weapon'' the name of the weapon used.
** ''terrain'' the letter of the terrain the unit is on.

=== 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 outer event executes. 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 simple and elegant way to accomplish more complex tasks without resorting to excessive if statements.
Example:
[event]

name=turn 10 (example NOT NEEDED)

[event]

name=moveto (example NOT NEEDED)

[filter]

x,y= (put x,y)

[/filter]

[/event]

[/event]

~Matt Lazar (DEATH, DEATH_is_undead)

== See Also ==

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

[[Category: WML Reference]]