copyToken: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
mNo edit summary
No edit summary
 
(24 intermediate revisions by 7 users not shown)
Line 3: Line 3:
|trusted=true
|trusted=true
|version=1.3b51
|version=1.3b51
|description=Creates one or more copies of a [[Token]]. 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 v1.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.
As of b54 there is a new parameter that allows you to make some changes to the new tokens.
 
'''Note:''' You can make changes to the created tokens if they are done by a second macro that is executed after the macro that creates the copies. Look for [[execLink]] for calling a macro ''deferred''.
 


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
copyToken(id)
copyToken(tokenRef)
copyToken(id, numCopies)
copyToken(tokenRef, numCopies)
copyToken(id, numCopies, fromMap)
copyToken(tokenRef, numCopies, fromMap)
copyToken(id, numCopies, fromMap, updates)
copyToken(tokenRef, numCopies, fromMap, updates)
</source>
newId = copyToken(tokenRef, numCopies, fromMap, updates)
 
</syntaxhighlight>


'''Parameters'''
===Parameters===
{{param|id|The id of the token to copy.}}
{{param|tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to copy.}}
{{param|numCopies|The number of copies to create, defaults to {{code|1}} }}
{{param|numCopies|The number of copies to create, defaults to {{code|1}} }}
{{param|fromMap|The name of the map to copy from, defaults to the current map.}}
{{param|fromMap|The name of the map to copy from, defaults to the current map.}}
{{param|updates| a [[JSON Object]] that contains updates to be made to the copied [[Token]]s.}}
{{param|updates| a [[JSON Object]] that contains updates to be made to the copied [[Token]]s.}}
{{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.}}


You can use an empty string ("") for {{code|fromMap}} for the current map as of b54.
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
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 32: Line 27:
containing the [[Token]] ids of all the newly created [[Token]]s is returned.
containing the [[Token]] ids of all the newly created [[Token]]s is returned.


 
===Updates parameter===
'''Updates parameter'''


