I'm a robot

TexturePacker online documentation

Overview

TexturePacker is a GUI and command line tool to create sprite sheets or sprite atlases. Without specifying any additional options TexturePacker already creates very good results, but you also have many options available to adjust things to your needs.

Supported operating systems:

MacOS
TexturePacker currently runs on MacOS 10.7 (Lion) and above.
Windows
Every release version will be built for Windows XP, Vista, 7 and 8.
Linux (Ubuntu)
We support Linux (Ubuntu) version 13.10 (Saucy Salamander) and above.

Licensing & Installation

Choosing the license

You can test all features of the Pro version for 7 days. This license mode is chosen automatically for new installations.

If your trial period has already expired, please choose Essential or Pro.

You can always access the license screen by choosing Enter license key from the menu.

Please have a look at the TexturePacker licenses comparison page for a detailed overview on all features available in Essential or Pro version.

TexturePacker Pro

This button takes you to the CodeAndWeb online store. You can purchase a license forTexturePacker (or our other products) here.

A standard license contains all updates and upgrades - no matter if they are major or minor versions.

You can choose 1-year, 2-year or lifetime plans.

TexturePacker Essential

TexturePacker has a free mode called TexturePacker Essential. In this mode only basic sprite sheet functions are available.

If you use Pro features in this mode, you will get a warning before publishing and some of your sprites will turn red in the output.

Installation of the command line tool

You can install TexturePacker's command line client if you want. This allows you to perform powerful batch operations and even integrate TexturePacker into your build pipeline.

No harm is done if you skip this step during the initial setup. You can always select Install command line tool from the menu later.

TexturePacker FlashUnpacker

TexturePacker automatically calls the FlashUnpacker Addon when you add flash animations or sprites to TexturePacker. You only need to install it when you want to import flash animations into TexturePacker.

For more information and to download FlashUnpacker see the TexturePacker FlashUnpacker page

Creating your first sprite sheet

TexturePacker Documentation: Open a new project

Creating your first sprite sheet is really simple:

  1. Select the framework for your project.
  2. Drag and drop your sprites to the sprites panel on the left. You can drag single images or whole folders - and even .psd and .swf files.
  3. Set a destination path for your Data and Texture file
  4. Press Publish sprite sheet.

TexturePacker in many cases selects optimum settings depending on your framework. You can, however, change the settings and adjust nearly every aspect of the sheet. The settings and details are described in this documentation.

In case you can't find your favorite framework in the list, contact me or simply create your own custom exporter. With the built-in template system you can create all kinds of text files.

TexturePacker Documentation: A Spritesheet


Sprites Panel


Preview Panel


Settings Panel

User Interface

Tool Bar

Project

New project
New project
Create a new sprite sheet for your framework.
Open project
Open project
Open an existing .tps file.
Open project
Save project
Save the current project to disk. Creates a .tps file.
Open project
Save defaults
Save the current settings as default values. Next time you open TexturePacker, the options will be filled in with your saved values.

Sprites

Add image
Add sprites
Add new sprites to the sheet.
You can also add sprites by dropping them into the preview or the sprite list.
Add image
Remove sprites
Removes selected sprite or folder from your sprite sheet.
Add smart folder
Add smart folder
Add a folder containing sprites.

Publish

Publish sprite sheet
Publish sprite sheet
Publish current sprite sheet. Also available from the menu as Force Publish --force-publish.

Help & Feedback

Show TexturePacker tutorials
Show tutorial
Opens TexturePacker's tutorial page in your webbrowser.
Send Feedback to CodeAndWeb
Send Feedback
You think we can do better? Just let us know!

Sprites Panel

TexturePacker Documentation: Sprites Panel

Just drag and drop your sprites into the Sprites Panel on the left side to load them into TexturePacker.

Supported image formats are: bmp, gif, ico, jpeg, jpg, mng, pbm, pgm, pkm, png, ppm, psd, pvr, pvr.ccz, pvr.gz, pvrtc, svg, svgz, swf, tga, tif, tiff, webp, xbm, xpm.

You can also drag and drop complete folders of sprites onto the panel. TexturePacker imports all images inside that folder and uses sub-folder names as part of the final sprite name.

Any changes to the folder structure are synced in TexturePacker as soon as you re-enter the application.

Yellow folders are smart folders you've added to the project. They can be removed by pressing the Delete key.

Blue folders are folders inside a smart folder. They can only be removed via Finder/Explorer.

Flash animations appear as folders too.

You can delete sprites from the panel only if you added them as individual sprites.

Preview Panel

After you've added sprites to TexturePacker, you can see your sprite sheet inside the Preview Panel with your sprites aligned on the sprite sheet according to the algorithm set under Layout -> Algorithm. Almost all of the various TexturePacker options are updated in real-time so you can immediately see the changes made to your sprite sheet.

TexturePacker Documentation: Preview Panel

Zoom Panel

With the Zoom Panel at the bottom of the Preview Panel you can adjust the scaling factor of your Sprite Sheet Preview:

Use the slider to zoom in or out continuously.

Click - or + to zoom in predefined steps.

1:1 sets zoom factor to 100%.

To view your spritesheet completely inside the TexturePacker window use Fit.

