TexturePacker's custom exporter format

"Custom Exporters have saved me dozens of hours. I can't function without TexturePacker."
Richard Jarell

TexturePacker comes with a lot of different data output formats - both generic like JSON and XML but also platform specific like Cocos2D, Sparrow and others.

Sometimes this is not enough - because a game framework needs its own format - or because it simply does not fit your needs.

The simple solution for you is to create your own custom format. It's easier than you may think, just read the instructions below.

You can

  • alter an existing exporter shipped with TexturePacker:
    in Windows look under C:/Program Files/CodeAndWeb/TexturePacker/bin/exporters,
    Mac users go to Applications/TexturePacker.app/Contents/Resources/exporters.
    The plain exporter may be a good starting point.

    Make sure to duplicate the exporter folder to somewhere outside TexturePacker's installation path and rename the folder and the exporter contents as shown below!
  • or create a new one from scratch with the following manual.

Preparations before creating your own exporter

First of all, create a directory - it's the Exporter Directory that will contain all your custom exporters - e.g. my-TP-Exporters.

Now create a new subdirectory inside that directory - name it like the exporter you want to create - e.g. testexporter.

Your folder structure should now look like this:

TexturePacker Documentation: Custom exporter - folder structure preparations for export

Set the path to your Exporter Directory my-TP-Exporters in TexturePacker's preferences and then quit TexturePacker.

TexturePacker Documentation: Custom exporter - preferences

Structure of an exporter

An exporter consists of 2 or more files:

  • exporter.xml - the file describing the capabilities of the exporter
  • template.txt - the template for the output file format

Optional:

  • filter.qs - one (or more) file(s) to extend the template file with JavaScript

The exporter description file

Create an exporter.xml inside your testexporter directory.

Your folder structure should now look like this:

TexturePacker Documentation: Custom exporter - folder structure

Here's an example file, containing descriptions for all supported elements:

The template file

The template file contains a prototype of the data file to write with some additional markup to format the text, build loops and decisions.

If you copied the data from the example file above, you should now create a testexporter.txt in the same directory as the exporter.xml.

Your folder structure should now look like this:

TexturePacker Documentation: Custom exporter - folder structure
The file extension of the template file does not matter. However, it might be useful to give it the same extension as the Data file to enable syntax highlighting in your favorite text editor.
TexturePacker uses the Grantlee template engine - which is similar to Django templates. A basic description of the language is available from the Grantlee Documentation.

This example template file will write a data file containing a list of sprites with frame coordinates, a flag for rotation and the source coordinates:

// Created with TexturePacker (http://www.codeandweb.com/texturepacker)
//
// Sprite sheet: {{ texture.fullName }} ({{ texture.size.width }} x {{ texture.size.height }})
//
// {{ smartUpdateKey }}

sprites = [
{% for sprite in allSprites %}
    {{ sprite.trimmedName }} = [
        frame = [
            {{ sprite.frameRect.x }},
            {{ sprite.frameRect.y }},
            {{ sprite.frameRect.width }},
            {{ sprite.frameRect.height }}
        ],
        rotated = {{ sprite.rotated }},
        source = [
            {{ sprite.cornerOffset.x }},
            {{ sprite.cornerOffset.y }},
            {{ sprite.untrimmedSize.width }},
            {{ sprite.untrimmedSize.height }}
        ]
    ] {% if not forloop.last %}, {% endif %}
{% endfor %}
]

Using values

Values are surrounded by {{ and }}, values inside a structure are separated by ..

Filters can be used to format values - e.g. {{x|floatformat:3}} formats the floating point value with 3 digits.

Control structures

if

{% if condition %} ... {% else %} ... {% endif %} - conditional execution of one branch in the file.

for

{% for object in objectList %} ... {% endfor %} - loop over a list of elements.

Values and datatypes

The variables that can be used in the template file are described in detail in the table below:

Element Type Info
smartUpdateKey STRING hash string over all file dates, used to speed up export
settings SETTINGS contains tps file settings
variantIndex INT

0
variantCount-1
[0..variantCount-1]


