The process for generating a token with multiple images is somewhat complex, especially if you want a way to access and use those images (like changing your token image on the map). This could be useful for simple cases like having a unique token for each weapon your character wields. It's incredibly useful if you have a shapeshifter or other type of token that needs to be radically different depending on some circumstance.
I developed this by "standing on the backs of giants" which is to say, I did lots of looking around on the internet, in forums, and in the RPTools documentation. Here are some of the sources of information I gathered from:
- Adding extra image files to tokens - RPTools Wiki
- Add multiple images (More then 3) to a token. - RPTools.net
- Adding more image assets to Token object - RPTools.net
Some of these sources have slightly inaccurate information (maybe outdated??) so don't be surprised if what you see here doesn't exactly match what is in the above links. For example, the spreadsheet linked from the RPTools wiki just creates random GUIDs and that doesn't work. It must be the MD5 checksum of the file.
To run this on your machine you'll need to have the following installed:
- a copy of
perl(Strawberry Perl for Windows works) - a copy of
md5sum(my script expects output like that from the GNUWin32 version of md5sum which is 1 line per file with the checksum a space an asterisk and then the filename) - a zip file manipulation tool (e.g. 7-Zip, unzip, etc.)
- the ability to run commands in a terminal / command prompt window
This process should work on any platform (Windows, Linux, Mac, etc.) that has those tools available. I developed and tested this on Windows so your mileage may vary. If you experience problems, please let me know.
At it's core, the process isn't all that complicated, it's just tedious. That's exactly the sort of thing that computers are supposed to be good at, so "why not make the computer do it?" That's my thought process anyway.
Basically we want to add a collection of PNG files (you could use other types, but this tool only supports PNG because of transparency and that's super useful for tokens) to an existing token. You can change that by adjusting the $extension variable near the top of the file. I use an existing token because it's easier (and safer) than creating the entire token file from scratch.
Token files (extension .rptok) are just zip files that are renamed. That makes them easy to work with directly.
- Open Maptool and create a token using the base image you want for your token.
- Right click the token and select
impersonatefrom the menu. - In the chat window (select Windows | Chat if it's not visible) execute the following
[setProperty("AttachedImageMap", json.set("{}", "##imageName", "##imageID"))]. This will create an extra property attached to the token even though it generates no output. - Right click on the token and
Savethe token to a file. - Open the token file (.rptok) with a zip tool. I use 7-Zip but anything that will open a zip file will work. Note that you might have to rename it from x.rptok to x.zip for your zip program to accept it.
- Extract the
assetsfolder and thecontent.xmlfile. You can extract the rest if you want, but we wont be modifying anything else so there's really no need to extract them. - Rename the original PNG file (it will be named a long string of numbers and letters) in the assets directory to whatever you want the default view to be named such as "Default.png" or "Generic.png", etc.
- Copy all the additional images (.png files) you want to use into the assets folder. Note that files named 'portrait' and 'handout' will be handled specially if they exist (see below).
- IMPORTANT NOTE make sure you name the image files whatever you want the button label to be for the macro that changes to that image (including upper or lower case). I typically label them after the weapon or position of the character. So, you might have "Crossbow.png", "Short Sword.png" or "Prone.png", etc.
- Open a command prompt / terminal window and navigate into the assets folder you extracted. Run the attached perl script IN THE ASSETS FOLDER to rename the files and make the neccessary edits in content.xml (which is expected to be in the folder above 'assets').
- Using your Zip tool, copy the assets folder and the (now updated) content.xml file back into the .rptok file. Do NOT copy the backup file, content-xml.bak
- Save the .rptok file
- Now drag the updated .rptok file onto a map in MapTool.
- In MapTool open Window | Selected to show the Selected token pane.
- Now click on the new token. A macro button for each of the tokens images should appear in the "Selected" pane (again, Windows | Selected to turn this on if it isn't already). Clicking on one of the named macro buttons should change the appearance of the token. You can also activate the macros by right-clicking on the token and looking under "Macros" in the token's pop-up menu.
I've recently enhanced the tool to recognize the special file names 'portrait.png' and 'handout.png'. If image files with these names exist they will be removed from the list of macros created and added to the token as the portrait and handout images respectively. You can include one, both, or neither and the tool will do the right thing.
The tool now supports appending macros to tokens with existing macros. It also supports replacing existing portrait and handout images.
Hopefully this helps make the process of creating multi-image tokens easier.
P.S. You can easily create multiple consistent top-down tokens for free using Hero Forge. Create your character with whatever clothes, weapons, pose, etc. Then, under "Stage" select the "Base" then pick the "Slot Base" (scroll to the bottom of the bases). Then rotate the image so it's a top-down view. Do a screen capture of the character (I use GreenShot). If you still have some of the slot base showing, it's easy to remove (along with the background) using online tools like this one Remove Background from Image for Free – remove.bg. Save a few of these with different weapons and/or poses and you'll have a great collection of images to use with the above tool to create a multi-view character token.