Difference between revisions of "FilterWML"

From The Battle for Wesnoth Wiki
(→‎Filtering Units)
(→‎Filtering Weapons)
 
(77 intermediate revisions by 30 users not shown)
Line 3: Line 3:
  
 
A ''filter'' is a special WML block.
 
A ''filter'' is a special WML block.
−
Filters are used to describe a set of units, hexes, or weapons.
+
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.
 
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,
 
For example, if a unit filter contains two keys,
 
a unit must match both of the keys in order to match the filter.
 
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 ==
 
== Filtering Units ==
Line 21: Line 23:
 
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.
 
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,
+
See [[StandardUnitFilter]] for details.
−
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.
 
  
−
{{DevFeature}} : you can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables
+
== 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".
 +
A common use for location filters is to check the terrain of a space.
  
−
Any number of the following key/tags can be used in a standard unit filter:
+
See [[StandardLocationFilter]] for details.
  
−
* ''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]].
+
== Filtering Sides ==
−
* ''speaker'' alias for description
+
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
−
* ''type'' matches the unit's type name (can be a list of types)
+
Side filters are represented on this site by the phrase "standard side filter".
−
* ''race'' the race of the unit type.<br>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 {{DevFeature}}
 
−
* '''[wml_filter]''' {{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. {{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. {{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]''' {{DevFeature}} 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]''' (in 1.2 a special filter / {{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 {{DevFeature}}
 
−
** '''[filter]''' a standard unit filter; if present a unit must also be there {{DevFeature}}
 
−
** ''owner_side'' the side of the owner, if this location is an owned village. {{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 {{DevFeature}}
 
−
** ''radius'' matches if any location within the radius matches this filter {{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 {{DevFeature}}
 
−
** '''[and]''' an extra location filter. Unless a location matches the [and] filter, then it will be excluded. {{DevFeature}} ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); 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. {{DevFeature}}
 
−
** '''[not]''' an extra location filter. If a location matches the [not] filter, then that location will be excluded. {{DevFeature}}
 
−
** '''[filter_adjacent_location]''' a standard location filter; if present the correct number of adjacent locations must match this filter {{DevFeature}}
 
−
*** ''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"
 
  
−
* 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:
+
See [[StandardSideFilter]] for details.
−
  [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 {{DevFeature}} you would just do it like this:
 
−
  [kill]
 
−
    description=Gwiti Ha'atel
 
−
    [or]
 
−
      description=Tanar
 
−
    [/or]
 
−
  [/kill]
 
  
−
== Filtering Locations ==
+
== Filtering Weapons ==
  
−
As you have seen, standard unit filter can contain a location filter.
+
Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].
−
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:
+
These keys are used as filter input for attack filters.
−
* ''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 {{DevFeature}})
 
  
−
While some locations should only be one hex (like the starting position of a unit),
+
* '''range''': a range to filter
−
others filter over multiple hexes.
+
** '''melee''': only melee weapons pass
−
The following syntax is used to filter over multiple hexes:
+
** '''ranged''': only ranged weapons pass
 +
* '''name''': filter on the attack's name. See <code>data/units/</code> 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' or customised type. {{DevFeature1.17|23}} [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
 +
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
 +
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.
 +
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].
 +
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location. Does not work in 1.16. {{DevFeature1.17|17}} Works again.
 +
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.
 +
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
 +
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.
 +
* '''[filter_special]''':  {{DevFeature1.19|6}}  Filter on a weapon special by using[[StandardAbilityFilter]]
 +
** '''active''': if active=yes, true if the special is active at the current location. If active=no, true whether or not it's currently active, in this case, one special encoded in [attack] can be checked.
 +
* '''number''': {{DevFeature1.13|5}} filter on number of strikes
 +
* '''parry''': {{DevFeature1.13|5}} filter on parry value
 +
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value
 +
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost
 +
* '''attacks_used''': {{DevFeature1.17|13}} filter on attack's attack cost
 +
* '''min_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
 +
* '''max_range''': {{DevFeature1.19|4}} filter on attack's range (distance)
 +
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]. The context object for the formula is a '''weapon object''', which supports the following keys: '''name''', '''description''', '''type''', '''icon''', '''range''', '''damage''', '''number''', '''attack_weight''', '''defense_weight''', '''accuracy''', '''parry''', '''movement_used''', '''specials'''. The '''specials''' key is a list of all the special IDs the unit possesses. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable. Keys supported after specific version: {{DevFeature1.17|13}} '''attacks_used'''. {{DevFeature1.19|4}} '''min_range''', '''max_range'''.
  
−
Dashes('''-''') are used to have the location be a range of hexes.
+
'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.
−
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.
+
== Filtering Vision ==
−
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 '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).
−
the action '''[move_unit_fake]''' takes in a list of hexes,
 
−
and moves an image onto each of those hexes in order.
 
  
−
== Filtering Weapons ==
+
* '''visible''':
 +
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.
 +
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.
 +
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
 +
** 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.
 +
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.
  
−
Sometimes weapons are filtered on in WML.
+
'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:
−
Currently the only weapon filter is in the '''[effect]''' tag.
+
[event]
−
See also [[EffectWML]].
+
    name=moveto
 +
    first_time_only=yes
 +
    [filter]
 +
        side=2
 +
        [filter_vision]
 +
            side=1
 +
        [/filter_vision]
 +
    [/filter]
 +
    [message]
 +
        speaker=unit
 +
        message="I am your enemy. I know that you can see me here."
 +
    [/message]
 +
[/event]
  
−
These keys are used as filter input for weapon filters.
+
'''Note:''' In a location filter, this tag 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.
  
−
* ''range'' a range to filter
+
== Filtering on WML data ==
−
** '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 ===
+
Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between '''<>''' needs to be replaced by the actual data to be filtered for. The following conventions are possible:
  
−
'''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]'''''
+
* '''<key>=<value>''': Means that the key '''key''' must be present with the specified '''value'''.
−
At some places the terrains can be filtered with a  
+
* '''glob_on_<key>=<glob>''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In a glob, the '''*''' character matches any sequence of characters, while the '''?''' character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_<key>=*''' in a '''[not]''' tag.
−
match list. This list is only usable with the new terrain
+
* '''[<some_tag>]''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.
−
strings. The list is a comma separated list and matching will stop
+
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
−
at the first matched terrain string. There's one special character
+
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
−
''!'' which inverts the meaning of a match. Terrain strings can  
+
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.
−
use the wildcard * to match zero or more following letters, characters
 
−
behind the * are not allowed and the result is undefined.
 
  
−
Eg: <br>
+
== Tutorial ==
−
ww* matches ww, www, wwW but not WWW <br>
+
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]
−
!, ww returns false if ww found and true if not <br>
 
−
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.
 
  
 
== See Also ==
 
== See Also ==
  
−
* [[UnitWML]]
+
* [[AnimationWML#Animation_Filtering|Animation filtering]]
 +
* [[UnitTypeWML]]
 
* [[EventWML]]
 
* [[EventWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 +
* [[FilterWML/Examples - How to use Filter]]
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Latest revision as of 17:00, 3 November 2024

[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". A common use for location filters is to check the terrain of a space.

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/attacks are filtered on in WML. See also EventWML, EffectWML, AnimationWML.

These keys are used as filter input for attack 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/ 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' or customised type. (Version 1.17.23 and later only) [damage_type] can change the type of damage inflicted, and this change can be detected in the filter except when it is applied from a [damage_type] which affects the filtered attack, in this case only the type before any modification by a any [damage_type] will be detectable.
  • damage: filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
  • special_id: (Version 1.15.2 and later only) Filter on a weapon special by id, for example, magical in [chance_to_hit] id=magical. True if the unit has the special, whether or not it's currently active.
  • special_type: (Version 1.15.2 and later only) Filter on a weapon special by tag name for example, chance_to_hit in [chance_to_hit] id=magical. True if the unit has the special, whether or not it's currently active. For values see AbilitiesWML.
  • special_id_active: (Version 1.15.2 and later only) Like special_id, but true if the special is active at the current location. Does not work in 1.16. (Version 1.17.17 and later only) Works again.
  • special_type_active: (Version 1.15.2 and later only) Like special_type, but true if the special is active at the current location.
  • special: filter on the attack's special power, matches both id and tag name. (Version 1.15.2 and later only) Deprecated, see special_id and special_type instead.
  • special_active: (Version 1.13.8 and later only) Like special, but true if the special is active at the current location. (Version 1.15.2 and later only) Deprecated, see special_id and special_type instead.
  • [filter_special]: (Version 1.19.6 and later only) Filter on a weapon special by usingStandardAbilityFilter
    • active: if active=yes, true if the special is active at the current location. If active=no, true whether or not it's currently active, in this case, one special encoded in [attack] can be checked.
  • number: (Version 1.13.5 and later only) filter on number of strikes
  • parry: (Version 1.13.5 and later only) filter on parry value
  • accuracy: (Version 1.13.5 and later only) filter on accuracy value
  • movement_used: (Version 1.13.5 and later only) filter on attack's movement cost
  • attacks_used: (Version 1.17.13 and later only) filter on attack's attack cost
  • min_range: (Version 1.19.4 and later only) filter on attack's range (distance)
  • max_range: (Version 1.19.4 and later only) filter on attack's range (distance)
  • formula: (Version 1.13.5 and later only) filter using Wesnoth Formula Language. The context object for the formula is a weapon object, which supports the following keys: name, description, type, icon, range, damage, number, attack_weight, defense_weight, accuracy, parry, movement_used, specials. The specials key is a list of all the special IDs the unit possesses. Do not surround the formula in $(...), since that will erase the self variable. Keys supported after specific version: (Version 1.17.13 and later only) attacks_used. (Version 1.19.4 and later only) min_range, max_range.

[and], [or], and [not] subfilters are also supported.

Filtering Vision

The [filter_vision] tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the [hides] ability).

  • visible:
    • yes (default): matches when the location is not obscured by fog or shroud for the side and, when in a SUF, the unit is not hiding.
    • no: matches when the location is obscured by fog or shroud for the side or, when in a SUF, the unit is hiding.
  • respect_fog: yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded.
    • 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.
  • StandardSideFilter tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.

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

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

Note: In a location filter, this tag 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.

Filtering on WML data

Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. Anything between <> needs to be replaced by the actual data to be filtered for. The following conventions are possible:

  • <key>=<value>: Means that the key key must be present with the specified value.
  • glob_on_<key>=<glob>: (Version 1.15.0 and later only) Means that the key key must be present with a value that matches the specified glob. In a glob, the * character matches any sequence of characters, while the ? character matches any single character. In addition to the obvious, this is useful for matching the absence of a key - just place glob_on_<key>=* in a [not] tag.
  • [<some_tag>]: In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag some_tag present, and at least one of the some_tag tags must match the WML filter contained in [some_tag].
  • [not]: The WML filter contained in [not] must not match the WML.
  • [and]: (Version 1.15.0 and later only) In addition to the main filter, the filter contained in [and] must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.
  • [or]: (Version 1.15.0 and later only) Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with [or] tags, the first filter must not be wrapped in [or] tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other [or] tags are irrelevant.

Tutorial

See Also

Retrieved from "https://wiki.wesnoth.org/index.php?title=FilterWML&oldid=73926"
This page was last edited on 3 November 2024, at 17:00.