moveToken: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(Added examples and some clarification.)
No edit summary
 
(10 intermediate revisions by 8 users not shown)
Line 6: Line 6:


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
moveToken(x, y)
moveToken(x, y)
</source>
<source lang="mtmacro" line>
moveToken(x, y, units)
moveToken(x, y, units)
</source>
moveToken(x, y, units, tokenRef)
<source lang="mtmacro" line>
</syntaxhighlight>
moveToken(x, y, units, id)
</source>
'''Parameters'''
'''Parameters'''
* {{code|x}} - The X coordinate to move the token to.
* {{code|x}} - The X coordinate to move the token to.
* {{code|y}} - The Y coordinate to move the token to.
* {{code|y}} - The Y coordinate to move the token to.
* {{code|units}} - If set to {{false}}, the coordinates are a location on the grid in '''cells'''. Defaults to {{true}}, where the coordinates are ''Distance Per Cell'' '''units'''.
* {{code|units}} - If set to {{false}}, the coordinates are a location on the grid in '''cells'''. Defaults to {{true}}, where the coordinates are in ''Distance Per Cell'' '''pixels'''.
* {{code|id}} - The id [[Macros:Variables:string|string]] of the token to move, defaults to the [[Current Token]].
* {{code|tokenRef}} - Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to move, defaults to the [[Current Token]].{{TrustedParameter}}
{{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.}}


&nbsp;
<!-- The 'nbsp' is needed to close the DIV -->
|examples=
|examples=
Moves the [[Current Token]] down {{code|5}} '''units''', and left {{code|10}} '''units'''.
Moves the [[Current Token]] right {{code|5}} '''pixels''', and up {{code|10}} '''pixels'''.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: CurrentX = getTokenX()]
[h: CurrentX = getTokenX()]
[h: CurrentY = getTokenY()]
[h: CurrentY = getTokenY()]
Line 29: Line 28:
[h: NewY = CurrentY - 10]
[h: NewY = CurrentY - 10]
[h: moveToken(NewX, NewY)]
[h: moveToken(NewX, NewY)]
</source>
</syntaxhighlight>


Moves the [[Current Token]] down {{code|5}} '''cells''', and left {{code|10}} '''cells'''.
Moves the [[Current Token]] right {{code|5}} '''cells''', and up {{code|10}} '''cells'''.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: CurrentX = getTokenX(0)]
[h: CurrentX = getTokenX(0)]
[h: CurrentY = getTokenY(0)]
[h: CurrentY = getTokenY(0)]
Line 38: Line 37:
[h: NewY = CurrentY - 10]
[h: NewY = CurrentY - 10]
[h: moveToken(NewX, NewY, 0)]
[h: moveToken(NewX, NewY, 0)]
</source>
</syntaxhighlight>


|also=
|also=
{{func|getTokenX}},  
{{func|getTokenX}},  
{{func|getTokenY}}
{{func|getTokenY}},
{{func|moveTokenToMap}},
{{func|moveTokenFromMap}}


}}
}}
[[Category:Token Function]]
[[Category:Token Function]]

Latest revision as of 21:09, 17 May 2024

moveToken() Function

Introduced in version 1.3b51
Move a token to a new location.

Usage

moveToken(x, y)
moveToken(x, y, units)
moveToken(x, y, units, tokenRef)

Parameters

  • x - The X coordinate to move the token to.
  • y - The Y coordinate to move the token to.
  • units - If set to false(0), the coordinates are a location on the grid in cells. Defaults to true(1), where the coordinates are in Distance Per Cell pixels.
  • tokenRef - Either the token id or Token Name of the token to move, defaults to the Current Token.

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

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.


 

Examples

Moves the Current Token right 5 pixels, and up 10 pixels.
[h: CurrentX = getTokenX()]
[h: CurrentY = getTokenY()]
[h: NewX = CurrentX + 5]
[h: NewY = CurrentY - 10]
[h: moveToken(NewX, NewY)]

Moves the Current Token right 5 cells, and up 10 cells.

[h: CurrentX = getTokenX(0)]
[h: CurrentY = getTokenY(0)]
[h: NewX = CurrentX + 5]
[h: NewY = CurrentY - 10]
[h: moveToken(NewX, NewY, 0)]

See Also