Skip to content
View as Markdown

TexturePacker command line client

The command line client runs TexturePacker without the graphical user interface. Use it to pack sprite sheets in your build process, on a build server, or to update many projects at once.

This page shows how to install it and how to use it. The command line parameters reference explains every parameter, with defaults and examples. TexturePacker --help prints the options of the version you have installed.

Installation

Windows

Open the menu File / Install Command Line Tool. It does not change your system: it shows the folder to add to your PATH. For a standard installation, that folder is:

C:\Program Files\CodeAndWeb\TexturePacker\bin

You can do this in your scripts:

SET "PATH=C:\Program Files\CodeAndWeb\TexturePacker\bin;%PATH%"

To add the folder permanently, open Settings → System → About → Advanced system settings → Environment Variables, select the Path variable and add the folder shown above.

macOS

Use the menu TexturePacker / Install Command Line Tool to open this dialog:

Installing TexturePacker's command line tool on macOS

Click Install. TexturePacker asks for admin permissions to create a link to TexturePacker in /usr/local/bin. You can also create the link yourself:

sudo ln -s "/Applications/TexturePacker.app/Contents/MacOS/TexturePacker" \
  "/usr/local/bin/TexturePacker"

If you don't want a link, add TexturePacker to the PATH in your build scripts, .zshrc or .bashrc instead:

export PATH="/Applications/TexturePacker.app/Contents/MacOS/:$PATH"

Both ways work the same.

Linux

With the .deb package, there is nothing to do: installing it already puts TexturePacker on your PATH.

If you installed the Flatpak, add an alias to your .bashrc or .zshrc:

alias TexturePacker='flatpak run com.codeandweb.texturepacker'

Packing sprites

Packing a folder

To pack all sprites in a folder, e.g. for Phaser:

TexturePacker --format phaser --data out.json --sheet out.png spritefolder
  • --format sets the game engine or framework you pack for
  • --data sets the file name of the data file
  • --sheet sets the file name of the sprite sheet image
  • spritefolder is the folder that contains your sprites

TexturePacker adds all sprites in spritefolder, including its sub-folders. You can pass several folders, or single sprite files if you want more control over what goes into the sheet.

Building .tps projects

TexturePacker can also build the projects you create in the graphical user interface. Save the project as a .tps file and pass it to the command line client:

# one project
TexturePacker sheet.tps

# several projects
TexturePacker sheet1.tps sheet2.tps sheet3.tps

# all projects in the current folder (macOS and Linux only)
TexturePacker *.tps

Using a .tps file as a template

Options on the command line override the settings in a .tps file. So you can keep your packing settings in a .tps file, without sprites or output file names, and pass the sprites and file names on the command line:

TexturePacker config.tps --data sheet.json --sheet sheet.png sprites

Using TexturePacker in your build

TexturePacker only rebuilds a sprite sheet when something changed. It compares time stamps and a smart update hash that it stores in the sprite sheet's data file, and rebuilds the sheet if

  • a sprite was changed, added or removed,
  • the settings changed,
  • you use a different version of TexturePacker, or
  • you pass --force-publish.

This check is very fast, so you can run TexturePacker in every build without slowing it down. You also don't have to list your sprites as input dependencies, e.g. in make: TexturePacker keeps track of them itself.

Updating .tps project files

You can change the settings of .tps files from the command line, without opening the graphical user interface. This is useful to change the same setting in many projects at once.

For example, to change the padding in project.tps:

TexturePacker project.tps --padding 10 --save project.tps

This loads project.tps, changes the padding and saves the project again, without packing.

Converting images

TexturePacker can also convert single images between texture formats with --convert-texture. See Image Conversion for details.

Line endings

TexturePacker writes files with the line endings of your operating system: LineFeed (LF) on macOS and Linux, CarriageReturn-LineFeed (CRLF) on Windows.

If your team works on Windows as well as macOS or Linux, configure your version control system to convert between the two styles. Our tutorial How to handle line endings in git shows how.