Settings Panel

On the right hand side of TexturePacker you have numerous options to optimize your sprite sheet. If you open TexturePacker for the first time, you will only see the most important options. View all available options by clicking show advanced on the respective Settings Panel.

The settings to optimize your sprite sheet are described in detail in Texture Settings.

Command line

You use TexturePacker on the command line like this:
TexturePacker [options] [<imagefolder>] [<images>] [<tpsfiles>]

You can specify one or more image folders or .tps files or images for processing:

<imagefolder>
Recursively adds all known image files from the folder to the sprite sheet

<tpsfiles>
Builds sprite sheets using parameters from a .tps file, additional options override settings from the .tps

<images>
Adds single images, supported image formats are: bmp, gif, ico, jpeg, jpg, mng, pbm, pgm, pkm, png, ppm, psd, pvr, pvr.ccz, pvr.gz, pvrtc, svg, svgz, swf, tga, tif, tiff, webp, xbm, xpm.

Example1:
TexturePacker --data main.plist --format cocos2d --sheet main.png /path/to/your/assetsfolder

Creates main.plist and main.png from all image files in the assetsfolder directory with default cocos2d settings.

Example2:
TexturePacker /path/to/your/spritesheet.tps --force-publish

Force publishes your saved .tps file

In addition to the commands listed and described in the GUI documentation above you can use the following:

Option Description
--help Display help message
--version Print version information
--license-info Prints information about the currently installed license
--activate-license <key> Activate a license key
--gui Launch TexturePacker with graphical user interface
--force-publish Ignore smart update hash and force re-publishing of the files
--replace <regexp>=<string> Replaces matching parts of the sprites name with <string>; Uses full regular expressions, make sure to escape the expression
--ignore-files <wildcard> Ignores all images fitting the given pattern (may be used several times) You can use * and ?, make sure to escape the wildcards when working with bash. Please specify the complete path like /path/to/your/sprite.png or use a wildcard like *your/sprite.jpg
--background-color <rrggbb> Set solid background color, default is none, which is transparent The value is a tuple of 3 hexadecimal digit pairs, each pair represents a color channel in order red, green, blue, E.g. ff0000 for red, ffffff for white
--verbose More output
--quiet Display errors only

Texture Settings

This chapter describes the options used for packing your sprite sheets. The options are available from command line and from the graphical user interface.

Heads up!
In this documentation command line options are highlighted: this is a command line option

Data

TexturePacker Documentation: Settings Data

Data Format --format <name>

You can set the Data Format or framework when you open a new project. Depending on your choice this enables additional features.

If you want to convert your project to another framework and not start a new project from scratch click the wrench button and select another framework.

Make sure to save your current project before converting it!

Data file --data <filename>

Choose the destination and file name for the Data file. The Data file contains the metadata where the sprites are found inside the texture.

The value entered must be an absolute path. TexturePacker converts it into a relative path to the .tps file when saving - allowing you to move the complete set of data to other locations.

If you are using Multipack or Scaling variants to create different variations of a sprite sheet, make sure that the Data file name contains a placeholder:

Placeholder Description
{v} Scaling variant name
{n} Multipack index, starting with 0
{n1} Multipack index, starting with 1

Trim sprite names --trim-sprite-names

Removes image file extensions from the sprite names - e.g. .png, .tga.

Prepend folder name

Prepends the smart folder's name as part of the sprite name.

Sub-folder names are always included in the sprite name.

Texture path --texturepath <path>

This value can be used to prepend a path before the file name of the texture in the Data file. This can be used to store the sprite sheet image in another location than the Data file.

Example: /assets

Class file --classfile-file <filename>

(only available if Data Format is MonoGame)

Choose the file name for the classfile output file.

Java file --java-file <filename>

(only available if Data Format is AndEngine)

Choose the file name for the Java file. The Java file contains the additional metadata used by AndEngine.

The value entered must be an absolute path. TexturePacker converts it into a relative path to the .tps file when saving - allowing you to move the complete set of data to other locations.

If you are using Multipack or Scaling variants to create different variations of a sprite sheet, make sure that the Data file name contains a placeholder:

Placeholder Description
{v} Scaling variant name
{n} Multipack index, starting with 0
{n1} Multipack index, starting with 1

Java package name --andengine-packagename <name>

(only available if Data Format is AndEngine)

Enter the package name for the additional Java metadata.

Atlas bundle --format spritekit --data <filename.atlasc>

(only available if Data Format is SpriteKit)

Choose the atlasc directory containing all data and image files.

The value entered must be an absolute path. TexturePacker converts it into a relative path to the .tps file when saving - allowing you to move the complete set of data to other locations.

Header file --header-file <filename>

(only available if Data Format is SpriteKit)

Choose the file name for the header file containing definitions for the sprites and animations.
This file is optional. Ignored if filename is empty.

The value entered must be an absolute path. TexturePacker converts it into a relative path to the .tps file when saving - allowing you to move the complete set of data to other locations.

Filtering

(only available if Data Format is LibGDX)
Sets the filtering values in the LibGDX exporter. For more details see LibGDX specification: http://www.badlogicgames.com/wordpress/?p=1403

