getDistance: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(Initial write-up.)
 
(Updated for b55 changes and created examples for the function.)
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>


|changes=
{{code|b55}} - added the optional metric argument.
}}
}}
[[Category:Distance Function]]
[[Category:Distance Function]]

Revision as of 06:44, 14 April 2009

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")]


Version Changes

b55 - added the optional metric argument.