getTokenFacing: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(Initial write-up.)
 
No edit summary
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{stub}}
{{MacroFunction
{{MacroFunction
|name=getTokenFacing
|name=getTokenFacing
|trusted=true
|trusted=false
|version=1.3b51
|version=1.3b51
|description=
|description=
Gets the facing angle of the token, or {{code|""}} if there is no facing.
Gets the facing angle for the specified or current token. Values will range from -179 to +180. Default facing is -90 degrees or down, 0 degrees is to the right, +90 degrees is up, +180 degrees is to the left. The jump in the value range is the difference between "exactly left" (+180) and "almost exactly left, but tilted 1 degree down" (-179).<br />
Note that [[math#atan2_r|math.atan2_r]] can be used to calculate facing from a direction given in two coordinate pairs.


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getTokenFacing()
getTokenFacing()
</source>
getTokenFacing(tokenRef)
<source lang="mtmacro" line>
getTokenFacing(tokenRef, mapname)
getTokenFacing(id)
</syntaxhighlight>
</source>
'''Parameters'''
'''Parameters'''
* {{code|id}} - The id of the token to get the facing from, defaults to the current token. If this parameter is used, this function requires a trusted macro.
{{param|tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to get the facing from, defaults to the current token.}}{{TrustedParameter}}
{{param|mapname|The name of the map to find the token.  Defaults to the current map.}}
{{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.}}


'''Returns'''
The angle in degrees or {{code|""}} if no facing has been set
|example=
<syntaxhighlight lang="mtmacro" line>
[h: switchToken("Mage")]
[r: token.name]: [r: r = getTokenFacing()]<br>
[h: switchToken("Elf")]
[r: token.name]: [r: r = getTokenFacing()]<br>
[h: switchToken("Hero")]
[r: token.name]: [r: r = getTokenFacing()]<br>
[h: switchToken("Troll")]
[r: token.name]: [r: r = getTokenFacing()]
</syntaxhighlight>
'''Returns:'''<br />
[[File:GetTokenFacing.png]]
|also=
[[setTokenFacing]]<br />[[getTokenRotation]]
|changes=
{{change|1.5.4|Added {{code|mapname}} parameter option.}}
}}
}}
[[Category:Token Function]]
[[Category:Token Function]]

Latest revision as of 16:19, 14 May 2024

getTokenFacing() Function

Introduced in version 1.3b51
Gets the facing angle for the specified or current token. Values will range from -179 to +180. Default facing is -90 degrees or down, 0 degrees is to the right, +90 degrees is up, +180 degrees is to the left. The jump in the value range is the difference between "exactly left" (+180) and "almost exactly left, but tilted 1 degree down" (-179).
Note that math.atan2_r can be used to calculate facing from a direction given in two coordinate pairs.

Usage

getTokenFacing()
getTokenFacing(tokenRef)
getTokenFacing(tokenRef, mapname)

Parameters

  • tokenRef - Either the token id or Token Name of the token to get the facing from, defaults to the current token.

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

  • mapname - The name of the map to find the token. Defaults to the current map.
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.


Returns The angle in degrees or "" if no facing has been set

Example

[h: switchToken("Mage")]
[r: token.name]: [r: r = getTokenFacing()]<br>
[h: switchToken("Elf")]
[r: token.name]: [r: r = getTokenFacing()]<br>
[h: switchToken("Hero")]
[r: token.name]: [r: r = getTokenFacing()]<br>
[h: switchToken("Troll")]
[r: token.name]: [r: r = getTokenFacing()]

Returns:

See Also

Version Changes

  • 1.5.4 - Added mapname parameter option.