Min Filter --andengine-minfilter <name>

(only available if Data Format is AndEngine)

Sets the minimizing filtering values in the AndEngine exporter.

GUI value CMD value Description
nearest Nearest
linear Linear
linear_mipmap_linear LinearMipmapLinear Will fetch the two best-fitting images from the mipmap chain and then sample the four nearest texels from each of the two images, combining them to the final output pixel.
linear_mipmap_nearest LinearMipmapNearest Will fetch the best-fitting image from the mipmap chain based on the pixel/texel ratio and then sample the texels with a linear filter. Usually gives the best results.
nearest_mipmap_linear NearestMipmapLinear Will fetch the two best-fitting images from the mipmap chain and then sample the nearest texel from each of the two images, combining them to the final output pixel.
nearest_mipmap_nearest NearestMipmapNearest Will fetch the best-fitting image from the mipmap chain based on the pixel/texel ratio and then sample the texels with a nearest filter.

Mag Filter --andengine-magfilter <name>

(only available if Data Format is AndEngine)

Sets the magnifying filtering values in the AndEngine exporter.

GUI value CMD value Description
nearest MagNearest Magnify using nearest neighbor algorithm
linear MagLinear Magnify using linear algorithm

Wrap t/s --andengine-wrapt <Clamp|Repeat> / --andengine-wraps <Clamp|Repeat>

(only available if Data Format is AndEngine)

Sets the wrap value in the AndEngine Data file.

Texture

Texture format --texture-format <id>

Choose the Texture format your framework supports. Depending on your choice this enables additional features.

Texture file --sheet <filename>

Choose the file name for the Texture file. The Texture file contains the image data of the sprite sheet.

The value entered must be an absolute path. TexturePacker converts it into a relative path to the .tps file when saving - allowing you to move the complete set of data to other locations.

TexturePacker Documentation: Settings Texture

If you are using Multipack or Scaling variants to create different variations of a sprite sheet, make sure that the Texture file name contains a placeholder:

Placeholder Description
{v} Scaling variant name
{n} Multipack index, starting with 0
{n1} Multipack index, starting with 1

DPI --dpi <value>

Sets DPI (dots per inch) for PNG and JPG format. Does not have any effect on most gaming frameworks since they just care about the pixel size. Might affect web-based frameworks.

Png Opt Level --png-opt-level <value>

(only available if Texture format is PNG)

Optimization for PNG files. TexturePacker probes for settings to reduce the .png file size.

If you set Png Opt Level to 1 a 8-bit PNG with 256 colors is generated. (default)

The higher the level, the more combinations are tested.

Warning: Setting high values might take a long time during Publish!

PVR Quality --pvr-quality <value>

(only available if Texture format is PVR or ATF and Pixel Format includes PVR)

Set the quality for PVR compression. Valid values: verylow (- low quality, fast), low, normal, high, best (- best quality, very slow (default)).

JPG Quality --jpg-quality <value>

(only available if Texture format is JPG)

Set the quality for the lossy .jpg compression. Valid range is 0 (low quality) to 100 (best quality).

WebP Quality --webp-quality <value>

(only available if Texture format is WebP)

Set the quality level for WebP format (0 = low, 100 = high, >100 = lossless), default is lossless.

JXR Compression --jxr-compression <value>

(only available if Texture format is ATF)

Set the compression level for JPEG XR encoder (0 = lossless, 1..100 = lossy compression), default is lossless.

JXR Trim Flexbits --jxr-trim-flexbits <value>

(only available if Texture format is ATF)

Number of flexbits to trim, 0 (default) .. 15.

Increases packing ratio by removing detail from the image.

JXR Color Format jxr-color-mode <value>

(only available if Texture format is ATF)

Color sampling mode for JXR codec: YUV444, YUV422, YUV420.

ETC1 Quality --etc1-quality <value>

(only available if Texture format is ATF and Pixel Format includes ETC1)

Set quality for ETC1 compression: low, low-perceptual, high, high-perceptual.

DXT Quality --dxt-mode <value>

(only available if Texture format is ATF and Pixel Format includes DXT)

Set DXT1/5 compression mode: linear, perceptual.

Flip PVR --flip-pvr

(only available if Texture format is PVR)

Flips the PVR file vertically. Required by Unity and some other frameworks

Premultiply alpha --premultiply-alpha

Enables pre-multiplied alpha. With premultiply alpha all color values are multiplied with the alpha value. This is required by some frameworks for faster rendering of the textures.

Pixel format --opt <pixelformat>

Specifies the Pixel format used in the Texture file.

Some formats have native support for the Pixel formats such as .pvr.

Formats like .tga or .png only support 32-bit color values. TexturePacker reduces the colors according to the settings but still writes 32-bit data. This still has some advantages: The memory usage is usually reduced and colors can be dithered. On the target system a simple shift of the color values is sufficient to build the target color values.

Some of the formats like ETC1, PVRTC 2-bit, or PVRTC 4-bit require special decoding in hardware or software and can only be used with specific Data Formats.

