User:Ken Oh

2009-06-24T16:06:19Z

Ken Oh: /* WesSaga (none released, Wesnoth 1.5.8) */

EventWML

2009-06-24T16:03:39Z

Ken Oh: and a note about the interchangability of spaces/underscores in event name

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

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

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

Usage:
name=<value>

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

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

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker_misses,defender_misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

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

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else. Spaces in event names can be interchanged with underscores (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

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

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

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

; new turn
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

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

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

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

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

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

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

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

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

; moveto
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)

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

; attack end
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

; attacker hits
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

; attacker misses
: Same as ''attacker_hits'', but is triggered when the attacker misses.

; defender hits
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

; defender misses
: Same as ''defender_hits'', but is triggered when the defender misses.

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

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

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

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

; recruit
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

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

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

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

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

; menu item X
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== Custom events.

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives.

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will every time the criteria are met instead of only the first time.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

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

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

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

After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

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

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

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

== A Trap for the Unwary ==

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

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

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

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

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

== Miscellaneous Notes and Examples ==

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

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

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

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

=== Nested Event Example ===

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

[event]
name=turn 10

[event]
name=moveto

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

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

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

=== Delayed Variable Substitution Example ===

This code will display the turn on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

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

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

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

[event]
name=turn 10

[event]
name=moveto

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

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

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

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

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

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

== See Also ==

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

[[Category: WML Reference]]

EventWML

2009-06-24T16:00:24Z

Ken Oh: removed unscores from event names

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

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

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

Usage:
name=<value>

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

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

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker_misses,defender_misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

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

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

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

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

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

; new turn
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

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

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

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

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

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

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

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

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

; moveto
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)

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

; attack end
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

; attacker hits
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

; attacker misses
: Same as ''attacker_hits'', but is triggered when the attacker misses.

; defender hits
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

; defender misses
: Same as ''defender_hits'', but is triggered when the defender misses.

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

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

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

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

; recruit
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

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

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

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

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

; menu item X
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== Custom events.

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives.

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will every time the criteria are met instead of only the first time.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

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

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

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

After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

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

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

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

== A Trap for the Unwary ==

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

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

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

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

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

== Miscellaneous Notes and Examples ==

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

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

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

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

=== Nested Event Example ===

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

[event]
name=turn 10

[event]
name=moveto

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

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

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

=== Delayed Variable Substitution Example ===

This code will display the turn on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

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

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

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

[event]
name=turn 10

[event]
name=moveto

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

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

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

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

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

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

== See Also ==

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

[[Category: WML Reference]]

User:Ken Oh

2009-06-24T15:54:22Z

Ken Oh: updated

ConditionalActionsWML

2009-05-02T12:22:41Z

Ken Oh: someone finally explained this to me and i figured i should pass it on. please correct if wrong.

{{WML Tags}}

Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.

== Conditional Actions ==

These actions describe actions that should be executed only if certain conditions are met.

=== [if] ===

