copyToken: Difference between revisions
(No difference)
|
Revision as of 23:13, 9 February 2023
copyToken() Function
Note: This function can only be used in a Trusted Macro
Usage
copyToken(id)
copyToken(id, numCopies)
copyToken(id, numCopies, fromMap)
copyToken(id, numCopies, fromMap, updates)
newId = copyToken(id, numCopies, fromMap, updates)
Parameters
id
- The id or name of the token to copy.numCopies
- The number of copies to create, defaults to1
fromMap
- The name of the map to copy from, defaults to the current map.updates
- a JSON Object that contains updates to be made to the copied Tokens.
You can use an empty string ("") for fromMap
for the current map as of b54.
The return type of this function is determined by the number of copies that you are making. If you are only creating a single copy of the token then a string containing the Tokens id, if you are making more than one copy then a JSON Array containing the Token ids of all the newly created Tokens is returned.
Updates parameter
updates
is a JSON Object that can contain one or more of the following fields. Field names are case-sensitive.
name
- The name of the new Token.label
- The label for the new Token.gmName
- The GM name for the new Token.layer
- The layer for the new Token. By default, changing the layer of a new token will also change its shape. Tokens changed to theObject
orBackground
layer will become top-down tokens. For tokens moved to theToken
orHidden
layer, MapTool will attempt to determine their shape based on their image.forceShape
- when the layer field is set, setting this tofalse
(0
) will disable the automatic change of shape.x
- The X Co-ordinate for the new Token. Default is0
.y
- The Y Co-ordinate for the new Token. Default is0
.useDistance
-1
(true) or0
(false). Determines if the "Distance Per Cell" measurement for the map is used for the x,y coordinates. Unused if neitherx
nory
is specified. Default is false. Use1
(true) for tokens that are not snap-to-grid and must be placed by pixel position instead of grid cell position.facing
- Sets the facing for the Token. If the Token is on the background or object layer this sets the rotation.size
- Sets the size of the Token. The list of sizes is dependent on the type of grid.delta
- Userelativeto
instead ofdelta
starting in 1.9.0.1
(true) or0
(false). Indicates whether the x,y coordinates are relative to the position of the original token. Added in 1.3b77. To be considered deprecated in 1.9.0relativeto
- A string defining what thex
andy
parameters should be relative to. Can be"map"
for absolute positioning,"source"
for the token to be copied, or"current"
for the Current Token. Defaults to"map"
. To be added in 1.9.0tokenImage
/tokenPortrait
/tokenHandout
- Changes the coresponding image. Value can be either an assetId or an image token name. Added in 1.3b77.
The values for all of these fields are evaluated so all text within {}
or []
goes through the standard macro processing. There is currently no way to modify the new token from inside these macro commands, however.
When the name is not changed using the updates
parameter, the new name for the token follows the naming method for cut and paste.
This function can copy Tokens in the token, hidden, object, and background layers. If you do not override the destination using the
layer
field of updates
then the new copies are made in the same layer as the source. Likewise if x
and y
are not specified then these locations are the same as the source.
Examples
Make a single copy of the Hero from the current map.
[h: copyToken("Hero")]
Make a single copy of the Hero from another map.
[h: copyToken("Hero", 1, "Green Room")]
Or if you are playing paranoia and want to create six clones.
[h: copyToken("Hero", 6, "Clone Vat")]
But as a PC the new tokens don't get new names so we could give each of them a new name in b54+ using the following.
[h: cloneNo = 0]
[h: updates = json.set("{}",
"name", "Hero Clone - [r: cloneNo = cloneNo + 1]"
)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
This will copy all our clones to the current map but spaced out along the X axis.
[h: cloneNo = 0]
[h: x = 0]
[h: updates = json.set("{}",
"name", "Hero Clone - [r: cloneNo = cloneNo + 1]",
"x", "[r: x = x + 2]",
"y", 0
)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
Or combining rotation
[h: x = 0]
[h: facing = 0]
[h: cloneNo = 0]
[h: updates = json.set("{}",
"name", "Hero Clone - [r: cloneNo = cloneNo + 1]",
"x", "[r: x = x + 2]",
"y", 0,
"facing", "[r: facing = facing + 40]"
)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
And now we have tumbling clones:
The source token was configured as a Top Down token for this effect, otherwise the facing
setting would produce a facing arrow
for Tokens on the token or hidden layers.
This example shows using the new relativeto
parameter available in 1.9.0. Specifying "map"
means all x,y coordinates are treated as absolute coordinates on the map. Specifying "source"
places copied tokens relative to the position of the token that is beingc copied. Specifying "current"
places copied tokens relative to the Current Token. x
and y
are measured in grid cells if useDistance
is false (the default) or in pixels if true
.
[h: x = 0]
[h: updates = "{
x: '[r: x = x + 2]',
relativeto: 'source',
}" ]
[h: copyToken(currentToken(), 3, "", updates)]
Make three copies of the currently selected token on the current map. Place the first copy two grid cells to the right of the original token. This used to be accomplished using "delta": 1,
.
[h: x = 0]
[h: updates = "{
x: '[r: x = x + 2]',
relativeto: 'current',
}" ]
[h: copyToken(currentToken(), 3, "", updates)]
Make three copies of the currently selected token on the current map. Place the first copy two grid cells to the right of the Current Token.
also
moveTokenToMap(), moveTokenFrom()
changes
- 1.3b54 - Added optional
updates
parameter. - 1.3b77 - Added
tokenImage
,portraitImage
,handoutImage
, anddelta
toupdates
.
- 1.5.7 - Token copies can now be modified within same macro, and
tokenPortrait
andtokenHandout
can now be used instead ofportraitImage
andhandoutImage
. - 1.9.0 - The positioning system for copied tokens has been altered to be more straightforward.
delta
is now a deprecated parameter which has been replaced withrelativeto