getDistance: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(Initial write-up.)
 
No edit summary
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{stub}}
{{MacroFunction
{{MacroFunction
|name=getDistance
|name=getDistance
Line 5: Line 4:
|version=1.3b51
|version=1.3b51
|description=
|description=
Returns the distance between two tokens.
Returns the distance between two tokens or objects.  


|usage=
|usage=
Line 16: Line 15:
<source lang="mtmacro" line>
<source lang="mtmacro" line>
getDistance(target, units, source)
getDistance(target, units, source)
</source>
<source lang="mtmacro" line>
getDistance(target, units, source, metric)
</source>
</source>
'''Parameters'''
'''Parameters'''
* {{code|target}} - The id of the token that the distance is measured to.
{{param|target|The id of the token that the distance is measured to.}}
* {{code|units}} - If set to {{code|false}}({{code|0}}), the distance is given in cells, otherwise the default is to return the distance in Distance Per Cell units.
{{param|units|If set to {{code|false}}({{code|0}}), the distance is given in cells, otherwise the default is to return the distance in Distance Per Cell units.}}
* {{code|source}} - The id of the token to measure the distance from, the default is the current token.
{{param|source|The id of the token to measure the distance from, the default is the current token.}}
{{param|metric|The movement metric to use which defaults to the movement metric in the users preferences, the metric can be one of the following strings}}
** {{code|NO_GRID}} - The grid is ignored and straight line distance between the tokens is returned.
** {{code|ONE_TWO_ONE}} - First Diagonal movement costs 1, second 2, and so on (Square grid only).
** {{code|ONE_ONE_ONE}} - Diagonal movement costs a single square (Square grid only).
** {{code|MANHATTAN}} - Diagonal movement costs 2 (Square grid only).
** {{code|NO_DIAGONALS}} - No diagonal movement is allowed (Square grid only).
 
|example=
To get the distance from the current token to the ''Altar''.
<source lang="mtmacro" line>
[h: dist = getDistance("Altar")]
</source>
 
To get the distance between the ''Altar'' and the ''Sacrifice'' in the number of squares or hexes.
<source lang="mtmacro" line>
[h: dist = getDistance("Altar", 0, "Sacrifice")]
</source>
 
To get the distance between the ''Altar'' and the ''Sacrifice'' in ''map distance'' units.
<source lang="mtmacro" line>
[h: dist = getDistance("Altar", 1, "Sacrifice")]
</source>
 
To get the straight line distance between the ''Altar'' and the ''Sacrifice''.
<source lang="mtmacro" line>
[h: dist = getDistance("Altar", 1, "Sacrifice", "NO_GRID")]
</source>


|also= {{func|getDistanceToXY}} {{func|getTokens}}
|changes=
{{change|1.3b55|Added the optional {{code|metric}} argument.}}
}}
}}
[[Category:Distance Function]]
[[Category:Distance Function]]

Revision as of 21:32, 3 May 2015

getDistance() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.3b51
Returns the distance between two tokens or objects.

Usage

getDistance(target)
getDistance(target, units)
getDistance(target, units, source)
getDistance(target, units, source, metric)

Parameters

  • target - The id of the token that the distance is measured to.
  • units - If set to false(0), the distance is given in cells, otherwise the default is to return the distance in Distance Per Cell units.
  • source - The id of the token to measure the distance from, the default is the current token.
  • metric - The movement metric to use which defaults to the movement metric in the users preferences, the metric can be one of the following strings
    • NO_GRID - The grid is ignored and straight line distance between the tokens is returned.
    • ONE_TWO_ONE - First Diagonal movement costs 1, second 2, and so on (Square grid only).
    • ONE_ONE_ONE - Diagonal movement costs a single square (Square grid only).
    • MANHATTAN - Diagonal movement costs 2 (Square grid only).
    • NO_DIAGONALS - No diagonal movement is allowed (Square grid only).

Example

To get the distance from the current token to the Altar.
[h: dist = getDistance("Altar")]

To get the distance between the Altar and the Sacrifice in the number of squares or hexes.

[h: dist = getDistance("Altar", 0, "Sacrifice")]

To get the distance between the Altar and the Sacrifice in map distance units.

[h: dist = getDistance("Altar", 1, "Sacrifice")]

To get the straight line distance between the Altar and the Sacrifice.

[h: dist = getDistance("Altar", 1, "Sacrifice", "NO_GRID")]

See Also

Version Changes

  • 1.3b55 - Added the optional metric argument.