Difference between revisions of "FilterWML"

From The Battle for Wesnoth Wiki
(Changed stale link to units.wesnoth.org)
(Filtering Weapons: Document #4424/#3915)
(37 intermediate revisions by 17 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 28: Line 30:
 
Several actions, such as '''[terrain]''', also use location filters.
 
Several actions, such as '''[terrain]''', also use location filters.
 
Location filters are represented on this site by the phrase "standard location filter".
 
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.
 
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 ==
 
== Filtering Weapons ==
  
Sometimes weapons are filtered on in WML.  See also [[EventWML]], [[EffectWML]], [[AnimationWML]].
+
Sometimes weapons/attacks are filtered on in WML.  See also [[EventWML]], [[EffectWML]], [[AnimationWML]].
  
These keys are used as filter input for weapon filters.
+
These keys are used as filter input for attack filters.
  
 
* '''range''': a range to filter
 
* '''range''': a range to filter
 
** '''melee''': only melee weapons pass  
 
** '''melee''': only melee weapons pass  
 
** '''ranged''': only ranged weapons pass  
 
** '''ranged''': only ranged weapons pass  
* '''name''': filter on the attack's name.
+
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.
See '''data/units/''' or http://www.wesnoth.org/units/
+
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
to find the name of a particular unit's attack.
+
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''type''': filter on the attack's type.
+
* '''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.
Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
+
* '''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''': filter on the attack's special power.
+
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location.
For values see [[AbilitiesWML]].
+
* '''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.
 +
* '''number''': {{DevFeature1.13|5}} filter on number of attacks
 +
* '''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
 +
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]
 +
 
 +
'''[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 {{tag|AbilitiesWML|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.
  
== Filtering Terrains ==
+
'''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]
  
Use '''[filter_location]''' within '''[filter]''' , for example:
+
'''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.
  
[event]
+
== Filtering on WML data ==
:[filter]
 
::[filter_location]
 
::terrain=Ch
 
::[/filter_location]
 
:[/filter]
 
[/event]
 
  
At some places the terrains can be filtered with a
+
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. The following conventions are possible:
match list. The list is a comma separated list and matching will stop
 
at the first matched [[TerrainCodesWML|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: <br>
+
* '''key=value''': Means that the key '''key''' must be present with the specified value.
ww* matches ww, www, wwW but not WWW <br>
+
* '''glob_on_key=glob''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_key=*''' in a '''[not]''' tag.
!, ww returns false if ww found and true if not <br>
+
* '''[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]'''.
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.
+
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.
 +
* '''[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.
 +
* '''[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.
  
For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].
+
== Tutorial ==
 +
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]
  
 
== See Also ==
 
== See Also ==
  
* [[UnitWML]]
+
* [[UnitTypeWML]]
 
* [[EventWML]]
 
* [[EventWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 22:43, 17 October 2019

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

D:

damage, 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, found_item, for, foreach, 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, 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, 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.

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