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 it's 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
  
• ability: unit has an ability with the given id; see AbilitiesWML
• 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
• 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
• 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. 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 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. 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]: 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. If the filter encounters a nested [not] tag, the attributes and containers inside the tag should not match for the upper filter to match. Note: [filter_wml] is especially slow, unless it contains only a child [variables], which is used for matching variables stored inside the unit.
• [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.
• 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"].

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]

See Also

• Examples - How to use filters