Difference between revisions of "AbilitiesWML"

From The Battle for Wesnoth Wiki
(Common keys and tags for every weapon special)
(Abilities and their effects: There's no such thing as [filter_second] in an ability)
 
(40 intermediate revisions by 8 users not shown)
Line 4: Line 4:
 
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.
 
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.
  
Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.
+
Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.
  
Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.
+
Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.
  
 
== The ''[abilities]'' tag ==
 
== The ''[abilities]'' tag ==
Line 20: Line 20:
 
* '''[teleport]''': allows the unit to teleport
 
* '''[teleport]''': allows the unit to teleport
 
* '''[hides]''': renders the unit invisible to enemies
 
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for [plague], [heal_on_hit], and [swarm] can be placed in the [abilities] tag. These "weapon specials as abilities" will give that weapon special to all attacks the unit has.
+
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
 
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
 
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.
+
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.
  
 
=== Available formula variables in Abilities and Weapon Specials  ===
 
=== Available formula variables in Abilities and Weapon Specials  ===
Line 28: Line 28:
 
{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
 
{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
 
* '''self''': (unit) the unit that has the ability
 
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability.
+
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
 
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
 
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
 
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
 
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
Line 36: Line 36:
  
 
{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using  
 
{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using  
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do not precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
+
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
  
 
* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
 
* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
Line 48: Line 48:
 
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
 
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
 
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
 
* '''affect_enemies''': if equal to 'yes' (default is 'no'), 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. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''.
+
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
 
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
 
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
 +
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
 +
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
 +
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
 +
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
 
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
 
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* '''[affect_adjacent]''': an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
+
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
 
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
 
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
 
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
 
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
Line 57: Line 61:
 
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
 
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
 
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
 
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
+
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
 +
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].
  
 
=== Extra keys used by the ''[heals]'' ability ===
 
=== Extra keys used by the ''[heals]'' ability ===
Line 72: Line 77:
  
 
* '''value''': set resistance to this value.
 
* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. This value '''must''' be set in order for [resistance] to function.
+
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''add''': adds to resistance.
+
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
 +
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
 
* '''sub''': subtracts from resistance.
 
* '''sub''': subtracts from resistance.
 
* '''multiply''': multiplies resistance value.  
 
* '''multiply''': multiplies resistance value.  
Line 86: Line 92:
  
 
* '''value''': the percentage bonus to damage.
 
* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage.
+
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
 
* '''sub''': the cumulative percentage bonus subtracted to damage.
 
* '''sub''': the cumulative percentage bonus subtracted to damage.
 +
* '''multiply''': multiplies resistance value.
 +
* '''divide''': divides resistance value.
 
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
 
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
 
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
 
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
Line 96: Line 104:
 
Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
 
Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
 
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.  
 
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.  
* '''max_value''': the maximum percentage bonus given.
+
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''min_value''': the minimum percentage bonus given.
+
* '''sub''': the cumulative percentage bonus subtracted to damage.
 +
* '''multiply''': multiplies resistance value.
 +
* '''divide''': divides resistance value.
 +
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
 +
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.
  
 
=== Extra keys used by the ''[hides]'' ability ===
 
=== Extra keys used by the ''[hides]'' ability ===
Line 105: Line 117:
 
=== Extra tags used by the ''[teleport]'' ability ===
 
=== Extra tags used by the ''[teleport]'' ability ===
  
* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.)  You may use $teleport_unit inside the tunnel tag for filtering purposes.
+
* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.)  You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.
  
=== Extra tags and keys used by weapon special abilities ===
+
=== Extra tags and keys used by weapon specials as abilities ===
  
* '''[filter_student]''': {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. Work like '''[filter_self]''' of specific weapon special.
+
* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
 
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
 
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
 +
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
 +
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
 +
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
 
* Other keys and tags appropriate to the specific weapon special.
 
* Other keys and tags appropriate to the specific weapon special.
  
Line 133: Line 148:
 
The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:
 
The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:
  
* '''[attacks]''': modifies the number of attacks of a weapon
+
* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round
+
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon
+
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon
+
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
 +
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
 
* '''[disable]''': disables the weapon
 
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt
+
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
 
* '''[firststrike]''': forces the weapon to always strike first
 
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects
+
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
 
* '''[petrifies]''': turns the target to stone
 
* '''[petrifies]''': turns the target to stone
 
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
 
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
Line 146: Line 162:
 
* '''[slow]''': slows the target
 
* '''[slow]''': slows the target
 
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
 
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
* '''[damage_type]''' {{DevFeature1.17|23}}: type of damage changed by replacement or addition of another type
 
 
Any other tag is valid, but will result in a special that does nothing but report it is there.
 
Any other tag is valid, but will result in a special that does nothing but report it is there.
  
Line 163: Line 178:
 
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.  
 
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.  
 
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
 
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* '''[filter_self]''': the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
+
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* '''[filter_opponent]''': the special will only be active if the opponent matches this SUF.
+
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* '''[filter_attacker]''': the special will only be active if the attacker matches this SUF.
+
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* '''[filter_defender]''' the special will only be active if the defender matches this SUF.
+
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
 
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
Line 178: Line 193:
 
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
 
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
 
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
 
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
+
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
 +
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].
  
 
=== Common keys and tags for specials with a value ===
 
=== Common keys and tags for specials with a value ===
Line 184: Line 200:
 
The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).  
 
The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).  
  
