FilterWML

Filtering in WML

A filter is a special WML block. Filters are used to describe a set of units, hexes, or weapons. Filters are defined as matching something if all the keys in the filter match that thing. For example, if a unit filter contains two keys, a unit must match both of the keys in order to match the filter.

Filtering Units

Filters are often used in action tags (see EventWML). In this case the phrase "standard unit filter" is used in place of the set of standard keys. Sometimes a filter is used to find the first unit that matches the filter; for example, the [recall] tag recalls that unit.

Standard unit filters are also used in the tags [filter] and [filter_second]. These are subtags of [event] which describe when the event should trigger. Most event names (see EventWML) have units related to them called "primary unit" and "secondary unit". In order for an event to be triggered, primary unit must match the filter contained in [filter], and secondary unit must match the filter contained in [filter_second].

When a unit filter is applied to a map, first it applies to all units on the field, based on their coordinates. Next it applies to units in the recall list. This is important to remember as it means, for example, that the tag [kill] can be used to kill units in the recall list.

Any number of the following key/tags can be used in a standard unit filter:

• description unit matches the given description. This is the same as description in the [unit] tag. Note that it is independent of user_description, which can be internationalized independent of this. See SingleUnitWML.
• speaker alias for description
• type matches the unit's type name (can be a list of types)
• race the race of the unit type.
  Races are listed in the unit files (data/units/)
• ability unit has a given ability; see AbilitiesWML
• side the unit is on the given side (can be a list)
• has_weapon the unit has a weapon with the given name
• canrecruit 1 if the unit can recruit (i.e. is a leader)
• gender female if the unit is female rather than the default of male
• role the unit has been assigned the given role; see [role], InternalActionsWML
• [not] this subtag contains another filter.
  If the content of this filter is matched, the parent's filter won't be, and vice-versa.
• [filter] standard location filter - the tile that the unit is standing on matches the location filter.
• You are limited to having one description, however this can be worked around. If you have several specific units you want excepted from matching, use a separate [not] subfilter for each one. If you want to match any of several specific units, you can apply DeMorgan's law and do the test by having a [not] subfilter and then below that another [not] subfilter for each unit you want included. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:

 [kill]
   [not]
     description=Gwiti Ha'atel
   [/not]
   [not]
     description=Tanar
   [/not]
 [/kill]

And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:

 [kill]
   [not]
     [not]
       description=Gwiti Ha'atel
     [/not]
     [not]
       description=Tanar
     [/not]
   [/not]
 [/kill]

although this is probably easier achieved using two tags:

 [kill]
   description=Gwiti Ha'atel
 [/kill]
 [kill]
   description=Tanar
 [/kill]

Filtering Locations

As you have seen, standard unit filter can contain a location filter. Several actions, such as [terrain], also use location filters. Location filters are represented on this site by the phrase "standard location filter".

The following keys are used:

• x the first coordinate
• y the second coordinate

While some locations should only be one hex (like the starting position of a unit), others filter over multiple hexes. The following syntax is used to filter over multiple hexes:

Dashes(-) are used to have the location be a range of hexes. There must be values before and after the dash; everything in between these numbers (inclusively) is part of the range.

Commas(,) are used to separate coordinates into a list. The x and y lists are then paired up, with each pair representing one hex or range.

Note: although the ordering of locations in a list generally does not matter, the action [move_unit_fake] takes in a list of hexes, and moves an image onto each of those hexes in order.

Filtering Weapons

Sometimes weapons are filtered on in WML. Currently the only weapon filter is in the [effect] tag. See also EffectWML.

These keys are used as filter input for weapon filters.

• range a range to filter
  • 'short' only melee weapons pass
  • 'long' only ranged weapons pass
• name filter on the attack's name.

See data/units/ or http://wesnoth.slack.it/unitlist.cgi to find the name of a particular unit's attack.

• type filter on the attack's type.

Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'holy'.

• special filter on the attack's special power.

For values see AbilitiesWML.

See Also

• UnitWML
• EventWML
• ReferenceWML