From FilterWML, this is the standard way of filtering on locations. The following attributes and sub-tags are permitted:
- time_of_day: filter matches only on a given time of day (one of lawful, chaotic or neutral). Note: chaotic, lawful and neutral; these are not times of day, these are alignments. To match against 'dawn', 'dusk', 'first watch' etc., use the time_of_day_id key described below.
- time_of_day_id: this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from data/core/macros/schedules.cfg. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
- terrain: comma separated list of terrains. (See also: Filtering Terrains).
- x,y: the same as in the unit filter; supports any range (notes)
- [filter] with a StandardUnitFilter as argument; if present a unit must also be there
- owner_side: the side of the owner, if this location is an owned village.
- 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
- radius: matches if any location within the radius matches this filter (notes)
- [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
- [and]: an extra location filter. Unless a location matches the [and] filter, then it will be excluded. 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.
- [not]: an extra location filter. If a location matches the [not] filter, then that location will be excluded.
- [filter_adjacent_location]: a standard location filter; if present the correct number of adjacent locations 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"
Notes about Coordinate Usage
When specifying coordinates, the following keys are used:
- x: the first coordinate
- y: the second coordinate
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.
Notes about Radius Usage
- If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location] terrain=Gg^Vh [and] x=$x1 y=$y1 radius=1 [/and] [/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location] x,y=15,23 radius=5 [not] [filter] [/filter] [/not] [have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.