Adding extra image files to tokens

 This article is a stub, you can help the RPTools Wiki project by contributing content to expand this article.

This technique lets you add an arbitrary amount of image assets to a token by adding them directly to the token file outside of MapTool.

You can definitely do this any number of ways by examining the unzipped contents of an rptok file. Generally, you need to do four things to make this work:

• Token images named with a UUID and an extension in the rptok's /asset/ directory
• Matching text files named for the matching UUID (no extension) containing matching Asset XML
• XML Entries in /content.xml inside the imageAssetMap tag
• A property in /content.xml to expose your asset IDs in MapTool

Step by step instructions

Quick disclaimer: This guide was written at MapTool version 1.8.5 - This trick to add addition token images has been used by multiple people over the years, but isn't a feature of MapTool. These additional assets are not, to my knowledge, protected in any way by the MapTool token file definition and any future updates to MapTool. Basically, any update to how MapTool tokens handle additional images inserted in this way might break this hack.

1. Save space on your images by resizing to reasonable dimensions and using a tool like https://tinypng.com to compress them. Check for quality after compression.
2. Copy the following spreadsheet, remove the names/filetypes, and populate with a list of your additional images on each row. This spreadsheet generates XML and JSON for you, and a uuid() cell function which generates UUIDs that will work. Remember to COMPLETELY clear the Image Name field before entering your images to force the UUID to regenerate: Google Drive App Token Image Asset Generator
3. Add a property to your token to expose the images with a dummy JSON object. Include some unique dummy values so it is easy to find and edit within your token's XML data later. This code will work while impersonating your token:
   
   [setProperty("AttachedImageMap", json.set("{}", "##imageName", "##imageID"))]
   
   
4. Save your token to your harddrive. Make a second backup copy elsewhere, just in case.
5. Unzip your token to a folder. This will be where you add your images, asset files, and edit the content.xml.
6. Place your image(s) in the /assets/ directory of the token, naming them according to their UUID, e.g. "48a2a53444244b4681fd23d51aeb5d76.png".
7. Create a text titled for each UUID (no extension) in the /assets/ directory. Each file should contain their associated 'Asset XML' content.
8. Edit /content.xml in a text editor.
9. Add the 'XML' Entries in the imageAssetMap. You'll see at least one entry already for the token image, you can add it under that.
   
   IMPORTANT: Copy-pasting multi-line fields from Google Sheets can add double quotes around the pasted content. Remove those!!
   
   
10. Search for your dummy JSON property value. Paste in the 'JSON' value to replace it. Your pasted content will not have HTML entity double quotes, but they will work fine in MapTool - no need to 'escape' the quotes.
11. Open your .rptok file as an archive, and replace the contents with the contents of your unzipped folder.
    
    IMPORTANT: DO NOT Zip up your files up and rename the result with an .rptok extension - I have found it isn't reliable. Adding/Replacing files in an exported .rptok directly without unzipping works better.
    
    
12. Test your token. Drag it onto a new map, and run this macro while impersonating the token:
    
    [r, foreach(vImg, getProperty("AttachedImageMap"), ""): "<img src='asset://" + json.get(getProperty("AttachedImageMap"), vImg) + "' width=50>"]
    
    
13. Test your token again. Save the token to a new location, open a new campaign, drag the token to the map, and use the test script again. Sometimes new UUIDs are generated inside the Asset text files, which then needs to be updated throughout the token (it is very annoying). I think this technique avoids that problem, but resaving your token and testing is the best way to be sure.

You're done! Now you can access the UUIDs by grabbing their asset IDs by reference from your JSON token property.