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.

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

Data

Data format and file settings for TexturePacker sprite sheets

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 Data Format 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 in this field and also all file names described below must be absolute paths. TexturePacker convert them into paths relative 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:

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

Auto-detect animations

(only available for some frameworks like LibGDX, SpriteKit, Cocos2D-x)

For some frameworks it is possible to mark a group of sprites as animation in the data file. TexturePacker automatically defines animations for sprites which have the same base name and only differ in a numerical suffix.

For the sprites walk_001.png , walk_002.png , walk_003.png TexturePacker would define an animation walk in the data file.

To disable this feature you can uncheck Auto-detect animations

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.

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

(only available if Data Format is SpriteKit)

Choose the atlasc directory containing all data and image files.

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.

Filtering

(only available if Data Format is LibGDX)

Sets the filtering values in the LibGDX exporter.

Texture

TexturePacker basic texture settings.

Texture format --texture-format <id>

Choose an image file 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:

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

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. All optimizations are lossless.

ValueDescription
0always write 32 bit png files
1write indexed (8 bit) png files if possible (default)
2 7activate additional file size optimization steps

The higher the level, the more combinations are tested.

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

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/2, PVRTC or PVRTC2 require special decoding in hardware or software and can only be used with specific Data Formats.

GUI/CMD valueDescription
RGBA8888default, 4 bytes per pixel, 8 bits per channel
RGBA44442 bytes per pixel, 4 bits per channel
RGBA55512 bytes per pixel, 5 bits per color channel, 1 bit transparency
RGBA55553 bytes per pixel, 5 bits per channel, not supported on all platforms
BGRA88884 bytes per pixel, 8 bits per channel
RGB8883 bytes per pixel, 8 bits per channel, no transparency
RGB5652 bytes per pixel, 5 bits for red and blue, 6 bits for green, no transparency
PVRTCI_2BPP_RGBAPVRTC with 2 bits per pixel, (PVR file only, no real-time preview available)
PVRTCI_4BPP_RGBAPVRTC with 4 bits per pixel, (PVR file only, no real-time preview available)
PVRTCI_2BPP_RGBPVRTC with 2 bits per pixel, no transparency, (PVR file only, no real-time preview available)
PVRTCI_4BPP_RGBPVRTC with 4 bits per pixel, no transparency, (PVR file only, no real-time preview available)
PVRTCII_2BPPPVRTC2 with 2 bits per pixel, (PVR file only, no real-time preview available)
PVRTCII_4BPPPVRTC2 with 4 bits per pixel, (PVR file only, no real-time preview available)
ETC1_RGBETC1 compression, no alpha channel (PVR / PKM file only)
ETC1_AETC1 compression, alpha channel only (PVR / PKM file only)
ETC2_RGBETC2 compression, no alpha (PVR file only)
ETC2_RGBAETC2 compression, color+alpha channel (PVR file only)
DXT1/BC1Compressed with DXT1, 1 bit transparency (PVR file only)
DXT5/BC3Compressed with DXT5, transparency (PVR file only)
ALPHAGrayscale image of the alpha channel
ALPHA_INTENSITY16 bit alpha + intensity

ATF settings (Adobe Texture Format)

ATF is Adobe's own texture format which can be read by Flash applications.

For the ATF texture format there is no image format selector. In this case the ATF Settings button opens an configuration dialog. There you can configure all the image formats you want to add to the ATF container.

ATF file compression - JXR only

JXR compression

ATF file compression - pvrtc, dxt, etc

Hardware compression

TexturePacker saves loss-less compressed JXR data by default. The advantage is that this format works on all devices and gives you the best quality.

Move the JXR compression to the right to get lossy compression with better compression rates but less image quality.

You can also enable hardware compression with PVRTC, DXT, ETC1 and ETC2 codecs. With these settings you have to decide which compression formats you need for the devices you want to support. E.g. use PVRTC for iOS devices, use DXT, ETC1, ETC2 for Android.

The hardware compressed data can additionally be compressed with JXR to reduce the file size even further.

