TexturePacker online documentation

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.

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

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.

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.

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:

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>

Choose the file name for the classfile output file.

Java file --java-file <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 Multipack or Scaling variants to create different variations of a sprite sheet, make sure that the Data file name contains a placeholder:

Java package name --andengine-packagename <name>

Enter the package name for the additional Java metadata.

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

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>

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>

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.

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 Multipack or Scaling variants to create different variations of a sprite sheet, make sure that the Texture file name contains a placeholder:

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>

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>

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>

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

WebP Quality --webp-quality <value>

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

JXR Compression --jxr-compression <value>

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

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

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

Increases packing ratio by removing detail from the image.

JXR Color Format jxr-color-mode <value>

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

ETC1 Quality --etc1-quality <value>

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

DXT Quality --dxt-mode <value>

Set DXT1/5 compression mode: linear, perceptual.

Flip PVR --flip-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.

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.

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

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

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.

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.

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.

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

Algorithm --algorithm <name>

There are currently 2 algorithms:

Order --basic-order <mode>

(only available if Algorithm is Basic)

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

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

Heuristics --maxrects-heuristics <mode>

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

Pack --pack-mode <mode>

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

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.

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

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.

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:

Pivot Point

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

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.

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.

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".

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.

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:

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

The sprites and normal maps are connected through their names.

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}

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

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:

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