View source for Token

{{Languages|Token}}
=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 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 one is '''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:

# Locate the new image(s) to be stored in the token,
# Calculate the checksum of the image (it's an MD5 checksum),
# Rename the image file to be the checksum, removing any filename extension in the process,
# Move the new file into the '''assets''' directory,
# Record the name of the old image from the '''assets''' directory, and
# 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.
[[Category:Token]]
[[Token Types]]
[[Library_Token|Library Token]]
[[Image_Token|Image Token]]
[[TokenTool QuickStart|TokenTool QuickStart Guide]]
[[Introduction_to_Tokens|Introduction to Tokens]]