Difference between revisions of "StandardUnitFilter"

From The Battle for Wesnoth Wiki
Line 1: Line 1:
 +
From [[FilterWML]], this is the standard way of filtering units.
 +
 
When a unit filter is applied to a map, first it applies to all units on the field,
 
When a unit filter is applied to a map, first it applies to all units on the field,
 
based on their coordinates.
 
based on their coordinates.
Line 8: Line 10:
  
  
Any number of the following key/tags can be used in a standard unit filter:
+
The following attributes and sub-tags are allowed:
  
 
* '''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]].
 
* '''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]].
Line 38: Line 40:
 
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
 
* '''[filter_location]''': [[StandardLocationFilter]] - 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:
+
== A Note about Re-Using the Same Attribute ==
 +
You are limited to having one attribute, such as '''description''' in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:
 
   [kill]
 
   [kill]
 
     [not]
 
     [not]
Line 48: Line 51:
 
   [/kill]
 
   [/kill]
 
:And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:
 
: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]
 
:although you would just do it like this:
 
 
   [kill]
 
   [kill]
 
     description=Gwiti Ha'atel
 
     description=Gwiti Ha'atel

Revision as of 07:29, 1 March 2008

From FilterWML, this is the standard way of filtering units.

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.

You can access the filtered unit within the filter as the $this_unit variable, see SingleUnitWML for the possible content of these variables


The following attributes and sub-tags are allowed:

  • 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: yes 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
  • level: the level of the unit
  • defense: current defense of the unit on current tile (chance to hit %, like in movement type definitions)
  • movement_cost: current movement cost of the unit on current tile
  • x,y: the position of the unit
  • find_in: name of an array or container variable; if present, the unit will not match unless it is also found stored in the variable
  • [filter_vision]: this tests whether or not the unit is currently visible
    • visible: yes or no, default yes
    • viewing_side: the side(s) which you are checking if they are able to see (or not see) the unit. All sides listed here must pass the test. If no side is listed, it will check the visibility all enemy sides.
  • [wml_filter]: this is WML level filter for the unit. In it, you can filter on anything that is in the WML description of a unit. This description can be found in any savegame also in SingleUnitWML.
  • [and]: an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.
  • [or]: an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
  • [not]: an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
  • [filter_adjacent]: standard unit filter; if present the correct number of adjacent units must match this filter
    • count: a number, range, or comma separated range; default "1-6"
    • adjacent: a comma separated list of directions; default "n,ne,se,s,sw,nw"
    • is_enemy: a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
  • [filter_location]: StandardLocationFilter - the tile that the unit is standing on matches the location filter.

A Note about Re-Using the Same Attribute

You are limited to having one attribute, such as description in a StandardUnitFilter. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. 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]
   description=Gwiti Ha'atel
   [or]
     description=Tanar
   [/or]
 [/kill]