TexturePacker command line parameters

TexturePacker [options] [<sprite files>|<folders>] [<*.tps>]

You pass TexturePacker the sprites you want to pack: single image files, folders (TexturePacker adds everything inside them, including sub-folders) and .tps project files. New to TexturePacker on the command line? The command line client page shows how to install it and pack your first sheet.

When you pass a .tps file, the options you add on the command line override the settings stored in that file. That way, one project file can serve as a template for many sheets.

The following parameter documentation is grouped by what you want to do. Each group starts with the basic parameters, the ones you need for everyday packing, followed by advanced parameters for fine-tuning.

TexturePacker --help prints the options of the version you have installed.

Long examples are split over several lines with \ at the line end. That works in the macOS and Linux shells; on Windows, type the command on a single line.

Input and output files

These parameters decide which sprites go into the sheet, which files come out, and which game engine the data file is written for.

Basic

Input: list the sprites before, after or between the options, the order doesn't matter. You can mix single image files (.png, .jpg, .webp, .psd, …), folders and .tps project files. TexturePacker adds all images inside a folder, including its sub-folders, and the sprite names keep the path below that folder: sprites/hero/run_01.png becomes hero/run_01.png.

Examples

TexturePacker --format phaser \
  --data assets/atlas.json --sheet assets/atlas.png sprites

Packs everything in the sprites folder into a Phaser atlas: assets/atlas.json and assets/atlas.png.

TexturePacker --format pixijs4 \
  --data atlas.json --sheet atlas.webp \
  --trim-sprite-names --prepend-folder-name sprites

Writes a WebP sheet for PixiJS. The texture format follows the .webp file name, and the sprites are named like sprites/hero/run_01.

TexturePacker game.tps \
  --data build/atlas.json --sheet build/atlas.png

Uses all settings and sprites from game.tps, but writes the files to the build folder.

Advanced

Exporter-specific options

Some formats write an additional file or have settings of their own. These options only work together with the matching --format. TexturePacker --help lists them for the version you have installed.

Sheet layout

These parameters control how big the sheet may get, how TexturePacker places the sprites, how much space it leaves around them, how it trims them, and at which scale it packs them.

Basic

Examples

TexturePacker --format phaser \
  --data atlas.json --sheet atlas-{n}.png \
  --max-size 1024 --multipack sprites

Splits the sprites over as many 1024×1024 sheets as needed: atlas-0.png, atlas-1.png, … Phaser loads all of them from the single data file atlas.json.

TexturePacker --format phaser \
  --data atlas.json --sheet atlas.png \
  --padding 2 --extrude 1 --trim-mode Trim sprites

Leaves 2 pixels between the sprites, repeats the edge pixels once against flickering and trims transparent borders.

TexturePacker --format phaser \
  --data atlas-half.json --sheet atlas-half.png \
  --scale 0.5 sprites

Packs a half-resolution sheet, e.g. for smaller screens.

Advanced

Size

Packing

Spacing and trimming

Scaling

TexturePacker --format phaser \
  --data atlas{v}.json --sheet atlas{v}.png \
  --variant 1:@2x --variant 0.5: sprites

Writes atlas@2x.png at full size and atlas.png at half size in one run, each with its own data file.

Image quality and compression

These parameters trade file size and memory against image quality. The pixel format decides how many bits each pixel gets, and every compressed texture format has its own quality setting.

Basic

The Texture Compression page explains which GPU formats your target platforms support.

Examples

TexturePacker --format phaser \
  --data atlas.json --sheet atlas.png \
  --pixel-format RGBA4444 sprites

Stores 16 bits per pixel instead of 32: half the memory, with slight color banding.

TexturePacker --format phaser \
  --data atlas.json --sheet atlas.webp \
  --webp-quality 80 sprites

Writes a lossy WebP sheet at quality 80, much smaller than a PNG.

TexturePacker --format cocos2d-x \
  --data atlas.plist --sheet atlas.ktx \
  --pixel-format ASTC_6x6 --astc-quality 3 sprites

Writes a GPU-compressed ASTC texture that stays compressed in video memory.

Advanced

Info, logging and licensing

These parameters show information about TexturePacker, control how much it prints, and manage the license on machines without a user interface, e.g. build servers.

Basic

Examples

TexturePacker --activate-license TP-????-????-????-????

Activates a Single User or Volume license on this machine. You only need to do this once.

A Docker/CI license works differently: TexturePacker releases it again when it exits, so pass the key with every call, or set the TP_FLOATING_LICENSE environment variable instead. See Docker & CI.

TexturePacker --activate-license TP-????-????-????-???? \
  --format phaser --data atlas.json --sheet atlas.png sprites

Packs with a Docker/CI license that is claimed for this run and released when TexturePacker exits.

TexturePacker --verbose --format phaser \
  --data atlas.json --sheet atlas.png sprites

Prints what TexturePacker does while packing, which helps when a build step fails.

Advanced

Converting single images

--convert-texture turns TexturePacker into an image converter: it converts one image file into another format, without packing a sprite sheet.

In this mode, TexturePacker accepts the options from Image quality and compression, plus --scale, --scale-mode, --texture-format, --size-constraints, --force-squared and the padding and trim options (--trim, --trim-margin, --trim-threshold, --padding, --heuristic-mask).

The Image Conversion page explains usage and options, with examples.