{{code|updates}} is a [[JSON Object]] that can contain one or more of the following fields.  Field names are case-sensitive.
{{code|updates}} is a [[JSON Object]] that can contain one or more of the following fields.  Field names are case-sensitive.
Line 39: Line 33:
* {{code|label}} - The label for the new [[Token]].
* {{code|label}} - The label for the new [[Token]].
* {{code|gmName}} - The GM name for the new [[Token]].
* {{code|gmName}} - The GM name for the new [[Token]].
* {{code|layer}} - The layer for the new [[Token]].
* {{code|layer}} - The layer for the new [[Token]]. By default, changing the layer of a new token will also change its shape. Tokens changed to the {{code|Object}} or {{code|Background}} layer will become top-down tokens. For tokens moved to the {{code|Token}} or {{code|Hidden}} layer, MapTool will attempt to determine their shape based on their image.
* {{code|forceShape}} - when the layer field is set, setting this to {{false}} will disable the automatic change of shape.
* {{code|x}} - The X Co-ordinate for the new [[Token]].  Default is {{code|0}}.
* {{code|x}} - The X Co-ordinate for the new [[Token]].  Default is {{code|0}}.
* {{code|y}} - The Y Co-ordinate for the new [[Token]].  Default is {{code|0}}.
* {{code|y}} - The Y Co-ordinate for the new [[Token]].  Default is {{code|0}}.
Line 45: Line 40:
* {{code|facing}} - Sets the facing for the [[Token]]. If the [[Token]] is on the background or object layer this sets the rotation.
* {{code|facing}} - Sets the facing for the [[Token]]. If the [[Token]] is on the background or object layer this sets the rotation.
* {{code|size}} - Sets the size of the [[Token]].  The list of sizes is dependent on the type of grid.
* {{code|size}} - Sets the size of the [[Token]].  The list of sizes is dependent on the type of grid.
* {{code|delta}} - {{code|1}} (true) or {{code|0}} (false).  Indicates whether the x,y coordinates are relative to the position of the original token.  '''Added in 1.3b77.'''
* {{code|delta}} - Use {{code|relativeto}} instead of {{code|delta}} starting in 1.9.0. {{code|1}} (true) or {{code|0}} (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.0'''
* {{code|tokenImage}} / {{code|portraitImage}} / {{code|handoutImage}} - Changes the coresponding image. Value can be either an assetId or an image token name. '''Added in 1.3b77.'''
* {{code|relativeto}} - A string defining what the {{code|x}} and {{code|y}} parameters should be relative to. Can be {{code|"map"}} for absolute positioning, {{code|"source"}} for the token to be copied, or {{code|"current"}} for the [[Current Token]]. Defaults to {{code|"map"}}. '''To be added in 1.9.0'''
* {{code|tokenImage}} / {{code|tokenPortrait}} / {{code|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 {{code|{} }} or {{code|[]}} goes through the standard macro processing.  The macro commands inside the quotes (demonstrated below) are executed as each new token is created.  The new token is also the context of the macro command, meaning there is an implied {{func|switchToken}} on the new token.  DO NOT count on the execution order of individual commands in separate values of the {{code|updates}} parameter, however. The order is controlled by the order in which the Java code processes the parameters and it is not documented here.  This is as of '''1.3b78'''
The values for all of these fields are evaluated so all text within {{code|{} }} or {{code|[]}} 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 {{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}} are not specified then these locations are the same as the source.




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.
==Examples==
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}}
are not specified then these locations are the same as the source.
 
|example=
Make a single copy of the Hero from the current map.
Make a single copy of the Hero from the current map.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: copyToken("Hero")]
[h: copyToken("Hero")]
</source>
</syntaxhighlight>


Make a single copy of the Hero from another map.
Make a single copy of the Hero from another map.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: copyToken("Hero", 1, "Green Room")]
[h: copyToken("Hero", 1, "Green Room")]
</source>
</syntaxhighlight>


Or if you are playing paranoia and want to create six clones.
Or if you are playing paranoia and want to create six clones.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: copyToken("Hero", 6, "Clone Vat")]
[h: copyToken("Hero", 6, "Clone Vat")]
</source>
</syntaxhighlight>


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.
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.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: cloneNo = 0]
[h: updates = "{
                name: 'Hero Clone - [r: cloneNo = cloneNo + 1]'
              }"
]
[h: cloneNo = 0]
[h: cloneNo = 0]
[h: updates = json.set("{}",
        "name", "Hero Clone - [r: cloneNo = cloneNo + 1]"
)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
</source>
</syntaxhighlight>


This will copy all our clones to the current map but they are all on top of each other, to line them up
This will copy all our clones to the current map but spaced out along the X axis.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: cloneNo = 0]
[h: cloneNo = 0]
[h: x = 0]
[h: x = 0]
[h: updates = "{  
[h: updates = json.set("{}",
                name: 'Hero Clone - [r: cloneNo = cloneNo + 1]',
        "name", "Hero Clone - [r: cloneNo = cloneNo + 1]",
                x: '[r: x = x + 2]',
        "x", "[r: x = x + 2]",
                y: 0
        "y", 0
              }"
)]
]
[h: cloneNo = 0]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
</source>
</syntaxhighlight>


Or combining rotation
Or combining rotation
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: cloneNo = 0]
[h: x = 0]
[h: x = 0]
[h: facing = 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: 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)]
[h: copyToken("Hero", 6, "Clone Vat", updates)]
</source>
</syntaxhighlight>


And now we have tumbling clones:
And now we have tumbling clones:
Line 123: Line 111:
[[Image:PointingClones.jpeg|frame|center|Tumbling Clones using Round Tokens and Facing Arrows]]
[[Image:PointingClones.jpeg|frame|center|Tumbling Clones using Round Tokens and Facing Arrows]]


This example shows using the new {{code|delta}} parameter available in '''1.3b77'''.  Specifying {{code|true}} means all x,y coordinates are treated as offsets from the original token. They are measured in grid cells if {{code|useDistance}} is false (the default) or in pixels if {{code|true}}.
This example shows using the new {{code|relativeto}} parameter available in '''1.9.0'''.  Specifying {{code|"map"}} means all x,y coordinates are treated as absolute coordinates on the map. Specifying {{code|"source"}} places copied tokens relative to the position of the token that is beingc copied. Specifying {{code|"current"}} places copied tokens relative to the [[Current Token]]. {{code|x}} and {{code|y}} are measured in grid cells if {{code|useDistance}} is false (the default) or in pixels if {{code|true}}.
 
<syntaxhighlight lang="mtmacro" line>
[h: x = 0]
[h: updates = "{
    x: '[r: x = x + 2]',
    relativeto: 'source',
}" ]
[h: copyToken(currentToken(), 3, "", updates)]
</syntaxhighlight>
 
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 {{code|"delta": 1,}}.


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: x = 0]
[h: x = 0]
[h: updates = "{  
[h: updates = "{  
     x: '[r: x = x + 2]',
     x: '[r: x = x + 2]',
     delta: 1,
     relativeto: 'current',
}" ]
}" ]
[h: copyToken(currentToken(), 3, "", updates)]
[h: copyToken(currentToken(), 3, "", updates)]
</source>
</syntaxhighlight>


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.)
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=
==also==
{{func|moveTokenToMap}},  
{{func|moveTokenToMap}},  
{{func|moveTokenFrom}}
{{func|moveTokenFrom}}


|changes=
==changes==
{{change|1.3b54|Added optional {{code|updates}} parameter.}}
{{change|1.3b54|Added optional {{code|updates}} parameter.}}
{{change|1.3b77|Added {{code|tokenImage}}, {{code|portraitImage}}, {{code|handoutImage}}, and {{code|delta}} to {{code|updates}}.}}
{{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, and {{code|tokenPortrait}} and {{code|tokenHandout}} can now be used instead of {{code|portraitImage}} and {{code|handoutImage}}.}}
{{change|1.9.0|The positioning system for copied tokens has been altered to be more straightforward. {{code|delta}} is now a deprecated parameter which has been replaced with {{code|relativeto}}}}
[[Category:Token Function]]
[[Category:Token Function]]

Latest revision as of 23:59, 12 May 2024

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 v1.5.7, making changes to the copies required special techniques to ensure the changes were kept. See copyToken legacy page.

Usage

copyToken(tokenRef)
copyToken(tokenRef, numCopies)
copyToken(tokenRef, numCopies, fromMap)
copyToken(tokenRef, numCopies, fromMap, updates)
newId = copyToken(tokenRef, numCopies, fromMap, updates)

Parameters

  • tokenRef - Either the token id or Token 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.
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.


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 the Object or Background layer will become top-down tokens. For tokens moved to the Token or Hidden layer, MapTool will attempt to determine their shape based on their image.
  • forceShape - when the layer field is set, setting this to false(0) will disable the automatic change of shape.
  • 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 - Use relativeto instead of delta starting in 1.9.0. 1 (true) or 0 (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.0
  • relativeto - A string defining what the x and y 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.0
  • tokenImage / 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:

Tumbling Clones using Top-down Tokens

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 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, and delta to updates.
  • 1.5.7 - Token copies can now be modified within same macro, and tokenPortrait and tokenHandout can now be used instead of portraitImage and handoutImage.
  • 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 with relativeto
Retrieved from "https://rptools.hyperbooks.com/index.php?title=copyToken&oldid=34847"