Token

Languages:  English  • 日本語

This article is about the token file format used in MapTool. For more general information about tokens, read the Introduction to Tokens.

Token: token

Every object that can be dropped down on a map and manipulated by the GM or the players is a token of some type. The possible token types are Image Token, Library Token, PC Token, and NPC Token. In addition, when images are dropped onto a map layer other than the Token layer, they take on the name object or stamp instead. (The term stamp is often used to denote an image that is placed repeatedly, sometimes in a pattern, whereas object means a less often used image. A forest would be full of tree stamps but an office building would have table and chair objects.)

This page discusses how tokens and objects are saved externally; the overall file format as well as some specifics about how to manipulate the contents of the .rptok file.

Overall File Format

Tokens can be saved by the token owner by right-clicking on the token and choosing Save As..., then navigating to a directory and entering a filename. The filename will automatically have .rptok appended to the end to indicate that the file contains token contents. The actual format of the file, however, is an ordinary ZIP file! This means you can rename the file to end with .zip and treat it as any other ZIP file. There are a number of features related to this:

• All tokens are automatically stored in a compressed format.
• All tokens can contain multiple data files inside
  • One file is called content.xml
  • Another file is called properties.xml
  • A directory is also included called assets
    • The token image is stored here,
    • The token portrait is stored here, and
    • The token handout is stored here.
  • The last file is called thumbnail

Examining the Contents of a Token File

Because the token files are ZIP files, you can easily extract the images or other data from the token. To do so, unpack the ZIP file into a directory on your computer. Look inside the assets directory and you'll see multiple filenames. They will appear to be random strings of letters and numbers, but actually the are checksums of the image they contain. You can think of a checksum as a summary of the content. These files don't have filename extensions so you may not be able to view the content unless you use a program that ignores the filename extension and looks at the content instead. One example utility that does that is the GNU Image Manipulation Program, or GIMP for short.

Note that some versions of MapTool (which ones?) store the asset as the image data encoded in XML. This makes the image unviewable using _any_ standard graphics tool. Trevor has said that this is a bug and future versions will use the actual graphics image format (JPG or PNG).

Modifying the Images or Other Data Inside a Token File

Modifying the images used in the token is more complex, however. Here are the required pieces of the puzzle:

1. Locate the new image(s) to be stored in the token,
2. Calculate the checksum of the image (it's an MD5 checksum),
3. Rename the image file to be the checksum, removing any filename extension in the process,
4. Move the new file into the assets directory,
5. Record the name of the old image from the assets directory, and
6. Remove the old image from the assets directory.

Sounds easy, right? But that's only half of it. It turns out that just dumping images into the assets directory wouldn't tell MapTool enough about the image, such as what size to scale it to and whether it represented the portrait or handout image. Those details are stored in the content.xml file. This file is NOT in the assets directory, but is at the top level of the unpacked ZIP file.

If you open the content.xml file use a text editor. Do not use a word processor or saving the file could corrupt the contents with extra information created by the word processor. Use a program such as Notepad or TextPad to perform any editing. Obviously, an editor that understands the XML syntax can make editing much easier.

You need to locate the portion of the XML file that refers to the portrait image (if you were planning to replace the portrait) and replace the 16-character checksum from the old asset with the 16-character checksum of the new asset. Fortunately, you recorded that information as you performed the steps given above! But fear not -- if you did not record the old checksum value, you can simply delete the entire top-level directory and unpack the ZIP archive again, starting from the beginning.

The simplest way to make the change is to perform a string search for the old checksum, replacing it with the new one whenever you find it.

After you've made all of your replacements, use a ZIP utility to create a ZIP file containing the contents of the top-level directory and everything below it in the directory structure (which currently means the assets directory). Be sure that the directory structure is preserved because the assets directory must be there. Now the file can be dragged and dropped into MapTool! You can change the filename extension to .rptok if you like, but MapTool isn't particular about the name of the file, only about the contents.

See Also

• Token Types
• Library Token
• Image Token
• TokenTool QuickStart Guide
• Introduction to Tokens