Please note that TexturePacker uses PVRTC codec with 2 or 4 bits per pixel, but not yet PVRTC2 codec.
GUI/CMD value Description
RGBA8888 default, 4 bytes per pixel, 8 bits per channel
BGRA8888 4 bytes per pixel, 8 bits per channel
RGBA4444 2 bytes per pixel, 4 bits per channel
RGB888 3 bytes per pixel, 8 bits per channel, no transparency
RGB565 2 bytes per pixel, 5 bits for red and blue, 6 bits for green, no transparency
RGBA5551 2 bytes per pixel, 4 bits per color channel, 1 bit transparency
RGBA5555 3 bytes per pixel, 5 bits per channel, not supported on all platforms
PVRTC2 2 bits per pixel, iPhone only, only PVR files, no real-time preview available
PVRTC4 4 bits per pixel, iPhone only, only PVR files, no real-time preview available
PVRTC2_NOALPHA 2 bits per pixel, iPhone only, only PVR files, no real-time preview available
PVRTC4_NOALPHA 4 bits per pixel, iPhone only, only PVR files, no real-time preview available
ALPHA Black and white image of the alpha channel
ALPHA_INTENSITY 16 bit alpha + intensity, PVR export only
ETC1 ETC1 compression (pkm file only)

Dithering --dither-<mode>

Improves image quality when setting reduced-color formats like RGBA4444. When reducing colors, so-called "banding artifacts" might deliver low image quality. Try experimenting with dithering settings to reduce the artifacts.

RGBA8888 - full color palette RGBA 8888

This is the original image, exported with RGBA 8888 - using the full palette of 16,777,216 colors.

This consumes 4 bytes per pixel.

RGBA4444 using Nearest Neighbor - banding artifacts RGBA 4444, no dithering

Simple color reduction using nearest neighbor. This causes banding artifacts in the gradient.

This consumes 2 bytes per pixel.

RGBA4444 with dithering - good image quality RGBA 4444, with dithering

Color reduction using dithering - reducing the artifacts and delivering a good image quality.

This consumes 2 bytes per pixel.

TexturePacker comes with several dithering algorithms, please choose from the values below.

Methods with "alpha" in the name also dither transparency. This is useful for gradients, whereas the non-alpha version is better for crisp, solid sprites and tilemaps.

GUI value CMD value Description
NearestNeighbour none-nn Has the least color error but color distribution leads to less contrast than Linear.
Linear none-linear Creates a linear color distribution with some color error but better contrast than NearestNeighbour.
FloydSteinberg fs Uses Floyd-Steinberg dithering algorithm.
FloydSteinbergAlpha fs-alpha Uses Floyd-Steinberg dithering algorithm with alpha values.
Atkinson atkinson Uses Atkinson dithering algorithm.
AtkinsonAlpha atkinson-alpha Uses Atkinson dithering algorithm with alpha values.

Content Protection --content-protection <key>

Content Protection is currently available only for Cocos2D framework and file format pvr.ccz
TexturePacker: Content Protection

You can enter your own key in the line edit - or simply create a new one by pressing Create new key.

To disable encryption use Clear / Disable.

Save as Global Key stores the key in TexturePacker as global - using it for decryption in the .pvr viewer and allowing you paste it into other sprite sheets by simply pressing Use global key

For more information on Content Protection and how to use it see TexturePacker ContentProtection page

Layout

TexturePacker Documentation: Settings Layout

Max Size --max-width <int> --max-height <int>

Sets the maximum width/height for the texture, default is 2048.

--max-size <int> sets the value for width and height at once.

Fixed Size --width <int> --height <int>

Sets a fixed value for the size. Leave the fields empty to let TexturePacker determine the size.

Size constraints --size-constraints <value>

Forces the texture to meet size constraints.

GUI/CMD value Description
POT Forces the texture to have power-of-2 size (2, 4, 8, 16, 32, 64, 128, 256...).
AnySize Allows the texture to have any size. TexturePacker tries to find the minimum size. Use Pack to restrict the search for the optimum texture.
NPOT was removed in TexturePacker 3.5.3 because it was a workaround for a bug in iOS before version 5. iOS allocated additional memory if the textures were POT.
Please use AnySize instead.

Force squared --force-squared

Forces the texture to have a squared size.

Force word aligned --force-word-aligned

Word-aligned textures make sure that each row in the texture uses complete memory words.

Use this to optimize textures for formats such as iPhone.

With 32-bit color formats, all textures are word aligned. 16-bit formats might need to extend the texture by 1px in width.

Scaling variants (previously AutoSD)
--variant <scale>:<name>[:<filter>[:allowfraction][:<width>:<height>]]

This feature allows you to create and save multiple variations (or scaling factors) of the sprite sheet during publish without resizing all sprites in your graphics software by hand. Press the cog wheel button to open the Scaling variants dialog box.

To only build one scaling variation select No scaling variants and click Apply.

You can sort your variations with the buttons Up and Down or Delete them.

TexturePacker Documentation: Scaling variants options
Presets

Here you find several already-defined presets for scaling down. After selecting your desired preset click Apply.

This overwrites your current settings!
Variant name {v}

The extension for this variation. It will replace the {v} in the Data and Texture file names.

Scale

The scale factor for this variation. If you want to add a new scaling variant press Add.

