getTokenRotation: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
mNo edit summary
No edit summary
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{stub|No examples yet.}}
{{MacroFunction
{{MacroFunction
|name= getTokenRotation
|name= getTokenRotation
Line 6: Line 5:
|version=1.5.0
|version=1.5.0
|description=
|description=
Retrieves the token's rotation angle in degrees.
Retrieves the angle of rotation for the token from the default position.  Returned value is in degrees.
 
For Square, Round or Figure token types, this is the change in the facing indicator from the default of 0 degrees or no change in facing.  Positive is CW and negative is CCW. Values will range from -270 to +89.
 
For Top Down tokens, this is the rotation of the token image itself from the default of 0 degrees.


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getTokenRotation()
getTokenRotation()
getTokenRotation(id)
getTokenRotation(tokenRef)
</source>
getTokenRotation(tokenRef, mapRef)
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
{{param|id|The token id of the token to retrieve the rotation angle.  Defaults to the [[Current Token]].}}{{TrustedParameter}}
{{param|tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to retrieve the rotation angle.  Defaults to the [[Current Token]].}}{{TrustedParameter}}
{{param|mapRef|The Name or ID 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.}}
 
'''Result'''<br />
'''Result'''<br />
The function returns the token's rotation as a numeric value measured in degrees.
The function returns the token's rotation as a numeric value measured in degrees.
|example=
|example=
Needs real example showing possible return values.  I recall there was some discussion about whether the return value went from -90 to +270 or from 0 to 360.  It calls '''Token.getFacingInDegrees()'''.
Get the rotation for the four tokens shown below.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[r: getTokenRotation()]
[h: switchToken("Mage")]
</source>
[r: token.name] - [r: r = getTokenRotation()]<br>
[h: switchToken("Elf")]
[r: token.name] - [r: r = getTokenRotation()]<br>
[h: switchToken("Hero")]
[r: token.name] - [r: r = getTokenRotation()]<br>
[h: switchToken("Troll")]
[r: token.name] - [r: r = getTokenRotation()]</syntaxhighlight>
Returns:
Returns:
[[File:GetTokenRotation.png]]
'''Relation to Token Facing'''
When no facing has been set, [[getTokenFacing]] will return the blank string {{code|""}} but getTokenRotation will return 0. Consequently getTokenRotation does not require a check to ensure the result is usable for calculations.
To convert from rotation to facing (or vice versa) these relations can be used:
<syntaxhighlight lang="mtmacro" line>
facing = -(rotation + 90)
</syntaxhighlight>
<syntaxhighlight lang="mtmacro" line>
rotation = -(facing + 90)
</syntaxhighlight>


|also=
|also=
[[setTokenFacing]]
|changes=
{{change|1.5.4|Added {{code|mapname}} parameter option.}}
}}
}}
[[Category:Token Function]]
[[Category:Token Function]]

Latest revision as of 23:59, 14 May 2024

getTokenRotation() Function

• Introduced in version 1.5.0
Retrieves the angle of rotation for the token from the default position. Returned value is in degrees.

For Square, Round or Figure token types, this is the change in the facing indicator from the default of 0 degrees or no change in facing. Positive is CW and negative is CCW. Values will range from -270 to +89.

For Top Down tokens, this is the rotation of the token image itself from the default of 0 degrees.

Usage

getTokenRotation()
getTokenRotation(tokenRef)
getTokenRotation(tokenRef, mapRef)

Parameters

  • tokenRef - Either the token id or Token Name of the token to retrieve the rotation angle. Defaults to the Current Token.

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

  • mapRef - The Name or ID 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.


Result
The function returns the token's rotation as a numeric value measured in degrees.

Example

Get the rotation for the four tokens shown below. 
[h: switchToken("Mage")]
[r: token.name] - [r: r = getTokenRotation()]<br>
[h: switchToken("Elf")]
[r: token.name] - [r: r = getTokenRotation()]<br>
[h: switchToken("Hero")]
[r: token.name] - [r: r = getTokenRotation()]<br>
[h: switchToken("Troll")]
[r: token.name] - [r: r = getTokenRotation()]

Returns:

Relation to Token Facing

When no facing has been set, getTokenFacing will return the blank string "" but getTokenRotation will return 0. Consequently getTokenRotation does not require a check to ensure the result is usable for calculations.

To convert from rotation to facing (or vice versa) these relations can be used: 

facing = -(rotation + 90)
rotation = -(facing + 90)

See Also

setTokenFacing

Version Changes

  • 1.5.4 - Added mapname parameter option.
Retrieved from "https://rptools.hyperbooks.com/index.php?title=getTokenRotation&oldid=35091"