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 enough options available to adjust things to your needs.

Supported operating systems

MacOS

TexturePacker currently runs on MacOS 10.6 and above. (10.5 may work too, but since I have no system for testing this, it is not recommended).

Windows

Every release version will be built for Windows XP, Vista, 7 and 8.

Linux

The 2.x.x release runs on Linux, the new 3.x.x is planned to also be available for Linux soon.

Installation

MacOS

To install TexturePacker, simply open the TexturePacker.dmg file. Drag TexturePacker to your application folder.

Windows

To install TexturePacker on Windows, simply run the installer.

First use

With the first use TexturePacker opens a wizard guiding you through the initial setup.

Choosing the license

Test Pro for 1 week

You can test all features of the Pro version for 7 days. Simply press the "Test Pro for 1 week" button.

Buy License Online

This button takes you to the CodeAndWeb online store. You can purchase a license for TexturePacker here. TexturePacker licenses never expire. You can use the version you purchased as long as you want to. A standard license contains all updates and upgrades for 1 year - no matter if they are major or minor versions. After that year, a license renewal is required if you want to get new versions.

Use Essential (lite) version

TexturePacker has a free lite mode called TexturePacker Essential. In this mode basic sprite sheet functions are available, but not extended features like image optimization or algorithms other than Basic.

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.

Menu Bar

New

Create a new sprite sheet.

Open

Open an existing .tps file.

Save

Save the current document to disk. Creates a .tps file.

Save defaults

Save the current settings as default values. Next time you open TexturePacker, the options will be filled in with your saved values.

Add Sprites

Add a new single sprite to your sheet.

Add Folder

Add a folder containing sprites.

Delete

Delete current selection.

Publish

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

PVR Viewer

Open PVR Viewer.

Sprites Panel

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

You can drag and drop complete folders of sprites onto the panel. TexturePacker 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 and can't be removed.

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

Flash animations appear as folders too.

You can undock the Sprites Panel by clicking the small gray button on the left (see picture) or by just dragging it out of position. You can also hide it completely by unchecking it under 'View' in the menu bar. Re-dock it by double-clicking or dragging it onto TexturePacker's right window border.

Sprite Sheet Preview Panel

Zoom Panel

With the Zoom Panel you can adjust the scaling factor of your Sprite Sheet Preview.

On the left you have the scaling factor (default is 1), you can type in this field to change the zoom. You can also click on the arrows upward or downwards to change the zoom level in predefined steps as does the "-" or "+" magnifying glass.

Right next to it the "-"magnifying glass decreases zoom level in predefined steps.

With the slider bar you can adjust the zoom level smoothly by dragging the knob.

The "+"magnifying glass increases zoom level in predefined steps.

The golden "Zoom to pixel" magnifying glass resets the zoom factor to 1.

The "fit to window" magnifying glass chooses a zoom factor according to your window size, fitting the sprite inside and maximizing it.

TextureSettings Panel

You can undock the TextureSettings Panel by clicking the small gray button on the left (picture) or by just dragging it out of position. You can also hide it completely by unchecking it under 'View' in the menu bar. Re-dock it by double-clicking or dragging it to the left border of TexturePacker. The TextureSettings Panel can also dock over or under the sprite sheet preview window.

Data Format --format <name>

Choose the Data Format your game/web framework supports. You can also create your own data exporter in case your favorite framework is not yet supported. See chapter 'Make your own exporter' under 'Customization' for more info.

Data File --data <filename>

Choose the 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 AutoSD to create different variations of a sprite sheet, make sure that the file name contains the value you specify as the main extension. E.g. if your main extension is -ipadhd your file name might be texture-ipadhd.plist.

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.

If you are using AutoSD to create different variations of a sprite sheet, make sure that the file name contains the value you specify as the main extension. E.g. if your main extension is -ipadhd your file name might be texture-ipadhd.png.

Java file --andengine-java <filename>

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 AutoSD to create different variations of a sprite sheet, make sure that the file name contains the value you specify as main extension.

E.g. if your main extension is -ipadhd your file name might be texture-ipadhd.java.

Java package name --andengine-packagename <name>

Enter the package name for the additional Java metadata.

PngOpt Level --png-opt-level <value>

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

The higher the level, the more combinations are tested.

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

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.

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.

Flip PVR

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

JPG quality --jpg-quality <value>

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

Image 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, PVRTC2, or PVRTC4 require special decoding in hardware or software and can only be used with specific data formats.

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.

• 

  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.

• 

  RGBA 4444
  no dithering

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

  This consumes 2 bytes per pixel.

• 

  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.

AutoSD

This feature allows you to create and save multiple variations (e.g. scaling factors) of the sprite sheet during publish without resizing all sprites in your graphics software.

Press the cog wheel button to open the AutoSD dialog box.

1. Presets

Here you find already-defined presets for scaling down by 50% for Retina display and another variant scaling down 50% and 25% for Retina iPad. After selecting your preset press "Apply".

Warning: overwrites current settings!

