getDistance: Difference between revisions
Jump to navigation
Jump to search
Verisimilar (talk | contribs) (Initial write-up.) |
(Updated for b55 changes and created examples for the function.) |
||
| Line 1: | Line 1: | ||
{{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''' | ||
* {{ | * {{param|target|The id of the token that the distance is measured to.}} | ||
* {{ | * {{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.}} | ||
* {{ | * {{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 tofalse(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 stringsNO_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.