for hasSeparateAutoSDFiles=first
for hasSeparateAutoSDFile=last
for hasSeparateAutoSDFiles=all
multiPackIndex INT -1 for hasSeparateMultiPackFiles=false
[0..textureCount-1]for multipack textures
variantParams VARIANTPARAMS settings adapted for the current scaling variant
allResults RESULT[]
texture TEXTURE current texture (only available if hasSeparateMultiPackFiles=true)
sprites SPRITE[] sprites (without aliases) of the current texture (or of complete result, if hasSeparateMultiPackFiles=false)
allSprites SPRITE[] sprites (including aliases) of the current texture (or of complete result, if hasSeparateMultiPackFiles=false)
exporterProperties.MYPROP STRING or BOOL Contains the value of the custom exporter property MYPROP. Exporter properties can defined in the exporter description file, using the <property> element.
tp HASH Contains all elements described above. If you want to write your exporter in Javascript you can use this hash to pass all settings to a Javascript function.

The template file is loaded with a set of parameters created during the packing process. The values can be referenced using the template language.

smartUpdateKey

When a Publish is started, TexturePacker checks if the Data file already exists. If the file is found, the contents are read and a text sequence is searched for - $TexturePacker:SmartUpdate:....hashvalue....$. The value is a hash over all file dates, sizes and the parameters used to create the texture. If the value is identical with the current state of the files, no output is created to speed up batch operations.

To add this smart update key, use smartUpdateKey somewhere in the template file. Make sure that the value is somewhere in a comment or some other place where it does not confuse the module reading the data.

sprites and allSprites

sprites contains a list of unique sprites only. That means alias sprites (sprites which contain the same image) are not part of the list. You can reference them by accessing a sprite's .aliasList property.

allSprites contains a list of all sprites.
In most cases it's easier to use this property instead of sprites.

The standard way to iterate over the sprites is using

{% for sprite in allSprites %}
    ...
{% endfor %}

SETTINGS

This data type holds .tps file settings.

Element Type Info
autoSDSettings[0..variantCount-1] AUTOSDSETTINGS[] Scaling variant settings
ditherType [none-nn,
none-linear,
fs,
fs-alpha,
atkinson,
atkinson-alpha]
for more info see Dithering
textureFormat STRING texture format
outputFormat STRING output format
contentProtection.key STRING 32 hex digits
tpsName STRING name of the tps file
allowRotation BOOL rotation enabled
flipPVR BOOL flip PVR
forceIdenticalLayout BOOL force layout to be identical for all variants
multiPack BOOL multipacking enabled
trimSpriteNames BOOL trim sprite names
autoAliasEnabled BOOL automatic detection of duplicate sprites enabled
premultiplyAlpha BOOL premultiply alpha enabled
reduceBorderArtifacts BOOL reduce border artifacts enabled
fixedTextureSize SIZE have a fixed texture size
dataFormat STRING data format
textureSubPath STRING texture sub path
borderPadding INT border padding
shapePadding INT shape padding
commonDivisorX INT common divisor X
commonDivisorY INT common divisor Y
backgroundColor INT background color
writePivotPoints BOOL user has enabled pivot points
autodetectAnimations BOOL user has activated animation detection

AUTOSDSETTINGS

This data type holds AutoSD settings.

Element Type Info
scale INT scaling factor
extension STRING variant name
spriteFilter STRING sprite filter
acceptFractionalValues BOOL accept fractional values if no common factor can be found
maxTextureSize SIZE maximum texture size

RESULT

Structure containing a packing result.

Element Type Info
textures TEXTURE[] array of all textures
nonFittingSprites STRING[] array containing names of non-fitting sprites

TEXTURE

This data type holds a texture with all its parameters.

Element Type Info
size SIZE The width/height of the Texture file in pixels.
trimmedName STRING The name of the Texture file - without the extension.
fullName STRING The name of the Texture file with the extension.
absoluteFileName STRING The absolute path to the Texture file.
normalMapFileName STRING The path of the corresponding normal map sheet.
sprites[0..n] SPRITE[] The sprites on the current texture, without aliases.
allSprites[0..m] SPRITE[] All sprites on current texture, including aliases.
area INT Area of the texture in pixels (i.e. width*height).

SPRITE

This data type holds a sprite with all its parameters.