Sprite filter

Only sprites which apply to this filter will be packed into this variation. Filtering works on sprite names and folder paths, the filters will be processed longest first. You can also concatenate several search terms with , to have them packed into one spritesheet.

Max. Texture Size

The texture limits for this variation (not required with Force identical layout).

Identical layout - accept fractional values

Check this if you want to accept sub-pixel rendering. This might be needed if no common factor (see bottom left) can be found for all scaling factors. In this case, fractional values will be stored in the sprite sheet and this particular scaling variant will be excluded from calculating the common divisor.

Force identical layout --force-identical-layout

This will keep all scaled variation layouts identical. All sizes and coordinates will be divisible by the same common factor to avoid fractional values. E.g. if you scale down your texture by 0.5 the common factor is 2.0. That means all values will be forced to be divisible by 2.0.

Sprites will then be padded with transparency if necessary.

Using the Scaling variants feature

Assuming that your original sprites are for a Retina display iPad and you want to scale down to iPad and iPhone.
Name the Data file like sheet{v}.plist and the Texture file like sheet{v}.png.

Open the Scaling variants dialog by clicking on the cog wheel button . Press Add to add an empty variant.

Enter the following values: (see also the image above)

Variant name {v} Scale
-ipadhd 1.0
-hd 0.5
empty 0.25

After adding sprites and clicking Publish sprite sheet you should see the following files:

  • sheet-ipadhd.png
  • sheet-hd.png
  • sheet.png
  • sheet-ipadhd.plist
  • sheet-hd.plist
  • sheet.plist
Using the Scaling variants and Multipack feature together

If you have several scaling variants, plus you want to use multipack to create two or more spritesheets you have to include both placeholders into the Data and Texture file names like this:
spritesheet{n1}{v}.plist and spritesheet{n1}{v}.png.

The resulting files after clicking Publish are:

  • spritesheet1 -ipadhd.png
  • spritesheet1 -hd.png
  • spritesheet1.png
  • spritesheet2 -ipadhd.png
  • spritesheet2 -hd.png
  • spritesheet2.png
  • ...
  • spritesheet1 -ipadhd.plist
  • spritesheet1 -hd.plist
  • spritesheet1.plist
  • spritesheet2 -ipadhd.plist
  • spritesheet2 -hd.plist
  • spritesheet2.plist
  • ...
deprecated Scaling variants command line options

--auto-sd and --main-extension <string> as well as
--autosd-variant <scale>:<extension>[:allowfraction][:<width>[:<height>]]
are deprecated and only kept for compatibility with older versions of TexturePacker.

Scale --scale <float>

Sets the basic scaling factor for the texture. Default is 1 to use the original sprite sizes.

You can add and create multiple scale factors of a texture by using Scaling variants settings (see above).

Scale mode --scale-mode <mode>

This field contains different scaling modes for the sprites. The value is used for scaling and for Scaling variants settings.

GUI/CMD value Description
Smooth Scale by blending pixels - best for scaling down. Leaves blurry result when scaling up.
Fast Nearest neighbor scaling - OK for scaling down. Gives pixelated images when scaling up.
Scale2x Fixed size upscaling by factor of 2. Tries to optimize edges of pixel art.
Scale3x Fixed size upscaling by factor of 3. Tries to optimize edges of pixel art.
Scale4x Fixed size upscaling by factor of 4. Tries to optimize edges of pixel art.
Eagle Fixed size upscaling by factor of 2. Tries to optimize edges of pixel art.
Hq2x Fixed size upscaling by factor of 2. Tries to optimize edges of pixel art.

Algorithm --algorithm <name>

There are currently 2 algorithms:

GUI/CMD value Description
MaxRects Currently the best packing algorithm. Tries to use the least texture space by applying different heuristics when placing the sprites.
Basic Simple layout by filling sprites from left to right until the maximum width of the texture is reached. Good for fixed-size sprites.

Order --basic-order <mode>

(only available if Algorithm is Basic)

GUI/CMD value Description
Ascending Sorts values from small to large
Descending Sorts values from large to small

Sort by --basic-sort-by <value>

(only available if Algorithm is Basic)
Orders sprites before placing them into the sprite sheet.

GUI/CMD value Description
Best Tests all sorting variants and uses the result with the least used space
Name Sorts sprites by name
Width Sorts sprites by width
Height Sorts sprite by height
Area Sorts sprites by their area (width*height)
Circumference Sorts sprites by their circumference (width+height)

Heuristics --maxrects-heuristics <mode>

(only available if Algorithm is MaxRects)
Heuristics is used to place the sprites in the texture.

GUI/CMD value Description
Best Tests all available placements and uses the result with the least used space
ShortSideFit Short Side Fit
LongSideFit Long Side Fit
AreaFit Area Fit
BottomLeft Bottom Left
ContactPoint Contact Point

Pack --pack-mode <mode>

Controls how much time TexturePacker uses to find the minimum texture size.

GUI/CMD value Description
Fast Search for the minimum fitting power-of-2 size.
Good Searches for the minimum size but aborts after some time.
Best Searches intensively for the minimum size. Might take some time...

Multipack --multipack

