getDistance: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
m (Conversion script moved page getDistance to GetDistance without leaving a redirect: Converting page title to first-letter uppercase)
No edit summary
 
(3 intermediate revisions by 2 users not shown)
Line 7: Line 7:


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getDistance(target)
getDistance(target tokenRef)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getDistance(target, units)
getDistance(target tokenRef, units)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getDistance(target, units, source)
getDistance(target tokenRef, units, source tokenRef)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getDistance(target, units, source, metric)
getDistance(target tokenRef, units, source tokenRef, metric)
</source>
</syntaxhighlight>
'''Parameters'''
'''Parameters'''
{{param|target|The id of the token that the distance is measured to.}}
{{param|target tokenRefEither the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] 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|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|source tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] 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}}
{{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|NO_GRID}} - The grid is ignored and straight line distance between the tokens is returned.
Line 29: Line 29:
** {{code|MANHATTAN}} - Diagonal movement costs 2 (Square grid only).
** {{code|MANHATTAN}} - Diagonal movement costs 2 (Square grid only).
** {{code|NO_DIAGONALS}} - No diagonal movement is allowed (Square grid only).
** {{code|NO_DIAGONALS}} - No diagonal movement is allowed (Square grid only).
{{Note|Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.}}


|example=
|example=
To get the distance from the current token to the ''Altar''.
To get the distance from the current token to the ''Altar''.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: dist = getDistance("Altar")]
[h: dist = getDistance("Altar")]
</source>
</syntaxhighlight>


To get the distance between the ''Altar'' and the ''Sacrifice'' in the number of squares or hexes.
To get the distance between the ''Altar'' and the ''Sacrifice'' in the number of squares or hexes.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: dist = getDistance("Altar", 0, "Sacrifice")]
[h: dist = getDistance("Altar", 0, "Sacrifice")]
</source>
</syntaxhighlight>


To get the distance between the ''Altar'' and the ''Sacrifice'' in ''map distance'' units.
To get the distance between the ''Altar'' and the ''Sacrifice'' in ''map distance'' units.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: dist = getDistance("Altar", 1, "Sacrifice")]
[h: dist = getDistance("Altar", 1, "Sacrifice")]
</source>
</syntaxhighlight>


To get the straight line distance between the ''Altar'' and the ''Sacrifice''.
To get the straight line distance between the ''Altar'' and the ''Sacrifice''.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: dist = getDistance("Altar", 1, "Sacrifice", "NO_GRID")]
[h: dist = getDistance("Altar", 1, "Sacrifice", "NO_GRID")]
</source>
</syntaxhighlight>


|also= {{func|getDistanceToXY}} {{func|getTokens}}
|also= {{func|getDistanceToXY}} {{func|getTokens}}

Latest revision as of 02:51, 13 May 2024

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 tokenRef)
getDistance(target tokenRef, units)
getDistance(target tokenRef, units, source tokenRef)
getDistance(target tokenRef, units, source tokenRef, metric)

Parameters

  • target tokenRefEither the token id or Token Name of the token that the distance is measured to. - {{{2}}}
  • 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 tokenRef - Either the token id or Token Name 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).
Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.

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

getDistanceToXY() getTokens()

Version Changes

  • 1.3b55 - Added the optional metric argument.
Retrieved from "https://wiki.rptools.info/index.php?title=getDistance&oldid=17811"