copyToken: Difference between revisions

Revision as of 16:11, 11 October 2019

copyToken() Function

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

• Introduced in version 1.3b51

Creates one or more copies of a Token and returns the id of the created copy. This function is used to copy Tokens into the current map, the Tokens you are making copies of can reside on any map. Note: Prior to MapTool 1.5.7, making changes to the copies required special techniques to ensure the changes were kept. See copyToken legacy page.

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 to 1
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.
x - The X Co-ordinate for the new Token. Default is 0.
y - The Y Co-ordinate for the new Token. Default is 0.
useDistance - 1 (true) or 0 (false). Determines if the "Distance Per Cell" measurement for the map is used for the x,y coordinates. Unused if neither x nor y is specified. Default is false. Use 1 (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 - 1 (true) or 0 (false). Indicates whether the x,y coordinates are relative to the position of the original token. Added in 1.3b77.
tokenImage / portraitImage / handoutImage - 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 = "{ 
                 name: 'Hero Clone - [r: cloneNo = cloneNo + 1]'
               }"
]
[h: cloneNo = 0]
[h: copyToken("Hero", 6, "Clone Vat", updates)]

This will copy all our clones to the current map but they are all on top of each other, to line them up

[h: cloneNo = 0]
[h: x = 0]
[h: updates = "{ 
                 name: 'Hero Clone - [r: cloneNo = cloneNo + 1]',
                 x: '[r: x = x + 2]',
                 y: 0
               }"
]
[h: cloneNo = 0]
[h: copyToken("Hero", 6, "Clone Vat", updates)]

Or combining rotation

[h: cloneNo = 0]
[h: x = 0]
[h: facing = 0]
[h: updates = "{ 
                 name: 'Hero Clone - [r: cloneNo = cloneNo + 1]',
                 x: '[r: x = x + 2]',
                 y: 0,
                 facing: '[r: facing = facing + 40]'
               }"
]
[h: cloneNo = 0]
[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.

Tumbling Clones using Round Tokens and Facing Arrows

This example shows using the new delta parameter available in 1.3b77. Specifying true means all x,y coordinates are treated as offsets from the original token. They 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]',
    delta: 1,
}" ]
[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. (Note that the trailing comma after delta: 1 is ignored by MapTool.)

also

moveTokenToMap(), moveTokenFrom()

changes

1.3b54 - Added optional updates parameter.
1.3b77 - Added tokenImage, portraitImage, handoutImage, and delta to updates.

1.5.7 - Token copies can now be modified within same macro.

@@ Line 3: / Line 3: @@
 |trusted=true
 |version=1.3b51
-|description=Creates one or more copies of a [[Token]] and returns the id of the created copy. This function is used to copy [[Token]]s into the current map, the [[Token]]s you are making
+|description=Creates one or more copies of a [[Token]] and returns the id of the created copy. This function is used to copy [[Token]]s into the current map, the [[Token]]s you are making copies of can reside on any map. Note: Prior to MapTool 1.5.7, making changes to the copies required special techniques to ensure the changes were kept. See [[copyToken legacy]] page.
-copies of can reside on any map. '''You can not make any modifications to the newly created [[Token]]s in the macro that creates them'''. Any changes made to the newly created token are reverted as soon as the macro ends!
-As of b54 there is a new parameter that allows you to make some changes to the new tokens.
-'''Note:''' below you can find several methods on how to make changes to the newly created
 |usage=
@@ Line 18: / Line 13: @@
 newId = copyToken(id, numCopies, fromMap, updates)
 </source>
 ===Parameters===
@@ Line 27: / Line 21: @@
 You can use an empty string ("") for {{code|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
@@ Line 53: / Line 46: @@
 When the name is not changed using the {{code|updates}} parameter, the new name for the token follows the naming method for cut and paste.
 This function can copy [[Token]]s in the token, hidden, object, and background layers.  If you do not override the destination using the
-{{code|layer}} field of {{code|updates}} then the new copies are made in the same layer as the source.  Likewise if {{code|x}} and {{code|y}}
+{{code|layer}} field of {{code|updates}} then the new copies are made in the same layer as the source.  Likewise if {{code|x}} and {{code|y}} are not specified then these locations are the same as the source.
-are not specified then these locations are the same as the source.
-===How to make additional changes to the newly created token===
-As said, ANY changes made to the new token will be reverted as soon as the macro ends. However there are a couple of methods to do it anyway.
-The most reliable and straightforward method is to change the ORIGINAL token first and then copy it. You *can* revert the changes to the original after the copyToken. However if the original token is not on the same map then you can't immediately change the original. To solve that here some methods:
-a. The best methods in that case is to {{func|moveTokenFromMap}} to the current map and then {{func|moveTokenToMap}} back.
-b. You could also use {{func|setCurrentMap}}) to go to the 'original' map, change the token and switch back, that however will result in a minor flicker on screen.
-c. A final alternative is adding the 'lib:' prefix to the original, that way its properties are accessible throughout all maps
-. The simplest method is by creating an interrupt in the macro after the copies have been made. This is simply done with the use of {{func|input}}. This however will result in a pop-up on screen which you have to click away so the macro can continue with the update.
-. Another (not always working method) is to make changes to the created tokens done by a second 'deferred' macro that is called after the copies have been created. Look for [[execLink]] for calling a macro ''deferred''.
@@ Line 153: / Line 128: @@
 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.  (Note that the trailing comma after {{code|delta: 1}} is ignored by MapTool.)
-==examples of updates after copy==
-Simplest method:
-<source lang="mtmacro" line>
-[h:id=copyToken("Hero")]
-[h:input("junk|This interruption is required to create the new token. Click ok to continue.|Message |LABEL")]
-[h:setProperty("Strength", 3d6,id)]
-</source>
-Straightforward method:
-<source lang="mtmacro" line>
-[h:moveTokenFromMap("Hero", "Grasslands")]
-[h:setProperty("Strength", 3d6, "Hero")]
-[h:moveTokenToMap("Hero", "Grasslands")]
-[h:copyToken("Hero", 1, "Grasslands")]
-</source>
-Fancy method that leave the original token unchanged
-<source lang="mtmacro" line>
-[h:moveTokenFromMap("Hero", "Grasslands")]
-<!-- swap from name to token id as tokens with the same name will soon exist -->
-[h:origId = findToken("Hero")]
-<!-- copy original with same name -->
-[h:origCopyId = copyToken("Hero", 1, "", "{name: 'Hero'}")]
-<!-- update original with new properties -->
-[h:setProperty("Strength", 3d6, origId)]
-<!-- copy and then delete original -->
-[h:copyToken(origId, 1)]
-[h:removeToken(origId)]
-<!-- move the copy from BEFORE the changes back to the original map -->
-[h:moveTokenToMap(origCopyId, "Grasslands")]</source>
 ==also==
@@ Line 192: / Line 137: @@
 {{change|1.3b77|Added {{code|tokenImage}}, {{code|portraitImage}}, {{code|handoutImage}}, and {{code|delta}} to {{code|updates}}.}}
 }}
+{{change|1.5.7|Token copies can now be modified within same macro.}}
 [[Category:Token Function]]