Dithering --dither-type <dithertype>

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 - sprite with 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/CMD valueDescription
NearestNeighbourHas the least color error but color distribution leads to less contrast than Linear.
LinearCreates a linear color distribution with some color error but better contrast than NearestNeighbour.
FloydSteinbergUses Floyd-Steinberg dithering algorithm.
FloydSteinbergAlphaUses Floyd-Steinberg dithering algorithm with alpha values.
AtkinsonUses Atkinson dithering algorithm.
AtkinsonAlphaUses Atkinson dithering algorithm with alpha values.
PngQuantLowPNG-8 only: minimum dithering.
PngQuantMediumPNG-8 only: medium dithering.
PngQuantHighPNG-8 only: strong dithering.

Alpha Handling --alpha-handling <value>

Defines how color value of transparent pixels are processed:

GUI/CMD valueDescription
KeepTransparentPixelsTransparent pixels are copied from sprite to sheet without any change.
ClearTransparentPixelsColor values of transparent pixels are set to 0 (transparent black) to improve image packing ratio and identical sprite detection.
ReduceBorderArtifactsTransparent pixels get color of nearest solid pixel. These color values can reduce artifacts around sprites and remove dark halos at transparent borders. This feature is also known as "Alpha bleeding".
PremultiplyAlphaAll color values are multiplied with the alpha values. This is required by some frameworks for faster rendering of the textures.

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.

PVR Quality --pvr-quality <value>

(only available if Texture format is PVR and Pixel Format is PVRTCI or PVRTCII)

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

ETC1/2 Quality --etc1-quality <value> , --etc2-quality <value>

(only available if Texture format is PVR and Pixel Format is ETC1 or ETC2)

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

DXT Quality --dxt-mode <value>

