The Battle for Wesnoth Wiki - User contributions [en]

AbilitiesWML

2026-02-05T21:05:02Z

ZombieKnight: /* Extra keys used by the [regenerate] ability */

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

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
* {{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.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* 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 engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} 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 ===

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

* '''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''' {{DevFeature1.15|14}} 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.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''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.
* {{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]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[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'''.

{{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 ''[heals]'' and ''[regenerate]'' abilities ===
* '''value''': the amount healed.
* '''poison''': When the healed unit is poisoned, then unit takes usual poison damage instead. Interaction with poison can be changed with these values:
** ''cured'' - stops poison damage and heals the poison instead of healing
** ''slowed'' - stops poison damage instead of healing

* Use common keys and tags for abilities with a value.

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

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

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

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} 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. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''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.
* Use Common keys and tags for abilities with a 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.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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 [[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 specials as abilities ===

* {{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.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''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].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} 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]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage 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 ===

{{DevFeature1.13|?}} 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''' {{DevFeature1.15|14}} 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.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[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]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''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]''': {{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.
** '''[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 ===

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. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''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). {{DevFeature1.13|2}} 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'''.

{{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.
* '''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. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

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

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg 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 ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

AbilitiesWML

2026-02-05T21:04:53Z

ZombieKnight: /* Extra keys used by the [heals] ability */

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

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
* {{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.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* 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 engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} 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 ===

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

* '''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''' {{DevFeature1.15|14}} 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.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''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.
* {{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]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[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'''.

{{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 ''[heals]'' and ''[regenerate]'' abilities ===
* '''value''': the amount healed.
* '''poison''': When the healed unit is poisoned, then unit takes usual poison damage instead. Interaction with poison can be changed with these values:
** ''cured'' - stops poison damage and heals the poison instead of healing
** ''slowed'' - stops poison damage instead of healing

* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* '''poison''': {{DevFeature1.19|?}} changes the behavior when the healed unit is poisoned. possible values are:
** ''cured'' - heals the poison instead of healing
** ''slowed'' - does prevent poison damage, but doesn't remove it and doesn't heal the unit
** ''left empty, or with any other value'' - does not prevent the poison damage and does not heal, when poison is present

* Use common keys and tags for abilities with a value

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

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

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

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} 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. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''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.
* Use Common keys and tags for abilities with a 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.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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 [[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 specials as abilities ===

* {{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.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''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].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} 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]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage 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 ===

{{DevFeature1.13|?}} 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''' {{DevFeature1.15|14}} 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.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[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]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''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]''': {{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.
** '''[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 ===

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. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''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). {{DevFeature1.13|2}} 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'''.

{{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.
* '''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. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

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

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg 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 ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

AbilitiesWML

2026-01-29T09:42:48Z

ZombieKnight: /* Extra keys used by the [regenerate] ability */

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

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
* {{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.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* 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 engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} 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 ===

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

* '''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''' {{DevFeature1.15|14}} 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.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''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.
* {{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]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[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'''.

{{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 ''[heals]'' ability ===
* '''value''': the amount healed.
* '''poison''': {{DevFeature1.19|?}} changes the behavior when the healed unit is poisoned. possible values are:
** ''cured'' - heals the poison instead of healing
** ''slowed'' - does prevent poison damage, but doesn't remove it and doesn't heal the unit
** ''left empty, or with any other value'' - does not prevent the poison damage and does not heal, when poison is present

* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* '''poison''': {{DevFeature1.19|?}} changes the behavior when the healed unit is poisoned. possible values are:
** ''cured'' - heals the poison instead of healing
** ''slowed'' - does prevent poison damage, but doesn't remove it and doesn't heal the unit
** ''left empty, or with any other value'' - does not prevent the poison damage and does not heal, when poison is present

* Use common keys and tags for abilities with a value

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

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

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

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} 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. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''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.
* Use Common keys and tags for abilities with a 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.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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 [[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 specials as abilities ===

* {{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.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''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].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} 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]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage 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 ===

{{DevFeature1.13|?}} 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''' {{DevFeature1.15|14}} 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.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[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]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''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]''': {{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.
** '''[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 ===

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. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''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). {{DevFeature1.13|2}} 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'''.

{{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.
* '''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. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

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

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg 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 ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

AbilitiesWML

2026-01-29T09:42:34Z

ZombieKnight: /* Extra keys used by the [heals] ability */

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

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
* {{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.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* 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 engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} 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 ===

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

* '''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''' {{DevFeature1.15|14}} 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.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''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.
* {{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]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[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'''.

{{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 ''[heals]'' ability ===
* '''value''': the amount healed.
* '''poison''': {{DevFeature1.19|?}} changes the behavior when the healed unit is poisoned. possible values are:
** ''cured'' - heals the poison instead of healing
** ''slowed'' - does prevent poison damage, but doesn't remove it and doesn't heal the unit
** ''left empty, or with any other value'' - does not prevent the poison damage and does not heal, when poison is present

* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value

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

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

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

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} 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. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''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.
* Use Common keys and tags for abilities with a 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.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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 [[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 specials as abilities ===

* {{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.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''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].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} 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]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage 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 ===

{{DevFeature1.13|?}} 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''' {{DevFeature1.15|14}} 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.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[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]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''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]''': {{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.
** '''[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 ===

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. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''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). {{DevFeature1.13|2}} 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'''.

{{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.
* '''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. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

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

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg 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 ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

AbilitiesWML

2026-01-29T09:41:47Z

ZombieKnight: /* Extra keys used by the [heals] ability */

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

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
* {{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.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* 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 engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} 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 ===

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

* '''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''' {{DevFeature1.15|14}} 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.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''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.
* {{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]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[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'''.

{{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 ''[heals]'' ability ===
* '''value''': the amount healed.
* '''poison''': {{DevFeature1.19|?}} changes the behavior when the healed unit is poisoned.
possible values:
** ''cured'' - heals the poison instead of healing
** ''slowed'' - does prevent poison damage, but doesn't remove it and doesn't heal the unit
** ''left empty, or with any other value'' - does not prevent the poison damage and does not heal, when poison is present
* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value

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

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

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

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a 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]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} 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. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''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.
* Use Common keys and tags for abilities with a 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.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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 [[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 specials as abilities ===

* {{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.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''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].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} 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]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage 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 ===

{{DevFeature1.13|?}} 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''' {{DevFeature1.15|14}} 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.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''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 {{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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[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]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{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=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''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]''': {{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.
** '''[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 ===

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. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''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). {{DevFeature1.13|2}} 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'''.

{{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.
* '''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. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

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

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg 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 ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

LuaAPI/wesnoth/game events

2024-11-03T12:38:06Z

ZombieKnight: /* wesnoth.game_events.fire */

The <tt>game_events</tt> module contains functions for manipulating game event handlers and hooks that can be used for registering low-level game events.

== Functions ==

{{DevFeature1.17|6}}

=== wesnoth.game_events.add ===

Registers a new event handler, as [[EventWML]]. This function is the most flexible method of adding an event, which exposes all the available options via the options table, but there are also two other ways to add an event – [[#wesnoth.game_events.add_repeating|add_repeating]] is suitable for quick, recurring events, or [[#wesnoth.game_events.add_menu|add_menu]] for menu items, while [[#wesnoth.game_events.add_wml|add_wml]] is the underlying mechanism of the event tag and mostly exists just for quick compatibility.

* {{LuaGameOnly}} '''wesnoth.game_events.add'''(''options table'')

Registers an event handler in the scenario. The argument is a table containing several optional named arguments. The possible arguments are:

* '''name''': The name of the event to handle. This can be a string (a single event name, a comma-separated list, or an expression of WML variables that can expand to one or more event names) or a table of event names as individual strings (which can also possibly contain WML variables). Default is usually an empty string, but note that either a name or ID is required. If '''menu_item''' is true, the name defaults to "menu item id", where "id" is the same ID as below.
* '''id''': The event ID, used to remove it later; also, if an event with the same ID is already registered, then this event will be ignored and will not be registered. Default is an empty string. Required if '''menu_item''' is true. Note that either a name or ID is required for any event.
* '''menu_item''': True if this is a menu item (an ID is required); this means removing the menu item will automatically remove this event. Default false. Note that this does not, by itself, mean the event will be triggered when the menu item is selected. The '''name''' determines when the event is triggered.
* '''first_time_only''': Controls whether this event will fire more than once. Default true, meaning that it fires only once and is then removed.
* '''priority''': Events execute in order of decreasing priority, and secondarily in order of addition.
* '''filter''': Filters that, if not passed, will prevent the event from firing. There are three possible formats for this:
** A WML table with filter tags and attributes (like an [event] tag with no action content and no name or id). In this case the filters are parsed in the same way as they would be for an [event] tag. It can contain any supported event filter tag, or '''[insert_tag]''' tags that expand to a supported event filter tag.
** A table of the form <syntaxhighlight lang=lua inline>{filter_type = filter_contents}</syntaxhighlight>. The possible filter types are: '''formula''', '''condition''', '''side''', '''unit''', '''second_unit''', '''attack''', and '''second_attack'''. The '''formula''' filter is a string containing [[Wesnoth Formula Language]] code, while all other filters can either be a WML table containing the filter contents, or a string containing the name of a WML variable to load the filter from. In the second case, the variable will be read at event handling time, not at registration time, so modifying the variable will dynamically alter the event's filter. This is equivalent to using '''[insert_tag]''' (and delayed variable substitution, if nested) to define the filter in [[EventWML]].
** A function that optionally takes a WML table as argument and returns a boolean value.
* '''filter_args''': An optional WML table that will be passed to the '''filter''' function. This is used only if the '''filter''' is a function.
* '''content''': The content of the event. If '''action''' is specified, this is a WML table passed verbatim to that function when the event fires. If '''action''' is not specified, this will be interpreted as ActionWML to be executed when the event fires.
* '''action''': The function to call when the event triggers. It can take a WML table as argument (the '''content''') but does not return anything.

=== wesnoth.game_events.add_repeating ===

* {{LuaGameOnly}} '''wesnoth.game_events.add_repeating'''(''event name'', ''handler function'', [''priority''], [''on undo function''])

Registers a recurring event (as <syntaxhighlight lang=wml inline>[event]first_time_only=no</syntaxhighlight>) with the specified event name which will call the function when it triggers. The event name is the same as the '''name''' key in the options table in [[#wesnoth.game_events.add|game_events.add]].

The handler function takes no argument and returns nothing.

=== wesnoth.game_events.add_menu ===

* {{LuaGameOnly}} '''wesnoth.game_events.add_menu'''(''menu item id'', ''handler function'')

Registers a recurring event for a menu item. The first argument is the menu item ID, rather than an event name, so it cannot be an array or contain any commas. (TODO: Can it contain variables?) The event will be automatically linked to the menu item with the same ID and will be removed from the scenario if that menu item is removed. It will trigger when the menu item is selected.

The handler function takes no argument and returns nothing.

=== wesnoth.game_events.add_wml ===

* {{LuaGameOnly}} '''wesnoth.game_events.add_wml'''(''event config'')

This is simply the underlying implementation of the event tag. The argument is the entire content of an event tag. It will parse name, id, delayed_variable_substitution, first_time_only, filters, and [[ActionWML]] from this config and use that to register an event.

=== wesnoth.game_events.remove ===

* {{LuaGameOnly}} '''wesnoth.game_events.remove'''(''id'')

Removes the event handler with the given ID, if it exists. If it does not exist, this does nothing.

=== wesnoth.game_events.fire ===

* {{LuaGameOnly}} '''wesnoth.game_events.fire'''(''name'', [''first location'', [''second location'']], [''event data'']) → ''processed?''

Fires all events with the given name, passing any specified data into the event. If the locations passed in have a unit on them, that unit will become the primary or secondary unit of the event. The event data is a config that can contain arbitrary data.

The most common use of event data is to pass in the weapons for an attack event - to do this, add a '''first''' and '''second''' (weapon) tag to the config. Other data used by built-in events includes the '''damage_inflicted''' value in an attack hit event, or the '''owner_side''' value in a village capture event. For custom events, you can put anything you want in here.

=== wesnoth.game_events.fire_by_id ===

* {{LuaGameOnly}} '''wesnoth.game_events.fire'''(''id'', [''first location'', [''second location'']], [''event data'']) → ''processed?''

Same as [[#wesnoth.game_events.fire|fire]], but triggers the event with a specific ID instead of all events with the given name.

== Hooks ==

=== wesnoth.game_events.on_event ===

* {{LuaGameOnly}} '''wesnoth.game_events.on_event''' ↔ '''function'''(''event_name'')

This is a lower-level method of handling events. It triggers on all events before any registered event handlers and is passed the name of the event as its sole parameter - the rest of the event info is available via [[../#wesnoth.current|'''wesnoth.current.event_context''']]. This hook is called before any registered event handlers (eg [event] tags) for the event. The event names passed to '''on_event''' always use underscores instead of spaces.

'''Note:''' a on_event handler will not prevent undoing of that event, so if your callback intends to change the game state, you will need to take extra care to avoid out-of-sync errors. The easiest way is to have the callback register a new event with the same name, which will have the side-effect of disallowing undo. Since '''on_event''' is called before the event is fully processed, this new event will be triggered as soon as the callback exits. You could even wrap this functionality into a function:

<syntaxhighlight lang=lua>
function disallow_undo()
wesnoth.wml_actions.event { name = wesnoth.current.event_context.name }
end
</syntaxhighlight>

=== wesnoth.game_events.on_load ===

* {{LuaGameOnly}} '''wesnoth.game_events.on_load''' ↔ '''function'''(''scenario wml'')

This is a lower-level method of handling the load game event and the [[../#wesnoth.persistent_tags|'''wesnoth.persistent_tags''']] mechanism. It is called whenever the game is loaded, before the on_load event is triggered. If overriding this, be sure to call the original version of the function, as '''wesnoth.persistent_tags''' also depends on this event.

The scenario WML passed to this function is not the complete WML of the scenario but only the tags that the core Wesnoth engine does not know how to handle. You will never find an [event] or [side] tag in this table, for example. Although some core tags are already handled using this mechanism, you should not rely on this - for example, reading [item] tags in '''on_load''' is not guaranteed to work in future versions. The following is a list of all such tags:

color_palette color_range display end_level_data era event generator
item label lua menu_item modification modify_unit_type music
next_item_name objectives options side sound_source story terrain_graphics
time time_area tunnel undo_stack used_item variables

'''Note:''' since the '''on_load''' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a '''preload''' one - it's called even before '''preload''' fires. It can only be set inside a [lua] tag outside an event, either at [scenario] level or global.

=== wesnoth.game_events.on_save ===

* {{LuaGameOnly}} '''wesnoth.game_events.on_save''' ↔ '''function'''() → ''scenario wml''

The counterpart to '''on_load''', this function is called whenever the game is saved. Any returned WML is merged into the scenario WML in the saved game. Usually the higher-level [[../#wesnoth.persistent_tags|'''wesnoth.persistent_tags''']] mechanism is recommended instead of overriding this directly. If overriding this, be sure to call the original version of the function, as '''wesnoth.persistent_tags''' also depends on this event.

This callback can only be used to add ''custom'' data to the saved game. You can't use it to add extra data that the engine already knows about, such as events or sides, as such tags will be ignored when merging the result into the saved game WML. Although some core tags are already handled using this mechanism, you should not rely on this - for example, adding [item] tags in '''on_save''' is not guaranteed to work in future versions. See the '''on_load''' description above for a complete list of these tags.

Here's an example of how to use '''on_load''' and '''on_save''' to handle a custom tag:

<syntaxhighlight lang=lua>
-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i, tag in ipairs(cfg) do
if tag[1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = tag[2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, wml.tag.my_data{ value = level_local_data })
-- tell the engine to store them in the savefile
return cfg
end
</syntaxhighlight>

=== wesnoth.game_events.on_mouse_action ===

* {{LuaGameOnly}} '''wesnoth.game_events.on_mouse_action''' ↔ '''function'''(''x'', ''y'')

This function is called whenever the user left clicks on a hex, and is passed the coordinates of the clicked hex. This could be used for many purposes, such as a true long-ranged attack, but it has some problems.

The callback does ''not'' cancel the normal action that would have occurred as a result of the click, such as selecting or moving a unit. Furthermore, if the ''on_mouse_action'' callback takes some time to execute, it's possible the mouse moves during this time, and when the callback has completed, the action taken depends on the ''new'' position of the mouse, rather than the position that was originally clicked. Because of this bug, it is probably a bad idea to display any sort of animation in this callback or do anything that takes time.

In addition, this callback is unsynced, so it is not safe for use in multiplayer games unless you do [[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_single|manual sychronization]].

Some discussion of the problems with this callback can be found in [https://github.com/wesnoth/wesnoth/issues/2325 this enhancement request].

=== wesnoth.game_events.on_mouse_button ===

{{DevFeature1.17|22}}

* {{LuaGameOnly}} '''wesnoth.game_events.on_mouse_button''' ↔ '''function'''(''x'', ''y'', ''button'', ''event'') → ''consume?''

Registers a handler for mouse button events occurring on a valid map tile and when the UI is in a normal play state. It does not receive notification for any events on a GUI, the minimap, or when a message is up.

* '''x''', '''y''': The map coordinates the event occurred on
* '''button''': The name of the button as a string, which will be one of <syntaxhighlight lang=lua inline>"left"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"middle"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"right"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"mouse4"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"mouse5"</syntaxhighlight>.
* '''event''': One of <syntaxhighlight lang=lua inline>"down"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"up"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"click"</syntaxhighlight>

The usual order of events is down, up, and then click. However, left and middle clicks ''currently'' occur at the mouse down, so the order is different for these two. The most common use case will be to handle click events and ignore the rest. The callback may ''consume'' a click event, preventing the game engine from invoking it's default action, by returning ''true''. The return value when called for down or up events is ignored.

{| class="wikitable"
|+ Order of button events
|-
! Button
! Order
|-
| left
| down, click, up
|-
| middle
| down, click, up
|-
| right
| down, up, click
|-
| mouse4
| down, up, click
|-
| mouse5
| down, up, click
|}

At this time, there is no Lua support for drag and drop events. When a right, mouse4 or mouse5 down occurs on one tile, but then an up event on a different one (i.e., the mouse is dragged), there will be no click event. For a proper click event, both down and up must occur on the same tile. While this restriction is not currently possible with left and middle clicks, the behavior may be changed in a future release so that all mouse button events are handled consistently.

<big>'''WARNING'''</big>: ''Your event handler should be as brief as possible!'' It should check for the exact events it is looking for and immediately return false for all others. It should not attempt to display any messages, ask the user questions, pontificate the meaning of life, sell memorabilia on ebay, etc. Any intensive operations (requiring more than a few milliseconds) should be delegated to a [https://www.lua.org/pil/9.1.html coroutine] or otherwise scheduled to occur later (e.g., setting by a "flag" variable).

'''Example'''
<syntaxhighlight lang=lua>wesnoth.game_events.on_mouse_button = function(x, y, button, event)
if not (button == "right" and event == "click") then
return false
end

-- Do stuff here
return false
end
</syntaxhighlight>

=== wesnoth.game_events.on_mouse_move ===

* {{LuaGameOnly}} '''wesnoth.game_events.on_mouse_move''' ↔ '''function'''(''x'', ''y'')

This function is called when the mouse moves. More specifically, it's called whenever the currently hovered hex changes. This callback does not share most of the shortcomings of the '''on_mouse_action''' callback, but it is still unsynced.

[[Category:Lua Reference]]

LuaAPI/wesnoth/units

2024-11-01T17:59:19Z

ZombieKnight: /* wesnoth.units.to_map */

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

The entire units module is only available in the game. It is not available to plugins or map generators.

== Functions ==

=== wesnoth.units.advance ===

* {{LuaGameOnly}} '''wesnoth.units.advance'''(''unit'', [''animate'', ''fire_events''])
* {{LuaGameOnly}} ''unit'':'''advance'''([''animate'', ''fire_events''])

Advances the unit (and shows the advance unit dialog if needed) if the unit has enough XP. This function should be called after modifying the unit's experience directly. A similar function is called by Wesnoth internally after unit combat. The second argument is a boolean value that specifies whether the advancement should be animated. The third argument is a boolean value that specifies whether advancement related events should be fired.

This function only works for units on the map.

This function can also trigger multiple advancements if the unit has enough XP.

=== wesnoth.units.clone ===

* {{LuaGameOnly}} '''wesnoth.units.clone'''(''unit'') → ''copy of unit''
* {{LuaGameOnly}} ''unit'':'''clone'''()

Creates a private unit from another unit.

<syntaxhighlight lang='lua'>
-- extract a unit from the map
local u = wesnoth.units.find_on_map{ type = "Thug" }[1]:clone()
wesnoth.units.erase(u.x, u.y) -- note: not the same as u:erase(), which would be an error
-- u is still valid at this point
</syntaxhighlight>

=== wesnoth.units.erase ===

* {{LuaGameOnly}} '''wesnoth.units.erase'''(''unit'')
* {{LuaGameOnly}} '''wesnoth.units.erase'''(''x'', ''y'')
* {{LuaGameOnly}} ''unit'':'''erase'''()

Erases a unit from the map. After calling this on a unit, the unit is no longer valid. Does not work on private units - this usage will raise an error.

=== wesnoth.units.extract ===

* {{LuaGameOnly}} '''wesnoth.units.extract'''(''unit'')
* {{LuaGameOnly}} ''unit'':'''extract'''()

Removes a unit from the map or from a recall list and makes it private.

<syntaxhighlight lang='lua'>
-- remove all the units from the recall list of side 1 and put them in a WML container
local list = {}
for i,u in ipairs(wesnoth.units.find_on_recall{ side = 1 }) do
u:extract()
table.insert(list, u.__cfg)
end
wml.array_access.set("player_recall_list", list)
</syntaxhighlight>

Note: if the unit is on the map, this is just a shortcut for calling [[#wesnoth.units.clone]] and then [[#wesnoth.units.erase]]. It is, however, the only way to remove a unit from a recall list without putting it on the map.

=== wesnoth.units.matches ===

* {{LuaGameOnly}} '''wesnoth.units.matches'''(''unit'', ''filter'', [''other_unit'']) → ''matched?''
* {{LuaGameOnly}} '''wesnoth.units.matches'''(''unit'', ''filter'', [''location'']) → ''matched?''
* {{LuaGameOnly}} ''unit'':'''matches'''(''filter'', [''other_unit'']) → ''matched?''
* {{LuaGameOnly}} ''unit'':'''matches'''(''filter'', [''location'']) → ''matched?''

Returns true if the given unit matches the WML filter passed as the second argument. If ''other_unit'' is specified, it is used for the ''$other_unit'' auto-stored variable in the filter. Otherwise, this variable is not stored for the filter. If an extra ''location'' is specified, the filter matches as if the unit were at that location.

<syntaxhighlight lang='lua'>
assert(unit.canrecruit == wesnoth.units.matches(unit, { canrecruit = true }))
</syntaxhighlight>

=== wesnoth.units.find_attack ===

* {{LuaGameOnly}} '''wesnoth.units.find_attack'''(''unit'', ''filter'') → ''attack''
* {{LuaGameOnly}} ''unit'':'''find_attack'''(''filter'') → ''attack''

Returns the first attack that matches the given [[StandardWeaponFilter]].

=== wesnoth.units.to_map ===

* {{LuaGameOnly}} '''wesnoth.units.to_map'''(''unit'' [,''fire_event''])
* {{LuaGameOnly}} '''wesnoth.units.to_map'''(''unit'', ''x'', ''y'' [,''fire_event''])
* {{LuaGameOnly}} ''unit'':'''to_map'''([''x'', ''y'' [,''fire_event'']])

Places a unit on the map. This unit is described either by a WML table or by a proxy unit (to use the third form, it must be a proxy). Coordinates can be passed as additional arguments; otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed.

<syntaxhighlight lang='lua'>
-- create a unit with random traits, then erase it
wesnoth.units.to_map({ type = "Elvish Lady" }, 17, 42)
wesnoth.units.erase(17, 42)
</syntaxhighlight>

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.units.create]] and then putting the resulting unit on the map.

<syntaxhighlight lang='lua'>
-- move the leader back to the top-left corner
wesnoth.units.find_on_map({ canrecruit = true })[1]:to_map(1, 1)
</syntaxhighlight>

If x,y is a village, this function does not capture it (as of 1.14). Use [[LuaWML/Sides#wesnoth.set_village_owner|wesnoth.set_village_owner(x, y, unit.side)]] if that's what you want.

'''Caution:''' Using this function will trigger unit placed events. While this may be correct in most cases, there are some cases where it shouldn't, especially if the code is inside the definition of a custom WML tag — it would be an unexpected side-effect from the users point. To work around this, ''false'' can be passed additionally as the last argument. This is what is used internally for some tags such as [move_unit], [harm_unit], [unpetrify] or the feeding ability and is not officially part of the API.

=== wesnoth.units.to_recall ===

* {{LuaGameOnly}} '''wesnoth.units.to_recall'''(''unit'', [''side''])
* {{LuaGameOnly}} ''unit'':'''to_recall'''([''side''])

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit (to use the third form, it must be a proxy). The side of the recall list is given by the second argument if present, or by the side of the unit otherwise.

<syntaxhighlight lang='lua'>
-- put the unit at location 17,42 on the recall list for side 2
wesnoth.units.find_on_map{ x= 17, y = 42 })[1]:to_recall(2)
</syntaxhighlight>

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.units.create]] and then putting the resulting unit on a recall list.

=== wesnoth.units.rebuild ===

{{DevFeature1.19|4}}

* {{LuaGameOnly}} '''wesnoth.units.rebuild'''(''unit'')
* {{LuaGameOnly}} ''unit'':'''rebuild'''()

Immediately rebuilds the unit from its unit type and modifications, discarding any alterations to non-transient attributes. Does not reset transient attributes such as the units current hitpoints, moves, or experience.

=== wesnoth.units.transform ===

* {{LuaGameOnly}} '''wesnoth.units.transform'''(''unit'', ''to_type'', [''to_variation''])
* {{LuaGameOnly}} ''unit'':'''transform'''(''to_type'', [''to_variation''])

Changes the type of a unit and adjust attributes accordingly. Note that hit points are only changed if necessary to accommodate the new maximum hit points. Poison is automatically removed if the transformed unit is immune.

<syntaxhighlight lang='lua'>
local ev = wesnoth.current.event_context
local u = wesnoth.units.find_on_map{x=ev.x1, y=ev.y1}[1]
u:transform("Spearman")
-- If a full heal is desired:
u.hitpoints = u.max_hitpoints
u.status.poisoned = false
</syntaxhighlight>

=== wesnoth.units.select ===

Alias of [[LuaAPI/wesnoth/interface#wesnoth.interface.select_unit]].

=== wesnoth.units.scroll_to ===

Alias of [[LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex]].

=== wesnoth.units.ability ===

* {{LuaGameOnly}} '''wesnoth.units.ability'''(''unit'', ''ability_tag'') → ''affected''
* {{LuaGameOnly}} ''unit'':'''ability'''(''ability_tag'') → ''affected''

Returns true if the unit is currently affected by an ability with this given tag name. This means that the ability could be owned by the unit itself, or by an adjacent unit.

<syntaxhighlight lang='lua'>
function has_teleport(u)
return u:ability("teleport")
end
</syntaxhighlight>

=== wesnoth.units.chance_to_be_hit ===

* {{LuaGameOnly}} '''wesnoth.units.chance_to_be_hit'''(''unit'', ''terrain_code'') → ''hit chance''
* {{LuaGameOnly}} ''unit'':'''chance_to_be_hit'''(''terrain_code'') → ''hit chance''

Returns the chance that a unit will be hit on a particular terrain (based on its defence).

=== wesnoth.units.defense_on ===

* {{LuaGameOnly}} '''wesnoth.units.defense_on'''(''unit'', ''terrain_code'') → ''defense value''
* {{LuaGameOnly}} ''unit'':'''defense_on'''(''terrain_code'') → ''defense value''

Returns the defense of a unit on a particular terrain. (Note: it is the actual defense. So the lower it is, the weaker the unit is.)

<syntaxhighlight lang='lua'>
local flat_defense = u:defense_on("Gt")
</syntaxhighlight>

=== wesnoth.units.resistance_against ===

* {{LuaGameOnly}} '''wesnoth.units.resistance_against'''(''unit'', ''damage_type'', [''as_attacker''], [''x'', ''y'']) → ''resistance value''
* {{LuaGameOnly}} ''unit'':'''resistance_against'''(''damage_type'', [''as_attacker''], [''x'', ''y'']) → ''resistance value''

Returns the resistance of a unit against an attack type. (Note: it is the actual resistance. So the lower it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

<syntaxhighlight lang='lua'>
local fire_resistance = u:resistance_against("fire")
</syntaxhighlight>

=== wesnoth.units.jamming_on ===

* {{LuaGameOnly}} '''wesnoth.units.jamming_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''jamming_on'''(''terrain_code'') → ''cost''

Returns the jamming cost of a unit on a particular terrain.

<syntaxhighlight lang='lua'>
local jam_cost = u:jamming_on("Gt")
</syntaxhighlight>

=== wesnoth.units.movement_on ===

* {{LuaGameOnly}} '''wesnoth.units.movement_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''movement_on'''(''terrain_code'') → ''cost''

Returns the movement cost of a unit on a particular terrain.

<syntaxhighlight lang='lua'>
local move_cost = u:movement_on("Gt")
</syntaxhighlight>

=== wesnoth.units.vision_on ===

* {{LuaGameOnly}} '''wesnoth.units.vision_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''vision_on'''(''terrain_code'') → ''cost''

Returns the vision cost of a unit on a particular terrain.

<syntaxhighlight lang='lua'>
local see_cost = u:vision_on("Gt")
</syntaxhighlight>

=== wesnoth.units.add_modification ===

* {{LuaGameOnly}} '''wesnoth.units.add_modification'''(''unit'', ''type'', ''effects'', [''write_to_mods''])
* {{LuaGameOnly}} ''unit'':'''add_modification'''(''type'', ''effects'', [''write_to_mods''])

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (one of "trait", "object", or "advancement"). The option "advancement" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects. If ''write_to_mods'' false, causes it to not write the modification tag to the unit's [modifications] (as would be done with an [object] with no_write=true).

<syntaxhighlight lang='lua'>
local T = wml.tag
local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
local effects = {
id = "my_effect_id",
T.effect {
apply_to = "image_mod",
replace = "RC(red>blue)"
},
T.effect {
apply_to = "new_animation",
T.standing_animation {
-- AnimationWML
}
}
}
u:add_modification("object", effects)
</syntaxhighlight>

=== wesnoth.units.remove_modifications ===

* {{LuaGameOnly}} '''wesnoth.remove_modifications'''(''unit'', ''filter'', [''type''])
* {{LuaGameOnly}} ''unit'':'''remove_modifications'''(''filter'', [''type''])

Modifies a given unit. The unit needs to be a proxy unit. The second argument is a filter for the modifications to remove. It takes the same syntax as [[FilterWML#Filtering_on_WML_data|[filter_wml]]]; all matching modifications will be removed. The third argument is the type (tag name) of the modifications to search for; it defaults to "object", but you can also pass "trait" or "advancement".

<syntaxhighlight lang='lua'>
local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
u:remove_modifications({ id = "my_effect_id" })
</syntaxhighlight>

=== wesnoth.units.create_animator ===

* {{LuaGameOnly}} '''wesnoth.units.create_animator()'''

Returns an object that can be used to set up and run an animation. The object has three methods:

* ''animator'':'''run()'''

Runs the animation. Implicitly clears the animator.

* ''animator'':'''clear()'''

Clears any units previously added to the animation.

* ''animator'':'''add(''unit'', ''flag'', ''hits'', ''params'')'''

Adds a unit to the animation. The ''flag'' specifies which [[AnimationWML#Common_animation_events_used_by_the_engine|animation]] to play, and the ''hits'' parameter is required for attack animations to specify which variant of the animation to play. Possible keys in ''params'' are:

* '''facing''': A location. The animation will be played with the unit facing that location.

facing is currently not implemented/working. See https://github.com/wesnoth/wesnoth/issues/9032

* '''value''': Either a number or a list of two numbers. Use this to pass ''value'' and/or ''value_second'' to default animations that use them.
* '''with_bars''': Whether to show HP bars and such while the animation plays.
* '''text''': Text to float as the animation plays.
* '''color''': Color of the floating text - a list of red, green, blue.
* '''primary''': The primary weapon to use for the animation. Must be a Lua unit attack proxy.
* '''secondary''': The secondary weapon to use for the animation.

Normal usage is to create it, call '''add''' one or more times, then call '''run'''.

=== wesnoth.units.create ===

* {{LuaGameOnly}} '''wesnoth.units.create'''(''unit_info'') → ''unit''

Creates a private unit from a WML table.

<syntaxhighlight lang='lua'>
local u = wesnoth.units.create{ type = "White Mage", gender = "female" }
</syntaxhighlight>

=== wesnoth.units.find_on_map ===

* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'') → ''array of units''
* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'', ''fake_location'') → ''array of units''
* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'', ''other_unit'') → ''array of units''

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters. If a second unit is passed, it can be referenced via the $other_unit variable in the main filter as well as via the "other" variable in WFL formulas used in the main filter. If a location is passed, the filter is run as if the unit were at that location (rather than its real location). This affects things such as [filter_adjacent] and ability_active, and should work even for a unit on the recall list.

<syntaxhighlight lang='lua'>
local leaders_on_side_two = wesnoth.units.find_on_map{ side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name
</syntaxhighlight>

=== wesnoth.units.find_on_recall ===

* {{LuaGameOnly}} '''wesnoth.units.find_on_recall'''(''filter'') → ''array of units''

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

=== wesnoth.units.find ===

* {{LuaGameOnly}} '''wesnoth.units.find'''(''filter'') → ''array of units''

Returns a list of all units matching the WML filter, both those on the map and those on the recall lists. It is a shorthand for calling both '''find_on_map''' and '''find_on_recall''' and combining the resulting arrays.

=== wesnoth.units.get ===

* {{LuaGameOnly}} '''wesnoth.units.get'''(''x'', ''y'') → ''unit or nil''
* {{LuaGameOnly}} '''wesnoth.units.get'''(''id'') → ''unit or nil''

Returns the unit at the given location or with the given ID.

<syntaxhighlight lang='lua'>
local args = ...
local unit = wesnoth.units.get(args.x1, args.y1)
</syntaxhighlight>

=== wesnoth.units.get_hovered ===

Alias of [[LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit]].

[[Category:Lua Reference]]

LuaAPI/wesnoth/interface

2024-10-29T14:09:34Z

ZombieKnight: /* wesnoth.interface.add_item_image */

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

The entire interface module is only available in the game. It is not available to plugins or map generators.

== Interface functions ==

=== wesnoth.interface.delay ===

* {{LuaGameOnly}} '''wesnoth.interface.delay'''(''milliseconds'')

Delays the engine for a period of time, specified in milliseconds.

<syntaxhighlight lang=lua>
wesnoth.delay(500)
</syntaxhighlight>

=== wesnoth.interface.deselect_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.deselect_hex'''()

Reverses any highlight_hex call, leaving all locations unhighlighted. Takes no arguments.

=== wesnoth.interface.highlight_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.highlight_hex'''(''x'', ''y'')

Draws an outline around the specified hex.

=== wesnoth.interface.select_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.select_unit'''(''x'', ''y'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} '''wesnoth.units.select'''(''unit'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} ''unit'':'''select'''([''show_movement'', [''fire_events'']])

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false).

This function is available under two different names, but the possible arguments are the same in both cases. In other words, '''wesnoth.units.select''' can be called with a location instead of a unit, and '''wesnoth.interface.select_unit''' can be called with a unit instead of a location.

<syntaxhighlight lang=lua>
wesnoth.interface.select_unit(14, 6, true, true)
</syntaxhighlight>

If called without arguments, this function deselects the current unit from the map as long as the mouse cursor is not on its hex. It will continue to be displayed on the UI sidebar in any case.

=== wesnoth.interface.float_label ===

* {{LuaGameOnly}} '''wesnoth.interface.float_label'''(''x'', ''y'', ''text'')

Pops some text above a map tile.

<syntaxhighlight lang=lua>
wesnoth.float_label(unit.x, unit.y, "Ouch")
</syntaxhighlight>

=== wesnoth.interface.get_displayed_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.get_displayed_unit'''() → ''unit''
* {{LuaGameOnly}} '''wesnoth.units.get_hovered'''() → ''unit''

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

<syntaxhighlight lang=lua>
local name = tostring(wesnoth.interface.get_displayed_unit().name)
</syntaxhighlight>

=== wesnoth.interface.get_hovered_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_hovered_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently hovered tile, that is, where the mouse cursor is located. This is mostly useful for defining command-mode helpers.

=== wesnoth.interface.get_selected_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_selected_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently selected (highlighted) tile. This is mostly useful for defining command-mode helpers.

<syntaxhighlight lang=lua>
function chg_unit(attr, val)
local x, y = wesnoth.interface.get_selected_hex()
if not x then wesnoth.message("Error", "No unit selected."); return end
wesnoth.units.modify({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)
</syntaxhighlight>

=== wesnoth.interface.get_viewing_side ===

* {{LuaGameOnly}} '''wesnoth.interface.get_viewing_side'''() → ''side'', ''full_vision''

Returns the viewing side of the current client in a multiplayer game.

For a player participating in the game, this will always be the side that they control, or, if they control multiple sides, the one they most recently had control over. However, for an observer client, this will return the currently-active side instead.

The second return value indicates whether the current client has full vision. This can only happen in replays or for observers.

For obvious reasons, use of this function can easily cause out-of-sync errors. Use with care.

=== wesnoth.interface.lock===

* {{LuaGameOnly}} '''wesnoth.interface.lock'''(''lock'')

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_hex still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

<syntaxhighlight lang=lua>
wesnoth.interface.lock_view(true)
wesnoth.interface.scroll_to_hex(12, 14, false, true)
</syntaxhighlight>

=== wesnoth.interface.is_locked ===

* {{LuaGameOnly}} '''wesnoth.interface.is_locked'''() → ''locked?''

Returns a boolean indicating whether gamemap view scrolling is currently locked.

=== wesnoth.interface.scroll_to_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll_to_hex'''(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} '''wesnoth.units.scroll_to'''(''unit'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} ''unit'':'''scroll_to'''([''only_if_visible'', [''instant'', [''only_if_needed'']]])

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen. It is also possible to pass a unit instead of a pair of tile coordinates (regardless of which module the function is called from).

<syntaxhighlight lang=lua>
local u = wesnoth.units.get "hero"
u:scroll_to()
</syntaxhighlight>

=== wesnoth.interface.scroll ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll'''(''dx'', ''dy'')

Scrolls the map by the given amount, which may be either positive or negative.

=== wesnoth.interface.zoom ===

* {{LuaGameOnly}} '''wesnoth.interface.zoom'''(''factor'', [''relative'']) → ''new_zoom''

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then
<syntaxhighlight lang=lua inline>wesnoth.zoom(2)</syntaxhighlight>
sets it to 2, while
<syntaxhighlight lang=lua inline>wesnoth.zoom(2, true)</syntaxhighlight>
sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call
<syntaxhighlight lang=lua inline>wesnoth.zoom(1, true)</syntaxhighlight>
to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.

=== wesnoth.interface.skip_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.skip_messages'''([''skip?''])

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.

=== wesnoth.interface.is_skipping_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.is_skipping_messages'''()

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.

=== wesnoth.interface.add_chat_message ===

* {{LuaGameOnly}} '''wesnoth.interface.add_chat_message'''([''speaker'',] ''message'')

Displays a string in the onscreen chat. The chat line speaker is "Lua" by default, but it can be changed by passing a string before the message.

<syntaxhighlight lang=lua>
wesnoth.interface.add_chat_message "Hello World!" -- will result in "<Lua> Hello World!"
wesnoth.interface.add_chat_message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."
</syntaxhighlight>

See also [[LuaAPI/wml#wml.error|wml.error]] for displaying error messages.

=== wesnoth.interface.clear_chat_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.clear_chat_messages'''()

Removes all messages from the onscreen chat, including error messages.

=== wesnoth.interface.add_item_image ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_image'''(''location'', ''filename'')

Places an image at a given location and registers it as a WML ''[item]'' would do, so that it can be restored after save/load. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.add_item_image(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.add_item_halo ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_halo'''(''location'', ''filename'')

Behaves the same as [[#wesnoth.interface.add_item_image]] but for halos.

=== wesnoth.interface.remove_item ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_item'''(''location'', [''filename''])

Removes an overlay set by [[#wesnoth.interface.add_item_image]] or [[#wesnoth.interface.add_item_halo]]. If no filename is provided, all the overlays on a given tile are removed. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_item(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.get_items ===

* {{LuaGameOnly}} '''wesnoth.interface.get_items'''(''location'') → ''array of item tables''

Get all items placed on the specified location. Note that the location must be passed as separate x and y coordinates.

=== wesnoth.interface.add_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.add_hex_overlay'''(''location'', ''item_wml'')

Places a hex overlay (either an image or a halo) on the given location. The overlay is described by a table supporting the same fields as [[InterfaceActionsWML|[item]]]. This is a lower-level version of the item functions above. Note that the overlay is not kept over save/load cycles.

<syntaxhighlight lang=lua>
wesnoth.interface.add_hex_overlay(17, 42, { image = "items/orcish-flag.png" })
</syntaxhighlight>

=== wesnoth.interface.remove_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.remove_hex_overlay'''(''location'', [''filename''])

Removes all the overlays at the given location, including any added by '''wesnoth.interface.add_item_halo''' or '''wesnoth.interface.add_item_image''' (however, such a removal will not be kept over save/load cycles). If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_hex_overlay(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.end_turn'''([''next_side''])

Immediately ends the current side's turn. By default, the next sequential side will gain control, but if you pass an argument that side gains control instead.

The ''next_side'' can either be a valid side number, or a valid side number plus the total number of sides in the scenario. In the latter case, this function also increases the turn counter by 1.

Using this, it's entirely possible to pass control around without ever increasing the turn counter.

=== wesnoth.interface.allow_end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''allow'')
* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''reason'')

Enables or disables ending the turn in the UI. You can optionally pass a translatable string to show to the player if they attempt to do so anyway. It will be shown to the player without any additional framing, so it should normally be phrased similar to "You cannot end your turn because...".

To allow the player to end their turn again, just pass '''true'''. If you pass '''false''', a default message will be shown.

=== wesnoth.interface.color_adjust ===

* {{LuaGameOnly}} '''wesnoth.interface.color_adjust'''(''red'', ''green'', ''blue'')

Adjust the screen tint. (0,0,0) is no tint, and possible values range from -255 to 255.

=== wesnoth.interface.add_overlay_text ===

{{DevFeature1.17|3}}

* {{LuaGameOnly}} '''wesnoth.interface.add_overlay_text'''(''text'' [, ''options'']) → ''text handle''

Adds a text overlay to the screen that does not move with the map. [[Pango formatting]] is supported. The ''options'' table supports the following keys:

* ''size'' - The font size.
* ''max_width'' - Sets the maximum width the text can occupy on the screen, either in screen units (pixels) or as a percentage (a string ending in <tt>%</tt>). If the text is too long to fit in that width, it will automatically be word-wrapped. Defaults to 100%.
* ''color'' - The text color, either as a six-digit hex string (no leading <tt>#</tt>) or an array of three integers (red, green, and blue).
* ''bgcolor'' - If present, a background in this color is placed behind the text to enhance readability. This works like the background behind chat messages, but can be any colour. It is formatted the same as ''color''. If omitted, the background is fully transparent (ie, there is no background).
* ''bgalpha'' - If a background colour is specified, this sets its transparency. The default is fully opaque.
* ''duration'' - How long the text should be displayed, in milliseconds, or the string <syntaxhighlight lang=lua inline>'unlimited'</syntaxhighlight> for an infinite duration. Defaults to two seconds.
* ''fade_time'' - When the label is removed, either explicitly or because its duration expired, this is the time it takes to fade out, in milliseconds. A value of 0 means the label disappears instantly. Defaults to 100.
* ''halign'' - Where to anchor the text horizontally on the screen. Must be one of <syntaxhighlight lang=lua inline>'left', 'center', 'right'</syntaxhighlight>.
* ''valign'' - Where to anchor the text vertically on the screen. Must be one of <syntaxhighlight lang=lua inline>'top', 'center', 'bottom'</syntaxhighlight>.
* ''location'' - The screen offset where the text should be placed, relative to the specified anchor. Defaults to (0,0).

The text handle returned from this function supports the following method calls:

* ''handle'':'''move'''(''x'', ''y'')

Moves the text to a new location on the screen. The provided ''x'' and ''y'' are offsets from its current location.

* ''handle'':'''remove'''([''fade_time''])

Remove the text from the screen, optionally overriding the fade-out time.

* ''handle'':'''replace'''(''text'', ''options'') → ''handle''

Replaces the text with new text. Options are the same as in ''add_overlay_text'', and the returned handle is the same one.

=== wesnoth.interface.handle_user_interact ===

{{DevFeature1.17|6}}

* {{LuaGameOnly}} '''wesnoth.interface.handle_user_interact'''()

Handle user interaction with the game interface. This can be inserted into Lua code that takes a long time to execute in order to prevent the user interface from freezing.

== wesnoth.interface.game_display ==

* {{LuaGameOnly}} '''wesnoth.interface.game_display'''.''theme_item'' ↔ '''function'''() → ''wml table of theme elements''

This is an associative table linking item names to functions that describe the content of the in-game user interface. These functions are called with no arguments whenever the user interface is refreshed, and must return a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a '''help''' field that points to the help section that is displayed when the user clicks on the theme item.

Note that the '''wesnoth.interface.game_display''' cannot be iterated using '''pairs''' or '''next''' to retrieve the items from the current theme. However, built-in items ''can'' be recovered as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

<syntaxhighlight lang=lua>
local old_unit_status = wesnoth.interface.game_display.unit_status
function wesnoth.interface.game_display.unit_status()
local _ = wesnoth.textdomain "mydomain"
local u = wesnoth.interface.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, wml.tag.element {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
})
end
return s
end
</syntaxhighlight>

The things that would need to be to modified in the above code are:

* the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
* the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
* the path to the image ("entangled.png").
* the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in '''wesnoth.interface.game_display''' which will have an effect in the game, together with sample output and a brief description of their use.

=== unit_name ===

Shows the name of the unit the mouse is hovering over.

=== unit_type ===

Shows the type of the unit the mouse is hovering over.

=== unit_race ===

Shows the race of the unit the mouse is hovering over.

=== unit_side ===

Shows the side number and team color of the unit the mouse is hovering over.

=== unit_level ===

Shows the level of the unit the mouse is hovering over.

=== unit_amla ===

Similar to unit_advancement_options but shows AMLAs only.

=== unit_traits ===

Shows the list of trait names for the unit the mouse is hovering over.

=== unit_status ===

Shows the status icons for statuses afflicting the unit the mouse is hovering over.

=== unit_alignment ===

Shows the alignment of the unit the mouse is hovering over.

=== unit_abilities ===

Shows the ability names of the unit the mouse is hovering over.

=== unit_hp ===

Shows the current and maximum hit points of the unit the mouse is hovering over.

=== unit_xp ===

Shows the current and target experience points of the unit the mouse is hovering over.

=== unit_advancement_options ===

Shows the options the unit the mouse is hovering over has for advancement, including both level ups and AMLAs. This item is not used in the default theme.

=== unit_defense ===

Shows the defense of the unit the mouse is hovering over.

=== unit_vision ===

Shows the current and maximum vision points of the unit the mouse is hovering over.

=== unit_moves ===

Shows the current and maximum movement points of the unit the mouse is hovering over.

=== unit_weapons ===

Shows the available weapons of the unit the mouse is hovering over. The default generator expresses each weapon line (basic details, specials, etc) as a separate <code>element</code>. For example:

<syntaxhighlight lang=wml>
[element]
image="melee.png"
tooltip="...stuff..."
[/element]
[element]
image="arcane.png"
tooltip="...stuff..."
[/element]
[element]
text="6×3 holy sword"
tooltip="...stuff..."
[/element]
[element]
# This is empty if the range and type icons both exist.
text="melee-arcane"
tooltip="...stuff..."
[/element]
# If the weapon has accuracy or parry...
[element]
text="+20%/-10%"
tooltip="Accuracy: +20%
Parry: -10%
"
[/element]
# If the weapon has special abilities...
[element]
text="magical"
tooltip="...stuff..."
[/element]
</syntaxhighlight>

=== unit_image ===

Shows the sprite of the unit the mouse is hovering over.

=== unit_profile ===

Shows the portrait of the unit the mouse is hovering over.

=== selected_unit ===

Nearly every item beginning with '''unit_''' has a corresponding item beginning with '''selected_unit_''', which describes the currently-selected unit (if any) rather than the unit the mouse is hovering over. These items are not used in the default theme.

There is no '''selected_unit_amla''' however.

=== highlighted_unit_weapons ===

This is almost the same as '''selected_unit_weapons''' but with slightly different logic of choosing which unit to show.

=== tod_stats and selected_tod_stats ===

Shows the time of day stats for the hex the mouse is hovering over or the hex the selected unit is on. The time of day stats shows the counter of your position in the schedule as well as the entire cycle.

=== time_of_day and selected_time_of_day ===

Shows the time of day image for the hex the mouse is hovering over or the hex the selected unit is on.

=== unit_box ===

This is an experimental item that combines a unit display and the time of day.

=== turn ===

Shows the current turn count.

=== gold ===

Shows the amount of gold for the active side.

=== villages ===

Shows the number of villages owned by the active side.

=== num_units ===

Shows the number of units owned by the active side.

=== upkeep ===

Shows the upkeep and expenses for the active side.

=== income ===

Shows the income for the active side

=== terrain_info ===

Shows the icons of the terrain on hex the mouse is hovering over.

=== terrain  ===



Shows the name of the terrain on the hex the mouse is hovering over. For example:

<syntaxhighlight lang=wml>
[element]
text="Grassland (Flat)"
[/element]
</syntaxhighlight>

=== position ===

Shows the map coordinates of the hex the mouse is hovering over.

=== zoom_level ===

Shows the zoom level as a percentage. This item is not used in the default theme.

=== side_playing ===

Shows the active side's flag.

=== observers ===

When there is no observer, it returns an empty table. When there are observers, it returns:

<syntaxhighlight lang=wml>
[element]
tooltip="Observers
<observer1>
<observer2>
"
image="misc/eye.png"
[/element]
</syntaxhighlight>

=== report_clock ===

This returns the current time in HH:MM format according to the user's preferences, for example:

<syntaxhighlight lang=wml>
[element]
text="22:32"
[/element]
</syntaxhighlight>

=== report_countdown ===

This returns the current chess-timer countdown in MM:SS format for the player's turn, for example:

<syntaxhighlight lang=wml>
[element]
text="12:43"
[/element]
</syntaxhighlight>

Depending on the time limit, the text may also be colored using [[Pango formatting|Pango markup]].

If there is no time limit set then it forwards to [[#wesnoth.interface.game_display.report_clock|report_clock]].

[[Category:Lua Reference]]

LuaAPI/wesnoth/interface

2024-10-29T14:08:54Z

ZombieKnight: /* wesnoth.interface.add_item_halo */

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

The entire interface module is only available in the game. It is not available to plugins or map generators.

== Interface functions ==

=== wesnoth.interface.delay ===

* {{LuaGameOnly}} '''wesnoth.interface.delay'''(''milliseconds'')

Delays the engine for a period of time, specified in milliseconds.

<syntaxhighlight lang=lua>
wesnoth.delay(500)
</syntaxhighlight>

=== wesnoth.interface.deselect_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.deselect_hex'''()

Reverses any highlight_hex call, leaving all locations unhighlighted. Takes no arguments.

=== wesnoth.interface.highlight_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.highlight_hex'''(''x'', ''y'')

Draws an outline around the specified hex.

=== wesnoth.interface.select_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.select_unit'''(''x'', ''y'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} '''wesnoth.units.select'''(''unit'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} ''unit'':'''select'''([''show_movement'', [''fire_events'']])

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false).

This function is available under two different names, but the possible arguments are the same in both cases. In other words, '''wesnoth.units.select''' can be called with a location instead of a unit, and '''wesnoth.interface.select_unit''' can be called with a unit instead of a location.

<syntaxhighlight lang=lua>
wesnoth.interface.select_unit(14, 6, true, true)
</syntaxhighlight>

If called without arguments, this function deselects the current unit from the map as long as the mouse cursor is not on its hex. It will continue to be displayed on the UI sidebar in any case.

=== wesnoth.interface.float_label ===

* {{LuaGameOnly}} '''wesnoth.interface.float_label'''(''x'', ''y'', ''text'')

Pops some text above a map tile.

<syntaxhighlight lang=lua>
wesnoth.float_label(unit.x, unit.y, "Ouch")
</syntaxhighlight>

=== wesnoth.interface.get_displayed_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.get_displayed_unit'''() → ''unit''
* {{LuaGameOnly}} '''wesnoth.units.get_hovered'''() → ''unit''

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

<syntaxhighlight lang=lua>
local name = tostring(wesnoth.interface.get_displayed_unit().name)
</syntaxhighlight>

=== wesnoth.interface.get_hovered_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_hovered_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently hovered tile, that is, where the mouse cursor is located. This is mostly useful for defining command-mode helpers.

=== wesnoth.interface.get_selected_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_selected_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently selected (highlighted) tile. This is mostly useful for defining command-mode helpers.

<syntaxhighlight lang=lua>
function chg_unit(attr, val)
local x, y = wesnoth.interface.get_selected_hex()
if not x then wesnoth.message("Error", "No unit selected."); return end
wesnoth.units.modify({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)
</syntaxhighlight>

=== wesnoth.interface.get_viewing_side ===

* {{LuaGameOnly}} '''wesnoth.interface.get_viewing_side'''() → ''side'', ''full_vision''

Returns the viewing side of the current client in a multiplayer game.

For a player participating in the game, this will always be the side that they control, or, if they control multiple sides, the one they most recently had control over. However, for an observer client, this will return the currently-active side instead.

The second return value indicates whether the current client has full vision. This can only happen in replays or for observers.

For obvious reasons, use of this function can easily cause out-of-sync errors. Use with care.

=== wesnoth.interface.lock===

* {{LuaGameOnly}} '''wesnoth.interface.lock'''(''lock'')

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_hex still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

<syntaxhighlight lang=lua>
wesnoth.interface.lock_view(true)
wesnoth.interface.scroll_to_hex(12, 14, false, true)
</syntaxhighlight>

=== wesnoth.interface.is_locked ===

* {{LuaGameOnly}} '''wesnoth.interface.is_locked'''() → ''locked?''

Returns a boolean indicating whether gamemap view scrolling is currently locked.

=== wesnoth.interface.scroll_to_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll_to_hex'''(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} '''wesnoth.units.scroll_to'''(''unit'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} ''unit'':'''scroll_to'''([''only_if_visible'', [''instant'', [''only_if_needed'']]])

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen. It is also possible to pass a unit instead of a pair of tile coordinates (regardless of which module the function is called from).

<syntaxhighlight lang=lua>
local u = wesnoth.units.get "hero"
u:scroll_to()
</syntaxhighlight>

=== wesnoth.interface.scroll ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll'''(''dx'', ''dy'')

Scrolls the map by the given amount, which may be either positive or negative.

=== wesnoth.interface.zoom ===

* {{LuaGameOnly}} '''wesnoth.interface.zoom'''(''factor'', [''relative'']) → ''new_zoom''

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then
<syntaxhighlight lang=lua inline>wesnoth.zoom(2)</syntaxhighlight>
sets it to 2, while
<syntaxhighlight lang=lua inline>wesnoth.zoom(2, true)</syntaxhighlight>
sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call
<syntaxhighlight lang=lua inline>wesnoth.zoom(1, true)</syntaxhighlight>
to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.

=== wesnoth.interface.skip_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.skip_messages'''([''skip?''])

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.

=== wesnoth.interface.is_skipping_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.is_skipping_messages'''()

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.

=== wesnoth.interface.add_chat_message ===

* {{LuaGameOnly}} '''wesnoth.interface.add_chat_message'''([''speaker'',] ''message'')

Displays a string in the onscreen chat. The chat line speaker is "Lua" by default, but it can be changed by passing a string before the message.

<syntaxhighlight lang=lua>
wesnoth.interface.add_chat_message "Hello World!" -- will result in "<Lua> Hello World!"
wesnoth.interface.add_chat_message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."
</syntaxhighlight>

See also [[LuaAPI/wml#wml.error|wml.error]] for displaying error messages.

=== wesnoth.interface.clear_chat_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.clear_chat_messages'''()

Removes all messages from the onscreen chat, including error messages.

=== wesnoth.interface.add_item_image ===

* {{LuaGameOnly}} '''wesnoth.interface.place_item_image'''(''location'', ''filename'')

Places an image at a given location and registers it as a WML ''[item]'' would do, so that it can be restored after save/load. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.place_item_image(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.add_item_halo ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_halo'''(''location'', ''filename'')

Behaves the same as [[#wesnoth.interface.add_item_image]] but for halos.

=== wesnoth.interface.remove_item ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_item'''(''location'', [''filename''])

Removes an overlay set by [[#wesnoth.interface.add_item_image]] or [[#wesnoth.interface.add_item_halo]]. If no filename is provided, all the overlays on a given tile are removed. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_item(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.get_items ===

* {{LuaGameOnly}} '''wesnoth.interface.get_items'''(''location'') → ''array of item tables''

Get all items placed on the specified location. Note that the location must be passed as separate x and y coordinates.

=== wesnoth.interface.add_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.add_hex_overlay'''(''location'', ''item_wml'')

Places a hex overlay (either an image or a halo) on the given location. The overlay is described by a table supporting the same fields as [[InterfaceActionsWML|[item]]]. This is a lower-level version of the item functions above. Note that the overlay is not kept over save/load cycles.

<syntaxhighlight lang=lua>
wesnoth.interface.add_hex_overlay(17, 42, { image = "items/orcish-flag.png" })
</syntaxhighlight>

=== wesnoth.interface.remove_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.remove_hex_overlay'''(''location'', [''filename''])

Removes all the overlays at the given location, including any added by '''wesnoth.interface.add_item_halo''' or '''wesnoth.interface.add_item_image''' (however, such a removal will not be kept over save/load cycles). If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_hex_overlay(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.end_turn'''([''next_side''])

Immediately ends the current side's turn. By default, the next sequential side will gain control, but if you pass an argument that side gains control instead.

The ''next_side'' can either be a valid side number, or a valid side number plus the total number of sides in the scenario. In the latter case, this function also increases the turn counter by 1.

Using this, it's entirely possible to pass control around without ever increasing the turn counter.

=== wesnoth.interface.allow_end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''allow'')
* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''reason'')

Enables or disables ending the turn in the UI. You can optionally pass a translatable string to show to the player if they attempt to do so anyway. It will be shown to the player without any additional framing, so it should normally be phrased similar to "You cannot end your turn because...".

To allow the player to end their turn again, just pass '''true'''. If you pass '''false''', a default message will be shown.

=== wesnoth.interface.color_adjust ===

* {{LuaGameOnly}} '''wesnoth.interface.color_adjust'''(''red'', ''green'', ''blue'')

Adjust the screen tint. (0,0,0) is no tint, and possible values range from -255 to 255.

=== wesnoth.interface.add_overlay_text ===

{{DevFeature1.17|3}}

* {{LuaGameOnly}} '''wesnoth.interface.add_overlay_text'''(''text'' [, ''options'']) → ''text handle''

Adds a text overlay to the screen that does not move with the map. [[Pango formatting]] is supported. The ''options'' table supports the following keys:

* ''size'' - The font size.
* ''max_width'' - Sets the maximum width the text can occupy on the screen, either in screen units (pixels) or as a percentage (a string ending in <tt>%</tt>). If the text is too long to fit in that width, it will automatically be word-wrapped. Defaults to 100%.
* ''color'' - The text color, either as a six-digit hex string (no leading <tt>#</tt>) or an array of three integers (red, green, and blue).
* ''bgcolor'' - If present, a background in this color is placed behind the text to enhance readability. This works like the background behind chat messages, but can be any colour. It is formatted the same as ''color''. If omitted, the background is fully transparent (ie, there is no background).
* ''bgalpha'' - If a background colour is specified, this sets its transparency. The default is fully opaque.
* ''duration'' - How long the text should be displayed, in milliseconds, or the string <syntaxhighlight lang=lua inline>'unlimited'</syntaxhighlight> for an infinite duration. Defaults to two seconds.
* ''fade_time'' - When the label is removed, either explicitly or because its duration expired, this is the time it takes to fade out, in milliseconds. A value of 0 means the label disappears instantly. Defaults to 100.
* ''halign'' - Where to anchor the text horizontally on the screen. Must be one of <syntaxhighlight lang=lua inline>'left', 'center', 'right'</syntaxhighlight>.
* ''valign'' - Where to anchor the text vertically on the screen. Must be one of <syntaxhighlight lang=lua inline>'top', 'center', 'bottom'</syntaxhighlight>.
* ''location'' - The screen offset where the text should be placed, relative to the specified anchor. Defaults to (0,0).

The text handle returned from this function supports the following method calls:

* ''handle'':'''move'''(''x'', ''y'')

Moves the text to a new location on the screen. The provided ''x'' and ''y'' are offsets from its current location.

* ''handle'':'''remove'''([''fade_time''])

Remove the text from the screen, optionally overriding the fade-out time.

* ''handle'':'''replace'''(''text'', ''options'') → ''handle''

Replaces the text with new text. Options are the same as in ''add_overlay_text'', and the returned handle is the same one.

=== wesnoth.interface.handle_user_interact ===

{{DevFeature1.17|6}}

* {{LuaGameOnly}} '''wesnoth.interface.handle_user_interact'''()

Handle user interaction with the game interface. This can be inserted into Lua code that takes a long time to execute in order to prevent the user interface from freezing.

== wesnoth.interface.game_display ==

* {{LuaGameOnly}} '''wesnoth.interface.game_display'''.''theme_item'' ↔ '''function'''() → ''wml table of theme elements''

This is an associative table linking item names to functions that describe the content of the in-game user interface. These functions are called with no arguments whenever the user interface is refreshed, and must return a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a '''help''' field that points to the help section that is displayed when the user clicks on the theme item.

Note that the '''wesnoth.interface.game_display''' cannot be iterated using '''pairs''' or '''next''' to retrieve the items from the current theme. However, built-in items ''can'' be recovered as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

<syntaxhighlight lang=lua>
local old_unit_status = wesnoth.interface.game_display.unit_status
function wesnoth.interface.game_display.unit_status()
local _ = wesnoth.textdomain "mydomain"
local u = wesnoth.interface.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, wml.tag.element {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
})
end
return s
end
</syntaxhighlight>

The things that would need to be to modified in the above code are:

* the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
* the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
* the path to the image ("entangled.png").
* the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in '''wesnoth.interface.game_display''' which will have an effect in the game, together with sample output and a brief description of their use.

=== unit_name ===

Shows the name of the unit the mouse is hovering over.

=== unit_type ===

Shows the type of the unit the mouse is hovering over.

=== unit_race ===

Shows the race of the unit the mouse is hovering over.

=== unit_side ===

Shows the side number and team color of the unit the mouse is hovering over.

=== unit_level ===

Shows the level of the unit the mouse is hovering over.

=== unit_amla ===

Similar to unit_advancement_options but shows AMLAs only.

=== unit_traits ===

Shows the list of trait names for the unit the mouse is hovering over.

=== unit_status ===

Shows the status icons for statuses afflicting the unit the mouse is hovering over.

=== unit_alignment ===

Shows the alignment of the unit the mouse is hovering over.

=== unit_abilities ===

Shows the ability names of the unit the mouse is hovering over.

=== unit_hp ===

Shows the current and maximum hit points of the unit the mouse is hovering over.

=== unit_xp ===

Shows the current and target experience points of the unit the mouse is hovering over.

=== unit_advancement_options ===

Shows the options the unit the mouse is hovering over has for advancement, including both level ups and AMLAs. This item is not used in the default theme.

=== unit_defense ===

Shows the defense of the unit the mouse is hovering over.

=== unit_vision ===

Shows the current and maximum vision points of the unit the mouse is hovering over.

=== unit_moves ===

Shows the current and maximum movement points of the unit the mouse is hovering over.

=== unit_weapons ===

Shows the available weapons of the unit the mouse is hovering over. The default generator expresses each weapon line (basic details, specials, etc) as a separate <code>element</code>. For example:

<syntaxhighlight lang=wml>
[element]
image="melee.png"
tooltip="...stuff..."
[/element]
[element]
image="arcane.png"
tooltip="...stuff..."
[/element]
[element]
text="6×3 holy sword"
tooltip="...stuff..."
[/element]
[element]
# This is empty if the range and type icons both exist.
text="melee-arcane"
tooltip="...stuff..."
[/element]
# If the weapon has accuracy or parry...
[element]
text="+20%/-10%"
tooltip="Accuracy: +20%
Parry: -10%
"
[/element]
# If the weapon has special abilities...
[element]
text="magical"
tooltip="...stuff..."
[/element]
</syntaxhighlight>

=== unit_image ===

Shows the sprite of the unit the mouse is hovering over.

=== unit_profile ===

Shows the portrait of the unit the mouse is hovering over.

=== selected_unit ===

Nearly every item beginning with '''unit_''' has a corresponding item beginning with '''selected_unit_''', which describes the currently-selected unit (if any) rather than the unit the mouse is hovering over. These items are not used in the default theme.

There is no '''selected_unit_amla''' however.

=== highlighted_unit_weapons ===

This is almost the same as '''selected_unit_weapons''' but with slightly different logic of choosing which unit to show.

=== tod_stats and selected_tod_stats ===

Shows the time of day stats for the hex the mouse is hovering over or the hex the selected unit is on. The time of day stats shows the counter of your position in the schedule as well as the entire cycle.

=== time_of_day and selected_time_of_day ===

Shows the time of day image for the hex the mouse is hovering over or the hex the selected unit is on.

=== unit_box ===

This is an experimental item that combines a unit display and the time of day.

=== turn ===

Shows the current turn count.

=== gold ===

Shows the amount of gold for the active side.

=== villages ===

Shows the number of villages owned by the active side.

=== num_units ===

Shows the number of units owned by the active side.

=== upkeep ===

Shows the upkeep and expenses for the active side.

=== income ===

Shows the income for the active side

=== terrain_info ===

Shows the icons of the terrain on hex the mouse is hovering over.

=== terrain  ===



Shows the name of the terrain on the hex the mouse is hovering over. For example:

<syntaxhighlight lang=wml>
[element]
text="Grassland (Flat)"
[/element]
</syntaxhighlight>

=== position ===

Shows the map coordinates of the hex the mouse is hovering over.

=== zoom_level ===

Shows the zoom level as a percentage. This item is not used in the default theme.

=== side_playing ===

Shows the active side's flag.

=== observers ===

When there is no observer, it returns an empty table. When there are observers, it returns:

<syntaxhighlight lang=wml>
[element]
tooltip="Observers
<observer1>
<observer2>
"
image="misc/eye.png"
[/element]
</syntaxhighlight>

=== report_clock ===

This returns the current time in HH:MM format according to the user's preferences, for example:

<syntaxhighlight lang=wml>
[element]
text="22:32"
[/element]
</syntaxhighlight>

=== report_countdown ===

This returns the current chess-timer countdown in MM:SS format for the player's turn, for example:

<syntaxhighlight lang=wml>
[element]
text="12:43"
[/element]
</syntaxhighlight>

Depending on the time limit, the text may also be colored using [[Pango formatting|Pango markup]].

If there is no time limit set then it forwards to [[#wesnoth.interface.game_display.report_clock|report_clock]].

[[Category:Lua Reference]]

UnitTypeWML

2024-08-27T11:39:56Z

ZombieKnight: /* Attacks */

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

UnitTypeWML

2024-08-27T11:39:21Z

ZombieKnight: /* Attacks */

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

UnitTypeWML

2024-08-27T11:38:53Z

ZombieKnight: /* Attacks */

{{WML Tags}}

__TOC__

== Unit Type ==

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub.
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.

== Other tags ==
* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.

* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.
* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

Template:Lua Functions

2024-08-08T06:37:50Z

ZombieKnight:

{| class="reference-sidebar"
|
[[{{SERVER}}{{localurl:Template:Lua Functions|action=edit}} edit]]'''Lua Functions'''
|-
|''wesnoth''
[[LuaAPI/wesnoth#wesnoth.as_text|wesnoth.as_text]] 
[[LuaAPI/wesnoth#wesnoth.colors|wesnoth.colors]] 
[[LuaAPI/wesnoth#wesnoth.compile_formula|wesnoth.compile_formula]] 
[[LuaAPI/wesnoth#wesnoth.current|wesnoth.current]] 
[[LuaAPI/wesnoth#wesnoth.current_version|wesnoth.current_version]] 
[[LuaAPI/wesnoth#wesnoth.custom_synced_commands|wesnoth.custom_synced_commands]] 
[[LuaAPI/wesnoth#wesnoth.deprecate_api|wesnoth.deprecate_api]] 
[[LuaAPI/wesnoth#wesnoth.deprecated_message|wesnoth.deprecated_message]] 
[[LuaAPI/wesnoth#wesnoth.dofile|wesnoth.dofile]] 
[[LuaAPI/wesnoth#wesnoth.effects|wesnoth.effects]] 
[[LuaAPI/wesnoth#wesnoth.eval_formula|wesnoth.eval_formula]] 
[[LuaAPI/wesnoth#wesnoth.game_config|wesnoth.game_config]] 
[[LuaAPI/wesnoth#wesnoth.get_language|wesnoth.get_language]] 
[[LuaAPI/wesnoth#wesnoth.log|wesnoth.log]] 
[[LuaAPI/wesnoth#wesnoth.micro_ais|wesnoth.micro_ais]] 
[[LuaAPI/wesnoth#wesnoth.ms_since_init|wesnoth.ms_since_init]] 
[[LuaAPI/wesnoth#wesnoth.name_generator|wesnoth.name_generator]] 
[[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]] 
[[LuaAPI/wesnoth#wesnoth.persistent_tags|wesnoth.persistent_tags]] 
[[LuaAPI/wesnoth#wesnoth.print_attributes|wesnoth.print_attributes]] 
[[LuaAPI/wesnoth#wesnoth.races|wesnoth.races]] 
[[LuaAPI/wesnoth#wesnoth.require|wesnoth.require]] 
[[LuaAPI/wesnoth#wesnoth.scenario|wesnoth.scenario]] 
[[LuaAPI/wesnoth#wesnoth.simulate_combat|wesnoth.simulate_combat]] 
[[LuaAPI/wesnoth#wesnoth.terrain_types|wesnoth.terrain_types]] 
[[LuaAPI/wesnoth#wesnoth.textdomain|wesnoth.textdomain]] 
[[LuaAPI/wesnoth#wesnoth.type|wesnoth.type]] 
[[LuaAPI/wesnoth#wesnoth.unit_types|wesnoth.unit_types]] 
[[LuaAPI/wesnoth#wesnoth.version|wesnoth.version]] 
[[LuaAPI/wesnoth#wesnoth.wml_actions|wesnoth.wml_actions]] 
[[LuaAPI/wesnoth#wesnoth.wml_conditionals|wesnoth.wml_conditionals]] 
|-
|''wesnoth.achievements''
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.get|wesnoth.achievements.get]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has|wesnoth.achievements.has]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.has_sub_achievement|wesnoth.achievements.has_sub_achievement]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.progress|wesnoth.achievements.progress]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set|wesnoth.achievements.set]] 
[[LuaAPI/wesnoth/achievements#wesnoth.achievements.set_sub_achievement|wesnoth.achievements.set_sub_achievement]] 
|-
|''wesnoth.audio''
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list|wesnoth.audio.music_list]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.add|wesnoth.audio.music_list.add]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.all|wesnoth.audio.music_list.all]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.clear|wesnoth.audio.music_list.clear]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.current|wesnoth.audio.music_list.current]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.next|wesnoth.audio.music_list.next]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.play|wesnoth.audio.music_list.play]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.previous|wesnoth.audio.music_list.previous]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.remove|wesnoth.audio.music_list.remove]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.music_list.volume|wesnoth.audio.music_list.volume]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.play|wesnoth.audio.play]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.sources|wesnoth.audio.sources]] 
[[LuaAPI/wesnoth/audio#wesnoth.audio.volume|wesnoth.audio.volume]] 
|-
|''wesnoth.game_events''
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add|wesnoth.game_events.add]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_menu|wesnoth.game_events.add_menu]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_repeating|wesnoth.game_events.add_repeating]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.add_wml|wesnoth.game_events.add_wml]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire_by_id|wesnoth.game_events.fire_by_id]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_event|wesnoth.game_events.on_event]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_load|wesnoth.game_events.on_load]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_action|wesnoth.game_events.on_mouse_action]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_button|wesnoth.game_events.on_mouse_button]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_mouse_move|wesnoth.game_events.on_mouse_move]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.on_save|wesnoth.game_events.on_save]] 
[[LuaAPI/wesnoth/game_events#wesnoth.game_events.remove|wesnoth.game_events.remove]] 
|-
|''wesnoth.interface''
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_chat_message|wesnoth.interface.add_chat_message]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_hex_overlay|wesnoth.interface.add_hex_overlay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_halo|wesnoth.interface.add_item_halo]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_item_image|wesnoth.interface.add_item_image]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.add_overlay_text|wesnoth.interface.add_overlay_text]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.allow_end_turn|wesnoth.interface.allow_end_turn]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.clear_chat_messages|wesnoth.interface.clear_chat_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.color_adjust|wesnoth.interface.color_adjust]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.delay|wesnoth.interface.delay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.deselect_hex|wesnoth.interface.deselect_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.end_turn|wesnoth.interface.end_turn]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.float_label|wesnoth.interface.float_label]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit|wesnoth.interface.get_displayed_unit]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_hovered_hex|wesnoth.interface.get_hovered_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_items|wesnoth.interface.get_items]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_selected_hex|wesnoth.interface.get_selected_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.get_viewing_side|wesnoth.interface.get_viewing_side]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.handle_user_interact|wesnoth.interface.handle_user_interact]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.highlight_hex|wesnoth.interface.highlight_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_locked|wesnoth.interface.is_locked]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.is_skipping_messages|wesnoth.interface.is_skipping_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.lock|wesnoth.interface.lock]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_hex_overlay|wesnoth.interface.remove_hex_overlay]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.remove_item|wesnoth.interface.remove_item]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll|wesnoth.interface.scroll]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex|wesnoth.interface.scroll_to_hex]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.select_unit|wesnoth.interface.select_unit]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.skip_messages|wesnoth.interface.skip_messages]] 
[[LuaAPI/wesnoth/interface#wesnoth.interface.zoom|wesnoth.interface.zoom]] 
|-
|''wesnoth.map''
[[LuaAPI/wesnoth/map#wesnoth.map.add_label|wesnoth.map.add_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.are_hexes_adjacent|wesnoth.map.are_hexes_adjacent]] 
[[LuaAPI/wesnoth/map#wesnoth.map.create|wesnoth.map.create]] 
[[LuaAPI/wesnoth/map#wesnoth.map.distance_between|wesnoth.map.distance_between]] 
[[LuaAPI/wesnoth/map#wesnoth.map.find|wesnoth.map.find]] 
[[LuaAPI/wesnoth/map#wesnoth.map.generate|wesnoth.map.generate]] 
[[LuaAPI/wesnoth/map#wesnoth.map.generate_height_map|wesnoth.map.generate_height_map]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get|wesnoth.map.get]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_adjacent_hexes|wesnoth.map.get_adjacent_hexes]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_area|wesnoth.map.get_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_direction|wesnoth.map.get_direction]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_hexes_in_radius|wesnoth.map.get_hexes_in_radius]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_label|wesnoth.map.get_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_owner|wesnoth.map.get_owner]] 
[[LuaAPI/wesnoth/map#wesnoth.map.get_relative_dir|wesnoth.map.get_relative_dir]] 
[[LuaAPI/wesnoth/map#wesnoth.map.iter|wesnoth.map.iter]] 
[[LuaAPI/wesnoth/map#wesnoth.map.make_bitmap|wesnoth.map.make_bitmap]] 
[[LuaAPI/wesnoth/map#wesnoth.map.matches|wesnoth.map.matches]] 
[[LuaAPI/wesnoth/map#wesnoth.map.on_board|wesnoth.map.on_board]] 
[[LuaAPI/wesnoth/map#wesnoth.map.on_border|wesnoth.map.on_border]] 
[[LuaAPI/wesnoth/map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]] 
[[LuaAPI/wesnoth/map#wesnoth.map.place_area|wesnoth.map.place_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.read_location|wesnoth.map.read_location]] 
[[LuaAPI/wesnoth/map#wesnoth.map.remove_area|wesnoth.map.remove_area]] 
[[LuaAPI/wesnoth/map#wesnoth.map.remove_label|wesnoth.map.remove_label]] 
[[LuaAPI/wesnoth/map#wesnoth.map.rotate_right_around_center|wesnoth.map.rotate_right_around_center]] 
[[LuaAPI/wesnoth/map#wesnoth.map.set_owner|wesnoth.map.set_owner]] 
[[LuaAPI/wesnoth/map#wesnoth.map.split_terrain_code|wesnoth.map.split_terrain_code]] 
[[LuaAPI/wesnoth/map#wesnoth.map.terrain_mask|wesnoth.map.terrain_mask]] 
|-
|''wesnoth.paths''
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_cost_map|wesnoth.paths.find_cost_map]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_path|wesnoth.paths.find_path]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_reach|wesnoth.paths.find_reach]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vacant_hex|wesnoth.paths.find_vacant_hex]] 
[[LuaAPI/wesnoth/paths#wesnoth.paths.find_vision_range|wesnoth.paths.find_vision_range]] 
|-
|''wesnoth.schedule''
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_illumination|wesnoth.schedule.get_illumination]] 
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.get_time_of_day|wesnoth.schedule.get_time_of_day]] 
[[LuaAPI/wesnoth/schedule#wesnoth.schedule.replace|wesnoth.schedule.replace]] 
|-
|''wesnoth.sides''
[[LuaAPI/wesnoth/sides#wesnoth.sides.add_ai_component|wesnoth.sides.add_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.append_ai|wesnoth.sides.append_ai]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.change_ai_component|wesnoth.sides.change_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.create|wesnoth.sides.create]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.debug_ai|wesnoth.sides.debug_ai]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.delete_ai_component|wesnoth.sides.delete_ai_component]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.find|wesnoth.sides.find]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.get|wesnoth.sides.get]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_enemy|wesnoth.sides.is_enemy]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_fogged|wesnoth.sides.is_fogged]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.is_shrouded|wesnoth.sides.is_shrouded]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.iter|wesnoth.sides.iter]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.matches|wesnoth.sides.matches]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.override_shroud|wesnoth.sides.override_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_fog|wesnoth.sides.place_fog]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.place_shroud|wesnoth.sides.place_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_fog|wesnoth.sides.remove_fog]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.remove_shroud|wesnoth.sides.remove_shroud]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.set_id|wesnoth.sides.set_id]] 
[[LuaAPI/wesnoth/sides#wesnoth.sides.switch_ai|wesnoth.sides.switch_ai]] 
|-
|''wesnoth.sync''
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_multiple|wesnoth.sync.evaluate_multiple]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.evaluate_single|wesnoth.sync.evaluate_single]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]] 
[[LuaAPI/wesnoth/sync#wesnoth.sync.run_unsynced|wesnoth.sync.run_unsynced]] 
|-
|''wesnoth.units''
[[LuaAPI/wesnoth/units#wesnoth.units.resistance_against|wesnoth.units.resistance_against]] 
[[LuaAPI/wesnoth/units#wesnoth.units.ability|wesnoth.units.ability]] 
[[LuaAPI/wesnoth/units#wesnoth.units.add_modification|wesnoth.units.add_modification]] 
[[LuaAPI/wesnoth/units#wesnoth.units.advance|wesnoth.units.advance]] 
[[LuaAPI/wesnoth/units#wesnoth.units.chance_to_be_hit|wesnoth.units.chance_to_be_hit]] 
[[LuaAPI/wesnoth/units#wesnoth.units.clone|wesnoth.units.clone]] 
[[LuaAPI/wesnoth/units#wesnoth.units.create|wesnoth.units.create]] 
[[LuaAPI/wesnoth/units#wesnoth.units.create_animator|wesnoth.units.create_animator]] 
[[LuaAPI/wesnoth/units#wesnoth.units.defense_on|wesnoth.units.defense_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.erase|wesnoth.units.erase]] 
[[LuaAPI/wesnoth/units#wesnoth.units.extract|wesnoth.units.extract]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find|wesnoth.units.find]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_attack|wesnoth.units.find_attack]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_map|wesnoth.units.find_on_map]] 
[[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] 
[[LuaAPI/wesnoth/units#wesnoth.units.get|wesnoth.units.get]] 
[[LuaAPI/wesnoth/units#wesnoth.units.get_hovered|wesnoth.units.get_hovered]] 
[[LuaAPI/wesnoth/units#wesnoth.units.jamming_on|wesnoth.units.jamming_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.matches|wesnoth.units.matches]] 
[[LuaAPI/wesnoth/units#wesnoth.units.movement_on|wesnoth.units.movement_on]] 
[[LuaAPI/wesnoth/units#wesnoth.units.remove_modifications|wesnoth.units.remove_modifications]] 
[[LuaAPI/wesnoth/units#wesnoth.units.scroll_to|wesnoth.units.scroll_to]] 
[[LuaAPI/wesnoth/units#wesnoth.units.select|wesnoth.units.select]] 
[[LuaAPI/wesnoth/units#wesnoth.units.to_map|wesnoth.units.to_map]] 
[[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] 
[[LuaAPI/wesnoth/units#wesnoth.units.transform|wesnoth.units.transform]] 
[[LuaAPI/wesnoth/units#wesnoth.units.vision_on|wesnoth.units.vision_on]] 
|-
|''ai''
[[LuaAPI/ai#ai.aspects|ai.aspects]] 
[[LuaAPI/ai#ai.attack|ai.attack]] 
[[LuaAPI/ai#ai.check_attack|ai.check_attack]] 
[[LuaAPI/ai#ai.check_move|ai.check_move]] 
[[LuaAPI/ai#ai.check_recall|ai.check_recall]] 
[[LuaAPI/ai#ai.check_recruit|ai.check_recruit]] 
[[LuaAPI/ai#ai.check_stopunit|ai.check_stopunit]] 
[[LuaAPI/ai#ai.fallback_human|ai.fallback_human]] 
[[LuaAPI/ai#ai.get_attacks|ai.get_attacks]] 
[[LuaAPI/ai#ai.get_targets|ai.get_targets]] 
[[LuaAPI/ai#ai.move|ai.move]] 
[[LuaAPI/ai#ai.move_full|ai.move_full]] 
[[LuaAPI/ai#ai.read_only|ai.read_only]] 
[[LuaAPI/ai#ai.recall|ai.recall]] 
[[LuaAPI/ai#ai.recruit|ai.recruit]] 
[[LuaAPI/ai#ai.side|ai.side]] 
[[LuaAPI/ai#ai.stopunit_all|ai.stopunit_all]] 
[[LuaAPI/ai#ai.stopunit_attacks|ai.stopunit_attacks]] 
[[LuaAPI/ai#ai.stopunit_moves|ai.stopunit_moves]] 
[[LuaAPI/ai#ai.suitable_keep|ai.suitable_keep]] 
|-
|''filesystem''
[[LuaAPI/filesystem#filesystem.canonical_path|filesystem.canonical_path]] 
[[LuaAPI/filesystem#filesystem.have_asset|filesystem.have_asset]] 
[[LuaAPI/filesystem#filesystem.have_file|filesystem.have_file]] 
[[LuaAPI/filesystem#filesystem.image_size|filesystem.image_size]] 
[[LuaAPI/filesystem#filesystem.read_file|filesystem.read_file]] 
[[LuaAPI/filesystem#filesystem.resolve_asset|filesystem.resolve_asset]] 
|-
|''functional''
[[LuaAPI/functional#functional.choose|functional.choose]] 
[[LuaAPI/functional#functional.choose_map|functional.choose_map]] 
[[LuaAPI/functional#functional.filter|functional.filter]] 
[[LuaAPI/functional#functional.filter_map|functional.filter_map]] 
[[LuaAPI/functional#functional.find|functional.find]] 
[[LuaAPI/functional#functional.find_map|functional.find_map]] 
[[LuaAPI/functional#functional.map|functional.map]] 
[[LuaAPI/functional#functional.map_array|functional.map_array]] 
[[LuaAPI/functional#functional.reduce|functional.reduce]] 
[[LuaAPI/functional#functional.take_while|functional.take_while]] 
[[LuaAPI/functional#functional.zip|functional.zip]] 
|-
|''gui''
[[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition]] 
[[LuaAPI/gui#gui.get_user_choice|gui.get_user_choice]] 
[[LuaAPI/gui#gui.show_dialog|gui.show_dialog]] 
[[LuaAPI/gui#gui.show_help|gui.show_help]] 
[[LuaAPI/gui#gui.show_inspector|gui.show_inspector]] 
[[LuaAPI/gui#gui.show_lua_console|gui.show_lua_console]] 
[[LuaAPI/gui#gui.show_menu|gui.show_menu]] 
[[LuaAPI/gui#gui.show_narration|gui.show_narration]] 
[[LuaAPI/gui#gui.show_popup|gui.show_popup]] 
[[LuaAPI/gui#gui.show_prompt|gui.show_prompt]] 
[[LuaAPI/gui#gui.show_story|gui.show_story]] 
[[LuaAPI/gui#gui.widget|gui.widget]] 
|-
|''location_set''
[[LuaAPI/location_set#location_set.clear|location_set.clear]] 
[[LuaAPI/location_set#location_set.clone|location_set.clone]] 
[[LuaAPI/location_set#location_set.create|location_set.create]] 
[[LuaAPI/location_set#location_set.diff|location_set.diff]] 
[[LuaAPI/location_set#location_set.empty|location_set.empty]] 
[[LuaAPI/location_set#location_set.filter|location_set.filter]] 
[[LuaAPI/location_set#location_set.get|location_set.get]] 
[[LuaAPI/location_set#location_set.insert|location_set.insert]] 
[[LuaAPI/location_set#location_set.inter|location_set.inter]] 
[[LuaAPI/location_set#location_set.inter_merge|location_set.inter_merge]] 
[[LuaAPI/location_set#location_set.invert|location_set.invert]] 
[[LuaAPI/location_set#location_set.iter|location_set.iter]] 
[[LuaAPI/location_set#location_set.of_map|location_set.of_map]] 
[[LuaAPI/location_set#location_set.of_pairs|location_set.of_pairs]] 
[[LuaAPI/location_set#location_set.of_raw|location_set.of_raw]] 
[[LuaAPI/location_set#location_set.of_shroud_data|location_set.of_shroud_data]] 
[[LuaAPI/location_set#location_set.of_triples|location_set.of_triples]] 
[[LuaAPI/location_set#location_set.of_wml_var|location_set.of_wml_var]] 
[[LuaAPI/location_set#location_set.random|location_set.random]] 
[[LuaAPI/location_set#location_set.remove|location_set.remove]] 
[[LuaAPI/location_set#location_set.size|location_set.size]] 
[[LuaAPI/location_set#location_set.stable_iter|location_set.stable_iter]] 
[[LuaAPI/location_set#location_set.symm|location_set.symm]] 
[[LuaAPI/location_set#location_set.to_map|location_set.to_map]] 
[[LuaAPI/location_set#location_set.to_pairs|location_set.to_pairs]] 
[[LuaAPI/location_set#location_set.to_shroud_data|location_set.to_shroud_data]] 
[[LuaAPI/location_set#location_set.to_stable_pairs|location_set.to_stable_pairs]] 
[[LuaAPI/location_set#location_set.to_triples|location_set.to_triples]] 
[[LuaAPI/location_set#location_set.to_wml_var|location_set.to_wml_var]] 
[[LuaAPI/location_set#location_set.union|location_set.union]] 
[[LuaAPI/location_set#location_set.union_merge|location_set.union_merge]] 
|-
|''mathx''
[[LuaAPI/mathx#mathx.clamp|mathx.clamp]] 
[[LuaAPI/mathx#mathx.lerp|mathx.lerp]] 
[[LuaAPI/mathx#mathx.random|mathx.random]] 
[[LuaAPI/mathx#mathx.random_choice|mathx.random_choice]] 
[[LuaAPI/mathx#mathx.round|mathx.round]] 
[[LuaAPI/mathx#mathx.shuffle|mathx.shuffle]] 
|-
|''stringx''
[[LuaAPI/stringx#stringx.anim_split|stringx.anim_split]] 
[[LuaAPI/stringx#stringx.escaped_split|stringx.escaped_split]] 
[[LuaAPI/stringx#stringx.format_conjunct_list|stringx.format_conjunct_list]] 
[[LuaAPI/stringx#stringx.format_disjunct_list|stringx.format_disjunct_list]] 
[[LuaAPI/stringx#stringx.iter_range|stringx.iter_range]] 
[[LuaAPI/stringx#stringx.iter_ranges|stringx.iter_ranges]] 
[[LuaAPI/stringx#stringx.join|stringx.join]] 
[[LuaAPI/stringx#stringx.join_map|stringx.join_map]] 
[[LuaAPI/stringx#stringx.map_split|stringx.map_split]] 
[[LuaAPI/stringx#stringx.parenthetical_split|stringx.parenthetical_split]] 
[[LuaAPI/stringx#stringx.parse_range|stringx.parse_range]] 
[[LuaAPI/stringx#stringx.quoted_split|stringx.quoted_split]] 
[[LuaAPI/stringx#stringx.split|stringx.split]] 
[[LuaAPI/stringx#stringx.trim|stringx.trim]] 
[[LuaAPI/stringx#stringx.vformat|stringx.vformat]] 
|-
|''unit_test''
[[LuaAPI/unit_test#unit_test.assert|unit_test.assert]] 
[[LuaAPI/unit_test#unit_test.assert_approx_equal|unit_test.assert_approx_equal]] 
[[LuaAPI/unit_test#unit_test.assert_contains|unit_test.assert_contains]] 
[[LuaAPI/unit_test#unit_test.assert_equal|unit_test.assert_equal]] 
[[LuaAPI/unit_test#unit_test.assert_greater|unit_test.assert_greater]] 
[[LuaAPI/unit_test#unit_test.assert_greater_equal|unit_test.assert_greater_equal]] 
[[LuaAPI/unit_test#unit_test.assert_in_range|unit_test.assert_in_range]] 
[[LuaAPI/unit_test#unit_test.assert_less|unit_test.assert_less]] 
[[LuaAPI/unit_test#unit_test.assert_less_equal|unit_test.assert_less_equal]] 
[[LuaAPI/unit_test#unit_test.assert_not_equal|unit_test.assert_not_equal]] 
[[LuaAPI/unit_test#unit_test.assert_nothrow|unit_test.assert_nothrow]] 
[[LuaAPI/unit_test#unit_test.assert_throws|unit_test.assert_throws]] 
[[LuaAPI/unit_test#unit_test.assert_throws_with|unit_test.assert_throws_with]] 
[[LuaAPI/unit_test#unit_test.fail|unit_test.fail]] 
[[LuaAPI/unit_test#unit_test.finish|unit_test.finish]] 
[[LuaAPI/unit_test#unit_test.fire_wml_menu_item|unit_test.fire_wml_menu_item]] 
[[LuaAPI/unit_test#unit_test.log|unit_test.log]] 
[[LuaAPI/unit_test#unit_test.succeed|unit_test.succeed]] 
[[LuaAPI/unit_test#unit_test.tostring|unit_test.tostring]] 
|-
|''wml''
[[LuaAPI/wml#wml.all_variables|wml.all_variables]] 
[[LuaAPI/wml#wml.array_access.get|wml.array_access.get]] 
[[LuaAPI/wml#wml.array_access.get_proxy|wml.array_access.get_proxy]] 
[[LuaAPI/wml#wml.array_access.set|wml.array_access.set]] 
[[LuaAPI/wml#wml.array_variables|wml.array_variables]] 
[[LuaAPI/wml#wml.attribute_count|wml.attribute_count]] 
[[LuaAPI/wml#wml.child_array|wml.child_array]] 
[[LuaAPI/wml#wml.child_count|wml.child_count]] 
[[LuaAPI/wml#wml.child_range|wml.child_range]] 
[[LuaAPI/wml#wml.clone|wml.clone]] 
[[LuaAPI/wml#wml.diff|wml.diff]] 
[[LuaAPI/wml#wml.equal|wml.equal]] 
[[LuaAPI/wml#wml.error|wml.error]] 
[[LuaAPI/wml#wml.eval_conditional|wml.eval_conditional]] 
[[LuaAPI/wml#wml.find_child|wml.find_child]] 
[[LuaAPI/wml#wml.fire|wml.fire]] 
[[LuaAPI/wml#wml.get_child|wml.get_child]] 
[[LuaAPI/wml#wml.get_nth_child|wml.get_nth_child]] 
[[LuaAPI/wml#wml.interpolate|wml.interpolate]] 
[[LuaAPI/wml#wml.literal|wml.literal]] 
[[LuaAPI/wml#wml.load|wml.load]] 
[[LuaAPI/wml#wml.matches_filter|wml.matches_filter]] 
[[LuaAPI/wml#wml.merge|wml.merge]] 
[[LuaAPI/wml#wml.parse|wml.parse]] 
[[LuaAPI/wml#wml.parsed|wml.parsed]] 
[[LuaAPI/wml#wml.patch|wml.patch]] 
[[LuaAPI/wml#wml.remove_child|wml.remove_child]] 
[[LuaAPI/wml#wml.remove_children|wml.remove_children]] 
[[LuaAPI/wml#wml.shallow_literal|wml.shallow_literal]] 
[[LuaAPI/wml#wml.shallow_parsed|wml.shallow_parsed]] 
[[LuaAPI/wml#wml.tag|wml.tag]] 
[[LuaAPI/wml#wml.tostring|wml.tostring]] 
[[LuaAPI/wml#wml.tovconfig|wml.tovconfig]] 
[[LuaAPI/wml#wml.valid|wml.valid]] 
[[LuaAPI/wml#wml.variables|wml.variables]] 
[[LuaAPI/wml#wml.variables_proxy|wml.variables_proxy]] 
|-
|''wml-utils''
[[LuaAPI/wml-utils#utils.check_key|utils.check_key]] 
[[LuaAPI/wml-utils#utils.get_sides|utils.get_sides]] 
[[LuaAPI/wml-utils#utils.handle_event_commands|utils.handle_event_commands]] 
[[LuaAPI/wml-utils#utils.optional_side_filter|utils.optional_side_filter]] 
[[LuaAPI/wml-utils#utils.scoped_var|utils.scoped_var]] 
[[LuaAPI/wml-utils#utils.set_exiting|utils.set_exiting]] 
[[LuaAPI/wml-utils#utils.vwriter|utils.vwriter]] 
|}<includeonly>[[Category:Lua Reference]]</includeonly><noinclude>A box with all the Lua functions, each one linking to the page and section they are described in. It was generated using [[/Updating|this method]]. This box should be included in [[LuaAPI|Lua reference]] page.</noinclude>

LuaAPI/wesnoth/units

2024-08-07T18:00:42Z

ZombieKnight:

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

The entire units module is only available in the game. It is not available to plugins or map generators.

== Functions ==

=== wesnoth.units.advance ===

* {{LuaGameOnly}} '''wesnoth.units.advance'''(''unit'', [''animate'', ''fire_events''])
* {{LuaGameOnly}} ''unit'':'''advance'''([''animate'', ''fire_events''])

Advances the unit (and shows the advance unit dialog if needed) if the unit has enough XP. This function should be called after modifying the unit's experience directly. A similar function is called by Wesnoth internally after unit combat. The second argument is a boolean value that specifies whether the advancement should be animated. The third argument is a boolean value that specifies whether advancement related events should be fired.

This function only works for units on the map.

This function can also trigger multiple advancements if the unit has enough XP.

=== wesnoth.units.clone ===

* {{LuaGameOnly}} '''wesnoth.units.clone'''(''unit'') → ''copy of unit''
* {{LuaGameOnly}} ''unit'':'''clone'''()

Creates a private unit from another unit.

<syntaxhighlight lang='lua'>
-- extract a unit from the map
local u = wesnoth.units.find_on_map{ type = "Thug" }[1]:clone()
wesnoth.units.erase(u.x, u.y) -- note: not the same as u:erase(), which would be an error
-- u is still valid at this point
</syntaxhighlight>

=== wesnoth.units.erase ===

* {{LuaGameOnly}} '''wesnoth.units.erase'''(''unit'')
* {{LuaGameOnly}} '''wesnoth.units.erase'''(''x'', ''y'')
* {{LuaGameOnly}} ''unit'':'''erase'''()

Erases a unit from the map. After calling this on a unit, the unit is no longer valid. Does not work on private units - this usage will raise an error.

=== wesnoth.units.extract ===

* {{LuaGameOnly}} '''wesnoth.units.extract'''(''unit'')
* {{LuaGameOnly}} ''unit'':'''extract'''()

Removes a unit from the map or from a recall list and makes it private.

<syntaxhighlight lang='lua'>
-- remove all the units from the recall list of side 1 and put them in a WML container
local list = {}
for i,u in ipairs(wesnoth.units.find_on_recall{ side = 1 }) do
u:extract()
table.insert(list, u.__cfg)
end
wml.array_access.set("player_recall_list", list)
</syntaxhighlight>

Note: if the unit is on the map, this is just a shortcut for calling [[#wesnoth.units.clone]] and then [[#wesnoth.units.erase]]. It is, however, the only way to remove a unit from a recall list without putting it on the map.

=== wesnoth.units.matches ===

* {{LuaGameOnly}} '''wesnoth.units.matches'''(''unit'', ''filter'', [''other_unit'']) → ''matched?''
* {{LuaGameOnly}} '''wesnoth.units.matches'''(''unit'', ''filter'', [''location'']) → ''matched?''
* {{LuaGameOnly}} ''unit'':'''matches'''(''filter'', [''other_unit'']) → ''matched?''
* {{LuaGameOnly}} ''unit'':'''matches'''(''filter'', [''location'']) → ''matched?''

Returns true if the given unit matches the WML filter passed as the second argument. If ''other_unit'' is specified, it is used for the ''$other_unit'' auto-stored variable in the filter. Otherwise, this variable is not stored for the filter. If an extra ''location'' is specified, the filter matches as if the unit were at that location.

<syntaxhighlight lang='lua'>
assert(unit.canrecruit == wesnoth.units.matches(unit, { canrecruit = true }))
</syntaxhighlight>

=== wesnoth.units.find_attack ===

* {{LuaGameOnly}} '''wesnoth.units.find_attack'''(''unit'', ''filter'') → ''attack''
* {{LuaGameOnly}} ''unit'':'''find_attack'''(''filter'') → ''attack''

Returns the first attack that matches the given [[StandardWeaponFilter]].

=== wesnoth.units.to_map ===

* {{LuaGameOnly}} '''wesnoth.units.to_map'''(''unit'')
* {{LuaGameOnly}} '''wesnoth.units.to_map'''(''unit'', ''x'', ''y'')
* {{LuaGameOnly}} ''unit'':'''to_map'''([''x'', ''y''])

Places a unit on the map. This unit is described either by a WML table or by a proxy unit (to use the third form, it must be a proxy). Coordinates can be passed as additional arguments; otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed.

<syntaxhighlight lang='lua'>
-- create a unit with random traits, then erase it
wesnoth.units.to_map({ type = "Elvish Lady" }, 17, 42)
wesnoth.units.erase(17, 42)
</syntaxhighlight>

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.units.create]] and then putting the resulting unit on the map.

<syntaxhighlight lang='lua'>
-- move the leader back to the top-left corner
wesnoth.units.find_on_map({ canrecruit = true })[1]:to_map(1, 1)
</syntaxhighlight>

If x,y is a village, this function does not capture it (as of 1.14). Use [[LuaWML/Sides#wesnoth.set_village_owner|wesnoth.set_village_owner(x, y, unit.side)]] if that's what you want.

'''Caution:''' Using this function will trigger unit placed events. While this may be correct in most cases, there are some cases where it shouldn't, especially if the code is inside the definition of a custom WML tag — it would be an unexpected side-effect from the users point. To work around this, ''false'' can be passed additionally as the last argument. This is what is used internally for some tags such as [move_unit], [harm_unit], [unpetrify] or the feeding ability and is not officially part of the API.

=== wesnoth.units.to_recall ===

* {{LuaGameOnly}} '''wesnoth.units.to_recall'''(''unit'', [''side''])
* {{LuaGameOnly}} ''unit'':'''to_recall'''([''side''])

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit (to use the third form, it must be a proxy). The side of the recall list is given by the second argument if present, or by the side of the unit otherwise.

<syntaxhighlight lang='lua'>
-- put the unit at location 17,42 on the recall list for side 2
wesnoth.units.find_on_map{ x= 17, y = 42 })[1]:to_recall(2)
</syntaxhighlight>

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.units.create]] and then putting the resulting unit on a recall list.

=== wesnoth.units.transform ===

* {{LuaGameOnly}} '''wesnoth.units.transform'''(''unit'', ''to_type'', [''to_variation''])
* {{LuaGameOnly}} ''unit'':'''transform'''(''to_type'', [''to_variation''])

Changes the type of a unit and adjust attributes accordingly. Note that hit points are only changed if necessary to accommodate the new maximum hit points. Poison is automatically removed if the transformed unit is immune.

<syntaxhighlight lang='lua'>
local ev = wesnoth.current.event_context
local u = wesnoth.units.find_on_map{x=ev.x1, y=ev.y1}[1]
u:transform("Spearman")
-- If a full heal is desired:
u.hitpoints = u.max_hitpoints
u.status.poisoned = false
</syntaxhighlight>

=== wesnoth.units.select ===

Alias of [[LuaAPI/wesnoth/interface#wesnoth.interface.select_unit]].

=== wesnoth.units.scroll_to ===

Alias of [[LuaAPI/wesnoth/interface#wesnoth.interface.scroll_to_hex]].

=== wesnoth.units.ability ===

* {{LuaGameOnly}} '''wesnoth.units.ability'''(''unit'', ''ability_tag'') → ''affected''
* {{LuaGameOnly}} ''unit'':'''ability'''(''ability_tag'') → ''affected''

Returns true if the unit is currently affected by an ability with this given tag name. This means that the ability could be owned by the unit itself, or by an adjacent unit.

<syntaxhighlight lang='lua'>
function has_teleport(u)
return u:ability("teleport")
end
</syntaxhighlight>

=== wesnoth.units.chance_to_be_hit ===

* {{LuaGameOnly}} '''wesnoth.units.chance_to_be_hit'''(''unit'', ''terrain_code'') → ''hit chance''
* {{LuaGameOnly}} ''unit'':'''chance_to_be_hit'''(''terrain_code'') → ''hit chance''

Returns the chance that a unit will be hit on a particular terrain (based on its defence).

=== wesnoth.units.defense_on ===

* {{LuaGameOnly}} '''wesnoth.units.defense_on'''(''unit'', ''terrain_code'') → ''defense value''
* {{LuaGameOnly}} ''unit'':'''defense_on'''(''terrain_code'') → ''defense value''

Returns the defense of a unit on a particular terrain. (Note: it is the actual defense. So the lower it is, the weaker the unit is.)

<syntaxhighlight lang='lua'>
local flat_defense = u:defense_on("Gt")
</syntaxhighlight>

=== wesnoth.units.resistance_against ===

* {{LuaGameOnly}} '''wesnoth.units.resistance_against'''(''unit'', ''damage_type'', [''as_attacker''], [''x'', ''y'']) → ''resistance value''
* {{LuaGameOnly}} ''unit'':'''resistance_against'''(''damage_type'', [''as_attacker''], [''x'', ''y'']) → ''resistance value''

Returns the resistance of a unit against an attack type. (Note: it is the actual resistance. So the lower it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

<syntaxhighlight lang='lua'>
local fire_resistance = u:resistance_against("fire")
</syntaxhighlight>

=== wesnoth.units.jamming_on ===

* {{LuaGameOnly}} '''wesnoth.units.jamming_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''jamming_on'''(''terrain_code'') → ''cost''

Returns the jamming cost of a unit on a particular terrain.

<syntaxhighlight lang='lua'>
local jam_cost = u:jamming_on("Gt")
</syntaxhighlight>

=== wesnoth.units.movement_on ===

* {{LuaGameOnly}} '''wesnoth.units.movement_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''movement_on'''(''terrain_code'') → ''cost''

Returns the movement cost of a unit on a particular terrain.

<syntaxhighlight lang='lua'>
local move_cost = u:movement_on("Gt")
</syntaxhighlight>

=== wesnoth.units.vision_on ===

* {{LuaGameOnly}} '''wesnoth.units.vision_on'''(''unit'', ''terrain_code'') → ''cost''
* {{LuaGameOnly}} ''unit'':'''vision_on'''(''terrain_code'') → ''cost''

Returns the vision cost of a unit on a particular terrain.

<syntaxhighlight lang='lua'>
local see_cost = u:vision_on("Gt")
</syntaxhighlight>

=== wesnoth.units.add_modification ===

* {{LuaGameOnly}} '''wesnoth.units.add_modification'''(''unit'', ''type'', ''effects'', [''write_to_mods''])
* {{LuaGameOnly}} ''unit'':'''add_modification'''(''type'', ''effects'', [''write_to_mods''])

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (one of "trait", "object", or "advancement"). The option "advancement" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects. If ''write_to_mods'' false, causes it to not write the modification tag to the unit's [modifications] (as would be done with an [object] with no_write=true).

<syntaxhighlight lang='lua'>
local T = wml.tag
local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
local effects = {
id = "my_effect_id",
T.effect {
apply_to = "image_mod",
replace = "RC(red>blue)"
},
T.effect {
apply_to = "new_animation",
T.standing_animation {
-- AnimationWML
}
}
}
u:add_modification("object", effects)
</syntaxhighlight>

=== wesnoth.units.remove_modifications ===

* {{LuaGameOnly}} '''wesnoth.remove_modifications'''(''unit'', ''filter'', [''type''])
* {{LuaGameOnly}} ''unit'':'''remove_modifications'''(''filter'', [''type''])

Modifies a given unit. The unit needs to be a proxy unit. The second argument is a filter for the modifications to remove. It takes the same syntax as [[FilterWML#Filtering_on_WML_data|[filter_wml]]]; all matching modifications will be removed. The third argument is the type (tag name) of the modifications to search for; it defaults to "object", but you can also pass "trait" or "advancement".

<syntaxhighlight lang='lua'>
local u = wesnoth.units.find_on_map{ canrecruit = true }[1]
u:remove_modifications({ id = "my_effect_id" })
</syntaxhighlight>

=== wesnoth.units.create_animator ===

* {{LuaGameOnly}} '''wesnoth.units.create_animator()'''

Returns an object that can be used to set up and run an animation. The object has three methods:

* ''animator'':'''run()'''

Runs the animation. Implicitly clears the animator.

* ''animator'':'''clear()'''

Clears any units previously added to the animation.

* ''animator'':'''add(''unit'', ''flag'', ''hits'', ''params'')'''

Adds a unit to the animation. The ''flag'' specifies which [[AnimationWML#Common_animation_events_used_by_the_engine|animation]] to play, and the ''hits'' parameter is required for attack animations to specify which variant of the animation to play. Possible keys in ''params'' are:

* '''facing''': A location. The animation will be played with the unit facing that location.

facing is currently not implemented/working. See https://github.com/wesnoth/wesnoth/issues/9032

* '''value''': Either a number or a list of two numbers. Use this to pass ''value'' and/or ''value_second'' to default animations that use them.
* '''with_bars''': Whether to show HP bars and such while the animation plays.
* '''text''': Text to float as the animation plays.
* '''color''': Color of the floating text - a list of red, green, blue.
* '''primary''': The primary weapon to use for the animation. Must be a Lua unit attack proxy.
* '''secondary''': The secondary weapon to use for the animation.

Normal usage is to create it, call '''add''' one or more times, then call '''run'''.

=== wesnoth.units.create ===

* {{LuaGameOnly}} '''wesnoth.units.create'''(''unit_info'') → ''unit''

Creates a private unit from a WML table.

<syntaxhighlight lang='lua'>
local u = wesnoth.units.create{ type = "White Mage", gender = "female" }
</syntaxhighlight>

=== wesnoth.units.find_on_map ===

* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'') → ''array of units''
* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'', ''fake_location'') → ''array of units''
* {{LuaGameOnly}} '''wesnoth.units.find_on_map'''(''filter'', ''other_unit'') → ''array of units''

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters. If a second unit is passed, it can be referenced via the $other_unit variable in the main filter as well as via the "other" variable in WFL formulas used in the main filter. If a location is passed, the filter is run as if the unit were at that location (rather than its real location). This affects things such as [filter_adjacent] and ability_active, and should work even for a unit on the recall list.

<syntaxhighlight lang='lua'>
local leaders_on_side_two = wesnoth.units.find_on_map{ side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name
</syntaxhighlight>

=== wesnoth.units.find_on_recall ===

* {{LuaGameOnly}} '''wesnoth.units.find_on_recall'''(''filter'') → ''array of units''

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

=== wesnoth.units.find ===

* {{LuaGameOnly}} '''wesnoth.units.find'''(''filter'') → ''array of units''

Returns a list of all units matching the WML filter, both those on the map and those on the recall lists. It is a shorthand for calling both '''find_on_map''' and '''find_on_recall''' and combining the resulting arrays.

=== wesnoth.units.get ===

* {{LuaGameOnly}} '''wesnoth.units.get'''(''x'', ''y'') → ''unit or nil''
* {{LuaGameOnly}} '''wesnoth.units.get'''(''id'') → ''unit or nil''

Returns the unit at the given location or with the given ID.

<syntaxhighlight lang='lua'>
local args = ...
local unit = wesnoth.units.get(args.x1, args.y1)
</syntaxhighlight>

=== wesnoth.units.get_hovered ===

Alias of [[LuaAPI/wesnoth/interface#wesnoth.interface.get_displayed_unit]].

[[Category:Lua Reference]]

Sandbox

2024-07-29T05:29:26Z

ZombieKnight: /* [awesometag] */

The sandbox is for editing and formatting experiments. If you are already logged in, click on the "Edit" link above to experiment yourself!
[[Category:Wesnoth Wiki]]

== Widget definition ==

This page describes the definition of all widgets in the toolkit. Every
widget has some parts in common, first of all; every definition has the
following fields.

=== Label ===

A label displays a text, the text can be wrapped but no scrollbars are provided.

Although the label itself has no event interaction it still has two states.
The reason is that labels are often used as visual indication of the state
of the widget it labels.

Note: The above is outdated, if "link_aware" is enabled then there is interaction.

The following states exist:
* state_enabled, the label is enabled.
* state_disabled, the label is disabled.

{| border="1"
!key
!type
!default
!description
|-
| link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|-
| link_color
| [[GUIVariable#string|string]]
| #ffff00
| The color to render links with. This string will be used verbatim in pango markup for each link.
|}

-----

== Widget instance ==

Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

=== Label ===

A label displays a text, the text can be wrapped but no scrollbars are provided.

List with the label specific variables:
{| border="1"
!key
!type
!default
!description
|-
| wrap
| [[GUIVariable#bool|bool]]
| false
| Is wrapping enabled for the label.
|-
| characters_per_line
| [[GUIVariable#unsigned|unsigned]]
| 0
| Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text. text_alignment & h_align & "left" & How is the text aligned in the label.
|}

-----

== [awesometag] ==
The '''[awesometag]''' is used to do awesome things.

* '''awesomekey''': A place to put an awesome value

<div class="toccolours mw-collapsible mw-collapsed">
Awesome example:
<div class="mw-collapsible-content">
<syntaxhighlight lang=wml>
[awesometag]
awesomekey=awesomevalue
[fire_event]
name=awesome_event
[/fire_event]
[/awesometag]
</syntaxhighlight>
</div>
</div>

-----

Comment by '''Dreadnough''': They have a great core with versatile Spearman and fast Cavalry. Depending on the situation they can add highly specialised units such as Heavy Infantry, Mages, Meremen and Horseman. Finally their fencers can slip through enemy ranks and enable breakthroughs or disrupt the enemy's movement. As a lawful faction, they depend very much on the time of day, which results in dynamic unit movement.

Comment by '''ForestDragon''': Rebels. Well, female elves are certainly quite attractive. For example, the marksman line.

Comment by '''Elven''': Northerners have simple strategy. Kill weak units, poison and kill strong units. You can have a lot of units, make some a level 2 units and never retreat, never surrender!

Comment by '''patience_reloaded''': Undead due to their reliability when used correctly: Ghosts are very hard for most normal units (especially melee ones) to kill quick, most of the faction is poison-resistant, and due to having fixed traits, you know exactly what you get when you recruit them.

Comment by '''Hsaelt''': Knalgans i like because they can take punishment and deliver punishment. Good HP, good damage outputs on units like gryphons and those guys with firearms. No real weaknesses in res good defence on hills mountains and those are commonplace

Comment by '''Knightmare''': (Plays Drakes) Fire and Blood.

Comment by '''Computer_player''': I love dunefolk because they bring something different to the table and out of the factions closest to being mainlined, they are the one with the most work done. I really like the dynamic of the Dunefolk (Khalifate long ago) faction, however I am waiting to play Dunefolk proper with the next stable version.

Comment by '''egallager''': Check out the [[ReferenceWML]] page. [[User:Egallager|Egallager]] ([[User talk:Egallager|talk]]) 03:34, 8 May 2023 (UTC)

Comment by '''ZombieKnight''': Personally I like Saurians: Great sand and swamp defense in combination with three most useful specials in the game (skirmisher, heals +8 and magical) and both physical and magical attack you got all you'll ever need.

(1.18 they got four new friends into the team ;) )