FilterWML

[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;

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.

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

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
• level the level of the unit
• 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 Template:DevFeature
• [wml_filter] Template:DevFeature 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. Template:DevFeature 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. Template:DevFeature
• [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] Template:DevFeature standard unit filter - will not match unless the correct number of adjacent units 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"
• [filter_location] (in 1.2 a special filter / Template:DevFeature standard location filter) - the tile that the unit is standing on matches the location filter.
  • time_of_day filter matches only on a given time of day (one of lawful, chaotic or neutral).
  • terrain comma separated list of terrains. If you are using terrain letters (TerrainLettersWML), then yes you must use commas to separate the terrains; this is different from the the [store_locations] tag or IF_TERRAIN macro (of utils.cfg)! So instead of "gfm", write "g,f,m" here.
  • x,y the same as in the unit filter; supports any range Template:DevFeature
  • [filter] a single unit filter; if present a unit must also be there Template:DevFeature
  • owner_side the side of the owner, if this location is an owned village. Template:DevFeature
  • find_in name of an array or container variable; if present, the location will not match unless it is also found stored in the variable Template:DevFeature
  • radius matches if any location within the radius matches this filter Template:DevFeature
  • [filter_radius] a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter Template:DevFeature
  • [and] an extra location filter. Unless a location matches the [and] filter, then it will be excluded. Template:DevFeature Note: all extra location filters are considered after the containing filter (and any radius information); they are then processed in the order encountered.
  • [or] an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter. Template:DevFeature
  • [not] an extra location filter. If a location matches the [not] filter, then that location will be excluded. Template:DevFeature

• 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]

although in Template:DevFeature you would just do it like this:

 [kill]
   description=Gwiti Ha'atel
   [or]
     description=Tanar
   [/or]
 [/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

(in the development version, all the keys and tags found in [filter_location] above are part of the standard location filter Template:DevFeature)

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
  • 'melee' only melee weapons pass
  • 'ranged' 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.

Filtering Terrains

(SVN terrain only) At some places the terrains can be filtered with a match list. This list is only usable with the new terrain strings. The list is a comma separated list and matching will stop at the first matched terrain string. There's one special character ! which inverts the meaning of a match. Terrain strings can use the wildcard * to match zero or more following letters, characters behind the * are not allowed and the result is undefined.

Eg:
ww* matches ww, www, wwW but not WWW
!, ww returns false if ww found and true if not
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.

See Also

• UnitWML
• EventWML
• ReferenceWML