StandardUnitFilter

[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, core, credits_group, criteria;

D: damage, damage_type, 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, fonts, for, foreach, found_item, 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, resolution, 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 (action, scenario), 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;

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 term StandardUnitFilter means that the set of such keys and tags (see below) can appear at that point. Often a StandardUnitFilter needs to be included in a [filter] tag. But many tags take the StandardUnitFilter directly as an argument, like [kill] and [have_unit]. See Special:WhatLinksHere/StandardUnitFilter for tags which can contain a StandardUnitFilter.

The following attributes and sub-tags are allowed:

• id: unit matches the given id. This is the same as id in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this (see SingleUnitWML). id= can be a comma-separated list, every unit with one of these ids matches.
• speaker: alias for id (no comma-separated list supported)
• type: matches the unit's type name (can be a list of types)
• type_adv_tree: (Version 1.13.7 and later only) matches the type name of the unit and all its advancements (can be a list)
• race: the race of the unit type. This can be a comma-separated list; the unit's race must match one of the given races.
  Mainline races are listed in data/core/units.cfg
  
• variation: the unit type variation id (can be a list of variation ids)
• has_variation: matches if the unit type for the unit defines at least one of the variation ids provided as a comma-separated list
• upkeep: (Version 1.15.3 and later only) The upkeep of the unit. Can be either a non-negative number or one of the special values loyal, free, full. Note that while loyal and free are synonymous with an upkeep of 0, the value full is not synonymous with any single numeric value – it is equivalent to $this_unit.level.
• ability: unit has an ability with the given id; see AbilitiesWML
• ability_type: (Version 1.13.7 and later only) unit has an ability with the given type (tag name) - eg, ability_type=heals will match a unit with any healing ability.
• ability_type_active: (Version 1.13.8 and later only) unit has an active ability with the given type (tag name).
• ability_id_active: (Version 1.15.13 and later only) unit has an active ability with the given id; see AbilitiesWML
• trait: (Version 1.13.8 and later only) This can be a comma-separated list. The unit must have at least one of the specified traits.
• status: (Version 1.13.0 and later only) matches if the unit has the specified status active. This can be a comma-separated list, in which case the unit will match as long as it has one of the listed statuses active (note: possible statuses are listed on the SingleUnitWML page).
• side: the unit is on the given side (can be a list)
• has_weapon: the unit has a weapon with the given name (Version 1.13.5 and later only) Now deprecated
• [has_attack]: (Version 1.13.5 and later only) the unit has a weapon matching the StandardWeaponFilter. If this is present, has_weapon is ignored.
• 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 (this can be a comma-separated list).
• 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. Can be a number, range, or comma separated range.
• x,y: the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
• find_in: name of an array or container variable; if present, the unit will not match unless a unit with the same id is already stored in the variable
• [filter_vision]: this tests whether or not the unit is currently visible
  • visible: yes or no, default yes. When "yes", this matches units that are not obscured by fog or shroud, and that are not hiding (via the [hides] ability). When "no", this matches units that are obscured by fog or shroud, or that are hiding.
  • StandardSideFilter tags and keys. Filter for who may be able to see (or not see) the unit. If there is *at least one* matching side which can see the unit then the filter matches, and otherwise it fails to match.
• [filter_wml]: Converts the unit to WML (as if by [store_unit]) and tests it against a WML filter. For a list of things in the WML that could be filtered on, see SingleUnitWML or open a saved game in a text editor. Note that this is slower than other methods, so if possible it's better to use other filter keys and tags; however, if the WML filter contains only a child [variables], then the unit is not converted to WML and the filter is matched only against the unit's variables (which are already WML).
• [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] with a StandardUnitFilter as argument; do not use a [filter] tag. If present the correct number of adjacent units must match this filter.
  • StandardUnitFilter tags and keys
  • 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" (see notes)
  • is_enemy: a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
  • $other_unit: (Version 1.13.2 and later only) Within [filter_adjacent], the special variable $other_unit refers to the filtered unit from the enclosing filter, while $this_unit refers (as with all StandardUnitFilters) to the unit being filtered on.
• [filter_location]: StandardLocationFilter - the tile that the unit is standing on matches the location filter.
• [filter_side]: The currently filtered unit's side must match this StandardSideFilter for the unit to match.
  • StandardSideFilter tags and keys
• formula: A formula using Wesnoth Formula Language. The self variable is set to the current $this_unit, and the formula should return a boolean. If it returns 0, the filter does not match. Otherwise, the filter does match. (Version 1.13.5 and later only) If the filter has a secondary unit, the formula can access it using the other variable. Both the unit and the secondary unit are a unit object, with keys documented below. Do not surround the formula in $(...), since that will erase the self variable.
• lua_function: the name of a Lua function in the global environment that takes a unit as an argument and returns true if the given unit matches the filter. (Version 1.13.5 and later only) Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as my_filter_functions["goto"].

Wesnoth Formula Language

When using the formula key, the self and (if present) other objects support the following keys:

• x, y, loc - the latter is a location object such as what would be returned from loc().
• id
• type
• name
• usage
• canrecruit, leader
• undead - true if the unit has the not_living status
• attacks - a list of weapon objects
• abilities - a list of the ability IDs the unit possesses
• hitpoints, max_hitpoints
• experience, max_experience
• moves, max_moves
• attacks_left, max_attacks
• level, full - full refers to the unit's level to support the formula upkeep = full
• traits - a list of the trait IDs
• extra_recruit
• advances_to
• status - a list of active statuses
• side_number
• cost
• upkeep
• loyal - a constant 0 to support the formula upkeep = loyal
• hidden
• petrified - true if the unit has the petrified status
• resting
• role
• race
• gender
• variation
• zoc
• alignment
• facing
• resistance, movement_cost, vision_cost, jamming_cost, defense - (Version 1.15.3 and later only) Maps containing the basic movetype data. The defense and resistance maps contain the actual defense and resistance values, rather than the values specified in the WML, so you do not need to subtract them from 100.
• flying (Version 1.15.3 and later only)
• vars - WFL variables owned by the unit, which can be set and used by FormulaAI
• wml_vars - the WML variables stored in the unit
• n, s, ne, se, nw, sw, lawful, chaotic, neutral, liminal, male, female - these are all defined to be the equivalent string so that, for example, you can write a formula like alignment = liminal and gender = female without needing to quote the alignment and gender strings.

A Note about Re-Using the Same Attribute

You are limited to having each attribute, such as id, appear once or less 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]
        id=Gwiti Ha'atel
    [/not]
    [not]
        id=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]
    id=Gwiti Ha'atel
    [or]
       id=Tanar
    [/or]
[/kill]

Tutorial

• How To Use Filter (with examples)

See Also

• FilterWML