* '''value''': the value to be used.
+
* '''value''': the value to be used.  
* '''add''': the number to add to the base value.
+
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
 
* '''sub''': the number to subtract from the base value.
 
* '''sub''': the number to subtract from the base value.
 
* '''multiply''': this multiplies the base value.
 
* '''multiply''': this multiplies the base value.
Line 193: Line 209:
 
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.
 
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.
  
=== Extra keys used by the ''[damage_type]'' special {{DevFeature1.17|23}} ===
+
==== Common calculations ====
 +
 
 +
Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.
 +
 
 +
{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.
 +
 
 +
Prior to 1.19.4:
 +
 
 +
* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
 +
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.
 +
 
 +
=== Extra keys used by the ''[damage_type]'' special ===
 +
 
 +
{{DevFeature1.17|23}}
  
 
* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
 
* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
 
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.
 
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.
 +
 +
'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.
 +
 +
'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.
  
 
=== Extra keys used by the ''[berserk]'' special ===
 
=== Extra keys used by the ''[berserk]'' special ===
Line 205: Line 238:
 
=== Extra keys used by the ''[plague]'' special ===
 
=== Extra keys used by the ''[plague]'' special ===
  
* '''type''': the unit type to be spawned on kill.
+
* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.
  
 
=== Extra keys used by the ''[swarm]'' special ===
 
=== Extra keys used by the ''[swarm]'' special ===
Line 217: Line 250:
 
=== Macros for common weapon specials ===
 
=== Macros for common weapon specials ===
  
 +
[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
 
* WEAPON_SPECIAL_BACKSTAB
 
* WEAPON_SPECIAL_BACKSTAB
 
* WEAPON_SPECIAL_BERSERK
 
* WEAPON_SPECIAL_BERSERK

Latest revision as of 18:41, 15 December 2024

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D:

damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and [filter_self] can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use [filter_opponent].

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use [filter_opponent], while the student can be filtered with [filter_student].

The [abilities] tag

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

  • [heals]: modifies the hitpoints of a unit at the beginning of 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
  • (Version 1.15.0 and later only) All weapon specials except for [plague], [heal_on_hit], and [swarm] can be placed in the [abilities] tag. These "weapon specials as abilities" will give the weapon special to all attacks the unit has.
  • Any other tag is valid (for example [dummy]), but will result in an ability that does nothing but report it's there. Note: a dummy ability must have an id for the name and description to display.
  • (Version 1.15.3 and later only) All the engine weapon specials can be placed in the [abilities] tag now.

Available formula variables in Abilities and Weapon Specials

(Version 1.15.? and later only) When using formulas in abilities and weapon specials, the following formula variables are available:

  • self: (unit) the unit that has the ability
  • student: (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
  • attacker: (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
  • defender: (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
  • other: (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

Common keys and tags for every ability

(Version 1.13.? and later only) All keys inside any ability that expects a numeric value will also accept formulas using Wesnoth Formula Language. In order to use a formula in these keys, you must enclose it in parentheses. However, do not precede those parentheses with a dollar sign like $(...), since that will erase the self variable.

  • name: the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
  • female_name: the (translatable) name of the ability when possessed by a female unit. Defaults to name if not specified.
  • name_inactive: the (translatable) name of the ability when inactive. Defaults to name if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set name_inactive to an empty string (nothing after the equals sign).
  • female_name_inactive: the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to name_inactive if not specified. You should thus set female_name as well!
  • description: the (translatable) description of the ability.
  • description_inactive: the (translatable) description of the ability when inactive. Defaults to description if not specified.
  • special_note (Version 1.15.14 and later only) Translatable string, which will be displayed in the unit’s help. See also UnitTypeWML#Special_Notes.
  • affect_self: if equal to 'yes' (default), the ability will affect the unit that has it.
  • affect_allies: if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
  • affect_enemies: if equal to 'yes' (default is 'no'), 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. Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the leadership ability" section. (Version 1.17.5 and later only), bug fixed.
  • id: this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
  • halo_image: (Version 1.17.22 and later only) if used, the halo specified showed on unit affected by ability.
  • overlay_image: (Version 1.17.22 and later only) if used, the overlay specified showed on unit affected by ability.
  • halo_image_self: (Version 1.17.22 and later only) if used, the halo specified showed on unit who has ability when active.
  • overlay_image_self: (Version 1.17.22 and later only) if used, the overlay specified showed on unit who has ability when active.
  • [filter]: StandardUnitFilter If the unit owning the ability does not match this filter, the ability will be inactive.
  • [affect_adjacent]: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the affect_allies and affect_enemies keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
  • [filter_self]: if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a StandardUnitFilter as argument.
  • [filter_adjacent]: if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys adjacent, count, is_enemy, just like in a StandardUnitFilter, with the one difference that, in the absence of a specified count, all listed directions must match (so, with two directiones eg adjacent=n,s, the default is count=2). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and (Version 1.13.2 and later only) $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
  • [filter_adjacent_location]: like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
  • [filter_base_value]: filters on the value before any modifications; uses the keys equals, not_equals, etc. If several keys are used all have to match.
  • [event]: EventWML. (Version 1.19.4 and later only) An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that name=prestart events, for example, would usually never trigger). See WML Abilities. Shortcut of [unit_type][event].

Extra keys used by the [heals] ability

  • value: the amount healed.
  • poison: can be one of slowed,cured. slowed means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

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. Default: 0%. (Version 1.17.24 and later only) Default: no limit.
  • min_value: (Version 1.19.0 and later only) minimum resistance value. Default: no limit.
  • add: adds to resistance. Note the interaction with sub in #Common_calculations.
  • sub: subtracts from resistance.
  • multiply: multiplies resistance value.
  • divide: divides 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.

These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).

  • [filter_weapon]: (Version 1.15.0 and later only) If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
  • [filter_second_weapon]: (Version 1.15.0 and later only) If present, the resistance ability only takes effect when the opponent uses a matching weapon.

Extra keys used by the [leadership] ability

  • value: the percentage bonus to damage.
  • add: the cumulative percentage bonus to damage. Note the interaction with sub in #Common_calculations.
  • sub: the cumulative percentage bonus subtracted to damage.
  • multiply: multiplies resistance value.
  • divide: divides resistance value.

Note: cumulative leadership with cumulative=yes and value= doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use add= or sub= key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a [leadership] with the same id to be added you will be able to reuse cumulative=yes in 1.17.12 and later, otherwise, if you want to add the value of another [leadership] only once even with the same id in several copies, use add.

  • [filter_weapon]: (Version 1.15.0 and later only) If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
  • [filter_second_weapon]: (Version 1.15.0 and later only) If present, the leadership ability only takes effect when the opponent uses a matching weapon.

Extra keys used by the [illuminates] ability

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.

  • value: the percentage bonus to lawful units. Units with alignment=lawful do +value % damage when under the influence of a unit with this ability. Units with alignment=chaotic do -value % damage. Units with alignment=neutral are unaffected by this ability. Units with alignment=liminal do -(abs(value)) % damage. value can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
  • add: the cumulative percentage bonus to damage. Note the interaction with sub in #Common_calculations.
  • sub: the cumulative percentage bonus subtracted to damage.
  • multiply: multiplies resistance value.
  • divide: divides resistance value.
  • max_value: the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
  • min_value: the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

Extra keys used by the [hides] ability

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

Extra tags used by the [teleport] ability

  • [tunnel] - a tunnel tag (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

Extra tags and keys used by weapon specials as abilities

  • [filter_student]: (Version 1.15.0 and later only) If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching [filter_adjacent] will be affected. Replaces [filter_self] of normal weapon specials.
  • overwrite_specials: (Version 1.15.13 and later only) If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If overwrite_specials=one_side, the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If overwrite_specials=both_sides, all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
  • [overwrite]: (Version 1.17.22 and later only) Part of overwrite_specials. Allows more flexibility in determining which specials should take priority over other specials of the same type.
    • priority: A numeric value to use when determining which special should be used if multiple specials of the same type have the overwrite_specials attribute. Default is 0.
    • [experimental_filter_specials]: StandardAbilityFilter Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
  • Other keys and tags appropriate to the specific weapon special.

Macros for common abilities

macro reference

  • ABILITY_AMBUSH
  • ABILITY_CURES
  • ABILITY_HEALS
  • ABILITY_ILLUMINATES
  • ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
  • (Version 1.13.2 and later only) ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
  • 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:

  • [attacks]: modifies the number of attacks of a weapon, in using value, add, sub, multiply or divide attributes
  • [berserk]: pushes the attack for more than one combat round, using value attribute, value is 1 by default
  • [chance_to_hit]: modifies the chance to hit of a weapon, using same standard numerical attributes as [attacks]
  • [damage]: modifies the damage of a weapon, using same attributes as [attacks] and [chance_to_hit]
  • [damage_type] (Version 1.17.23 and later only): changes the damage type of a weapon
  • [disable]: disables the weapon
  • [drains]: heals the attacker half of the damage dealt, using same attributes as [attacks] and [chance_to_hit], value is 50% by default
  • [firststrike]: forces the weapon to always strike first
  • [heal_on_hit]: heals the attacker when an attack connects, using same attributes as [attacks] and [chance_to_hit], value is 0 by default
  • [petrifies]: turns the target to stone
  • [plague]: when used to kill an enemy, a friendly unit takes its place
  • [poison]: poisons the target
  • [slow]: slows the target
  • [swarm]: number of strikes decreases as the unit loses hitpoints

Any other tag is valid, but will result in a special that does nothing but report it is there.

Common keys and tags for every weapon special

(Version 1.13.? and later only) All keys inside any weapon special that expects a numeric value will also accept formulas using Wesnoth Formula Language. In order to use a formula in these keys, you must enclose it in parentheses.

  • name: the (translatable) name of the special. If omitted, the special will be hidden from the player.
  • name_inactive: the (translatable) name of the special when inactive. Defaults to name if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set name_inactive to an empty string (nothing after the equals sign).
  • description: the (translatable) description of the special.
  • description_inactive: the (translatable) description of the special when inactive. Defaults to description if not specified.
  • special_note (Version 1.15.14 and later only) Translatable string, which will be displayed in the unit’s help. See also UnitTypeWML#Special_Notes.
  • 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 (default: self). Determines who the effects of this special are applied to.
  • [filter_adjacent]: if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys adjacent, count, is_enemy, just like in a StandardUnitFilter. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified count, all listed directions must match (so, with two directiones eg adjacent=n,s, the default is count=2). The variables $this_unit and (Version 1.13.2 and later only) $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
  • [filter_adjacent_location]: like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
  • [filter_self]: the special will only be active if the owner matches this StandardUnitFilter (SUF).
  • [filter_opponent]: the special will only be active if the opponent matches this SUF.
  • [filter_attacker]: the special will only be active if the attacker matches this SUF.
  • [filter_defender] the special will only be active if the defender matches this SUF.
  • overwrite_specials: if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
  • [overwrite]: (Version 1.17.22 and later only) Allows more flexibility in determining which specials should take priority over other specials of the same type.
    • priority: A numeric value to use when determining which special should be used if multiple specials of the same type have the overwrite_specials attribute. Default is 0.
    • [experimental_filter_specials]: StandardAbilityFilter Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], (Version 1.19.5 and later only) [experimental_filter_specials] deprecated, use [filter_specials] instead.
  • [event]: EventWML. (Version 1.19.4 and later only) An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that name=prestart events, for example, would usually never trigger). See WML Abilities. Shortcut of [unit_type][event].

Common keys and tags for specials with a value

The [damage], [attacks], and [chance_to_hit] specials take values that specify how those specials modify their respective base values. The [drains] special takes a value specifying the percentage of damage drained (default 50) and [heal_on_hit] takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

  • value: the value to be used.
  • add: the number to add to the base value. Note the interaction with sub in #Common_calculations.
  • sub: the number to subtract from the base value.
  • multiply: this multiplies the base value.
  • divide: this divides the base value.
  • cumulative: if set to 'yes', this special will be cumulative with the base value.
  • backstab: if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). (Version 1.13.2 and later only) This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
  • [filter_base_value]: filters on the value before any modifications; uses the keys equals, not_equals, less_than, greater_than, less_than_equal_to, greater_than_equal_to.

Common calculations

Several abilities and weapon specials take the keys add, sub, multiply and divide.

(Version 1.19.4 and later only) add and sub work independently.

Prior to 1.19.4:

  • If add and sub are used in the same ability, the add is ignored
  • If add and sub are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

Extra keys used by the [damage_type] special

(Version 1.17.23 and later only)

  • replacement_type: replaces the attack type with the specified type when [damage_type] is active.
  • alternative_type: add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

Note: In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

Note: If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

Extra keys used by the [berserk] special

  • value: the maximum number of combat rounds (default 1).
  • cumulative: if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

Extra keys used by the [plague] special

  • type: the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

Extra keys used by the [swarm] special

  • swarm_attacks_max: the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
  • swarm_attacks_min: the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.

The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

Macros for common weapon specials

macro reference

  • 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

This page was last edited on 15 December 2024, at 18:41.