Difference between revisions of "StandardLocationFilter"

From The Battle for Wesnoth Wiki
Line 8: Line 8:
 
* '''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
 
* '''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
 
* '''radius''': matches if any location within the radius matches this filter
 +
* '''[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.
 
: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]
 
   [have_location]
Line 17: Line 46:
 
   [/and]
 
   [/and]
 
   [/have_location]
 
   [/have_location]
 
* '''[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"
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 07:36, 1 March 2008

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).
  • terrain: comma separated list of terrains. If you are using terrain letters (TerrainCodesWML), 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
  • [filter]: a StandardUnitFilter; 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
  • [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]