Element Type Info
fileData FILEDATA sprite file data
size SIZE The width/height of the sprite in pixels.
frameRect RECT frame rectangle, pixel coordinates
frameRectWithoutRotation RECT frame rectangle, pixel coordinates without rotation
frameRectRel RECT frame rectangle, relative uv coordinates (0..1)
sourceRect RECT source rectangle
cornerOffset POINT corner offset
untrimmedSize SIZE untrimmed size of sprite
trimmed BOOL true if sprite is trimmed
rotated BOOL true if sprite is rotated
isSolid BOOL true if sprite has no transparent pixels
trimmedName STRING The name of the sprite file - without the extension.
fullName STRING The name of the Texture file with the extension.
aliasList[0..n] SPRITE[] contains the list of identical sprites
centerOffset POINT Center offset
pivotPoint POINT x and y coordinates of the Pivot Point
pivotPointNorm POINT Pivot point coordinates, relative to the sprite size
vertices POINT[] Polygon points approximating the outline of the sprite. Sprite coordinate system.
verticesUV POINT[] Polygon points approximating the outline of the sprite. Texture coordinate system.
triangleIndices INT[] Triangulation of the sprite's polygon. The values in this list are indices in the vertices / verticesUV array.
scale9Enabled BOOL User enabled 9-patch scaling for this sprite
scale9Borders RECT The 9-patch borders.
scale9Paddings RECT The 9-patch paddings.

FILEDATA

This data type holds a file.

Element Type Info
absoluteFileName STRING absolute path of the file
fileSize FLOAT size of the file
created DATE creation date of the file
lastModified DATE last modified date of the file

VARIANTPARAMS

This data type holds the settings adapted for the current scaling variant.

Element Type Info
scale INT Scaling factor
shapePadding INT shape padding in pixels
borderPadding INT border padding in pixels
commonDivisorX INT Common Divisor X
commonDivisorY INT Common Divisor Y
extrude INT Extrude in pixels
baseFactor INT Common base factor of all scaling variants
maxTextureSize SIZE Maximum texture size in pixels
fixedTextureSize SIZE Fixed texture size in pixels

RECT

This data type holds a rectangle.

Element Type Info
x INT x coordinate
y INT y coordinate
width INT width in pixels
height INT height in pixels

POINT

This data type holds a point.

Element Type Info
x INT x coordinate
y INT y coordinate

SIZE

This data type holds a size.

Element Type Info
width INT width in pixels
height INT height in pixels

Enhancing the exporter with JavaScript

In some cases a pure template system is not enough - e.g. if you need to do some calculations. This can be achieved by enhancing the system with some JavaScript.

For this, create 2 directories inside the exporter's folder: grantlee and grantlee/0.2:

TexturePacker Documentation: Custom exporter - folder structure

In the 0.2 folder place your JavaScript file. The extension must be .qs.

Contents of the JavaScript file

Inside the file a filter can be registered. A filter is a function that receives a value, processes it, and returns it to the template which adds the value to the output file.

The following example registers a filter called makecssselector which takes a string, replaces all occurrences of -hover with :hover, and returns the result.

// the filter function
var MakeSelectorFilter = function(input)
{
    var input = input.rawString();
    return input.replace("-hover",":hover");
};

// the filter name
MakeSelectorFilter.filterName = "makecssselector";

// register the filter
Library.addFilter("MakeSelectorFilter");
It is important to convert the function parameter to a regular string if you want to use JavaScript functions like split, replace etc. You can do this by calling .rawString() on the parameter.
The function's result must be a string. If you want to use the function to calculate conditions you can return an empty string "" in case of false and a string with content "true".
Use {% if variable|testfunction %} to test the condition from the template.

Loading and using the filter

Loading a filter is easy. Just add the following line to the template:

{% load makecssselector %}

The value must be the same as the file name.

Using the filter is done by appending the filter's name to a value:

{{sprite.trimmedName|makecssselector}}

Tricks

Since a filter only takes a single parameter, some tricks can be used to perform calculations with multiple parameters:

Use one filter to set a global variable, use another to perform the calculation:

width = 1;

var SetWidth = function (input) {
    width = input; // store the value
    return ""; // return empty string
};
SetWidth.filterName = "setWidth";
Library.addFilter("SetWidth");

var MakeRelX = function (input) {
    return String(input / width); // perform calculation, return result as string
};
MakeRelX.filterName = "makeRelX";
Library.addFilter("MakeRelX");

This is how you can use it:

{{texture.size.width|setWidth}} -- set the width
{{sprite.frameRect.x|makeRelX}} -- calculate x/width