(only available if Texture format is PVR and Pixel Format is 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

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 <number> --max-height <number>

Sets the maximum width/height for the texture, default is 2048. --max-size <number> sets the value for width and height at once.

Fixed Size --width <number> --height <number>

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.

ValueDescription
POTForces the texture to have power-of-2 size (2, 4, 8, 16, 32, 64, 128, 256...).
WordAlignedWord-aligned textures make sure that each row in the texture uses complete memory words. Texture width is set to a multiple of 2 (for 16-bit formats), this might extend the texture by 1px in width.
AnySizeAllows the texture to have any size. TexturePacker tries to find the minimum size. Use Pack option ( --pack-mode ) to restrict the search for the optimum texture.

Force squared --force-squared

Forces the texture to have a squared size.

Scaling variants --variant <scale>:<name>[:<filter>[:allowfraction][:<width>:<height>]]

This feature allows you to create and save multiple variants (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 variants select No scaling variants and click Apply .

You can sort your variants 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 variants. It will replace the {v} in the Data and Texture file names.

Scale

The scale factor for this variants. 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 variants. 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 sprite sheet.

Max. Texture Size

The texture limits for this variant (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 variant 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 sprite sheets you have to include both placeholders into the Data and Texture file names like this:

sheet{n1}-{v}.plist and sheet{n1}-{v}.png .

The resulting files after clicking Publish are:

  • sheet1-ipadhd.png
  • sheet1-hd.png
  • sheet1.png
  • sheet2-ipadhd.png
  • sheet2-hd.png
  • sheet2.png
  • ...
  • sheet1-ipadhd.plist
  • sheet1-hd.plist
  • sheet1.plist
  • sheet2-ipadhd.plist
  • sheet2-hd.plist
  • sheet2.plist
  • ...

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 valueDescription
SmoothScale by blending pixels - best for scaling down. Leaves blurry result when scaling up.
FastNearest neighbor scaling - OK for scaling down. Gives pixelated images when scaling up.
Scale2xFixed size up-scaling by factor of 2. Tries to optimize edges of pixel art.
Scale3xFixed size up-scaling by factor of 3. Tries to optimize edges of pixel art.
Scale4xFixed size up-scaling by factor of 4. Tries to optimize edges of pixel art.
EagleFixed size up-scaling by factor of 2. Tries to optimize edges of pixel art.
Hq2xFixed size up-scaling by factor of 2. Tries to optimize edges of pixel art.

Algorithm --algorithm <name>

TexturePacker provides three packing algorithms:

GUI/CMD valueDescription
PolygonThe best packing algorithm for non-rectangular sprites. Tries to find a tight packing for polygon sprite outlines. As sprite bounding boxes might overlap, this packing algorithm can only be used if your framework supports import of mesh vertices.
MaxRectsCurrently the best packing algorithm for rectangles. Tries to use the least texture space by applying different heuristics when placing the sprites.
BasicSimple 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 valueDescription
AscendingSorts values from small to large
DescendingSorts 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 valueDescription
BestTests all sorting variants and uses the result with the least used space
NameSorts sprites by name
WidthSorts sprites by width
HeightSorts sprites by height
AreaSorts sprites by their area (width*height)
CircumferenceSorts 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 valueDescription
BestTests all available placements and uses the result with the least used space
ShortSideFitShort Side Fit
LongSideFitLong Side Fit
AreaFitArea Fit
BottomLeftBottom Left
ContactPointContact Point

Pack --pack-mode <mode>

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

GUI/CMD valueDescription
FastSearch for the minimum fitting power-of-2 size.
GoodSearches for the minimum size but aborts after some time.
BestSearches 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.

If you need TexturePacker to create scaling variants, each one with the same number of sprite sheets and same sprite placement, 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 sprite sheet numbers:

TagDescriptionExampleOutput
{n0}number, starting with 0sheet{n0}.pngsheet0.png, sheet1.png, ...
{n1}number, starting with 1sheet{n1}.pngsheet1.png, sheet2.png, ...

Using the Multipack and Scaling variants feature together

If you use Multipack to create two or more sprite sheets, plus you have several Scaling variants you have to include both placeholders into the Data and Texture file names like this:

sheet{n1}-{v}.plist and sheet{n1}-{v}.png.

The resulting files after clicking Publish are:

  • sheet1-ipadhd.png
  • sheet1-hd.png
  • sheet1.png
  • sheet2-ipadhd.png
  • sheet2-hd.png
  • sheet2.png
  • ...
  • sheet1-ipadhd.plist
  • sheet1-hd.plist
  • sheet1-plist
  • sheet2-ipadhd.plist
  • sheet2-hd.plist
  • sheet2-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 --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 modes:

GUI ValueCMD valueDescription
NoneNoneKeep the sprites as they are. Do not remove transparent pixels.
TrimTrimRemoves 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 positionCropKeepPosRemoves 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 positionCropRemoves 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.
PolygonPolygonApproximates the outline of the sprite using a polygon path. With this trim mode the polygon packer (see Algorithm selector) can pack the sprites even tighter than any rectangle-based packing algorithm. Based on the polygon outline a triangle mesh can be exported, your framework can use it to significantly reduce the number of transparent pixels which need to be processed.

Trim margin --trim-margin <number>

Transparent margin which is left over after trimming.

Alpha threshold --trim-threshold <number>

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.

Tracer Tolerance --tracer-tolerance <number>

(only available if trim mode is Polygon)

Determines how precise the polygon approximates the sprite outline.

Small values lead to a very close-fitting polygon. This allows very good packing results, but increases the processing time needed by the packer. At runtime you might get a performance gain due to the reduced overdraw, or a performance loss due to the larger amount of vertices which have to be processed.

With large tracer tolerance values the polygon is only a rough approximation of the sprite outline. The packer performance will increase, but the sprite sheets might get a bit larger. Runtime performance might get better (less vertices to process) or worse (higher overdraw). Setup some performance tests to find the best value for your sprites and target platform!

Extrude --extrude <number>

TexturePacker: Preventing sprite artifacts with 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 <number>

TexturePacker: Padding prevents artifacts from bleeding sprites

Border padding is the space between the sprites and the border of the sprite sheet. A value >0 adds transparent pixels around the borders of the sprite sheet.

Shape padding --shape-padding <number>

Sprite sheet: Shape padding to prevent bleeding artifacts from neighbor sprites

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.

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

Commandline only: --padding <number>

Combination of --shape-padding and --border-padding , value in pixels

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

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.

Shape outlines --shape-debug

(Only available on command line)

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.

Packing normal map sprite sheets with the same layout

Trim, crop, extrude and padding is applied on the sprites of 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

Image files with a file path containing the filter string are considered as normal maps. 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}