Difference between revisions of "EventWML"
From The Battle for Wesnoth Wiki
m (Fixed formatting (and grammar)) |
|||
| Line 1: | Line 1: | ||
== the [event] tag == | == the [event] tag == | ||
| − | + | This tag is a subtag of [scenario] which is used to describe a set of actions | |
which trigger at a certain point in the scenario. | which trigger at a certain point in the scenario. | ||
keys and tags that describe when the event should trigger: | keys and tags that describe when the event should trigger: | ||
| − | * ''name'' this is not like a normal 'name' key. | + | * ''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 | |
| − | You can use this event to set up things like village ownership. | + | * '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. |
| − | For things displayed on-screen such as character dialog, use 'start'. | + | * 'side turn' this event triggers when any player ends their turn. When a player ends their turn, before any 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. |
| − | + | * '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. | |
| − | When the last player ends their turn, before any events of this type trigger, | + | * 'victory' in this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]]) |
| − | the value of the WML variable '''turn_number''' | + | * '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]]) |
| − | is set to the number of the turn that is beginning. | ||
| − | |||
| − | When a player ends their turn, before any 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. | ||
| − | |||
| − | |||
| − | (''turns'' is specified in [scenario]) | ||
| − | |||
| − | not allied with side 1 are killed. | ||
| − | |||
| − | will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]]) | ||
| − | |||
| − | will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]]) | ||
Events with the following trigger types can be filtered on (see [[FilterWML]]) | Events with the following trigger types can be filtered on (see [[FilterWML]]) | ||
| Line 33: | Line 20: | ||
the position of ''primary_unit'' is stored in the variables 'x1' and 'y1', | the position of ''primary_unit'' is stored in the variables 'x1' and 'y1', | ||
and the position of ''secondary_unit'' is stored in 'x2' and 'y2'. | and the position of ''secondary_unit'' is stored in 'x2' and 'y2'. | ||
| − | + | ||
| − | Usually the location of ''primary_unit'' is also filtered on; | + | * 'moveto' triggers after ''primary_unit'' moves. Usually the location of ''primary_unit'' is also filtered on; remember that this is the location that ''primary_unit'' lands on, not the location it started on or any location it travels on. |
| − | remember that this is the location that ''primary_unit'' lands on, | + | * 'sighted' this event triggers when ''primary_unit'' moves to a location where ''secondary_unit'' is in ''primary_unit'''s sight range |
| − | not the location it started on or any location it travels on. | + | * 'attack' this event triggers when ''primary_unit'' attacks ''secondary_unit'' |
| − | + | ** '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.) | |
| − | moves to a location where ''secondary_unit'' is in ''primary_unit'''s sight range | ||
| − | |||
| − | ** '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.) | ||
** 'die' this event triggers when ''primary_unit'' is killed by ''secondary_unit'' | ** 'die' this event triggers when ''primary_unit'' is killed by ''secondary_unit'' | ||
| − | ** 'capture' this event triggers when ''primary_unit'' captures a village. | + | ** '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. |
| − | The village may have been previously neutral, or previously owned by another side; | + | ** '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.) |
| − | 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.) | ||
| − | An [allow_undo] tag anywhere within a moveto event will cancel any lack of undo functionality the event would have | + | An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have |
caused. It is up to the scenario designer to avoid abusing this command by allowing undo on events that shouldn't be | caused. It is up to the scenario designer to avoid abusing this command by allowing undo on events that shouldn't be | ||
undoable. The results of doing this may be strange. This actually does have functionality beyond aesthetics like | undoable. The results of doing this may be strange. This actually does have functionality beyond aesthetics like | ||
| Line 60: | Line 38: | ||
where the event mutates the scenario. | where the event mutates the scenario. | ||
| − | ''Primary_unit'' can be referred to as '''unit''' and | + | ''Primary_unit'' can be referred to as '''unit''' and ''Secondary_unit'' can be referred to as '''second_unit''' in [message] tags. For example: |
| − | ''Secondary_unit'' can be referred to as '''second_unit''' in [message] tags. For example | ||
[event] | [event] | ||
name=die | name=die | ||
| Line 68: | Line 45: | ||
message="Hahaha, I finally killed you!" | message="Hahaha, I finally killed you!" | ||
[/message] | [/message] | ||
| − | + | ||
[message] | [message] | ||
speaker=unit | speaker=unit | ||
| Line 76: | Line 53: | ||
These keys and tags are more complex ways to filter when an event should trigger: | 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 | + | * ''first_time_only'' whether the event should be removed from the scenario after it is triggered. Default is 'yes'. |
| − | after it is triggered. Default is 'yes'. | ||
* '''[filter]''' the event will only trigger if ''primary_unit'' matches this filter. | * '''[filter]''' the event will only trigger if ''primary_unit'' matches this filter. | ||
| − | ** standard unit filter- attributes for [filter] are described in [[FilterWML]] | + | ** standard unit filter - attributes for [filter] are described in [[FilterWML]] |
* '''[filter_second]''' is like [filter], but for ''secondary_unit'' | * '''[filter_second]''' is like [filter], but for ''secondary_unit'' | ||
** standard unit filter | ** standard unit filter | ||
| − | After the trigger conditions have been met, | + | 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: internal actions ([[InternalActionsWML]]) which are used by WML internally, | There are 3 main types of actions: internal actions ([[InternalActionsWML]]) which are used by WML internally, | ||
| Line 101: | Line 76: | ||
* [[FilterWML]] | * [[FilterWML]] | ||
* [[ReferenceWML]] | * [[ReferenceWML]] | ||
| − | |||
Revision as of 16:49, 25 August 2005
the [event] tag
This tag is a subtag of [scenario] 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:
- 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 any player ends their turn. When a player ends their turn, before any 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.
- '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. (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)
Events with the following trigger types can be filtered on (see FilterWML) Whenever one of these events is triggered, the position of primary_unit is stored in the variables 'x1' and 'y1', and the position of secondary_unit is stored in 'x2' and 'y2'.
- 'moveto' triggers after primary_unit moves. Usually the location of primary_unit is also filtered on; 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
- 'attack' this event triggers when primary_unit attacks secondary_unit
- '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.)
- '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.)
An [allow_undo] tag anywhere within a moveto event will cancel any lack of undo functionality the event would have
caused. It is up to the scenario designer to avoid abusing this command by allowing undo on events that shouldn't be
undoable. The results of doing this may be strange. This actually does have functionality beyond aesthetics like
signs: suppose you have an event that performs some action depending on the condition of an 'if' statement. This event
might be executed on every single move, but the body of the 'if' statement entered only in a few cases. Previously
this would completely disable undo for the entire scenario, while now it can be made to only disable undo in the cases
where the event mutates the scenario.
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
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: internal actions (InternalActionsWML) which are used by WML internally, display actions (InterfaceActionsWML) which show something to the user, and direct actions (DirectActionsWML) which have a direct effect on gameplay.
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".