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: --option <value>

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 Data Format button and select another framework.

Make sure to save your current project before converting it!

Data file --data <filename>

Set the output file name for the Data file. The Data file contains metadata like the sprite sizes and coordinates where the sprites can be found on the texture.

Make sure to enter an absolute path and ensure that all file names mentioned below are also absolute paths. TexturePacker converts them into paths relative to the .tps file when saving - allowing you to move the complete set of data to other locations.

When using Multipack or Scaling variants to create multiple sprite sheets, make sure that the Data file name contains a placeholder:

Note: In the UI this field might have another name like "JSON file", "XML file" or "Atlas bundle", depending on the selected framework.

Additional data files

For some frameworks it is possible to export a second data file, containing sprite IDs and other metadata as source code. In the graphical user interface a second file name input field is displayed, on command line the following framework-specific options are available:

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

Filtering

(only available if Data Format is LibGDX)

Sets the filtering values in the LibGDX exporter.

Texture

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.

When using Multipack or Scaling variants to create multiple sprite sheets, make sure that the Texture file name contains a placeholder:

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

(only available if Texture format is PNG)

Configure how much effort TexturePacker spends optimizing the PNG file size. All optimizations are lossless.

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

Image quality

If a lossy texture format is chosen instead of PNG, the image quality can be set with the corresponding slider in the UI. On command line the following options are available:

Pixel format --opt <pixelformat>

Specifies the pixel encoding used for the texture file.

Only Pixel formats supported by the currently selected Texture Format can be chosen.

Formats like .tga or .png only support 32-bit color values. Although it is possible to choose a 16-bit pixel format. Use this option if you want to load the image with 16-bit/pixels on your target system. TexturePacker will dither the image to reduce the number of colors, making the format conversion on your target system simpler.

Some pixel formats like ETC1/2, PVRTC or PVRTC2 require special decoding in hardware or software, make sure that your target supports them.

For PVRTC, ETC, DXT, ASTC, BASISU pixel formats there is no real-time preview available.

Dithering --dither-type <dithertype>

Enhances image quality when using reduced-color formats like RGBA4444. Reducing colors can sometimes result in "banding artifacts," which can negatively impact image quality. Consider experimenting with dithering settings to minimize these artifacts:

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 semi-transparent gradients, whereas the non-alpha version is better for crisp, solid sprites and tile maps.

Transparency Handling --alpha-handling <value>

Defines how color values of transparent pixels are processed:

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

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

Save as Global Key saves the key in TexturePacker as a global key. This key is used for decryption in the .pvr viewer, and it can be easily pasted into other sprite sheets by pressing Use global key. To disable encryption use Clear / Disable.

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

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.

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 differently scaled variants 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 variant, select No scaling variants and click Apply.

You can sort your variants 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}

This string is used to replace the {v} in the Data and Texture file names.

Scale

The scale factor for this variant. 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 variant. Filtering works on both sprite names and folder paths, and the filters are processed in descending order of length. You can also concatenate several search terms with , to have them packed into one sprite sheet.

Max. Texture Size

The texture size limit 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

By default, each scaling variant texture is packed individually, resulting in different sprite placements between textures. With this option, the sprites will be placed with the same layout on all textures, the textures only differ in the overall scale factor. All sizes and coordinates will be divisible by the same common factor to avoid fractional values. For example, if you scale down your texture by 0.5, the common factor is 2.0, forcing all values to be divisible by 2.0.

Sprites will then be padded with transparency if necessary.

Example

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. Use Add to add empty variants and enter the following values:

After adding sprites and clicking Publish sprite sheet the following files are generated:

If scaling variants are combined with the multipack feature, the file names must contain both placeholders, for details see multipack configuration.

Scale --scale <float>

Sets the basic scale factor for the sprites. Default is 1 to keep the original sprite sizes.

To add and create various versions of a texture with different scale factors, you can use the Scaling variants feature.

Scale mode --scale-mode <mode>

With this parameter you can select the algorithm which is used for scaling the sprites.

Algorithm --algorithm <name>

TexturePacker provides four packing algorithms:

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

(only available if Algorithm is Basic)

Sorts sprites before placing them into the sprite sheet.

Order --basic-order <mode>

(only available if Algorithm is Basic)

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.

Align to grid --align-to-grid <value>

Ensures that the top-left corners of the untrimmed sprites are placed on sprite sheet coordinates divisible by the specified value.

Multipack

Automatic Multipack --multipack

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

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

Manual Multipack

If you select the Manual Multipack mode, you can create sprite sheets by pressing the Add sheet button on top of the sprite list on the left side of the main window. Use the Add sprites toolbar button to add sprites to the currently selected sheet, with drag+drop you can move sprites and smart folders between sheets. For more details see The Manual Multipack mode.

This feature is not available on the command line.

Using the Multipack and Scaling variants feature together

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

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

The resulting files after clicking Publish are:

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

Each sprite gets its individual entry in the generated data file, but by default identical sprite images are only placed once on the texture to save space, the data entries refer to this "shared" sprite on the texture. These sprites are marked with a 'stack' icon in the texture preview.

By default, this feature is enabled, but you can disable it if required.

Sprites

Trim mode --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:

Trim margin --trim-margin <number>

Transparent margin which is left over after trimming.

Transparency 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 (fewer 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>

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 tile-maps this allows you to see if there are semi-transparent pixels at the borders of the tiles.

Border padding --border-padding <number>

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>

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

With TexturePacker normal map sprites can be packed on their own sprite sheet:

Pack with same layout --pack-normalmaps

Activate this option to pack normal maps on a separate sheet, with the same layout as the sprite sheet. Trim, crop, extrude and padding will be applied to the sprites and their corresponding normal maps. Both sheets share the same data file, as the coordinates and sizes of the sprites are the same on both textures.

The sprite and its normal map should have the same file name. The normal map file may have an additional suffix, like "_n". This allows TexturePacker to identify which sprites and normal maps match.

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

The name of the generated texture file containing the normal maps. In case you are using scaling variants or multipack, make sure to add the place holders {n} and {v}. If you leave this file name empty, TexturePacker automatically uses the sprite sheet file name with additional suffix _n.