StandardAbilityFilter

From The Battle for Wesnoth Wiki

From FilterWML, this is the experimental way to filtering ability inside StandardUnitFilter (Version 1.17.17 and later only).

It is used to filter out abilities or special weapons using multiple attributes simultaneously (ability type, ID, but also if it affects adjacent units, etc.). The concept is still experimental and developers should keep in mind that it is still possible that it will be removed for stable version 1.20 if it is not validated in version 1.19.

The term StandardAbilityFilter means that the set of such keys and tags (see below) can appear at that point. Often a StandardAbilityFilter needs to be included in a [experimental_filter_ability] or [experimental_filter_ability_active],tag. In [overwrite] subtags in weapon specials [experimental_filter_specials] use alsoStandardAbilityFilter.


The following attributes and sub-tags are allowed:

  • tag_name: matches with the specified ability types. If tag_name=heals then any ability [heals] will match.
  • id: unit has an ability with the given id. This can be a comma-separated list. The unit must have at least one of the specified abilities.
  • affect_self: matches abilities with affect_self having the specified value, this value is true by default in abilities.
  • affect_enemies: matches abilities with affect_enemies having the specified value, this value is false by default in abilities.
  • affect_allies: matches abilities with affect_allies having the specified value; however affect_alllies does not have a default value because its absence within an ability means that it only affects units on the same side as the possessor of it. So if affect_allies=none is checked, this will correspond to any ability not using this attribute.
  • affect_adjacent: match abilities with or without the [affect_adjacent] subtag. If the value is yes, matches abilities with this subtag.
  • type: specific to [plagues], match if the ability used as a weapon uses a matching type. If type=Walking Corpse, any weapon transforming a killed unit into that unit type will match. Other abilities using type can also be checked.
  • replacement_type (Version 1.17.23 and later only): specific to [damage_type], match if the ability used as a weapon uses a matching type. If replacement_type=arcane, any weapon who replace any type of damage by arcane will match.
  • alternative_type (Version 1.17.23 and later only): specific to [damage_type], match if the ability used as a weapon uses a matching type. If alternative_type=arcane, any weapon who add arcane to type of damage will match.
  • active_on: for abilities used as weapons and [resistance], check if the unit is active in the specified situation. If active_on=defense, then corresponds to active abilities only in defense. This attribute has the value both by default in these abilities.
  • apply_to: In special weapons, checks if the weapon applies to self, opponent, attacker and defender, apply_to=self by default. In resistance apply_to is used to determine the type of attack for which the resistance must be modified; it is not recommended to check an ability [resistance] with this attribute. (Version 1.19.1 and later only) It is modified to do an inclusion check for a comma-separated list of damage types in [resistance] abilities
  • cumulative: checks whether or not the cumulative option is used in abilities like [leadership] and all specials returning a numeric value.
  • value: if for example value=10-50, all abilities with value between 10 and 50 will match, [drains] without specified value will also match, [leadership], [illuminates], [heals], [regenerate] and [heal_on_hit] have default value equals to 0, [berserk] has default value to 1 and [drains] an value by default to 50. Abilities without a default value like [teleport] or [hides] but also '[dummy]' abilities will not be able to match. (Version 1.19.0 and later only) If value=default and the ability does have a default value like [drains], then match if the value (specified or not) equals the default value.
  • add, sub, multiply and divide: as for value, match if the ability uses the specified attribute with the correct value. For add and sub, if add=10 checked and an ability uses sub=-10, it will match. Multiply and divide do not have this reversibility.
  • overwrite_specials: works with capabilities using this attribute with the option specified none, one_side or both_sides. If overwrite_specials=none is checked, abilities without overwrite_specials will match.
  • [filter_wml] (Version 1.19.0 and later only): Converts the ability to WML and tests it against a WML filter. Note that this is slower than other methods, so if possible it's better to use other filter keys; but it can be used to check sub-tags or keys that don't exist in StandardAbilityFilter.

See Also

This page was last edited on 18 June 2024, at 09:42.