Latest revision as of 09:59, 18 February 2022

Page Updated:   2022-02-18

Main Page: API:Script Index

[edit] Duplicate a Character and Token - Add identifying numbers to the copies

The Duplicate a Character and Token(a.k.a DupCharToken)-script will duplicate a character sheet and tokens giving the new characters and tokens an identifying number and linking each new token to it's own individual new character sheet.
This script is useful for those who want to create multiple copies of monsters because they prefer multiple character sheets instead of linking tokens as Mooks.
Using an argument of "clean" causes it to clean up (delete) numbered tokens and characters such as this script creates.

[edit] Syntax

!DupCharToken (Number of tokens to create) (Starting number)
(Number to create) is the number of characters and tokens to copy/create. It defaults to 1. (Starting number) is the number to start numbering the tokens and characters from. Defaults to 1.
!DupCharToken clean
Clean up numbered characters and tokens such as this script creates.

[edit] Installation and Configuration

Use the Roll20 script library one-click install to Add the Script to your active API's. or Copy the script's code, available from the menu on the right and stored at Roll20's API GitHub Repository. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign.

The following text makes a good macro for using this script.

!dupCharToken ?{How many Duplicates|1} ?{Starting Number|1}

[edit] Known bugs/issues

1. If the avatar image of the character is not in a user library (i.e: it's a marketplace image or from the Monster Manual, or the like), due to limits placed upon the API, it can't set an avatar image. You will have to do that yourself, or (better yet) copy the image to your own library on roll20, and set the token to be copied to use the image in your library. Two ways to copy the image to your own library on roll20 are as follows: A) download an image and then upload it manually, either by downloading the set, or placing a copy on the VTT, pressing "z" and right clicking the preview. Or B) Right click the image in your marketplace collection (in the art library) and choosing "Copy to Library" or "Copy to Folder"B is probably faster, unless you are working with a whole set. After downloading the artwork to your own roll20 library, set the character and token to be copied to use that image.
2. It takes a while to make copies, and if it takes too long, the API processor might think that the script is in an Infinite Loop and cancel with an error message on the API scripts page. If nothing happens for a long period of time (more than 30 seconds) after a command to the script go to API scripts page of the campaign, and if there is an error message there, restart the API sandbox. You can then attempt the process again by breaking it down into smaller batches. If the campaign is small and the characters do not have excessive amounts of attributes and abilities, this script should be able to make over 40 copies in one go. But I am told that for larger campaigns with lots of characters, and if those characters have lots of attributes and abilities, this number can be lower. I think the number might also be higher or lower due to how busy (slow) the server is, so the process might work on some days but not on others. Anyway, if you need (for example) 20 Orcs, and you find the sandbox erroring out, try making two batches of 10, or 4 batches of 5.
3. Version 01.00 had unknown problems with the Roll20 script library, where the script could not be added or imported from the script library, and the only way to get it to work was to paste the code in from GitHub. You should now be able to use the script library one-click install, which will insure you always have the most up-to-date code.

[edit] Script Use

!DupCharToken 5
If you select a token named "Skel" that is linked to a character named "Skeleton" this will make 5 new characters, identical to the original, named "Skeleton 1" through "Skeleton 5", and make 5 new tokens, identical to the original and stacked in the exact same location, named "Skel 1" through "Skel 5". Each token will be linked to its corresponding character sheet in the exact same manor as the originals were linked.
!DupCharToken 5 3
As above, but would start numbering at 3 ending at number 7.
!DupCharToken clean
If you select any token named "Skel" or "Skel (number)" this will delete all tokens where the name is "Skel (any number)" and all characters named "Skeleton (any number)". The original token and character (without a number) will not be deleted.

[edit] Changelog

v 1.031 (2020-05-25)

• Bugfix with copying bio and gmnotes. Link

v 1.01 (2019-11-25)

• Fix issue with one-click install, run slightly faster.

v01.00 (2018-12-06)

• Release

[edit] See Also

• API:Script Index Curated list of Roll20 APIs
  • Token/API