TexturePacker can create multiple Data and Texture files if not all sprites could be packed into a single texture.

At the moment, the heuristics of Multipack may not deliver optimal results for your needs. Please experiment with the Algorithm and Heuristics options above.

If you need TexturePacker to create the same number of output spritesheets with the same naming convention in HD and SD (with SD textures in half the size), you have to check force identical layout in the Scaling variants options.

Use with care with the 32-bit version of TexturePacker - it might crash due to out-of-memory-situations.

Make sure to add one of the following placeholders to the Data and Texture file names to include the spritesheet numbers:

Tag Description Example Output
{n} number, starting with 0 spritesheet{n}.png spritesheet0.png
spritesheet1.png, ...
{n1} number, starting with 1 spritesheet{n1}.png spritesheet1.png
spritesheet2.png, ...
Using the Multipack feature

If you use multipack to create two or more spritesheets, you have to name the Data file like spritesheet{n1}.plist and the Texture file like spritesheet{n1}.png.

The resulting files after clicking Publish are:

  • spritesheet1.png
  • spritesheet2.png
  • ...
  • spritesheet1.plist
  • spritesheet2.plist
  • ...
Using the Multipack and Scaling variants feature together

If you use Multipack to create two or more spritesheets, plus you have several Scaling variants you have to include both placeholders into the Data and Texture file names like this:
spritesheet{n1} {v}.plist and spritesheet{n1} {v}.png .

The resulting files after clicking Publish are:

  • spritesheet1 -ipadhd.png
  • spritesheet1 -hd.png
  • spritesheet1.png
  • spritesheet2 -ipadhd.png
  • spritesheet2 -hd.png
  • spritesheet2.png
  • ...
  • spritesheet1 -ipadhd.plist
  • spritesheet1 -hd.plist
  • spritesheet1.plist
  • spritesheet2 -ipadhd.plist
  • spritesheet2 -hd.plist
  • spritesheet2.plist
  • ...

Allow rotation --enable-rotation / --disable-rotation

Allows the rotating of sprites clockwise or counterclockwise by 90 degrees if they have a better fit in the texture. Might not be supported by all game/web frameworks.

The rotation direction (cw/ccw) can be set in the exporter's XML file.

Detect identical sprites (previously Auto alias) --disable-auto-alias

Identical sprites are only stored once in the Texture file - but multiple times in the Data file.

Can be used to save space in the texture. E.g. if animations contain identical frames.

Sprites which are aliased are marked with the 'stack' icon.

Sprites

TexturePacker Documentation: Settings Sprites

Trim --trim-mode <value>

Removes transparent pixels from a sprite's border.

This shrinks the sprite's size, allows tighter packing of the sheet, and speeds up rendering since transparent pixels don't need to be processed.

Trim/Crop Threshold --trim-threshold <int>

Allowed values: 1 to 255, default is 1.

Pixels with an alpha value below this value will be considered transparent when trimming the sprite.

Very useful for sprites with nearly invisible alpha pixels at the borders.

Trim modes:

GUI value CMD value Description
None None Keep the sprites as they are. Do not remove transparent pixels.
Trim Trim Removes the transparency around a sprite. The sprites appear to have their original size when using them. This option might not be available in all frameworks.
Crop, keep Pos CropKeepPos Removes the transparency around a sprite. The sprites appear to have the smaller size when using them. The position in the original sprite is stored. This option might not be available in all frameworks.
Crop, flush Pos Crop Removes the transparency around a sprite. The sprites appear to have the smaller size when using them. The position in the original sprite set to 0/0. The sprite appears in the sheet as if it never had any transparency.

Pivot Point

Anchor Point. Specifies the position inside the sprite that is used as a center for rotation and placement.

Extrude --extrude <int>

TexturePacker Documentation: Extrude

Extrude repeats the sprite's pixels at the border.
Sprite's size is not changed.

There are two uses for this:

  • Reduce flickering in some cases where sprites have to be put next to each other in the final program.
  • Check if sprite outlines are OK. E.g. if you want to use sprites to create tilemaps this allows you to see if there are semi-transparent pixels at the borders of the tiles.

Border padding --border-padding <int>

TexturePacker Documentation: Padding

Border padding is the space between the sprites and the border of the sprite sheet. Value adds transparent pixels around the borders of the sprite sheet. Default is 2.

Shape padding --shape-padding <int>

Shape padding is the space between sprites. Value adds transparent pixels between sprites to avoid artifacts from neighbor sprites. The transparent pixels are not added to the sprites. Default is 2.

Use a value of at least 2 to avoid dragging in pixels from neighbor sprites when using OpenGL rendering.

Commandline only: --padding <int>
Combination of --shape-padding and --border-padding, value in pixels, default is 2

Inner padding --inner-padding <int>

Adds transparent pixels to the inside of the sprite, growing it.

There are two uses for this:

  • It can help in preventing cut-off artifacts near the edges of scaled sprites. E.g. if your sprite has a few pixels along its own boundaries, scaling the sprite up or down won't let these pixels appear as gaps or cuts.
  • It considerably reduces aliasing along the polygon edges when rotating trimmed or cropped sprites. E.g. if your sprite has many pixels along its own boundaries, it will be drawn more smoothly when rotating it.