Executes actions only if the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains [[:Category:ActionsWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[else]''': Contains [[:Category:ActionsWML|actions]] which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against.
** [[:Category:ActionsWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of [[:Category:ActionsWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 1024 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains [[:Category:ActionsWML|actions]] that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros.

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same [[:Category:ActionsWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

; [have_unit]
: A unit with greater than zero hit points matching this filter exists.
:* [[StandardUnitFilter]] '''*''': Selection criteria. '''* Note:''' ''Does '''not''' check for matching units in the recall list!''
:* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

; [have_location]
: A location matching this filter exists.
:* [[StandardLocationFilter]]: Selection criteria.
:* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

; [variable]
: Test the value of a WML variable (see [[VariablesWML]]) against another value.
:* '''name''': The name of the variable to test.
:* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
:** '''contains''': ''$name'' contains this string value.
:** '''equals''': ''$name'' is equal (string wise) to this value.
:** '''not_equals''': ''$name'' is not equal (string wise) to this value.
:** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
:** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value. '''*''' '''*''' Using '''numerical_equals'''/'''numerical_not_equals''' for numbers results in faster calculation than '''equals'''/'''not_equals'''.
:** '''greater_than''': ''$name'' is greater than this value.
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.
:** '''less_than''': ''$name'' is less than this value.
:** '''less_than_equal_to''': ''$name'' is less than or equal to this value.
:** '''boolean_equals''': ''$name'' has an equivalent boolean value. '''*'''
:** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value. '''*''' '''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''. These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0''' These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)

=== Meta Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any others. Useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an [[:Category:ActionsWML|action]] to take place. (See [[AdvancedConditionalWML|Example]])
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: A condition which reverses the evaluation of the contained condition(s).
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

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

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

AbilitiesWML

2009-04-21T17:40:52Z

Ken Oh: Had a fun 1.5 hours trying to figure out why [resistance] wasn't working.

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

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

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

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

* '''[heals]''': modifies the hitpoints of a unit at the beginning the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
Any other name is valid, but will result in an ability that does nothing but report it's there.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Macros for common abilities ===

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

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

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

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

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

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

=== Macros for common weapon specials ===

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

== See Also ==

* [[UnitWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

InternalActionsWMLUnitTags

2009-03-29T01:46:36Z

Ken Oh: removed [advancement] from list of alterable values, 1.5.14+ it is not https://gna.org/bugs/index.php?13274 will try to remember to put it back in if/when it goes back in

{{WML Tags}}

When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (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.)

* advances_to
* alignment
* alpha
* attacks_left
* canrecruit
* cost
* experience
* facing
* flying
* gender
* goto_x
* goto_y
* hitpoints
* id
* language_name (same as the name key in the unit config)
* max_experience
* max_hitpoints
* max_moves
* moves
* overlays
* resting
* side
* type
* unit_description
* unrenamable
* upkeep
* x
* y
* zoc
* [movement_costs]
* [defense]
* [resistance]
* [variables]
* [status]
* [attack]
* [modifications_description]
* [modifications]

These values are all children of the stored unit variable (it is a [[VariablesWML#Container|container]] variable) and the bracketed values (movement_costs, defense, etc.) are, themselves, container variables. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

== See Also ==
* [[VariablesWML]]
* [[InternalActionsWML]]

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

User:Ken Oh

2009-02-03T17:26:14Z

Ken Oh:

User:Ken Oh

2009-02-03T17:07:52Z

Ken Oh: /* Wesband + Modular RPG Era (v2, Wesnoth 1.5.2) */

WML Abilities

2009-01-21T12:55:54Z

Ken Oh: Edit in Mind Flay

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

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

=== Knockback ===

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

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

Requires the macro ''OPPOSITE_SIDE''.

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

[filter]
{FILTER}
[/filter]

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

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

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

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

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

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

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

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

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

=== Charm ===

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

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

{CHARM (type=Troll Whelp) fist}

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

[filter]
{FILTER}
[/filter]

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

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

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

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

{CLEAR_VARIABLE varname}
[/then]
)}

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

[event]
name=side turn
first_time_only=no

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

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

variable=possibly_charmed
kill=no
[/store_unit]

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

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

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

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

=== Bloodlust ===

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

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

{BLOODLUST (type=Dwarvish Ulfserker)}

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

[filter_second]
{FILTER}
[/filter_second]

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

=== Pickpocket ===

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

To do this, use this code:

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

Then put this event in your scenario:

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

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

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

===Soultaker===

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

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

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

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

[filter_second]
ability=soultaker
[/filter_second]

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

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

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

[+abilities]
#enddef

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

{ABILITY_SOULTAKER}

===Charm (Type 2)===

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

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

[/abilities]

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

[filter]
ability=charm_attack
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]

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

{CLEAR_VARIABLE unit_att_with_charm}

[/event]

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

[filter]
ability=charm_attack
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]

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

{CLEAR_VARIABLE unit_att_with_charm}

[/event]

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

[filter]
ability=charm_attack
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]
[filter_second]
canrecruit=no
[and]
level=0
[or]
level=1
[/or]
[/and]
[and]
[not]
[wml_filter]
[status]
not_living=yes
[/status]
[/wml_filter]
[/not]
[/and]
[/filter_second]

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

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

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

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

{CLEAR_VARIABLE charmer}
{CLEAR_VARIABLE charmed}

[/event]

[+abilities]

#enddef

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

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

#enddef

== Works ==

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

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

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

{FOREACH worker i}

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

{NEXT i}

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

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

== Mind Flay ==

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

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

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

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

== Initiative ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Blitz ==

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

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

[store_unit]
[filter]

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

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

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

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

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

== See Also ==

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

[[Category: UsefulWMLFragments]]

WML Abilities

2009-01-12T19:46:51Z

Ken Oh: added mind flay (raid in abilities era), initiative,blitz

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

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

=== Knockback ===

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

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

Requires the macro ''OPPOSITE_SIDE''.

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

[filter]
{FILTER}
[/filter]

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

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

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

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

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

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

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

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

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

=== Charm ===

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

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

{CHARM (type=Troll Whelp) fist}

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

[filter]
{FILTER}
[/filter]

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

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

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

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

{CLEAR_VARIABLE varname}
[/then]
)}

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

[event]
name=side turn
first_time_only=no

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

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

variable=possibly_charmed
kill=no
[/store_unit]

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

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

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

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

=== Bloodlust ===

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

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

{BLOODLUST (type=Dwarvish Ulfserker)}

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

[filter_second]
{FILTER}
[/filter_second]

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

=== Pickpocket ===

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

To do this, use this code:

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

Then put this event in your scenario:

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

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

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

===Soultaker===

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

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

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

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

[filter_second]
ability=soultaker
[/filter_second]

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

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

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

[+abilities]
#enddef

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

{ABILITY_SOULTAKER}

===Charm (Type 2)===

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

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

[/abilities]

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

[filter]
ability=charm_attack
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]

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

{CLEAR_VARIABLE unit_att_with_charm}

[/event]

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

[filter]
ability=charm_attack
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]

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

{CLEAR_VARIABLE unit_att_with_charm}

[/event]

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

[filter]
ability=charm_attack
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]
[filter_second]
canrecruit=no
[and]
level=0
[or]
level=1
[/or]
[/and]
[and]
[not]
[wml_filter]
[status]
not_living=yes
[/status]
[/wml_filter]
[/not]
[/and]
[/filter_second]

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

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

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

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

{CLEAR_VARIABLE charmer}
{CLEAR_VARIABLE charmed}

[/event]

[+abilities]

#enddef

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

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

#enddef

== Works ==

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

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

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

{FOREACH worker i}

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

{NEXT i}

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

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

== Mind Flay ==

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

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

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

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

== Initiative ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Blitz ==

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

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

[store_unit]
[filter]

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

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

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

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

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

== See Also ==

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

[[Category: UsefulWMLFragments]]

EventWML

2008-12-19T15:54:57Z

Ken Oh: Does filter_attack simply filter for anything on the weapon now?

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

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

Keys and tags that describe when the event should trigger:
* '''name''': this is not like a normal 'name' key. It is a basic description of when the event will trigger. {{DevFeature}} '''name''' can accept a list of commas separated descriptions for which the event must be triggered. Example: '''name= attacker_misses, defender_misses'''. Note that unless you use ''first_time_only=no'', the event will fire only once, not once for each listed type.
* '''prestart''': the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start'''.
* '''start''': this event triggers after the map is shown but before the scenario begins
* '''new turn''': this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.
* '''side turn''': this event triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.
* '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* '''turn X''': (for X some number) this event triggers at the start of turn ''X''. ''X'' cannot be 1.
* '''time over''': this event triggers on turn ''turns''. (''turns'' is specified in [scenario])
* '''enemies defeated''': this event triggers when all units with '''canrecruit=yes''' (i.e. all leaders) not allied with side 1 are killed.
* '''victory''': in this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also [endlevel], [[DirectActionsWML]])
* '''defeat''': in this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])
* '''ai turn''': is triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

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

* '''moveto'''': triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.
* '''sighted''': this event triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.)
* '''attack''': this event triggers when the primary unit attacks the secondary_unit.
* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the attacker.
* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.
* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the defender.
* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.
* '''attack_end''': is similar to '''attack''', but is instead triggered after the fight, not before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.
* '''stone''': this event triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).
* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.
* '''die''': this event triggers when the primary unit is killed by the secondary unit.
* '''capture''': this event triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.
* '''recruit''': this event triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.
* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.
* '''advance''': this event triggers just before the primary unit is going to advance to another unit.
* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.
* '''select''': triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''
* '''menu item X''': triggers when a WML menu item with id=X is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''
* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.
* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.
* {{DevFeature}} other events with a custom name may be invoked from [fire_event]
* {{DevFeature}} '''consider attack''': triggers before the attack dialog is displayed.
* {{DevFeature}} '''unconsider attack''': triggers when canceling out of the attack dialog.

An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.

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

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

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

These keys and tags are more complex ways to filter when an event should trigger:
* '''first_time_only''': whether the event should be removed from the scenario after it is triggered. Default is '''yes'''.
* '''[filter]''': the event will only trigger if the primary unit matches this filter.
** [[StandardUnitFilter]]: selection criteria
* '''[filter_second]''': is like [filter], but for the secondary unit.
** [[StandardUnitFilter]]: selection criteria
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack] and [filter_second_attack])
** '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')
** {{DevFeature}} '''range''': the ranged of the weapon used.

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

After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested events ===

There is 1 special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is created when the nested event is encountered (when executing the contents of the event). For example, you could create a portal that opens on turn 10. The outer event executes on turn 10, creating the nested moveto event, which executes when a player steps on a certain spot. An equivalent way of doing this would be to a single moveto event with an '''[if]''' statement to check for turn number, but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

Example:

[event]
name=turn 10

[event]
name=moveto

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

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

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

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

[event]
name=turn 2

[event]
name=moveto
delayed_variable_substitution=yes

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

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

[event]
name=turn 2

[event]
name=moveto
delayed_variable_substitution=no

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

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

== See Also ==

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

[[Category: WML Reference]]

EventWML

2008-12-19T15:43:45Z

2007-10-11T15:11:33Z

Ken Oh:

Neoriceisgood has fans! In the top four google searches leading to wesnoth, neoriceisgood has taken 5th place! (first 4 takes by keyword "wesnoth"). Read it [http://www.wesnoth.org/forum/viewtopic.php?t=17758 here]!

Alert all Wesnoth RPG fans! Now, coming to you from the creators of Wesnoth, is [http://www.silvertreerpg.org Silver Tree]! Version 0.2 has just been released.

User:Ken Oh

2007-08-27T15:23:00Z

Ken Oh:

User:Ken Oh

2007-08-24T21:18:31Z

Ken Oh:

User:Ken Oh

2007-08-24T21:17:39Z

Ken Oh: /* Despair and Decay (v0.3.1c, Wesnoth 1.2.x) */

User:Ken Oh

2007-08-24T21:16:16Z

Ken Oh: creation