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, weapons or something else. 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.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

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

See StandardUnitFilter for details.

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".

See StandardLocationFilter for details.

Filtering Sides

Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used. Side filters are represented on this site by the phrase "standard side filter".

See StandardSideFilter for details.

Filtering Weapons

Sometimes weapons are filtered on in WML. See also EventWML, EffectWML, AnimationWML.

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://www.wesnoth.org/units/ 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 'arcane'.

• damage: filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
• special: filter on the attack's special power.

For values see AbilitiesWML.

Filtering Terrains

This section describes basically the same as "Filtering Locations" above, namely a StandardLocationFilter.

Use [filter_location] within [filter] , for example:

[event]
    [filter]
        [filter_location]
            terrain=Ch 
        [/filter_location]
    [/filter]
[/event]

At some places the terrains can be filtered with a match list. 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.

Example 1:
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.

Example 2:
*^V* matches all village-terrain
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).

For a list of terrain types and their string codes see TerrainCodesWML.

Filtering Vision

The [filter_vision] tag allows you to filter locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side.

• visible:
  • yes (default): matches when the location is not obscured by fog or shroud for the viewing_side
  • no: matches when the location is obscured by fog or shroud for the viewing_side
• viewing_side: the observing side, or list of observing sides
  • When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
  • When no viewing sides are listed, all enemy sides must pass the visibility check.

Example: This event will fire when the enemy (side 2) moves to a location within the player's field of vision:

[event]
    name=moveto
    first_time_only=yes
    [filter]
        side=2
        [filter_vision]
            viewing_side=1 
        [/filter_vision]
    [/filter]
    [message]
        speaker=unit
        message="I am your enemy. I know that you can see me here."
    [/message]
[/event]

Note: This filter is only useful when the viewing side is under a fog or shroud. You can set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

See Also

• UnitTypeWML
• EventWML
• ReferenceWML