Common divisor --common-divisor-x <int> / --common-divisor-y <int>

Extends sprite's sizes to be divisible by this value. The sprite is extended with transparency.

Default is 1 which means the sprite's size is not changed. Max is 2048.

This can be used to:

  • Force identical sizes for sprites
  • Force identical layout across multiple scaling factors

The feature also influences Trim and Crop to match the given factors.

Heuristic mask --heuristic-mask

Samples the corner pixels of a sprite and removes identical background color. Can be used to cut sprites from a monochrome background.

Reduce border artifacts --reduce-border-artifacts

Adds color to transparent pixels by repeating a sprite's outer color values.

These color values can reduce artifacts around sprites and removes dark halos at transparent borders. This feature is also known as "Alpha bleeding".

This only works when Premultiply alpha is turned off.

Clean transparent pixels --disable-clean-transparency

Sets transparent pixels to color #000 to improve image packing ratio and identical sprite detection (AutoAlias)

Shape outlines --shape-debug

Draws a colored box around a sprite. Can be used for debugging or aligning sprites.

The outlines will also be contained in the resulting sprite sheet files. This is useful for debugging sprite behavior.

Normal maps

Some frameworks (e.g. Unity) require the normal maps to be packed with the same layout as the sprite sheet.

This new packing mode is introduced in TexturePacker 3.7.0:

TexturePacker Documentation: Packing normal map sprite sheets

Trim, crop, extrude and padding effect now effect both textures.

The sprites and normal maps are connected through their names.

TexturePacker Documentation: Settings Normal maps

Pack with same layout

TexturePacker creates a separate sprite sheet for the normal maps. Normal maps are packed in the same location as the sprites in the main texture.

Auto-detect

This option automatically detects normal mapped sprites based on the color values.

This heuristic should work in most cases and is used by default. Disable Auto-detect in cases where the heuristic fails and use Path filter and / or Normal map suffix instead.

Path filter

Each image's file path which contains the filter string is considered a normal map. Use this if you collect all your normal maps in a single folder — e.g. /normals/

Normal map suffix

Sprites containing this suffix are treated as normal maps. Use this if your normal maps all have a common suffix - e.g. _n

Sprite sheet file

The name of the sprite sheet file containing the normal maps. In case you are using scaling variants or multipack make sure to add the place holders {n} and {v}

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.

Basic 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

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

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

TexturePacker Documentation: Custom exporter - preferences

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:

<exporter version="1.0"> <!-- file format version, must be 1.0 -->

    <!-- identifier of the exporter -->
    <!-- change this if you duplicated an existing exporter -->
    <name>testexporter</name>
    
    <!-- old exporter identifiers (optional); if a tps file with such an id is opened,
         its id is automatically changed to the one specified in <name> -->
    <nameAlias>otherexporter</nameAlias>
    <nameAlias></nameAlias>
    
    <!-- name of the exporter that is shown in the framework selector dialog -->
    <!-- change this if you duplicated an existing exporter -->
    <displayName>TestExporter</displayName>
    
    <!-- description of the exporter -->
    <description>My first custom exporter for TexturePacker</description>

    <!-- exporter version; unused at the moment -->
    <version>1.0</version>
    
    <files>

        <!-- list of data files which should be generated -->        
        <file>

            <!-- name of this file type; used in the tps file 
                 and by the commandline client: for each MYDATA file 
                 a commandline option --MYDATA-file is evaluated -->
            <name>datafile</name>

            <!-- human readable name (used in the TexturePacker GUI) -->
            <displayName>MyDataFile</displayName>

            <!-- file extension, without '.' -->
            <fileExtension>txt</fileExtension>

            <!-- description what the file contains, 
                 used for tooltips in the GUI (optional) -->
            <description>My txt custom exporter for TexturePacker</description>

            <!-- name of the template file -->
            <template>testexporter.txt</template>

            <!-- this file is optional, i.e. if the user does not specify an
                 output file name, the file will not be generated; 
                 (optional, default is 'false') -->
            <optional>false</optional>
            
            <!-- specifies for which scaling variant this data file is generated:
                 all:   for all variants  (default)
                 first: only for the first variant
                 last:  only for the last one   -->
            <hasSeparateAutoSDFiles>all</hasSeparateAutoSDFiles>

            <!-- do not write a file for each multipack variation 
                 (optional, default is 'true') -->
            <hasSeparateMultiPackFiles>true</hasSeparateMultiPackFiles>

        </file>
       
        <!-- add more <file> ... </file> tags if you need more than one output file -->
    </files>

    <!-- target framework supports trimming -->
    <supportsTrimming>true</supportsTrimming>

    <!-- target framework supports rotated sprites -->
    <supportsRotation>true</supportsRotation>

    <!-- rotated sprites direction (cw/ccw), only required for supportsRotation=true -->
    <rotationDirection>cw</rotationDirection>

    <!-- supports texture sizes which are not powers of two -->
    <supportsNPOT>true</supportsNPOT>

    <!-- target framework supports pivot point settings 
         (optional, default=false) -->
    <supportsPivotPoint>false</supportsPivotPoint>
    
    <!-- ensure that width/height of generated texture is multiple of this factor 
         (optional, default=1) -->
    <textureSizeFactor>1</textureSizeFactor>

