VASSAL Reference Manual

Home > Module > Expressions > Range Expressions

Range Functions

Overview

Vassal provides a set of functions to calculate the range between 2 different locatons on a map. The range can be calulcated either in pixels, or in the native cell size of the map for Hex and Square grids.

If you ask for a range in Cells on a map that does not support it, then the range will be provided in pixels. The 'Cell' size will be based on the grid that applies at the From point.

Note	On maps with a Zoned Grid, the Grid at the From location is assumed to fill the entire Map for the purposes of the Range calculation.

If there are any errors during calculation (for example, trying to calculate the range to a piece on a different map), then a range of 0 will be reported.

Most of the functions are designed to be used within piece traits and calculate the range from the position of the current piece to another location.

Trait Only Functions

Most of the Range functions are marked with the notation [ Trait Only ]. These functions can only be used inside expressions in Piece Traits, or in components where they will be applied to individual pieces.

The fields in components where these functions can be used are:

The Additional matching expression field in any Global Key Command

Using these functions in any other context (for example a Map movement report) will return a result of 0.

Range functions

Range	Calculate the range in Grid Units between two locations.
Range(x, y) RangePx(x, y) [ Trait Only ]	Calculate the range in Grid Units or pixels from the current piece to the specified X, Y co-ordinate on the current Map. Range(100, 200) RangePx(100, 200) Calculate the range in Grid Units or pixels from the current piece to 100, 200 on the same Map.
Range(x1, y1, x2, y2) RangePx(x1, y1, x2, y2) [ Trait Only ]	Calculate the range in Grid Units or pixels from one X, Y position to another X, Y position on the current Map. Range(OldCurrentX, OldCurrentY, CurrentX, CurrentY) RangePx(OldCurrentX, OldCurrentY, CurrentX, CurrentY) Calculate the range in Grid Units or pixels from the previous position of the current piece to its current position.
Range(x1, y1, x2, y2, map) RangePx(x1, y1, x2, y2, map)	Calculate the range in Grid Units or pixels from one X, Y position to another X, Y position on named Map. Range(LastSeenX, LastSeenY, HomeX, HomeY, "BaseMap") RangePx(LastSeenX, LastSeenY, HomeX, HomeY, "BaseMap") Calculate the range in Grid Units or pixels on the Map BaseMap from position given by LastSeenX, LastSeenY to the position given by HomeX, HomeY.
Range(attachment) RangePx(attachment) [ Trait Only ]	Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the named Attachment. If the current piece is self-attached, it will not be selected as the piece to check the range. Range("MyGroup") RangePx("MyGroup") Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the MyGroup Attachment.
RangePx(attachment, expr) [ Trait Only ]	Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the named Attachment that also matches the supplied Property Match Expression. If the current piece is self-attached, it will not be selected as the piece to check the range. Range("MyGroup", "{Strength > 10}") RangePx("MyGroup", "{Strength > 10}") Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the MyGroup Attachment that has a Strength property value greateer than 10.

Range

Calculate the range in Grid Units between two locations.

Range(x, y)
RangePx(x, y)

[ Trait Only ]

Calculate the range in Grid Units or pixels from the current piece to the specified X, Y co-ordinate on the current Map.

Range(100, 200)
RangePx(100, 200)

Calculate the range in Grid Units or pixels from the current piece to 100, 200 on the same Map.

Range(x1, y1, x2, y2)
RangePx(x1, y1, x2, y2)

[ Trait Only ]

Calculate the range in Grid Units or pixels from one X, Y position to another X, Y position on the current Map.

Range(OldCurrentX, OldCurrentY, CurrentX, CurrentY)
RangePx(OldCurrentX, OldCurrentY, CurrentX, CurrentY)

Calculate the range in Grid Units or pixels from the previous position of the current piece to its current position.

Range(x1, y1, x2, y2, map)
RangePx(x1, y1, x2, y2, map)

Calculate the range in Grid Units or pixels from one X, Y position to another X, Y position on named Map.

Range(LastSeenX, LastSeenY, HomeX, HomeY, "BaseMap")
RangePx(LastSeenX, LastSeenY, HomeX, HomeY, "BaseMap")

Calculate the range in Grid Units or pixels on the Map BaseMap from position given by LastSeenX, LastSeenY to the position given by HomeX, HomeY.

Range(attachment)
RangePx(attachment)

[ Trait Only ]

Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the named Attachment.

If the current piece is self-attached, it will not be selected as the piece to check the range.

Range("MyGroup")
RangePx("MyGroup")

Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the MyGroup Attachment.

RangePx(attachment, expr)

[ Trait Only ]

Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the named Attachment that also matches the supplied Property Match Expression.

If the current piece is self-attached, it will not be selected as the piece to check the range.

Range("MyGroup", "{Strength > 10}")
RangePx("MyGroup", "{Strength > 10}")

Calculate the range in Grid Units or pixels from the current piece to the first piece attached to this piece by the MyGroup Attachment that has a Strength property value greateer than 10.