Difference between revisions of "AbilitiesWML"

From The Battle for Wesnoth Wiki
(Undo revision 46944 by BettyMorgan (Talk))
(Available formula variables in Abilities and Weapon Sepcials)
(48 intermediate revisions by 13 users not shown)
Line 16: Line 16:
 
* '''[teleport]''': allows the unit to teleport
 
* '''[teleport]''': allows the unit to teleport
 
* '''[hides]''': renders the unit invisible to enemies
 
* '''[hides]''': renders the unit invisible to enemies
 +
* {{DevFeature1.15|0}} A tag matching a [[#The_.5Bspecials.5D_tag|weapon special tag]] will confer that weapon special to units based on the given conditions. Most weapon specials are supported; however, '''plagues''', '''heal_on_hit''', and '''swarm''' are not.
 
Any other name is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. '''Note:''' a dummy ability must have an id for the name and description to display.
 
Any other name is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. '''Note:''' a dummy ability must have an id for the name and description to display.
 +
 +
=== 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.
 +
* '''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 ===
 
=== Common keys and tags for every ability ===
  
* '''name''': the name of the ability.
+
{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
* '''name_inactive''': the name of the ability when inactive.
+
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.
* '''description''': the description of the ability.
+
 
* '''description_inactive''': the description of the ability when inactive.
+
* '''name''': the (translatable) name of the ability.
* '''affect_self''': if equal to 'yes', the ability will affect the unit that has it.
+
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''affect_allies''': if equal to 'yes', the ability will affect allies in the specified adjacent hexes.
+
* '''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).
* '''affect_enemies''': if equal to 'yes', the ability will affect enemies in the specified adjacent hexes.
+
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified.
 +
* '''description''': the (translatable) description of the ability.
 +
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
 +
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
 +
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
 +
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
 
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability.
 
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability.
 
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
 
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''[adjacent_description]''': contains all four of the above keys, which are used when an adjacent unit receives the ability.
 
 
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
 
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* '''[affect_adjacent]''': each adjacent unit that does not match this filter will not receive its effects.
+
* '''[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 seperated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''.
+
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]].
+
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
 
* '''[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_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.
 +
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
 
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
 
* '''[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.
  
Line 40: Line 56:
  
 
* '''value''': the amount healed.
 
* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.
+
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").
  
 
=== Extra keys used by the ''[regenerate]'' ability ===
 
=== Extra keys used by the ''[regenerate]'' ability ===
Line 57: Line 73:
 
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
 
* '''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.
 
* '''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.
 +
* '''[filter_student]''': {{DevFeature1.15|0}} If present, the ability only takes effect on units matching this filter.
  
 
=== Extra keys used by the ''[leadership]'' ability ===
 
=== Extra keys used by the ''[leadership]'' ability ===
  
 
* '''value''': the percentage bonus to damage.
 
* '''value''': the percentage bonus to damage.
 +
* '''[filter_weapon]''': If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
 +
* '''[filter_second_weapon]''': If present, the leadership ability only takes effect when the opponent uses a matching weapon.
 +
* '''[filter_student]''': {{DevFeature1.15|0}} If present, the ability only takes effect on units matching this filter.
  
 
=== Extra keys used by the ''[illuminates]'' ability ===
 
=== Extra keys used by the ''[illuminates]'' ability ===
  
* '''value''': the percentage bonus to lawful units.
+
Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
 +
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.  
 
* '''max_value''': the maximum percentage bonus given.
 
* '''max_value''': the maximum percentage bonus given.
 
* '''min_value''': the minimum percentage bonus given.
 
* '''min_value''': the minimum percentage bonus given.
Line 74: Line 98:
 
=== Extra tags used by the ''[teleport]'' ability ===
 
=== Extra tags used by the ''[teleport]'' ability ===
  
* '''[tunnel]''' - a tunnel tag (see [[DirectActionsWML]]) (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.)  You may use $teleport_unit inside the tunnel tag for filtering purposes.
+
* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.)  You may use $teleport_unit inside the tunnel tag for filtering purposes.
 +
 
 +
=== Extra tags and keys used by weapon special abilities ===
 +
 
 +
* '''[filter_weapon]''': If present, the ability only takes effect when the owner of the ability uses a matching weapon.
 +
* '''[filter_second_weapon]''': If present, the ability only takes effect when the opponent uses a matching weapon.
 +
* '''[filter_student]''': If present, the ability only takes effect on units matching this filter.
 +
* Other keys and tags appropriate to the specific weapon special
  
 
=== Macros for common abilities ===
 
=== Macros for common abilities ===
Line 83: Line 114:
 
* ABILITY_ILLUMINATES
 
* ABILITY_ILLUMINATES
 
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
 
* 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_NIGHTSTALK
 
* ABILITY_REGENERATES
 
* ABILITY_REGENERATES
Line 94: Line 126:
 
The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:
 
The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:
  
* '''[damage]''': modifies the damage of a weapon
 
 
* '''[attacks]''': modifies the number of attacks of a weapon
 
* '''[attacks]''': modifies the number of attacks of a weapon
 +
* '''[berserk]''': pushes the attack for more than one combat round
 
* '''[chance_to_hit]''': modifies the chance to hit of a weapon
 
* '''[chance_to_hit]''': modifies the chance to hit of a weapon
* '''[slow]'''
+
* '''[damage]''': modifies the damage of a weapon
* '''[poison]'''
+
* '''[disable]''': disables the weapon
* '''[stones]''' ('''[petrifies]''' in recent versions.)
 
* '''[berserk]'''
 
* '''[firststrike]'''
 
 
* '''[drains]''': heals the attacker half of the damage dealt
 
* '''[drains]''': heals the attacker half of the damage dealt
* '''[heal_on_hit]''': heals the attacker when an attack connects {{DevFeature1.11}}
+
* '''[firststrike]''': forces the weapon to always strike first
* '''[plague]'''
+
* '''[heal_on_hit]''': heals the attacker when an attack connects
Any other name is valid, but will result in an special that does nothing but report it's there.
+
* '''[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 name is valid, but will result in an special that does nothing but report it is there.
  
 
=== Common keys and tags for every weapon special ===
 
=== Common keys and tags for every weapon special ===
  
* '''name''': the name of the 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_inactive''': the name of the special when inactive.
+
 
* '''description''': the description of the special.
+
* '''name''': the (translatable) name of the special.
* '''description_inactive''': the description of the special when inactive.
+
* '''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).
* '''value''': the value to be used. Applies to '''[damage]''', '''[attacks]''', '''[chance_to_hit]''' and '''[berserk]''' (the maximum number of combat rounds).
+
* '''description''': the (translatable) description of the special.
** {{DevFeature1.11}} Also applies to '''[drains]''' (percentage of damage drained) and '''[heal_on_hit]''' - negative values will harm the attacker, but not kill
+
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''add''' the number to add to the base value.
 
* '''sub''' the number to subtract from the base value.
 
* '''multiply''': same as '''value''', except that this multiplies the base value.
 
* '''divide''': same as '''value''', except that this divides the base value.
 
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
 
* '''type''': only usable in '''[plague]''', where it defines the unit type to be spawned on kill.
 
 
* '''id''': this ability will not be cumulative with other specials using this id.
 
* '''id''': this ability will not be cumulative with other specials using this id.
 
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
 
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both'''. Determines who the effects of this special are applied to.
+
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': [[StandardUnitFilter]], which takes an extra key '''adjacent''', which is used to specify which adjacent hexes to filter on. '''adjacent''' is a comma seperated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''.
+
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.  
* '''[filter_adjacent_location]''': like [filter_adjacent], except that it filters on the locations rather than the units.
+
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* '''[filter_self]''': the special will only be active if the owner matches this filter.
+
* '''[filter_self]''': the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a standard weapon filter.
+
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
* '''[filter_opponent]''': the special will only be active if the opponent matches this [[StandardUnitFilter]].
+
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
** '''[filter_weapon]''': a standard weapon filter.
+
* '''[filter_opponent]''': the special will only be active if the opponent matches this SUF.
* '''[filter_attacker]''': the special will only be active if the attacker matches this filter.
+
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''[filter_weapon]''': a standard weapon filter.
+
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* '''[filter_defender]''' the special will only be active if the defender matches this filter.
+
* '''[filter_attacker]''': the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a standard weapon filter.
+
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc.
+
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
 +
* '''[filter_defender]''' the special will only be active if the defender matches this SUF.
 +
** '''[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.
 +
 
 +
=== Common keys and tags for specials with a value ===
 +
 
 +
The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).
 +
 
 +
* '''value''': the value to be used.
 +
* '''add''': the number to add to the base value.
 +
* '''sub''': the number to subtract from the base value.
 +
* '''multiply''': this multiplies the base value.
 +
* '''divide''': this divides the base value.
 +
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
 +
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{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'''.
 +
 
 +
=== 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.
 +
 
 +
=== 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 ===
 
=== Macros for common weapon specials ===

Revision as of 23:21, 9 January 2021

[edit]WML Tags

A:

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

B:

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

C:

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

D:

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

E:

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

F:

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

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

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

I:

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

J:

jamming_costs, join;

K:

kill, killed;

L:

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

M:

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

N:

not, note;

O:

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

P:

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

R:

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

S:

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

T:

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

U:

unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

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

W:

while, wml_message, wml_schema;

Z:

zoom;

Abilities and their effects

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

The [abilities] tag

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

  • [heals]: modifies the hitpoints of a unit at the beginning of the healer's turn
  • [regenerate]: modifies the hitpoints of a unit at the beginning of the unit's turn
  • [resistance]: modifies the resistance of a unit to damage
  • [leadership]: modifies the damage of a unit
  • [skirmisher]: negates enemy zones of control
  • [illuminates]: modifies the time of day adjacent to the affected units
  • [teleport]: allows the unit to teleport
  • [hides]: renders the unit invisible to enemies
  • (Version 1.15.0 and later only) A tag matching a weapon special tag will confer that weapon special to units based on the given conditions. Most weapon specials are supported; however, plagues, heal_on_hit, and swarm are not.

Any other name is valid (for example [dummy]), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. Note: a dummy ability must have an id for the name and description to display.

Available formula variables in Abilities and Weapon Specials

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

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

Common keys and tags for every ability

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

  • name: the (translatable) name of the 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.
  • description: the (translatable) description of the ability.
  • description_inactive: the (translatable) description of the ability when inactive. Defaults to description if not specified.
  • affect_self: if equal to 'yes' (default), the ability will affect the unit that has it.
  • affect_allies: if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
  • affect_enemies: if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
  • cumulative: if set to 'yes', this ability will be cumulative with the base value for this ability.
  • id: this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
  • [filter]: StandardUnitFilter If the unit owning the ability does not match this filter, the ability will be inactive.
  • [affect_adjacent]: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the affect_allies and affect_enemies keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
  • [filter_self]: if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a StandardUnitFilter as argument.
  • [filter_adjacent]: if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys adjacent, count, is_enemy, just like in a StandardUnitFilter, with the one difference that, in the absence of a specified count, all listed directions must match (so, with two directiones eg adjacent=n,s, the default is count=2). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and (Version 1.13.2 and later only) $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
  • [filter_adjacent_location]: like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
  • [filter_base_value]: filters on the value before any modifications; uses the keys equals, not_equals, etc. If several keys are used all have to match.

Extra keys used by the [heals] ability

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

Extra keys used by the [regenerate] ability

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

Extra keys and tags used by the [resistance] ability

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

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

Extra keys used by the [leadership] ability

  • value: the percentage bonus to damage.
  • [filter_weapon]: If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
  • [filter_second_weapon]: If present, the leadership ability only takes effect when the opponent uses a matching weapon.
  • [filter_student]: (Version 1.15.0 and later only) If present, the ability only takes effect on units matching this filter.

Extra keys used by the [illuminates] ability

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

  • value: the percentage bonus to lawful units. Units with alignment=lawful do +value % damage when under the influence of a unit with this ability. Units with alignment=chaotic do -value % damage. Units with alignment=neutral are unaffected by this ability. Units with alignment=liminal do -(abs(value)) % damage. value can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
  • max_value: the maximum percentage bonus given.
  • min_value: the minimum percentage bonus given.

Extra keys used by the [hides] ability

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

Extra tags used by the [teleport] ability

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

Extra tags and keys used by weapon special abilities

  • [filter_weapon]: If present, the ability only takes effect when the owner of the ability uses a matching weapon.
  • [filter_second_weapon]: If present, the ability only takes effect when the opponent uses a matching weapon.
  • [filter_student]: If present, the ability only takes effect on units matching this filter.
  • Other keys and tags appropriate to the specific weapon special

Macros for common abilities

  • ABILITY_AMBUSH
  • ABILITY_CURES
  • ABILITY_HEALS
  • ABILITY_ILLUMINATES
  • ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
  • (Version 1.13.2 and later only) ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
  • ABILITY_NIGHTSTALK
  • ABILITY_REGENERATES
  • ABILITY_SKIRMISHER
  • ABILITY_STEADFAST
  • ABILITY_SUBMERGE
  • ABILITY_TELEPORT

The [specials] tag

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

  • [attacks]: modifies the number of attacks of a weapon
  • [berserk]: pushes the attack for more than one combat round
  • [chance_to_hit]: modifies the chance to hit of a weapon
  • [damage]: modifies the damage of a weapon
  • [disable]: disables the weapon
  • [drains]: heals the attacker half of the damage dealt
  • [firststrike]: forces the weapon to always strike first
  • [heal_on_hit]: heals the attacker when an attack connects
  • [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 name is valid, but will result in an special that does nothing but report it is there.

Common keys and tags for every weapon special

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

  • name: the (translatable) name of the special.
  • 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.
  • id: this ability will not be cumulative with other specials using this id.
  • active_on: one of defense or offense; if left out, the special is active on both.
  • apply_to: one of self,opponent,attacker,defender,both (default: self). Determines who the effects of this special are applied to.
  • [filter_adjacent]: if an adjacent unit does not match this filter, the special will not be active and no-one will receive its affects. Takes extra keys adjacent, count, is_enemy, just like in a StandardUnitFilter. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified count, all listed directions must match (so, with two directiones eg adjacent=n,s, the default is count=2). The variables $this_unit and (Version 1.13.2 and later only) $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
  • [filter_adjacent_location]: like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
  • [filter_self]: the special will only be active if the owner matches this StandardUnitFilter (SUF).
  • [filter_opponent]: the special will only be active if the opponent matches this SUF.
  • [filter_attacker]: the special will only be active if the attacker matches this SUF.
  • [filter_defender] the special will only be active if the defender matches this SUF.

Common keys and tags for specials with a value

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

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

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.

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

  • 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