2. Main Extension --main-extension <string>

This is the part from the main file name that is replaced with a scaling-specific extension.

This can be any part of the file name and the path. E.g. for Cocos2D-X, set the main extension as /ipad/ and the extension of the variants as /iphone/.

3. The variations list

Press the "+" button to add a new scaling variation.

4. 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 are padded with transparency if necessary.

AutoSD-Variations

After pressing the "+ or applying a preset, the list will contain some entries:

1. Scale

The scale factor for this variation.

2. Extension

The extension for this variation. It will replace the Main Extension in the file names for textures and data.

3. Max. Texture Size

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

4. Identical layout / accept fractional values

Check if you want to accept sub-pixel rendering. This might be needed if no common factor 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.

Example:

Assuming that your main sheet is for a Retina display iPad, name the texture and data files in blah-ipadhd.png and blah-ipadhd.plist.

Open AutoSD and set the main extension to -ipadhd.

Then create the other variants by pressing "+":

scale = 0.5, extension = -hd

scale = 0.25, extension = empty

The result after Publish is:

blah-ipadhd.png, blah-ipadhd.plist

blah-hd.png, blah-hd.plist

blah.png, blah.plist

Command line options

--auto-sd is deprecated and only kept for compatibility with older versions of TexturePacker.

You should use --main-extension <string> and --autosd-variant <scale>:<extension>[:allowfraction][:<width>[:<height>]] instead.

Content Protection --content-protection <key>

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

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.

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.

Pack --pack-mode <mode>

Controls how much time TexturePacker uses to find the minimum texture size with NPOT and Free constraints.

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 AutoSD settings (see TextureSettings above).

Scale mode --scale-mode <mode>

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

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 Layout -> 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>

Orders sprites before placing them into the sprite sheet.

Heuristics --maxrects-heuristics <mode>

Heuristics is used to place the sprites in the texture.

Border padding --border-padding <int>

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.

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.

Extrude --extrude <int>

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.

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.

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". Warning: This only works when premultiply alpha is turned off.

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.

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.

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.

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.

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.

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

Trim sprite names --trim-sprite-names

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

Filtering

(only available if Output -> Data Format is "LibGDX")

Sets the filtering values in the LibGDX exporter. For more details see LibGDX specification.

Description at http://www.badlogicgames.com/wordpress/?p=1403

Min Filter --andengine-minfilter <name>

Sets the minimizing filtering values in the AndEngine exporter.

Mag Filter --andengine-magfilter <name>

Sets the magnifying filtering values in the AndEngine exporter.

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

Sets the wrap value in the AndEngine data file.

under construction

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.

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
• filter.qs - an optional file you can use to extend the templates with JavaScript

Creating your own exporter

First of all, create a directory - it's the base directory that will contain all your custom exporters. E.g. myExporters.

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

Set the base exporter directory in TexturePacker's preferences:

The exporter description file

Create an exporter.xml inside that directory.

Here's an example file:

<exporter version="1.0">
  <!-- identifier of the exporter -->
  <name>testexporter</name>
 
  <!-- display name of the exporter for the combo box -->
  <displayName>TestExporter</displayName>
 
  <!-- description of the exporter -->
  <description>My first custom exporter for TexturePacker</description>
 
  <!-- exporter version -->
  <version>1.0</version>
 
  <!-- currently only one file allowed -
       more to come soon -->
  <files>
      <file>
          <!-- name of this file variable -->
          <name>maintext</name>
 
          <!-- human readable name (for GUI) -->
          <displayName>MySpriteSheet</displayName>
 
          <!-- file extension for the file -->
          <fileExtension>txt</fileExtension>
 
          <!-- name of the template file -->
          <template>testexporter.txt</template>
      </file>
  </files>
 
  <!-- target framework supports trimming -->
  <supportsTrimming>yes</supportsTrimming>
 
  <!-- target framework supports rotated sprites -->
  <supportsRotation>yes</supportsRotation>
 
  <!-- rotated sprites direction (cw/ccw) -->
  <rotationDirection>cw</rotationDirection>
 
  <!-- supports npot sizes -->
  <supportsNPOT>yes</supportsNPOT>
 
  <!-- supports file name stripping (remove .png etc.) -->
  <supportsTrimSpriteNames>yes</supportsTrimSpriteNames>
 
  <!-- supports texture subpath -->
  <supportsTextureSubPath>yes</supportsTextureSubPath>
</exporter>

The values that can be used in the table are described in detail below:

The template file

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

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

TexturePacker uses the Grantlee template engine - which is similar to Django templates. A basic description of the language is available from the Grantlee Documentation.

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.

Data structure

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

texture

Texture contains the basic layout of the texture.

smartUpdateKey

When a Publish is started, TexturePacker checks if the data file already exists. If the file is found the content 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 %}

You can now access the sprite's individual properties.

sprite

Example:

// Created with TexturePacker (http://www.texturepacker.com)
// {{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 %}
]

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. In the inner 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");

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

// 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";