</exporter>

The tags that can be used in the exporter file are described in detail in the table below:

Element Data type Info
<name> STRING Identifier for the exporter - should be unique. This value is stored when the exporter is referenced from a save file (.tps). It is also used to select the exporter from command line.
<nameAlias> STRING other old exporter identifiers which should now open with this exporter.
<displayName> STRING This value is used in the GUI's framework selector dialog to select the exporter.
<description> STRING A description of the exporter.
<version> STRING Version of the exporter.
<files> ARRAY of multiple <file> elements. For each entry a separate file is created during the publish process.
<file> ARRAY This element collects parameters for a single file.
<name> STRING Identifier for this type of file. Used in the tps file and by the commandline client
<displayName> STRING Display name of this file type. E.g. to present a selection box from the graphical user interface.
<fileExtension> STRING Extension of the Data file without '.' - e.g. txt.
<description> STRING what does the file contain, used for tooltips in the GUI (optional).
<template> STRING Name of the template file to create the data.
<optional> BOOL if not specified, the file will not be generated, default is 'false'.
<hasSeparateAutoSDFiles> ENUM

all
first
last
for which scaling variant is this data file generated:
for all variants (default)
only for the first variant
only for the last variant
<hasSeparateMultiPackFiles> BOOL write a file for each multipack variation, default is 'true'.
<supportsTrimming> BOOL Set this to true if the target framework supports trimmed sprites (sprites with transparency removed). TexturePacker delivers the offsets and size of the trimmed sprite to the template system. The user can still choose to disable trimming from the user interface. If supportsTrimming is set to false the option to enable trimming is not available in the user interface.
<supportsRotation> BOOL Set this to true if the target framework supports rotated sprites. The user can still decide not to enable rotated sprites from the user interface. If supportsRotation is set to false the option to enable sprite rotation is not available in the user interface.
<rotationDirection> ENUM

cw
ccw
The direction in which a sprite is rotated - if TexturePacker decides to rotate a sprites.
for clockwise
for counterclockwise rotation.
The amount of rotation is always 90°.
<supportsNPOT> BOOL If enabled TexturePacker allows the user to choose non-power-of-2 sizes for sprite sheets. Otherwise only power-of-2 (POT) sizes are enabled in the user interface.
<supportsPivotPoint> BOOL target framework supports pivot point settings (optional, default=false).
<textureSizeFactor> INT ensure that width/height of generated texture is multiple of this factor (optional, default=1).

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.

Top level variables

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

Element Data 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.textures ARRAY of TEXTURE array of all textures
allResults.nonFittingSprites ARRAY of STRING array of non-fitting sprites
texture TEXTURE current texture (only available if hasSeparateMultiPackFiles=true)
sprites ARRAY of SPRITE sprites (without aliases) of the current texture (or of complete result, if hasSeparateMultiPackFiles=false)
allSprites ARRAY of SPRITE sprites (including aliases) of the current texture (or of complete result, if hasSeparateMultiPackFiles=false)

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 have an identical sprite) 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 %}

Data types

SETTINGS

This data type holds .tps file settings.

Element Data type Info
autoSDSettings[0..variantCount-1] ARRAY of 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 enable rotation
flipPVR BOOL flip PVR
forceIdenticalLayout BOOL force layout to be identical for all variants
multiPack BOOL enable multipacking
shapeDebug BOOL outline shapes for debug
trimSpriteNames BOOL trim sprite names
autoAliasEnabled BOOL enable detection of duplicate sprites
premultiplyAlpha BOOL enable premultiply alpha
reduceBorderArtifacts BOOL enable reduce border artifacts
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
dpi INT dots per inch
backgroundColor INT background color
AUTOSDSETTINGS

This data type holds AutoSD settings.

Element Data 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
TEXTURE

This data type holds a texture with all its parameters.

Element Data 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.
sprites[0..n] ARRAY of SPRITE The sprites on the current texture, without aliases.
allSprites[0..m] ARRAY of SPRITE All sprites on current texture, including aliases.
SPRITE

This data type holds a sprite with all its parameters.

Element Data 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] ARRAY of SPRITE contains the list of identical sprites
centerOffset POINT Center offset
pivotPoint POINT x and y coordinates of the Pivot Point
FILEDATA

This data type holds a file.

Element Data 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 Data 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 Data 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 Data type Info
x INT x coordinate
y INT y coordinate
SIZE

This data type holds a size.

Element Data 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

Make your own exporter

Exporter for .less framework from Paul

In particular, this fits into a Twitter Bootstrap framework as follows:

// Copied from sprites.less with minimal change
.sprite_file(@file) {
     display: inline-block;
     vertical-align: -35%;
     background-image: @file;
     background-repeat: no-repeat;

    .ie7-restore-right-whitespace();
}

[class^="icon-mysprites-"],
[class*=" icon-mysprites-"] {
    .sprite_file(image-url('sprites/icon-mysprites.png'));
}

// Import the sprite file
@import "sprite-positions/icon-mysprites";
I'm a robot