# Quickstart: Your texture atlas in 5 seconds Installing TexturePacker is straightforward. If you run into issues, see [Installation and Licensing](https://www.codeandweb.com/texturepacker/documentation/installation-and-licensing.md). Video: **TexturePacker Quick Tutorial** (0:33) https://player.vimeo.com/video/849123907?h=b74be0f170 The small video above shows you how you can create your first sprite sheet in seconds: ## Select the exporter / data format This step is not required but is highly recommended if you plan to use your sprite sheet with a game engine. The data file contains information about the sprite positions, names, trimming, pivot points, 9-patch and other stuff. Here's a list of supported game engines, frameworks and data formats. Several other game engines work with TexturePacker by using the generic **JSON Hash** or **JSON Array** formats. * 2D Toolkit * Amethyst * AppGameKit * Axmol * Babylon.js * BatteryTech * BHive * Blacksmith 2D Engine * CAAT * CEGUI / OGRE * Cocos2d * Cocos Creator * CSS * Defold * EaselJS * Egret Engine * Felgo (V-Play) * GameMaker * Gideros * Godot 3 * Godot 4 * JSON Hash * JSON Array * Kivy * Kwik * LayaAir * LESS * LibGDX * LibRocket * Mapbox * MelonJS * Moai * Molecule Framework * MonoGame * Orx * Panda 2 * Phaser * PixiJS * PlayCanvas * PopcornFX * SASS * Slick2D * Solar2D * Spark AR Studio (discontinued) * Sparrow * Spine * SpriteKit * Spriter * SpriteStudio * UIKit * Unity * Unreal Engine / Paper2D * X2D * XAML * XML * ZIM ## Drop your sprites Drag & drop a folder containing your sprites on the left pane. TexturePacker scans it for known image formats such as PNG, JPG, PSD, SVG, BMP, TIFF and others. The sprite view updates each time you add new sprites to the folder, rename or change sprites. You can adjust the layout of the sprite sheet in the right panel — see [Texture Settings](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md) ## Click publish A click on the **Publish** button writes your sprite sheets. ## Importing the sprite sheet Many game development frameworks have built-in TexturePacker support, some require additional steps like Unity (installing our free TexturePacker importer plugin). Please check out the [Tutorials page](https://www.codeandweb.com/texturepacker/tutorials.md) for more information. # Installation TexturePacker is a GUI and command line tool to create sprite sheets or sprite atlases. Without specifying any additional options, TexturePacker already creates very good results, but you also have many options available to adjust things to your needs. ## Supported operating systems * **Windows 10 and 11** * **macOS 13** and newer (Intel and Apple Silicon) * **Linux** (Debian, Ubuntu, Fedora, CentOS, Arch, Mint, etc.) as Flatpak * **Ubuntu 22.04** and newer as .deb package Using an older operating system? See [which TexturePacker version runs on it](https://www.codeandweb.com/texturepacker/knowledgebase/older-versions.md). ## Download & install ### Windows Download the installer [TexturePacker-8.3.0.msi](https://www.codeandweb.com/texturepacker/download/8.3.0/win) file and double-click it for installation. ### macOS Download the [TexturePacker-8.3.0.dmg](https://www.codeandweb.com/texturepacker/download/8.3.0/mac) file and open it from your Downloads folder. Drag and drop TexturePacker.app into your Applications folder. ### Linux #### Debian/Ubuntu This installation works for distros using the _apt_ package manager. Start by downloading [TexturePacker-8.3.0.deb](https://www.codeandweb.com/texturepacker/download/8.3.0/linux-deb). Open the downloads folder and click the _TexturePacker-8.3.0.deb_ to install it using the software installer. You can also use the command line: ``` sudo apt install ./TexturePacker-8.3.0.deb ``` #### All distros using Flatpak We support other distros using the [Flatpak](https://flatpak.org/) package manager. Download [TexturePacker-8.3.0.flatpak](https://www.codeandweb.com/texturepacker/download/8.3.0/linux-flatpak) ``` flatpak install TexturePacker-8.3.0.flatpak ``` If it didn't work... You might see the following error during installation: ``` The application com.codeandweb.texturepacker/x86_64/master requires the runtime org.freedesktop.Platform/x86_64/ which was not found ``` If this is the case, the Flathub repository was not added to your system. It contains the base runtime that TexturePacker needs to run. Open a command line and run: ``` flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo ``` Now try again to install TexturePacker. To run TexturePacker, you can double-click its icon or use the command line: ``` flatpak run com.codeandweb.texturepacker ``` ### Docker You can also use TexturePacker inside a [Docker container](https://www.codeandweb.com/texturepacker/documentation/docker-ci.md), but this requires a special type of license, and you won't have access to the UI. ## Licenses You can test all features of TexturePacker for 7 days. This trial mode is available for new installations. If your trial period is over, you can still use TexturePacker in **Essential** mode or buy a license for the full version. Please have a look at the [TexturePacker licenses comparison page](https://www.codeandweb.com/texturepacker/licenses-comparison.md) for a detailed overview of all features available in the Essential vs. full version. ### TexturePacker Essential TexturePacker has a free mode called TexturePacker Essential. In this mode, only basic sprite sheet functions are available. If you use advanced features in this mode, you will get a warning before publishing and some of your sprites will turn red in the output. Essential is free for non-commercial projects only; commercial use requires a license. See the [EULA](https://www.codeandweb.com/texturepacker/documentation/eula) for details. ### TexturePacker full version Advanced features of TexturePacker require a license. You can purchase licenses directly from our [Store](https://www.codeandweb.com/store.md). With a license, you can use the latest TexturePacker release, and you can also download and use any future version released within a specific timeframe (1 year or lifetime, depending on the license type). ## Additional tools ### Installation of the command line tool TexturePacker can also be used as a command line client. This allows you to perform powerful batch operations and even integrate TexturePacker into your build pipeline. On Windows and macOS, use the menu entry **Install Command Line Tool**: on macOS, it links TexturePacker's command line executable into your search path; on Windows, it shows the folder to add to your `PATH`. On Linux, the menu entry does not exist: the .deb package already puts `TexturePacker` on your `PATH`. For the Flatpak, see the alias in [Command line](https://www.codeandweb.com/texturepacker/documentation/commandline.md#linux). See [Command line](https://www.codeandweb.com/texturepacker/documentation/commandline.md) for how to use it. ### TexturePacker FlashUnpacker TexturePacker's FlashUnpacker was an add-on for TexturePacker to extract animation sequences as sprites and pack them into a sprite sheet. As Adobe ended support for Flash Player in 2020 we've removed this feature from TexturePacker in 2021. If you still need to import sprites from Adobe Flash files (.swf), please use TexturePacker 5.5.0 or older. # TexturePacker CI installation We introduced the floating license model, also known as the Docker/CI license, in 2020. This permits the use of TexturePacker in a Continuous Integration (CI) system on a server or build machine. It also allows users to run it inside a Docker (or similar) container. Single User Licenses and Volume Licenses for TexturePacker are designed to be used by 'real' users on a desktop or laptop. These licenses do not permit use on a server or in automated builds. ## 1\. Get your Docker/CI license First, you have to purchase a Docker/CI license. Here are some things you should consider before the purchase: #### Concurrency Level The concurrency level describes how many instances of TexturePacker you want to run in parallel. It does not matter on how many computers it is running. E.g. you can run all instances on the same computer or distribute them if you have multiple build machines. During the checkout, you have to decide which concurrency level you need. You can increase the level at any time later from within the License Manager (opens in a new tab). #### License Restrictions 1. The license only works from the command line - use it on your build machines only. It is not meant for desktop use. 2. A single license can only run on the same type of operating system - Linux is the default. Please email us to transfer the license to Windows or macOS. #### Get the license The license is available from here: [Docker/CI license](https://www.codeandweb.com/store/texturepacker-ci.md). ## 2\. Upgrading TexturePacker The license permits you to always run the newest version of TexturePacker. You must use at least TexturePacker 7.0.3 - older versions have a bug that can cause issues with license release in certain cases. We've also changed what happens when no activation is available. Versions prior to 7.0.3 return an error in this case, making it difficult to add TexturePacker to a Makefile. The newer versions wait until a seat becomes available and thus do not interrupt the build process. Activating Docker/CI licenses has also been made easier - see below. [Download TexturePacker 8.3.0](https://www.codeandweb.com/texturepacker/download/8.3.0/win) for Windows [Also available for macOS and Linux](https://www.codeandweb.com/texturepacker/download.md) After installation, run TexturePacker from the command line and agree to the license terms. You can also agree to the terms via the UI. To use the license inside a Docker container, see [Docker installation](#docker-installation) below. ## 3\. Using the License in Your Build ### Using the `TP_FLOATING_LICENSE` environment variable The easiest way to use the license is to set an environment variable that contains the license key. This allows you to keep your build scripts free from the license key and does not require any modifications. ```bash export TP_FLOATING_LICENSE="TP-????-????-????-????" ``` Windows (cmd) ```batch set TP_FLOATING_LICENSE=TP-????-????-????-???? ``` Windows (PowerShell) ```powershell $env:TP_FLOATING_LICENSE="TP-????-????-????-????" ``` > **Warning:** Do not use this environment variable with a Volume or Single User License. Doing so results in TexturePacker activating and deactivating the license without performing any packing. ### Using `--activate-license` You can also set the Docker/CI license using `--activate-license` from the command line. Since TexturePacker allocates and deallocates the license with each start, you have to pass it to every call of TexturePacker. ```bash TexturePacker --activate-license TP-????-????-????-???? --sheet sheet.png --data sheet.json ..... ``` This method might be more cumbersome than using the environment variable, as it requires updates to your build scripts. ## 4\. Start your Build That's all - your build should now work as it did before. Consider increasing the concurrency level for your TexturePacker Docker/CI license if you have a powerful machine with many CPU cores and RAM. This will allow more parallel running instances. In rare cases, a license might not be properly released - e.g. if TexturePacker is killed without allowing it to release the license. This is no big problem because the activations are released by the server after 2 minutes automatically. If licenses get often stuck, please make sure that you are using TexturePacker 7.0.3 or newer. ## 5\. Conclusion Migrating from a Single User or Volume License to a Docker/CI license is easy. If you encounter any issues or have questions, don't hesitate to contact us for support. ## Optional: Docker installation Installing TexturePacker inside Docker is not hard to accomplish. Follow these steps for a simple setup: ### 1\. Create a Dockerfile This Dockerfile uses Ubuntu 24.04 LTS (22.04 or newer works), pulls the current Ubuntu build of TexturePacker straight from our [version-less download URL](https://www.codeandweb.com/product-downloads.md) and installs all required files. There is nothing to download by hand and nothing to keep up to date. ``` FROM ubuntu:24.04 ARG DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y --no-install-recommends \ libfontconfig \ libx11-6 \ libxkbcommon-x11-0 \ libglib2.0-0 \ libdbus-1-3 \ libgssapi-krb5-2 \ libgl1 \ libegl1 \ libegl-mesa0 \ && rm -rf /var/lib/apt/lists/* # Install TexturePacker ADD https://www.codeandweb.com/download/texturepacker/latest/linux-deb /tmp/TexturePacker.deb RUN apt-get update && apt-get install -y --no-install-recommends /tmp/TexturePacker.deb \ && rm -rf /var/lib/apt/lists/* /tmp/TexturePacker.deb # Uncomment this line if you agree to the license terms # RUN echo agree | TexturePacker --version ``` `ADD` rather than `RUN curl`: Docker caches a `RUN` line by its text alone, and the text of a version-less URL never changes, so a `RUN curl` layer would keep installing the build it downloaded the first time. See [Docker caches the layer, not the answer](https://www.codeandweb.com/product-downloads.md#docker-layer-caching) for how to force a rebuild to pick up a new release. Rebuilding this image gives you whatever the newest release is by then, as long as the `ADD` layer is not served from the cache (see above). Your Docker/CI license permits exactly that. A Single User or Volume license does not permit automated builds at all, and it only covers releases published inside its update window, so a rebuild can hand you one it does not cover. See [what a license covers](https://www.codeandweb.com/product-downloads.md#license-update-window). ### 2\. Build the image Build the image and install TexturePacker ``` docker build -t texturepacker:latest . ``` Run TexturePacker to read the license agreement. ``` docker run texturepacker:latest TexturePacker ``` **If you agree with the license terms, uncomment the last line in the Dockerfile**. This saves your agreement in the image. TexturePacker won't ask you again to agree when you use this image. ``` docker build -t texturepacker:latest . ``` ### Running TexturePacker inside the Container A Docker/CI license is a floating license that claims a "seat" when TexturePacker is started and automatically releases the license after the packing process. This is why every run of TexturePacker needs the license: pass it in the `TP_FLOATING_LICENSE` environment variable, or with `--activate-license` on the command line. Use a bind-mount to mount your sprite sheet directories and run the packing process. `-e TP_FLOATING_LICENSE` forwards the variable from your host, so export it there first (see above): ``` docker run --rm \ --mount type=bind,source=/tmp/spritesheets,target=/spritesheets \ -e TP_FLOATING_LICENSE \ texturepacker:latest \ sh -c 'TexturePacker /spritesheets/*.tps' ``` # TexturePacker GUI Documentation  Sprites Panel Preview Panel Settings Panel ## Tool Bar open **Open project** Open an existing .tps file. save **Save project** Save the current project to disk. Creates a .tps file. addSprite **Add sprites** Add new sprites to the sheet. removeSprite **Remove sprites** Removes selected sprite or folder from your sprite sheet. addFolder **Add smart folder** Add a folder containing sprites. spriteSettings **Sprite settings** Edit sprite pivot points and borders for 9-patch scaling. animationPreview **Preview Anims** Show an animation preview for the currently selected sprites. publish **Publish sprite sheet** Publishes when something changed. The menu also has 'Force publish sprite sheet', which rewrites the files regardless. splitSheet **Split sheet** Splits a sprite sheet into sprites. tutorials **Tutorial** Opens TexturePacker's tutorial page in your web browser. ## Sprites Panel  Just drag and drop your sprites into the Sprites Panel on the left side to load them into TexturePacker. Supported image formats are: astc, basis, bmp, dds, gif, ico, jpeg, jpg, ktx, ktx2, pbm, pgm, pkm, png, ppm, psd, pvr, pvr.ccz, pvr.gz, pvrtc, svg, svgz, tga, tif, tiff, webp, xbm, xpm You can also drag and drop **complete folders** of sprites onto the panel. TexturePacker imports all images inside that folder and uses sub-folder names as part of the final sprite name. Any changes to the folder structure are synced in TexturePacker as soon as you re-enter the application. Yellow folders are smart folders you've added to the project. They can be removed by pressing the Delete key. Blue folders are folders inside a smart folder. They can only be removed via Finder/Explorer. You can delete sprites from the panel only if you added them as individual sprites. ## Preview Panel After adding sprites to TexturePacker, you can see your sprite sheet in the Preview Panel. The sprites will be aligned on the sprite sheet based on the chosen algorithm set in **Layout -> Algorithm**. Almost all the various TexturePacker options are updated in real-time, so you can immediately see the changes made to your sprite sheet.  ## Zoom Panel With the Zoom Panel at the bottom of the window 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 sprite sheet completely inside the TexturePacker window use `Fit` . With the **Display outlines** checkbox you can visualize the sprite outlines and triangulation TexturePacker has calculated for your sprites. This makes sense if you've selected Trim mode **Polygon outline**. ## Settings Panel 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 **Advanced settings** on the respective Settings Panel. The settings to optimize your sprite sheet are described in detail in [Texture Settings](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md). ## Pivot point editor The **pivot point** (or anchor point) specifies the position inside the sprite that is used as a center for rotation and placement.  The pivot point and 9-patch editor are available from the toolbar: **Sprite settings**. The editor is only available for game development frameworks that are able to work with the settings, such as Unity and Cocos2d-x.  The editor displays sprites selected in the **Sprites panel**. You can select multiple sprites in the center view to adjust the pivot points of all of them. The panel on the right gives you number controls to set the exact pixel coordinates of the pivot point — both in absolute and relative coordinates. You can also set it to predefined positions such as center, top left etc. You can also define the default pivot point for new sprites. ## Multipack Multipack allows you to pack multiple sprite sheets in a single TexturePacker project. You can either place the sprites on the sheets manually — or use the fully automated mode. ### Auto Multipack Mode The auto multipack mode was designed to pack sprites into the minimum number of atlases possible. For this, TexturePacker automatically decides where to place a sprite and how many sprite sheets to create. While this approach works well for frameworks that have direct support for it, such as Cocos2d-x or Phaser, it may not be suitable for frameworks like Unity. This is because Unity tracks sprites per texture, and using the auto multipack mode may cause the distribution of sprites to change when a new sprite is added. This breaks the sprite references in Unity. There are also some disadvantages to using the auto multipack mode when it comes to optimizing PNG compression. For example, the quality of PNG-8 images can be improved by packing images with similar colors into the same atlas. Additionally, it can be difficult to optimize performance by reducing draw calls using this mode, as it requires knowledge of the context in which a sprite is used (e.g. background, foreground, UI, etc.). This is something that a tool cannot do automatically. ### The Manual Multipack mode The manual multipack mode gives you complete control over which sprites are packed onto which atlas. To enable this mode: In the **Advanced settings**, go to **Layout**/**Multipack** and set it to **Manual**. Alternatively, you can find this option under **Packing** in the **Basic settings**.  An "Add sheet" button will appear above the sprites panel on the left side of the TexturePacker window. You can use this button to add additional atlases to the project. If you have already added sprites to the project, they will be moved to a sprite sheet called "default". You can rename this sheet to whatever you prefer. #### Adding sprites There are several ways to add more sprites to your project: 1. Drag and drop new sprites onto a sprite sheet item in the tree view 2. Drag and drop a folder (we call it a **smart folder**) containing sprites onto a sprite sheet item in the tree view 3. Select a sprite sheet in the tree view and use the **Add sprites** button in the toolbar 4. Select a sprite sheet in the tree view and use the **Add smart folder** button in the toolbar **Smart folders** allow TexturePacker to automatically add all sprites in the folder to the sheet. When a change is made to the folder, TexturePacker will automatically update the sheet to reflect these changes. E.g. by adding, removing or renaming sprites. TexturePacker by default does not include the top level folder name in the sprite name. Just sub-folders are used to prefix the sprite name. E.g. if you add the folder `character`, the file `character/walk/walk_01.png` becomes `walk/walk_01.png`. If you want to include the folder name, enable **Prepend folder name** (right panel, in the **Data** section). #### Moving sprites between sheets You can move sprites or smart folders between sheets by dragging and dropping them to other sheets in the tree view. Dropping files onto the center view adds them to the sheet that is selected in the tree view, so use the tree view to move sprites to a specific sheet.  Note that only top-level items can be moved, such as sprites added directly to a sheet or the entire smart folder. It is not possible to move individual sprites inside a smart folder. This may seem like a limitation, but it is easy to work around. For example, if you have a character folder with sub-folders for character/walk/..., character/stand/..., character/idle/..., etc., simply add the sub-folders to the sheet instead. When identical sprites (same file) are added to multiple sheets, they are linked inside TexturePacker. This means that any changes made to pivot points or scaling will be applied to all sprites that originate from the same file. #### Ideas for organizing sprites Here are some ideas for organizing your sprites using this feature: * Keep all sprites in one project file instead of using multiple project files * Group animations by character or level on a sheet * Group sprites by color to improve PNG-8 compression and reduce the game's download size. * Group sprites by layers (background, characters, foreground, UI) to improve performance by reducing draw calls. #### Using device-specific scaling When you enable scaling variants in **Layout** / **Scaling Variants** on the right panel, you can optimize sprites for different display sizes and resolutions, such as desktop computers, tablets, and mobile phones. This allows you to ensure that the sprites are displayed correctly and clearly on different devices, while at the same time reducing the game's download size on mobile devices. In your game, you can use the screen size to determine which sprite sheet set to load. #### Publishing the sprite sheets After enabling multipack (manual or automatic), TexturePacker prompts you to add a `{n}` placeholder to your sprite sheet file names. The `{n}` placeholder is replaced by the sprite sheet number for automatic multipack, or by the sprite sheet name for manual multipack. For example, if your sprite sheet file name is `out/sheet-{n}.png` and you have sheets called `level1` and `background`, the sprite sheets are written as `sheet-level1.png` and `sheet-background.png`. If you only want the sprite sheet name, simply use `{n}.png`. You can also use the `{n}` placeholder as a folder name, along with the `{v}` placeholder for scaling variants. For example, using `out/{n}/{v}.png` would create a folder for each sheet and put the scaling variants inside. For example, you might have `out/background/mobile.png` or `out/level1/2x.png`, depending on your sheet names and scaling variant names. A click on **Publish sprite sheet** packs and saves all sprite sheets. #### Sprite sheet setting All sprite sheets have the same settings for size, packing mode, file type, and other options. Because of this, setting up a project is usually straightforward. Currently, you will still need to create two projects in TexturePacker if you want to export the sheet in different image formats such as JPG for background art and PNG for sprites. To publish the sprite sheet in different image formats (e.g. WebP, PNG, PVR), the easiest way is to set up a main project file and use the command line client of TexturePacker to override the output format parameters. You can put this in a simple script file and update all sprite sheets with a single start of that script. E.g. to publish the `main.tps` sheet as WebP you can use: ``` TexturePacker main.tps --sheet "out/{n}.webp" --texture-format webp ``` ## 9-patch editor The 9-patch editor is also part of the **Sprite settings**. It's only available for some game development frameworks.  Select the sprites you want to edit and check the **Enable 9-patch scaling**. Green bars appear on the sprite. Drag them with the mouse to split the sprite into 3 zones horizontally and vertically. The center zone is the part that scales, the border zones are fixed in their size. You can also use the number controls on the right side to enter exact values for the borders. Drag both green lines to one border to disable scaling in that direction (3-patch). ## Animation preview The animation preview is a small floating window, activated by pressing the **Preview Anims** toolbar button.  Select sprites in the **Sprites panel** to add them to the animation loop. Use the controls at the bottom of the window to control the playback speed and looping. You can also set the background color for the animation. The animation previewer updates in real time. This is very useful if you are adapting pivot points in the **Sprite settings**. # 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](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md) 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: ```batch 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:  Click **Install**. TexturePacker asks for admin permissions to create a link to TexturePacker in `/usr/local/bin`. You can also create the link yourself: ```bash 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: ```bash 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`: ```bash 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`](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md#input-output) sets the game engine or framework you pack for * [`--data`](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md#input-output) sets the file name of the data file * [`--sheet`](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md#input-output) 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](https://www.codeandweb.com/texturepacker/documentation/image-conversion.md) 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](https://www.codeandweb.com/tutorials/how-to-handle-line-endings-in-git.md) shows how. # TexturePacker command line parameters ``` TexturePacker [options] [|] [<*.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](https://www.codeandweb.com/texturepacker/documentation/commandline.md) 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`. | Parameter | Description | | --- | --- | | `--format ` | The game engine or framework you pack for. It decides the layout of the data file and some defaults, e.g. whether sprites may be rotated. `TexturePacker --help` lists all formats. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#data-format)
**Values:** exporter names, e.g. `phaser`, `pixijs4`, `unity`, `godot-spritesheet`, `cocos2d-x`, `spine`. | | `--data ` | The data file with the sprite names and positions. With `--multipack`, TexturePacker numbers extra files: `name-0`, `name-1`, … Formats that load several sheets from one data file, like `phaser`, write just one. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#data-file) | | `--sheet ` | The sprite sheet image. Its extension sets the texture format, unless you pass `--texture-format`. With `--multipack`, extra sheets are numbered like the data file. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#texture-file) | | `--texture-format ` | The image file format of the sheet. You only need it when the file extension is ambiguous. `TexturePacker --help` lists all formats. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#texture-format)
**Values:** `png`, `png8`, `webp`, `jpg`, `ktx`, `ktx2`, `basis`, `dds`, `pvr3ccz`, … | | `--trim-sprite-names` | Removes the file extension (`.png`, `.bmp`, `.jpg`) from the sprite names written to the data file: `hero/run_01` instead of `hero/run_01.png`. Your sprite files on disk keep their names. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#trim-sprite-names) | | `--prepend-folder-name` | Adds the name of the input folder to the sprite names in the data file: `sprites/hero/run_01.png` instead of `hero/run_01.png` when you pack the folder `sprites`. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#prepend-folder-name) | ### 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 | Parameter | Description | | --- | --- | | `--ignore-files ` | Leaves out all images matching the wildcard pattern (`*` and `?`), e.g. `--ignore-files "*/drafts/*"`. You can use it several times. Quote the pattern so your shell does not expand it. | | `--replace =` | Replaces the matching part of each sprite name with ``, e.g. `--replace "enemies/=e_"` turns `enemies/bat_01.png` into `e_bat_01.png`. You can use it several times. The expression is a Perl-compatible regular expression, so escape special characters. | | `--texturepath ` | Adds a path in front of the texture file name that is stored in the data file. Use it when your game loads the sheet from another folder than the data file. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#texture-path) | | `--enable-cache-busting` | Phaser and PixiJS only: appends a hash (e.g. `?v=ab12cd34`) to the texture file name in the data file, so browsers and CDNs load the new sheet after an update. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#enable-cache-busting) | | `--save .tps` | Saves the current settings as a `.tps` project file instead of packing. Combine it with a `.tps` file to change settings from the command line, e.g. `TexturePacker project.tps --padding 4 --save project.tps`. | | `--force-publish` | Writes the files even if nothing changed. By default, TexturePacker skips sheets whose sprites and settings are unchanged. | | `--pack-normalmaps` | Packs the normal maps on a separate sheet with the same layout as the sprites. By default, TexturePacker detects normal maps from their colors. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#pack-normal-maps) | | `--normalmap-filter ` | Treats all images whose path contains the text as normal maps, e.g. `normals/`. Turns on `--pack-normalmaps` and switches off the color-based detection. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#normal-map-path-filter) | | `--normalmap-suffix ` | Finds the normal map of a sprite by this suffix, e.g. `_n` for `hero_n.png`. Turns on `--pack-normalmaps` and switches off the color-based detection. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#normal-map-suffix) | | `--normalmap-sheet ` | The file the normal map sheet is written to. Numbered like `--sheet` when TexturePacker writes several sheets. Turns on `--pack-normalmaps`. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#normal-map-sheet)
**Default:** sheet name with suffix `_n`. | ### 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. | Parameter | Description | | --- | --- | | `--class-file ` | With `--format spritekit-swift`: Swift class file with the sprite names. | | `--classfile-file ` | With `--format monogame`: C# class file with the sprite names. | | `--header-file ` | With `--format cocos2d-x` or `--format spritekit` or `--format plain`: C++ / Objective-C header file. | | `--source-file ` | With `--format cocos2d-x`: C++ source file. | | `--spriteids-file ` | With `--format amethyst`: Rust file with the sprite IDs. | | `--css-media-query-2x ` | With `--format css`: media query for the `-2x` variant.
**Default:** a query that matches screens with 2× pixel density or 192 dpi. | | `--css-sprite-prefix ` | With `--format css`: prefix for the sprite names; works best with prefixes like `icon-`. | | `--easeljs-framerate ` | With `--format easeljs`: frame rate of the animations.
**Default:** `20`. | | `--gamemaker-texturegroup-frame-speed ` | With `--format gamemaker-texturegroup`: animation speed in frames per second, written for sprites with more than one frame.
**Default:** `30`. | | `--libgdx-legacy-output ` | With `--format libgdx`: writes the old data file format. | | `--orx-includeComments ` | With `--format orx`: writes comments into the data file. | | `--orx-optimizeSectionNames ` | With `--format orx`: turns image paths into PascalCase section names.
**Default:** `true`. | | `--orx-pixelSnap ` | With `--format orx`: snaps center pivot points to whole pixels. | | `--orx-keepInCache ` | With `--format orx`: keeps textures and animations in the cache. | | `--orx-keyDuration ` | With `--format orx`: duration of an animation key in seconds.
**Default:** `0.1`. | | `--spine-legacy-output ` | With `--format spine`: writes the old data file format. | | `--spritestudio-writePivots ` | With `--format spritestudio`: overwrites the pivots with TexturePacker's values; `false` keeps the pivots set in SpriteStudio.
**Default:** `true`. | | `--zim-framerate ` | With `--format zim`: frame rate of the animations.
**Default:** `20`. | | `--plain-string-property ` | With `--format plain`: demo property of the custom exporter example, available as `exporterProperties.string_property`. | | `--plain-bool-property ` | With `--format plain`: demo property of the custom exporter example, available as `exporterProperties.bool_property`. | ## 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 | Parameter | Description | | --- | --- | | `--max-size `
`--max-width `
`--max-height ` | Maximum size of the sheet in pixels: `--max-size` sets width and height at once, `--max-width` and `--max-height` set them separately. TexturePacker makes the sheet as small as possible within this limit. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#max-size)
**Default:** `2048`. | | `--multipack` | Creates as many sheets as needed when the sprites don't fit on one. A single sheet keeps its name, several become `name-0`, `name-1`, … Put `{n}` (starts at 0) or `{n1}` (starts at 1) into `--sheet` and `--data` to always number them. Formats like `phaser` write one data file for all sheets. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#automatic-multipack) | | `--algorithm ` | How sprites are placed. `MaxRects` packs tightest for rectangles, `Polygon` packs along the sprite outlines, `Basic` places sprites in rows (good for tile maps), `Grid` uses equal cells sized by the largest sprite. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#algorithm)
**Default:** `MaxRects` (`Polygon` for `unity-texture2d`). | | `--padding ` | Space in pixels between the sprites and around the sheet border. Sets `--shape-padding` and `--border-padding` at once. | | `--extrude ` | Repeats the sprite's edge pixels outward by this many pixels. Prevents flickering gaps between tiles and sprites when your game scales or moves them by fractions of a pixel. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#extrude)
**Default:** depends on `--format`. | | `--trim-mode ` | Removes transparent pixels around the sprites. `None` keeps them, `Trim` keeps the original sprite size in the data file, `Crop` and `CropKeepPos` use the trimmed size, `Polygon` traces the sprite outline. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#trim-mode)
**Default:** depends on `--format`. | | `--scale ` | Scales all sprites before packing: `0.5` packs them at half size. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#scale-factor)
**Default:** `1`. | ### 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 | Parameter | Description | | --- | --- | | `--width ` | Fixed width of the sheet in pixels. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#fixed-size) | | `--height ` | Fixed height of the sheet in pixels. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#fixed-size) | | `--size-constraints ` | Restricts the sheet size: `POT` = powers of 2 (256, 512, …), `MultipleOf4` = width and height divisible by 4, `CompressionBlocksize` = a multiple of the texture compression's block size, `WordAligned` = even width, `AnySize` = no restriction. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#size-constraints)
**Default:** depends on `--format`. | | `--force-squared` | Makes the sheet square. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#force-squared) | #### Packing | Parameter | Description | | --- | --- | | `--pack-mode ` | How hard TexturePacker tries to find the smallest sheet. `Fast` is quicker for large sprite sets while you work. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#pack-mode)
**Values:** `Fast`, `Good`, `Best`. **Default:** `Best`. | | `--maxrects-heuristics ` | Placement rule for the `MaxRects` algorithm. `Best` tries all and keeps the smallest result. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#maxrects-heuristics)
**Values:** `Best`, `ShortSideFit`, `LongSideFit`, `AreaFit`, `BottomLeft`, `ContactPoint`. **Default:** `Best`. | | `--basic-sort-by ` | Order in which the `Basic` algorithm places the sprites. `Best` tries all and keeps the smallest result. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#basic-sort-by)
**Values:** `Best`, `Name`, `Width`, `Height`, `Area`, `Circumference`. **Default:** `Best`. | | `--basic-order ` | Sort direction for `--basic-sort-by`. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#basic-order)
**Values:** `Ascending`, `Descending`. **Default:** `Ascending`. | | `--align-to-grid ` | `Polygon` algorithm only: places the top-left corner of each untrimmed sprite at pixel coordinates divisible by this value. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#align-to-grid) | | `--disable-rotation`
`--enable-rotation` | Forbids or allows rotating sprites by 90° to pack tighter. Your engine has to support rotated sprites; the format's default takes care of that. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#allow-rotation) | | `--common-divisor-x ` | Extends each sprite's width to a multiple of this many pixels, e.g. for tiles. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#common-divisor) | | `--common-divisor-y ` | Extends each sprite's height to a multiple of this many pixels. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#common-divisor) | | `--force-identical-layout` | Keeps the same layout in all `--variant` sheets. Might need `allowfraction` on some variants. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#force-identical-layout) | | `--disable-auto-alias` | Packs identical sprites separately. By default, TexturePacker packs them once and points all names at the same image. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#detect-identical-sprites) | #### Spacing and trimming | Parameter | Description | | --- | --- | | `--shape-padding ` | Space in pixels between the sprites only. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#shape-padding)
**Default:** depends on `--format`. | | `--border-padding ` | Space in pixels between the sprites and the sheet border only. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#border-padding)
**Default:** depends on `--format`. | | `--trim-threshold ` | Pixels with an alpha value below this threshold count as transparent when trimming. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#trim-threshold)
**Values:** `1` to `255`. **Default:** `1`. | | `--trim-margin ` | Transparent margin in pixels that stays around the sprite after trimming. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#trim-margin)
**Default:** `1`. | | `--tracer-tolerance ` | `Polygon` trim mode only: how far the polygon may deviate from the exact sprite outline. Lower values give more exact outlines with more vertices. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#tracer-tolerance)
**Default:** `200`. | | `--heuristic-mask` | For sprites without transparency: removes the pixels at the sprite border that share the same color, so a single-color background becomes transparent. | | `--default-pivot-point ,` | Pivot point written for all sprites, relative to the sprite size: `0,0` is the top-left corner, `0.5,0.5` the center.
**Values:** `0` to `1` each. | #### Scaling | Parameter | Description | | --- | --- | | `--variant ` | Adds a scaled copy of the sheet; use it several times for several resolutions. `` replaces `{v}` in the file names. With ``, only sprites whose name or folder path matches it go into the variant. `allowfraction` allows non-integer sizes with `--force-identical-layout`. `:` sets a maximum size for this variant. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#scalingvariants)
**Values:** `:[:[:allowfraction][::]]`. | | `--scale-mode ` | How sprites are resized. `Fast` uses nearest neighbor, which keeps pixel art crisp. `Scale2x` to `Hq2x` are fixed pixel-art upscalers. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#scale-mode)
**Values:** `Smooth`, `Fast`, `Scale2x`, `Scale3x`, `Scale4x`, `Eagle`, `Hq2x`. **Default:** `Smooth`. | ``` 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 | Parameter | Description | | --- | --- | | `--pixel-format ` | How the pixels are stored. Fewer bits per pixel mean smaller files and less GPU memory. The available formats depend on `--texture-format`; `TexturePacker --help` lists them all. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#pixel-format)
**Values:** e.g. `RGBA8888`, `RGBA4444`, `RGB565`, `ETC2_RGBA`, `ASTC_6x6`, `DXT5`. **Default:** `RGBA8888`. | | `--png-opt-level ` | PNG only, lossless: `0` always writes 32-bit PNGs, `1` writes 8-bit indexed PNGs when possible, `2` to `7` add more (and slower) optimization steps. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#png-opt-level)
**Default:** `1`. | | `--webp-quality ` | WebP only: quality of the lossy compression, from `0` (smallest) to `100` (best). Any value above `100` writes lossless WebP.
**Default:** lossless. | | `--jpg-quality ` | JPG only: from `0` (smallest) to `100` (best).
**Default:** `80`. | | `--pvr-quality ` | PVRTC pixel formats only: compression quality, from `0` (fastest) to `7` (best).
**Default:** `3`. | | `--astc-quality ` | ASTC pixel formats only: compression quality, from `0` (fastest) to `4` (best).
**Default:** `2`. | | `--basisu-quality ` | Basis Universal (`.basis`, `.ktx2`) only: compression quality, from `0` (fastest) to `4` (best).
**Default:** `2`. | | `--etc1-quality ` | ETC1 pixel formats only: compression quality, from `0` (fastest) to `100` (best).
**Default:** `70`. | | `--etc2-quality ` | ETC2 pixel formats only: compression quality, from `0` (fastest) to `100` (best).
**Default:** `70`. | The [Texture Compression](https://www.codeandweb.com/texturepacker/documentation/texture-compression.md) 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 | Parameter | Description | | --- | --- | | `--dxt-mode ` | DXT1 / DXT5 pixel formats only: how colors are weighted during compression.
**Values:** `linear`, `perceptual`. **Default:** `perceptual`. | | `--dither-type ` | Dithering hides color banding in reduced pixel formats like `RGBA4444`. `NearestNeighbour` and `Linear` don't dither; the `PngQuant` types are for `png8` only. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#dithering)
**Values:** `NearestNeighbour`, `Linear`, `FloydSteinberg`, `FloydSteinbergAlpha`, `Atkinson`, `AtkinsonAlpha`, `PngQuantLow`, `PngQuantMedium`, `PngQuantHigh`. **Default:** `NearestNeighbour`. | | `--alpha-handling ` | What happens to the color of transparent pixels. `ReduceBorderArtifacts` removes dark halos around sprites, `PremultiplyAlpha` is required by some engines, `DiscardAlpha` makes all pixels opaque. Pixel formats without alpha use `PremultiplyAlpha`. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#transparency-handling)
**Values:** `KeepTransparentPixels`, `ClearTransparentPixels`, `ReduceBorderArtifacts`, `PremultiplyAlpha`, `DiscardAlpha`. **Default:** `ClearTransparentPixels`. | | `--background-color ` | Fills the sheet background with a solid color, e.g. `ff0000` for red. | | `--flip-y` | Flips the texture vertically. Only works for hardware texture formats (`pvr`, `ktx`, `ktx2`, `zktx`, `astc`, `basis`, `dds`, `pkm`); needed e.g. by Phaser 4 and Unity. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#flip-y) | | `--dpi ` | Resolution stored in the image file. Games ignore it; it matters for print and design tools.
**Default:** `72`. | | `--content-protection ` | Encrypts `pvr.ccz` files with your 128-bit key (32 hex digits); Cocos2D only. [→ details](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#content-protection) | ## 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 | Parameter | Description | | --- | --- | | `--help` | Prints all options of the installed version, including the formats and exporter-specific options. | | `--activate-license ` | Activates TexturePacker with your license key. Floating licenses are deactivated automatically when TexturePacker exits. [→ details](https://www.codeandweb.com/texturepacker/documentation/docker-ci.md#using-activate-license) | | `--deactivate-license` | Deactivates the license on this machine, e.g. before you retire a build server. | | `--verbose` | Prints more details while packing. | ### 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](https://www.codeandweb.com/texturepacker/documentation/docker-ci.md). ``` 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 | Parameter | Description | | --- | --- | | `--version` | Prints the TexturePacker version. | | `--exporter-list` | Prints the names of all formats you can use with `--format`, one per line. | | `--quiet` | Prints nothing except errors. | | `--license-info` | Prints information about the installed license. | | `--custom-exporters-directory ` | Also loads your own exporters from this folder. See [Custom Exporters](https://www.codeandweb.com/texturepacker/documentation/custom-exporter.md). | | `--shape-debug` | Draws boxes around the sprite shapes in the sheet, for debugging. See [Shape outlines](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#shape-debug). | ## 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](#image-quality), 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](https://www.codeandweb.com/texturepacker/documentation/image-conversion.md) page explains usage and options, with examples. # 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 ` ## Data  ### Data Format `--format ` 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 ` 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: | Placeholder | Description | | --- | --- | | `{v}` | Scaling variant name | | `{n}` | Multipack index, starting with 0 | | `{n1}` | Multipack index, starting with 1 | 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: | Command line option | Description | | --- | --- | | `--class-file ` | Swift class output file (spritekit-swift) | | `--classfile-file ` | C# class output file (monogame) | | `--header-file ` | C++/ObjC header output file (cocos2d-x, spritekit, plain) | | `--source-file ` | C++ source output file (cocos2d-x) | | `--spriteids-file ` | Rust sprite id output file (amethyst) | ### 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** ### Enable cache busting `--enable-cache-busting` (only available if Data Format is **Pixi** or **Phaser**) Appends a hash-based query string (e.g. `?v=ab12cd34`) to the texture file name referenced in the data file. This forces browsers and CDNs to fetch the new texture after re-publishing the sprite sheet, instead of serving a stale cached version. Disabled by default. ### Texture path `--texturepath ` 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 ` Choose an image file format your framework supports. Depending on your choice, this enables additional features. | Format | Description | | :--- | :--- | | `png` | PNG (32bit). Lossless compression with full alpha support. Best for source assets and web. | | `png8` | PNG (8bit indexed). Smaller file size with up to 256 colors. Good for simple graphics. | | `jpg` | JPEG format. Lossy compression, no alpha support. Best for photographic content. | | `bmp` | Windows Bitmap. Uncompressed, large files. Useful for legacy compatibility. | | `tga` | Targa format. Supports alpha channel. Common in game development pipelines. | | `tiff` | Tagged Image File Format. Flexible format for high-quality images and print. | | `webp` | Modern web format. Supports both lossy and lossless compression with alpha. | | `pvr3` | PowerVR Texture Format (Version 3). Native format for iOS and PowerVR GPUs. | | `pvr3gz` | PowerVR Texture Format (Version 3), compressed with gzip. Smaller on disk, decompressed at load time. | | `pvr3ccz` | PowerVR Texture Format (Version 3), compressed with zlib, cocos2d header. | | `pkm` | ETC texture container. Simple format for ETC1/ETC2 compressed textures. | | `ktx` | Khronos Texture (Version 1). Standard container for OpenGL ES textures. | | `ktx2` | Khronos Texture (Version 2). Newer format with Basis Universal support. | | `zktx` | Khronos Texture (gzip compressed). KTX file compressed for smaller storage. | | `astc` | ASTC texture file. Direct container for ASTC compressed data. | | `basis` | Basis Universal compressed file. Transcodes to any GPU format at runtime. | | `dds` | DirectDraw Surface. Standard format for DirectX applications. | ### Texture file `--sheet ` 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: | Placeholder | Description | | --- | --- | | `{v}` | Scaling variant name | | `{n}` | Multipack index, starting with 0 | | `{n1}` | Multipack index, starting with 1 | ### Png Opt Level `--png-opt-level ` (only available if Texture format is **PNG**) Configure how much effort TexturePacker spends optimizing the PNG file size. All optimizations are lossless. | Value | Description | | --- | --- | | `0` | always write 32 bit png files | | `1` | write indexed (8 bit) png files if possible (default) | | `2` … `7` | activate additional file size optimization steps | 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: | Format | Option | Values (0: lowest quality, higher values: better quality) | | --- | --- | --- | | JPG | `--jpg-quality ` | 0 to 100 (default:80) | | WebP | `--webp-quality ` | 0 to 100 for lossy compression, >100 = lossless (default: lossless) | | PVRTC | `--pvr-quality ` | 0 to 7 (default: 3) | | ETC1 | `--etc1-quality ` | 0 to 100 (default: 70) | | ETC2 | `--etc2-quality ` | 0 to 100 (default: 70) | | ASTC | `--astc-quality ` | 0 to 4 (default: 2) | | BASIS | `--basisu-quality ` | 0 to 4 (default: 2) | | DXT1/5 | `--dxt-mode ` | `linear` or `perceptual` (quantization) | ### Pixel format `--pixel-format ` 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, but you can still choose a 16-bit pixel format for them. 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. See also the [Texture Compression](https://www.codeandweb.com/texturepacker/documentation/texture-compression.md) page for more information. | GUI/CMD value | Bits (RAM) | Description | Texture format | | --- | ---: | :--- | :--- | | `RGBA8888` | 32 | 32bit, 8bit/color, 8bit transparency | | | `RGBA4444` | 16 | 16bit, 4bit/color, 4bit transparency | | | `RGBA5551` | 16 | 16bit, 5bit/color, 1bit transparency | | | `RGBA5555` | 20 | 20bit, 5bit/color, 5bit transparency | | | `BGRA8888` | 32 | 32bit, 8bit/color, 8bit transparency | | | `RGB888` | 24 | 24bit, 8bit/color, no transparency | | | `RGB565` | 16 | 16bit, 5bit red, 6bit green, 5bit blue, no transparency | | | `ALPHA` | 8 | Grayscale image of the alpha channel (3x8bit), no transparency | | | `ALPHA_INTENSITY` | 16 | Grayscale image 3x8bit, 8bit transparency | | | `PVRTCI_2BPP_RGBA` | 2 | PVRTC compression, 2bit per pixel | PVR, KTX, ZKTX, KTX2 | | `PVRTCI_4BPP_RGBA` | 4 | PVRTC compression, 4bit per pixel | PVR, KTX, ZKTX, KTX2 | | `PVRTCI_2BPP_RGB` | 2 | PVRTC compression, 2bit per pixel, no transparency | PVR, KTX, ZKTX, KTX2 | | `PVRTCI_4BPP_RGB` | 4 | PVRTC compression, 4bit per pixel, no transparency | PVR, KTX, ZKTX, KTX2 | | `PVRTCII_2BPP` | 2 | PVRTC2 compression, 2bit per pixel | PVR, KTX, ZKTX, KTX2 | | `PVRTCII_4BPP` | 4 | PVRTC2 compression, 4bit per pixel | PVR, KTX, ZKTX, KTX2 | | `ETC1_RGB` | 4 | ETC1 compression, no alpha channel | PVR, KTX, ZKTX, KTX2, PKM | | `ETC1_A` | 4 | ETC1 compression, alpha channel only | PVR, KTX, ZKTX, KTX2, PKM | | `ETC2_RGB` | 4 | ETC2 compression, no alpha | PVR, KTX, ZKTX, KTX2, PKM | | `ETC2_RGBA` | 8 | ETC2 compression, color+alpha | PVR, KTX, ZKTX, KTX2, PKM | | `DXT1` | 4 | Compressed with DXT1, 1 bit transparency | PVR, KTX, ZKTX, KTX2, DDS | | `DXT5` | 8 | Compressed with DXT5, transparency | PVR, KTX, ZKTX, KTX2, DDS | | `ASTC_4x4` | 8.00 | Compressed with ASTC 4x4 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_5x4` | 6.40 | Compressed with ASTC 5x4 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_5x5` | 5.12 | Compressed with ASTC 5x5 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_6x5` | 4.27 | Compressed with ASTC 6x5 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_6x6` | 3.56 | Compressed with ASTC 6x6 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_8x5` | 3.20 | Compressed with ASTC 8x5 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_8x6` | 2.67 | Compressed with ASTC 8x6 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_8x8` | 2.00 | Compressed with ASTC 8x8 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_10x5` | 2.56 | Compressed with ASTC 10x5 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_10x6` | 2.13 | Compressed with ASTC 10x6 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_10x8` | 1.60 | Compressed with ASTC 10x8 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_10x10` | 1.28 | Compressed with ASTC 10x10 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_12x10` | 1.07 | Compressed with ASTC 12x10 | PVR, KTX, ZKTX, KTX2, ASTC | | `ASTC_12x12` | 0.89 | Compressed with ASTC 12x12 | PVR, KTX, ZKTX, KTX2, ASTC | | `BASISU_ETC1S` | 0.3 - 1.25 | Compressed with BasisUniversal ETC1S | PVR, KTX2, BASIS | | `BASISU_UASTC` | 4 - 8 | Compressed with BasisUniversal UASTC | PVR, KTX2, BASIS | For PVRTC, ETC, DXT, ASTC, BASISU pixel formats there is no real-time preview available. ### Dithering `--dither-type ` 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. | GUI/CMD value | Description | | --- | --- | | `NearestNeighbour` | Has the least color error but color distribution leads to less contrast than Linear. | | `Linear` | Creates a linear color distribution with some color error but better contrast than NearestNeighbour. | | `FloydSteinberg` | Uses Floyd-Steinberg dithering algorithm. | | `FloydSteinbergAlpha` | Uses Floyd-Steinberg dithering algorithm with alpha values. | | `Atkinson` | Uses Atkinson dithering algorithm. | | `AtkinsonAlpha` | Uses Atkinson dithering algorithm with alpha values. | | `PngQuantLow` | PNG-8 only: minimum dithering. | | `PngQuantMedium` | PNG-8 only: medium dithering. | | `PngQuantHigh` | PNG-8 only: strong dithering. | ### Transparency Handling `--alpha-handling ` Defines how color values of transparent pixels are processed: | GUI/CMD value | Description | | --- | --- | | `KeepTransparentPixels` | Transparent pixels are copied from sprite to sheet without any change. | | `ClearTransparentPixels` | Color values of transparent pixels are set to 0 (transparent black) to improve image packing ratio and identical sprite detection. | | `ReduceBorderArtifacts` | Transparent 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". | | `PremultiplyAlpha` | All color values are multiplied with the alpha values. This is required by some frameworks for faster rendering of the textures. | | `DiscardAlpha` | Sets the alpha channel to 255 (fully opaque); color channels are preserved. | ### Flip texture vertically `--flip-y` (only available for hardware texture formats: **pvr**, **ktx**, **ktx2**, **zktx**, **astc**, **basis**, **dds** and **pkm**) Flips the texture vertically. Required by Phaser 4, Unity (with PVR textures) and other frameworks which address textures from the bottom-left corner. Plain image formats such as PNG or JPG are never flipped. `--flip-pvr` (TexturePacker 8.2.1 and older) is still accepted as a deprecated alias for `--flip-y`. ### Content Protection `--content-protection ` 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](https://www.codeandweb.com/texturepacker/tutorials/texturepacker-content-protection.md) ## Layout  ### Max Size `--max-width ` `--max-height ` Sets the maximum width/height for the texture, default is 2048. `--max-size ` sets the value for width and height at once. ### Fixed Size `--width ` `--height ` Sets a fixed value for the size. Leave the fields empty to let TexturePacker determine the size. ### Size Constraints: `--size-constraints ` Forces the output texture to match specific size constraints. This is often necessary due to hardware or game engine limitations. For example, if you export sprite sheets as PNG files and your game engine (e.g. Unity or Unreal Engine) applies external compression, it may require textures to have power-of-two sizes or dimensions that are multiples of 4. When using compression formats such as **ASTC**, **PVRTC**, or **ETC1/ETC2** within TexturePacker, you typically do **not** need to set this option — TexturePacker automatically ensures the sprite sheet dimensions meet the required format constraints. | Value | Description | | --- | --- | | `POT` | Forces the texture to have a power-of-two size (e.g., 2, 4, 8, 16, 32, 64, 128, 256, ...). | | `MultipleOf4` | Forces the texture to have dimensions that are multiples of 4 (e.g., 4, 8, 12, 16, 20, ...). | | `WordAligned` | Ensures that each row in the texture uses complete memory words. For 16-bit formats, this aligns the width to a multiple of 2, which may add 1 pixel of padding. | | `CompressionBlocksize` | Makes width and height multiples of the compression block size of the pixel format (e.g., 4 for DXT and ETC). | | `AnySize` | Allows the texture to use any size. TexturePacker selects the smallest possible dimensions.
Use the `--pack-mode` option to influence how the optimal size is determined. | ### Force squared `--force-squared` Forces the texture to have a squared size. ### Scaling variants `--variant :[:[:allowfraction][::]]` 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 high-resolution (Retina) displays and you also want a half-size version for standard displays. 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: | Variant name | Scale | | --- | --- | | _@2x_ | 1.0 | | (leave empty) | 0.5 | After adding sprites and clicking **Publish sprite sheet** the following files are generated: | Texture file | Data file | | --- | --- | | _[sheet@2x.png](mailto:sheet@2x.png)_ | _[sheet@2x.plist](mailto:sheet@2x.plist)_ | | _sheet.png_ | _sheet.plist_ | If scaling variants are combined with the multipack feature, the file names must contain both placeholders, for details see [multipack configuration](#multipack-with-scalingvariants). ### Scale `--scale ` 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](#scalingvariants) feature. ### Scale mode `--scale-mode ` With this parameter you can select the algorithm which is used for scaling the sprites. | GUI/CMD value | Description | | --- | --- | | `Smooth` | Scaling by blending pixels: works best for scaling down, but it may result in a blurry output when scaling up. | | `Fast` | Nearest neighbor scaling - OK for scaling down. Gives pixelated images when scaling up. | | `Scale2x` | Fixed size up-scaling by factor of 2. Tries to optimize edges of pixel art. | | `Scale3x` | Fixed size up-scaling by factor of 3. Tries to optimize edges of pixel art. | | `Scale4x` | Fixed size up-scaling by factor of 4. Tries to optimize edges of pixel art. | | `Eagle` | Fixed size up-scaling by factor of 2. Tries to optimize edges of pixel art. | | `Hq2x` | Fixed size up-scaling by factor of 2. Tries to optimize edges of pixel art. | ### Algorithm `--algorithm ` TexturePacker provides four packing algorithms: | GUI/CMD value | Description | | --- | --- | | `Polygon` | The 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. | | `MaxRects` | Currently the best packing algorithm for rectangles. Tries to use the least texture space by applying different heuristics when placing the sprites. | | `Grid` | Places sprites on regular grid, the largest sprite determines the cell size. | | `Basic` | Simple layout by filling sprites from left to right until the maximum width of the texture is reached. Good for fixed-size sprites. | ### Sort by `--basic-sort-by ` (only available if Algorithm is **Basic**) Sorts sprites before placing them into the sprite sheet. | GUI/CMD value | Description | | --- | --- | | `Best` | Tests all sorting variants and uses the result with the least used space | | `Name` | Sorts sprites by name | | `Width` | Sorts sprites by width | | `Height` | Sorts sprites by height | | `Area` | Sorts sprites by their area (width\*height) | | `Circumference` | Sorts sprites by their circumference (width+height) | ### Order `--basic-order ` (only available if Algorithm is **Basic**) | GUI/CMD value | Description | | --- | --- | | `Ascending` | Sorts values from small to large | | `Descending` | Sorts values from large to small | ### Heuristics `--maxrects-heuristics ` (only available if Algorithm is **MaxRects**) Heuristics is used to place the sprites in the texture. | GUI/CMD value | Description | | --- | --- | | `Best` | Tests all available placements and uses the result with the least used space | | `ShortSideFit` | Short Side Fit | | `LongSideFit` | Long Side Fit | | `AreaFit` | Area Fit | | `BottomLeft` | Bottom Left | | `ContactPoint` | Contact Point | ### Pack `--pack-mode ` Controls how much time TexturePacker uses to find the minimum texture size. | GUI/CMD value | Description | | --- | --- | | `Fast` | Search for the minimum fitting power-of-2 size. | | `Good` | Searches for the minimum size but aborts after some time. | | `Best` | Searches intensively for the minimum size. Might take some time... | ### Align to grid `--align-to-grid ` 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: | Tag | Description | Example | Output | | --- | --- | --- | --- | | `{n}` | number, starting with 0 | `sheet{n}.png` | `sheet0.png`, `sheet1.png`, ... | | `{n1}` | number, starting with 1 | `sheet{n1}.png` | `sheet1.png`, `sheet2.png`, ... | #### 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](https://www.codeandweb.com/texturepacker/documentation/user-interface-overview.md#manual-multipack). 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: | Texture file | Data file | | --- | --- | | _[sheet1@2x.png](mailto:sheet1@2x.png)_ | _[sheet1@2x.plist](mailto:sheet1@2x.plist)_ | | _sheet1.png_ | _sheet1.plist_ | | _[sheet2@2x.png](mailto:sheet2@2x.png)_ | _[sheet2@2x.plist](mailto:sheet2@2x.plist)_ | | _sheet2.png_ | _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` 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 ` 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 Value | CMD value | Description | | --- | --- | --- | | None | `None` | Keep the sprites as they are. Do not remove transparent pixels. | | Trim | `Trim` | Removes the transparency around a sprite, but the sprite appears to have its original size when using it. The anchor point used for sprite placement does not change. This option might not be available in all frameworks. | | Crop, keep position | `CropKeepPos` | Removes the transparency around a sprite, resulting in a smaller size when using it. The position in the original sprite is preserved, meaning its anchor point used for sprite placement remains unchanged. This option might not be available in all frameworks. | | Crop, flush position | `Crop` | Removes the transparency around a sprite, resulting in a smaller size when using it. The position in the original sprite is set to 0/0, i.e. sprite placement changes depending on the amount of removed transparent border. The sprite appears in the sheet as if it never had any transparency. | | Polygon outline | `Polygon` | Approximates 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 ` Transparent margin which is left over after trimming. ### Transparency threshold `--trim-threshold ` 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 ` (only available if trim mode is **Polygon outline**) 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). Set up some performance tests to find the best value for your sprites and target platform! ### Extrude `--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 tile-maps this allows you to see if there are semi-transparent pixels at the borders of the tiles. ### Border padding `--border-padding `  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 `  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. Command line only: `--padding ` Combination of `--shape-padding` and `--border-padding` , value in pixels ### Common divisor `--common-divisor-x / --common-divisor-y ` 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 placeholders **{n}** and **{v}**. If you leave this file name empty, TexturePacker automatically uses the sprite sheet file name with additional suffix **\_n**. # Texture compression The chosen texture compression determines: * how much space the texture consumes on disk * how much memory it occupies on the GPU ## Texture and Pixel Formats In TexturePacker, it is important to distinguish between **Texture Format** and **Pixel Format**: * **Texture Format**: Configures the image file container (e.g., `.pvr`, `.ktx`, `.png`). It determines the file structure and extension. * **Pixel Format**: Configures the internal encoding of the pixel data (e.g., `ETC2`, `ASTC`, `RGBA8888`). In TexturePacker, you first select the [Texture Format](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#texture-format) (the container file type, e.g., KTX), and then the [Pixel Format](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#pixel-format) (the specific compression, e.g., ASTC). TexturePacker only displays pixel formats that are compatible with the selected Texture Format. ## Hardware vs. Software Compression The main difference between software and hardware compression lies in where the data is decompressed and how much memory it occupies on the GPU. ### Software Compression (e.g., PNG, JPG, WebP) * **Disk Space**: These formats are excellent for reducing file sizes for storage or download. * **GPU Processing**: They cannot be used directly by the GPU. The engine must decompress them into a raw format (like RGBA8888) in system memory before uploading them to the GPU. * **Memory Usage**: Once loaded, they take up the full amount of memory required for an uncompressed texture (e.g., 4 bytes per pixel for RGBA8888). ### Hardware Compression (e.g., ASTC, ETC2, PVRTC) * **Disk Space**: These formats often have larger file sizes than highly optimized PNGs or JPEGs. * **GPU Processing**: They are designed to be read directly by the GPU hardware in their compressed state. * **Memory Usage**: They remain compressed in GPU memory, typically using only a fraction of the memory (e.g., 1 byte per pixel or less). This reduces memory pressure and increases rendering performance due to lower bandwidth requirements (the amount of data transferred between memory and the GPU). ## Supported Hardware Compressions The table below provides an overview of the compression ratios and hardware-specific requirements for each format. **bpp** (bits per pixel) indicates how much memory each pixel requires: lower values mean better compression. | Compression | bpp | Hardware Restrictions / Notes | | :--- | :--- | :--- | | [ASTC](https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression) | 0.89 - 8.00 | Flexible block sizes (4x4 to 12x12). Supported on modern mobile (iOS, Android) and desktop GPUs. | | [ETC1](https://en.wikipedia.org/wiki/Ericsson_Texture_Compression) | 4 | No alpha channel. Standard for older Android devices. | | [ETC2](https://en.wikipedia.org/wiki/Ericsson_Texture_Compression) | 4 - 8 | Supports alpha (8 bpp). Standard for OpenGL ES 3.0 compatible devices. | | [PVRTC I](https://en.wikipedia.org/wiki/PVRTC) | 2 - 4 | Requires power-of-two (POT) textures (e.g., 512x512, 1024x2048), some platforms might require squared textures ([details](https://powervr-graphics.github.io/WebGL_SDK/WebGL_SDK/Documentation/Architecture%20Guides/PowerVR.Supported%20Extensions.OpenGL%20ES.EGL.pdf)). Legacy iOS format; use ASTC on current devices. | | [PVRTC II](https://en.wikipedia.org/wiki/PVRTC) | 2 - 4 | Improved quality over PVRTC I. Does not require square or POT textures. Only supported by some PowerVR GPUs, not by Apple devices. | | [DXT1 / BC1](https://en.wikipedia.org/wiki/S3_Texture_Compression) | 4 | No alpha or 1-bit transparency. Standard for desktop (DirectX). | | [DXT5 / BC3](https://en.wikipedia.org/wiki/S3_Texture_Compression) | 8 | Supports full alpha channel. Standard for desktop (DirectX). | | [Basis Universal (ETC1S mode)](https://github.com/BinomialLLC/basis_universal?tab=readme-ov-file#supported-texture-compression-modes) | 0.3 - 1.25 | Medium quality, fast transcoding to many other formats (ETC1, etc.). Highly compressed on disk. | | [Basis Universal (UASTC mode)](https://github.com/BinomialLLC/basis_universal/wiki/UASTC-LDR-4x4-Texture-Specification) | 4 - 8 | High quality, fast and simple transcoding to ASTC and BC7. Highly compressed on disk. | ## Supported Texture Formats Here's a list of Texture Formats (containers) TexturePacker supports, and the Hardware Compression algorithms (Pixel Formats) they can be compressed to. | Texture Format | File Extension | Supported Hardware Compression (Pixel Formats) | | :--- | :--- | :--- | | PVR | `.pvr` | PVRTC I+II, ETC1+2, DXT1+5, ASTC, Basis Universal (ETC1S+UASTC) | | KTX | `.ktx` | PVRTC I+II, ETC1+2, DXT1+5, ASTC | | ZKTX | `.ktx` | PVRTC I+II, ETC1+2, DXT1+5, ASTC (file zipped on disk) | | KTX2 | `.ktx2` | PVRTC I+II, ETC1+2, DXT1+5, ASTC, Basis Universal (ETC1S+UASTC) | | PKM | `.pkm` | ETC1, ETC2 | | DDS | `.dds` | DXT1, DXT5 | | ASTC | `.astc` | ASTC | | BASIS | `.basis` | Basis Universal (ETC1S & UASTC) | Other texture formats (like PNG, JPG, WebP, ...) are also supported by TexturePacker, but they cannot store hardware-compressed textures. **Note:** Support for Adobe Texture Format (`.atf`) was [removed](https://www.codeandweb.com/texturepacker/knowledgebase/atf-image-format.md) in TexturePacker version 6.0.2. # Automated Sprite Sheet Cutter  ## Why use a sprite sheet cutter? When you buy sprite sheets from an asset store or game-art provider, they’re often not organized in the way you need them in your game: * The sheet contains animations or items you don’t plan to use. * There's a lot of empty space around the sprites. * You want to merge selected animations or elements with assets from other sources. To build your own sprite sheets, you have to * split the original sheet into sprites * repack the sprite sheet for your game TexturePacker can handle both tasks for you. ## Overview Use TexturePacker's automated sprite sheet cutter to cut your sprite sheets into individual sprites. The sprite sheet cutter detects the following types of sprite sheets: * grid and strip (all sprites have the same size) * rectangle (sprites have different sizes, e.g. packed with TexturePacker's MaxRects algorithm) * file (by providing a data file such as `json`, `tpsheet`, `plist`, `atlas`) It automatically configures the slicing parameters based on gaps between sprites. This makes it a one-click solution for most sprite sheets. You can save all sprites - or only a selection. Sprites are automatically numbered so that you can extract animations and re-build them later. The whole process runs comfortably on your computer - no upload of your assets to dubious servers. ## Starting the Sprite Sheet Cutter & Adding Sprite Sheets  1. Click the **Split sheet** button in TexturePacker's toolbar 2. Drag and drop a sprite sheet onto the center view 3. Save the sprites The splitter now detects the layout of the sprites. This works well if your sprites have some space in between. For sheets without transparency, see [Cutting Sprite Sheets with a solid background color](#cutting-sprite-sheets-with-a-solid-background-color). If the detection does not work automatically, or does not slice the sprites as you wanted, use the parameters to adjust the splitter settings. ## Cutting Sprite Sheets with Different Layouts ### Cutting Grid/Strip-Based Sprite Sheets  For example, if your sprites are arranged in a clean grid or strip, they should be sliced automatically. Sometimes, if sprites are too close to each other, manual adjustment might be required. You can use the following settings: | Parameter | Description | | --- | --- | | **Columns** & **Rows** | Count the sprites in each column and row and set these parameters. Sprite size is updated automatically according to these settings. | | **Sprite Width** & **Sprite Height** | If you know the size of the sprites, use these settings. | | **Shape Padding** | Adjust this to the size of the gap between sprites. | | **Border Padding** | Adjust this to the size of the space from sprite to border. | ### Cutting Tile Sheets The tile size might not be detected automatically by the sprite sheet slicing tool. If this is the case, switch to the **Grid** mode. You can either set the number of **columns** and **rows** - or set the tile size using the **Sprite Width** and **Sprite Height** settings. Adjust the **Shape Padding** and **Border Padding** if your individual tiles are surrounded by transparency or repeating pixels. ### Cutting Irregular Sprite Sheets The sprite sheet splitter automatically switches to rectangular mode if no clear grid layout is detected. In this mode, it tries to find rectangles that cover a sprite completely. If you know that the sprites were packed with transparency in between, you can increase the **Padding** value. This allows the cutter to combine, for example, smaller particles into a bigger sprite.  ### Cutting Sprite Sheets with a solid background color For sheets without transparent pixels, **Remove solid background** is on by default. The cutter takes the background color from the corners of the sheet and removes it from the preview and the saved sprites (for image formats with transparency). Rectangular mode can then find the sprites, and grid mode skips empty cells. If the corners don't agree on one color, the option is disabled and nothing is removed. Use grid or data file mode for such sheets. Turn the option off to keep the background, for example for a sheet of solid tiles. ### Splitting with a Data File TexturePacker creates sprite sheets with optimized layouts. For this, it writes data files for many game engines. The data files contain information about a sprite's name, size and position on the sprite sheet. If you have such a file (some asset designers provide them), you can simplify the cutting process dramatically. If TexturePacker finds a sprite sheet data file with the same name as the texture file (e.g. `atlas.png`, `atlas.plist`) for one of the following game engines, it automatically splits the sprite sheets and assigns names to the sprites: | Framework | File format (extension) | | --- | --- | | Cocos2d / Cocos Creator | `plist` | | Godot | `tpsheet` | | Phaser | `json` | | LibGDX | `atlas` | | PixiJS | `json` | | Spine | `atlas` | | Unity | `tpsheet` | ## Naming & exporting Sprites Set the **Output directory** where you want to save your sprites. By default, a folder is created with the same name as the sprite sheet, but without the file extension. In the center view, select the sprites you want to export: * Use `CTRL` (Windows) or `CMD` (macOS) with the left mouse button to add or remove sprites from the selection. * Press and drag the mouse to use a rubber band selection. Set the **Sprite name template** for the sprites you want to export. The name can consist of all characters allowed in regular file names, including `/` to create subfolders. Use the following placeholders to add numbers to your sprite names, which is useful for naming animation phases: * `{n}` to add a number starting with 0. * `{n1}` to add a number starting with 1. For example, using `betty/run-{n1}.png` creates a folder named _betty_ inside the output directory. The sprites will be named _run-1.png_, _run-2.png_, and so on. Sprite numbers are automatically assigned from the top left to bottom right. Finally, press **Save selected sprites** (or **Save sprites**). If you have multiple animations or different sprites, repeat the process of selecting, setting the name, and saving. ## Repacking & Converting Sprite Sheets ### Why Should You Repack a Sprite Sheet? There are several reasons: * You have multiple sprite sheets you want to combine into a single one. * Your sprite sheets are inefficiently packed, containing a lot of transparency. * You want to create a scaled-down version for different platforms. * You want to reduce the file size. * You want to port them from one game engine to another. ### How to Repack an Existing Sprite Sheet Use the sprite sheet cutter to extract the sprites from the sheet. Organize them in a folder structure that fits your project's needs. E.g. by grouping animation phases or objects in a subfolder. Create a new project in TexturePacker and add your top-level sprite folder. Then select your game engine for the export and publish the new sprite sheet. ### Extracting Animations from a Sprite Sheet Animations in a grid / strip layout are easy to handle. They contain transparency for proper alignment. This means they should work out of the box. It's also no problem if you are using a data file with the sprite sheet. All information is already contained and makes the cutting really easy. In a rectangle-packed sheet, transparency around the sprites might have been trimmed (removed). Manual work is required here to properly re-align the animation frames. If the game engine you are creating the new sprite sheet for supports pivot points, it's also really easy to handle animations in TexturePacker. After adding the sprites, switch to the **Sprite settings** panel and use the pivot point tool to align the animations. Use the animation preview window to adjust the alignment in real-time. # Image Conversion TexturePacker's command line client can convert single images between different texture formats using the `--convert-texture` mode. Unlike the default sprite-sheet packing mode, this mode operates on one input image and re-encodes it to a different format. This is useful when you need to: * Convert textures to GPU-compressed formats like ASTC, DXT, or PVRTC for mobile games * Transcode images to Basis Universal for universal GPU compatibility * Batch-convert assets in your build pipeline * Resize or optimize images without creating sprite sheets ## Usage ```bash TexturePacker --convert-texture [

] [options] TexturePacker --convert-texture --texture-format [options] ``` You can either provide an output filename (the format is derived from the extension) or specify `--texture-format` explicitly. If only `--texture-format` is given, the output filename is derived from the input file (same base name, new extension). ## Options With the following options, you can configure how the input texture is pre-processed and encoded. ### File format and image compression | Option | Description | Documentation | | :--- | :--- | :--- | | `--texture-format` | Target file format (png, jpg, dds, pvr3, astc, etc.) | [Texture Format](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#texture-format) | | `--pixel-format` | Pixel encoding (RGBA8888, DXT5, ASTC\_6x6, PVRTCII\_4BPP, etc.) | [Pixel Format](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#pixel-format) | | `--background-color ` | Background color (hex) to replace transparency in formats without alpha channel | | | `--png-opt-level` | PNG compression effort (PNG only, lossless) | [Png Opt Level](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#png-opt-level) | | `---quality`
`--dxt-mode` | Format-specific compression quality settings | [Image Quality](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#image-quality) | | `--dither-type` | Dithering algorithm (FloydSteinberg, Atkinson, NearestNeighbour, etc.) | [Dithering](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#dithering) | ### Size and Scale | Option | Description | | :--- | :--- | | `--size-constraints ` | Set size constraint ([Supported modes](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#size-constraints)) | | `--force-squared` | Enlarge shorter side to match longer side | | `--scale ` | Scale factor (0.01 to 10.0) | | `--scale-mode ` | Interpolation mode for scaling ([Scale modes](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#scale-mode)) | | `--flip-y` | Flip texture vertically ([hardware texture formats only](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#flip-y)) | | `--dpi ` | Set DPI metadata value (PNG only) | ### Transparency and Trimming | Option | Description | | :--- | :--- | | `--trim` | Remove transparent edges | | `--trim-margin ` | Transparent border kept after trimming | | `--trim-threshold <1-255>` | Alpha cutoff for trimming (alpha values < threshold are treated as transparency) | | `--heuristic-mask` | Replace solid background color with transparency | | `--alpha-handling ` | How to modify color values of transparent pixels ([values](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#transparency-handling)) | | `--padding ` | Add transparent border around texture edges | ## Examples ### Basic Conversion Convert a PNG to KTX format: ```bash TexturePacker --convert-texture sprite.png sprite.ktx ``` ### Specifying Pixel Format Convert to KTX with a specific ASTC block size: ```bash TexturePacker --convert-texture sprite.png sprite.ktx --pixel-format ASTC_6x6 ``` ### Using Texture Format Flag Convert to Basis Universal with high quality (output name derived automatically as `sprite.basis`): ```bash TexturePacker --convert-texture sprite.png --texture-format basis --basisu-quality 3 ``` ### Combining Options Convert to PVR with trimming and scaling: ```bash TexturePacker --convert-texture diffuse.png diffuse.pvr \ --pixel-format PVRTCII_2BPP --pvr-quality 5 \ --trim --scale 0.5 ``` ## See Also * [Texture Compression](https://www.codeandweb.com/texturepacker/documentation/texture-compression.md) - Overview of GPU texture compression formats * [Command line](https://www.codeandweb.com/texturepacker/documentation/commandline.md) - How to use TexturePacker's command line tool # TexturePacker's custom exporter format > Custom Exporters have saved me dozens of hours. I can't function without TexturePacker. Richard Jarell TexturePacker comes with many different data output formats - both generic formats like JSON and XML, as well as platform-specific formats like Cocos2D, Sparrow, and others. However, sometimes these built-in formats aren't sufficient - either because your game framework requires its own specific format, or because the existing formats don't meet your particular needs. The solution is to create your own custom format. This process is easier than you might think - just follow the instructions below to get started. ## Where to start ### Modifying an existing exporter Many of the exporters are available in the TexturePacker folder: * Windows users look under **C:/Program Files/CodeAndWeb/TexturePacker/resources/exporters** * Mac users go to **/Applications/TexturePacker.app/Contents/Resources/exporters** The **plain** exporter may be a good starting point. Make sure to duplicate the exporter folder to somewhere outside TexturePacker's installation path and rename the folder and the exporter contents as shown below! ### Creating a new exporter from scratch That's of course possible too... but modifying an existing exporter is the recommended way. ## Preparations before creating your own exporter First, 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.  ## Structure of an exporter An exporter consists of 2 or more files: * **exporter.xml** - the file describing the capabilities of the exporter * **a template file** - the template for the output file format; it can have any name (e.g. _testexporter.txt_), _exporter.xml_ refers to it Optional: * **filter.qs** - one (or more) file(s) to extend the template file with JavaScript ## The exporter description file Create an _exporter.xml_ inside your _testexporter_ directory, or use an _exporter.xml_ of an existing exporter as starting point Here's an example file, containing descriptions for all supported elements: ```xml testexporter otherexporter TestExporter My first custom exporter for TexturePacker 1.0 mydata MyDataFile txt My txt custom exporter for TexturePacker false all true true true cw true true false true true true true true true false TopLeft 1 false 0 1 1 Polygon Polygon POT true 0.0,0.0 HD / SD 1.0 -2x 0.5 true sprite-prefix string img_ Sprite prefix Prefix for the sprite's name. true ``` ## The template file The template file contains a prototype of the data file to write with some additional markup to format the text, build loops and decisions. If you copied the data from the example file above, you should now create a **testexporter.txt** in the same directory as the **exporter.xml**. The file extension of the template file does not matter. However, it might be useful to give it the same extension as the Data file to enable syntax highlighting in your favorite text editor. TexturePacker uses the Grantlee template engine - which is similar to Django templates. The template syntax is described in detail at the end of this document. This example template file will write a data file containing a list of sprites with frame coordinates, a flag for rotation and the source coordinates: ```django // Created with TexturePacker (https://www.codeandweb.com/texturepacker) // // Sprite sheet: {{ texture.fullName }} ({{ texture.size.width }} x {{ texture.size.height }}) // // {{ smartUpdateKey }} sprites = [ {% for sprite in allSprites %} {{ sprite.trimmedName }} = [ frame = [ {{ sprite.frameRect.x }}, {{ sprite.frameRect.y }}, {{ sprite.frameRect.width }}, {{ sprite.frameRect.height }} ], rotated = {{ sprite.rotated }}, source = [ {{ sprite.cornerOffset.x }}, {{ sprite.cornerOffset.y }}, {{ sprite.untrimmedSize.width }}, {{ sprite.untrimmedSize.height }} ] ] {% if not forloop.last %}, {% endif %} {% endfor %} ] ``` ### Using Values in Templates Values in templates are enclosed within double curly braces: `{{ variable }}`. To access nested properties within a structure, use the dot notation: `{{ object.property }}`. You can apply filters to format values by using the pipe character. For example: * `{{ x|floatformat:3 }}` formats a floating point value with 3 decimal places * `{{ text|upper }}` converts text to uppercase * `{{ list|join:", " }}` joins list items with commas ### Control Structures Templates support several control structures that affect the rendering flow: #### Conditionals ``` {% if condition %} Content to render when condition is true {% else %} Content to render when condition is false {% endif %} ``` #### Loops ``` {% for item in itemList %} Content to render for each item Current item: {{ item }} {% endfor %} ``` ## Values and data types The variables that can be used in the template file are described in detail in the table below: | Element | Type | Info | | --- | --- | --- | | `smartUpdateKey` | STRING | hash string over all file dates, used to speed up export | | `dataAbsoluteFileName` | STRING | absolute file name of the current data file | | `settings` | [SETTINGS](#settings-type) | contains tps file settings | | `variantIndex` | INT | `0` for hasSeparateAutoSDFiles=first
`variantCount-1` for hasSeparateAutoSDFiles=last
`[0..variantCount-1]` for hasSeparateAutoSDFiles=all | | `multiPackIndex` | INT | `-1` for hasSeparateMultiPackFiles=false
`[0..textureCount-1]` for multipack textures | | `variantParams` | [VARIANTPARAMS](#variantparams-type) | settings adapted for the current scaling variant | | `allResults` | [RESULT\[\]](#result-type) | | | `texture` | [TEXTURE](#texture-type) | current texture (only available if hasSeparateMultiPackFiles=true) | | `sprites` | [SPRITE\[\]](#sprite-type) | sprites (without aliases) of the current texture (or of complete result, if hasSeparateMultiPackFiles=false) | | `allSprites` | [SPRITE\[\]](#sprite-type) | sprites (including aliases) of the current texture (or of complete result, if hasSeparateMultiPackFiles=false) | | `exporterProperties.MYPROP` | STRING or BOOL | Contains the value of the custom exporter property `MYPROP` . Exporter properties can be defined in the [exporter description file](#exporter-description), using the `` element. | | `tp` | HASH | Contains all elements described above. If you want to write your exporter in Javascript you can use this hash to pass all settings to a Javascript function. | The template file is loaded with a set of parameters created during the packing process. The values can be referenced using the template language. ### smartUpdateKey When publishing a spritesheet, TexturePacker checks if the _Data file_ already exists. If the file is found, its contents are read, and a text sequence is searched for - `$TexturePacker:SmartUpdate:....hashvalue....$`. This value is a hash calculated from all file dates, sizes, and the parameters used to create the texture. If the calculated hash is identical to the current state of the files, no output is created, which speeds up batch operations. To use this smart update feature, add `smartUpdateKey` somewhere in the template file. Ensure that the value is placed within a comment or another suitable location to avoid confusing the module reading the data. ### sprites and allSprites The `sprites` list contains unique sprites only, excluding alias sprites (sprites that contain the same image). To reference alias sprites, you can access a sprite's `.aliasList` property. On the other hand, `allSprites` contains a list of all sprites, including alias sprites. In most cases, using `allSprites` is more convenient than `sprites`. The standard way to iterate over the sprites is using ```django {% for sprite in allSprites %} ... {% endfor %} ``` ### SETTINGS This data type holds .tps file settings. | Element | Type | Info | | --- | --- | --- | | `autoSDSettings[0..variantCount-1]` | [AUTOSDSETTINGS\[\]](#autosdsettings-type) | Scaling variant settings | | `ditherType` | `NearestNeighbour`
`Linear`
`FloydSteinberg`
`FloydSteinbergAlpha`
`Atkinson`
`AtkinsonAlpha`
`PngQuantLow`
`PngQuantMedium`
`PngQuantHigh` | for more info see [Dithering](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#dithering) | | `textureFormat` | STRING | texture format | | `outputFormat` | STRING | output format | | `contentProtection.key` | STRING | 32 hex digits | | `tpsName` | STRING | name of the tps file | | `enableCacheBusting` | BOOL | cache busting enabled | | `allowRotation` | BOOL | rotation enabled | | `flipY` | BOOL | flip texture vertically (`flipPVR` is kept as a deprecated alias) | | `forceIdenticalLayout` | BOOL | force layout to be identical for all variants | | `multiPack` | BOOL | multipack enabled | | `trimSpriteNames` | BOOL | trim sprite names | | `autoAliasEnabled` | BOOL | automatic detection of duplicate sprites enabled | | `premultiplyAlpha` | BOOL | premultiply alpha enabled | | `reduceBorderArtifacts` | BOOL | reduce border artifacts enabled | | `fixedTextureSize` | [SIZE](#size-type) | have a fixed texture size | | `dataFormat` | STRING | data format | | `textureSubPath` | STRING | texture sub path | | `borderPadding` | INT | border padding | | `shapePadding` | INT | shape padding | | `commonDivisorX` | INT | common divisor X | | `commonDivisorY` | INT | common divisor Y | | `backgroundColor` | INT | background color | | `writePivotPoints` | BOOL | user has enabled pivot points | | `autodetectAnimations` | BOOL | user has activated animation detection | ### AUTOSDSETTINGS This data type holds AutoSD settings. | Element | Type | Info | | --- | --- | --- | | `scale` | FLOAT | scaling factor | | `extension` | STRING | variant name | | `spriteFilter` | STRING | sprite filter | | `acceptFractionalValues` | BOOL | accept fractional values if no common factor can be found | | `maxTextureSize` | [SIZE](#size-type) | maximum texture size | ### RESULT Structure containing a packing result. | Element | Type | Info | | --- | --- | --- | | `textures` | [TEXTURE\[\]](#texture-type) | array of all textures | | `nonFittingSprites` | STRING\[\] | array containing names of non-fitting sprites | ### TEXTURE This data type holds a texture with all its parameters. | Element | Type | Info | | --- | --- | --- | | `size` | [SIZE](#size-type) | The width/height of the Texture file in pixels. | | `trimmedName` | STRING | The name of the Texture file - without the extension. | | `fullName` | STRING | The name of the Texture file with the extension. | | `absoluteFileName` | STRING | The absolute path to the Texture file. | | `normalMapFileName` | STRING | The path of the corresponding normal map sheet, relative to texture file. | | `normalMapAbsoluteFileName` | STRING | The absolute path of the corresponding normal map sheet. | | `sprites[0..n]` | [SPRITE\[\]](#sprite-type) | The sprites on the current texture, without aliases. | | `allSprites[0..m]` | [SPRITE\[\]](#sprite-type) | All sprites on current texture, including aliases. | | `area` | INT | Area of the texture in pixels (i.e. width\*height). | ### SPRITE This data type holds a sprite with all its parameters. | Element | Type | Info | | --- | --- | --- | | `fileData` | [FILEDATA](#filedata-type) | sprite file data | | `size` | [SIZE](#size-type) | size of the trimmed sprite in pixels, including extrude; typically not needed by exporters | | `frameRect` | [RECT](#rect-type) | position and size of the trimmed sprite on the texture (without extrude, w/h swapped if sprite was rotated) | | `frameRectWithoutRotation` | [RECT](#rect-type) | position of the trimmed sprite on the texture, unrotated size | | `frameRectRel` | [RECT](#rect-type) | same as `frameRect`, but with coordinates divided by texture size -> value range (0..1) | | `sourceRect` | [RECT](#rect-type) | size of the trimmed sprite, x/y values = `cornerOffset`, see below | | `cornerOffset` | [POINT](#point-type) | offset from the top-left corner of the original sprite to the top-left corner of the trimmed sprite (0,0 for _Crop, flush pos_) | | `untrimmedSize` | [SIZE](#size-type) | size of the original, untrimmed sprite (_Crop_ modes: size of trimmed sprite) | | `trimmed` | BOOL | true if sprite is trimmed | | `rotated` | BOOL | true if sprite is rotated | | `isSolid` | BOOL | true if sprite has no transparent pixels | | `trimmedName` | STRING | The name of the sprite file - without the extension. | | `fullName` | STRING | The name of the sprite file with the extension. | | `name` | STRING | trimmedName or fullName, depending on [Trim sprite names](https://www.codeandweb.com/texturepacker/documentation/texture-settings.md#trim-sprite-names) flag. | | `aliasList[0..n]` | [SPRITE\[\]](#sprite-type) | contains the list of identical sprites | | `centerOffset` | [POINT](#point-type) | Center offset | | `pivotPoint` | [POINT](#point-type) | x and y coordinates of the Pivot Point | | `pivotPointNorm` | [POINT](#point-type) | Pivot point coordinates, relative to the sprite size | | `vertices` | [POINT\[\]](#point-type) | Polygon points approximating the outline of the sprite. Sprite coordinate system. | | `verticesUV` | [POINT\[\]](#point-type) | Polygon points approximating the outline of the sprite. Texture coordinate system. | | `triangleIndices` | INT\[\] | Triangulation of the sprite's polygon. The values in this list are indices in the `vertices` / `verticesUV` array. | | `scale9Enabled` | BOOL | User enabled 9-patch scaling for this sprite | | `scale9Borders` | [RECT](#rect-type) | The 9-patch borders. | | `scale9Paddings` | [RECT](#rect-type) | The 9-patch paddings. | | `scale` | FLOAT | The sprite's scaling factor as set in **Sprite settings**. Does not take global/variant scale in account. | The two figures below illustrate the interpretation of the exported elements `sourceRect` and `frameRect`:   ### FILEDATA This data type holds a file. | Element | Type | Info | | --- | --- | --- | | `absoluteFileName` | STRING | absolute path of the file | | `fileSize` | FLOAT | size of the file | | `created` | DATE | creation date of the file | | `lastModified` | DATE | last modified date of the file | ### VARIANTPARAMS This data type holds the settings adapted for the current scaling variant. | Element | Type | Info | | --- | --- | --- | | `scale` | FLOAT | Scaling factor | | `shapePadding` | INT | shape padding in pixels | | `borderPadding` | INT | border padding in pixels | | `commonDivisorX` | INT | Common Divisor X | | `commonDivisorY` | INT | Common Divisor Y | | `extrude` | INT | Extrude in pixels | | `baseFactor` | INT | Common base factor of all scaling variants | | `maxTextureSize` | [SIZE](#size-type) | Maximum texture size in pixels | | `fixedTextureSize` | [SIZE](#size-type) | Fixed texture size in pixels | ### RECT (Rectangle) | Element | Type | Info | | --- | --- | --- | | `x` | INT | x coordinate | | `y` | INT | y coordinate | | `width` | INT | width in pixels | | `height` | INT | height in pixels | `frameRectRel` is the exception: its values are FLOATs in the range 0..1. ### POINT | Element | Type | Info | | --- | --- | --- | | `x` | FLOAT | x coordinate | | `y` | FLOAT | y coordinate | ### SIZE | Element | Type | Info | | --- | --- | --- | | `width` | INT | width in pixels | | `height` | INT | height in pixels | ## Enhancing the Exporter with JavaScript While templates are powerful, sometimes you need more advanced functionality - such as complex calculations or data transformations. In these cases, you can enhance your exporter with JavaScript. ### Setting Up JavaScript Support To add JavaScript capabilities to your exporter: 1. Create two nested directories inside your exporter folder: * First create a **grantlee** directory * Then create a **0.2** directory inside it Your folder structure should look like this:  2. Place your JavaScript file(s) in the **grantlee/0.2** directory 3. Use the **.qs** extension for your JavaScript files ### Creating JavaScript Filters In your JavaScript file, you can create **filters** - functions that process template values. A filter: 1. Receives a value from the template 2. Processes or transforms that value 3. Returns the result, which is then included in the output Here's an example of a filter that converts CSS class selectors to proper CSS syntax: ```js // Define the filter function var MakeSelectorFilter = function(input) { // Convert the input to a regular JavaScript string var input = input.rawString(); // Process the string (replace "-hover" with ":hover") return input.replace("-hover", ":hover"); }; // Set the filter name (this is how it will be referenced in templates) MakeSelectorFilter.filterName = "makecssselector"; // Register the filter with the template system Library.addFilter("MakeSelectorFilter"); ``` #### Important Notes: * **Converting Input**: Always convert the input parameter to a regular JavaScript string using `.rawString()` before using JavaScript string methods like `split()` or `replace()`. * **Return Type**: Filters must return a string value. * **Conditional Filters**: To create a filter that evaluates a condition, return an empty string `""` for false or any non-empty string (like `"true"`) for true. Then use it in templates like: `{% if variable|testfunction %}` ### Using JavaScript Filters in Templates #### Loading Filters To use a JavaScript filter in your template, you first need to load it: ```django {% load makecssselector %} ``` **Important**: The value in the `load` tag must match the JavaScript file name (without the `.qs` extension). #### Applying Filters Once loaded, you can apply the filter to any value in your template by using the pipe character: ```django {{ sprite.trimmedName|makecssselector }} ``` This passes the value of `sprite.trimmedName` to your filter function and includes the result in the output. ### Advanced Techniques #### Working with Multiple Parameters Since filters can only receive one parameter directly, you can use these techniques to work with multiple values: ##### Technique 1: Using Global Variables You can use one filter to store a value in a global variable, then use another filter to perform calculations with it: ```js // Define a global variable width = 1; // First filter: stores a value for later use var SetWidth = function (input) { width = input; // store the value globally return ""; // return empty string (won't appear in output) }; SetWidth.filterName = "setWidth"; Library.addFilter("SetWidth"); // Second filter: uses the stored global value var MakeRelX = function (input) { return String(input / width); // calculate relative position }; MakeRelX.filterName = "makeRelX"; Library.addFilter("MakeRelX"); ``` In your template, use these filters in sequence: ```django {{ texture.size.width|setWidth }}{{ sprite.frameRect.x|makeRelX }} ``` The first filter (`setWidth`) stores the texture width but outputs nothing. The second filter (`makeRelX`) uses that stored width to calculate a relative position. #### Creating JavaScript-Only Exporters For complex exporters, you might prefer to handle most of the work in JavaScript rather than in templates. This approach offers several advantages: * More powerful data processing capabilities * Better control over output formatting * Easier maintenance for complex exporters * Native JSON generation without template syntax issues To create a JavaScript-only exporter, use a minimal template that passes all TexturePacker data to your JavaScript function: testexporter.txt ```django {% load testexporter %}{{ tp|exportData|safe }} ``` This template: 1. Loads your JavaScript file (`testexporter.qs`) 2. Passes the entire TexturePacker data structure (`tp`) to your `exportData` filter 3. Uses the `safe` filter to prevent HTML escaping of the output Then, in your JavaScript file, you can process the data and generate the output format: testexporter.qs ```js // Process sprite data var exportSprites = function(sprites) { var result = {}; for (var i = 0; i < sprites.length; i++) { var s = sprites[i]; var frame = [ s.frameRect.x, s.frameRect.y, s.frameRect.width, s.frameRect.height ]; result[s.trimmedName] = frame; } return result; } // Process texture data var exportTextures = function(root) { var textures = root.allResults[root.variantIndex].textures; var result = {}; for (var i = 0; i < textures.length; i++) { var textureName = textures[i].fullName; var sprites = exportSprites(textures[i].allSprites); result[textureName] = sprites; } return result; } // Main export function - creates the final output var exportData = function(root) { var doc = exportTextures(root); // Generate properly formatted JSON with indentation return JSON.stringify(doc, null, "\t"); } // Register the filter exportData.filterName = "exportData"; Library.addFilter("exportData"); ``` This example creates a JSON output with texture names as keys, each containing sprite frame data. Using `JSON.stringify()` ensures valid JSON formatting with proper indentation. ## Syntax of the Templates The syntax of templates contains four types of tokens: * Plain text * Comments * Variables * Control tags A simple template might look like this: ```django {# A simple template example #} Hello {{ person.name }}, {% if person.hasBirthday %} Happy Birthday! {% else %} Have a nice day! {% endif %} Bye, {{ myname }} ``` * Content inside `{# #}` are comments and are not part of the output. * Content inside `{{ }}` are variables which are substituted when the template is rendered. * Content inside `{% %}` are control tags which can affect the rendering of the template. TexturePacker supports commonly used tags such as `if`, `for`, `cycle` and a host of others (see [https://docs.djangoproject.com/en/dev/ref/templates/builtins/](https://docs.djangoproject.com/en/dev/ref/templates/builtins/)). It is also possible to define your own custom tags. Grantlee implements a subset of the Django template language: not every Django tag or filter is available. ### Loops The type of a variable determines how it can be used in templates. For example, treatment of items in an iterable context works as follows: Lists work as expected: ```django {% for item in mylist %} - {{ item }} {% endfor %} ``` ### Truthiness Truthiness of a variable is evaluated in a similar way to Python. That is: * An empty string is `false` * `0` is `false` * An empty list is `false` * Boolean `false` is `false` Everything else is `true`. ```django {% if mylist %} List items: {% for item in mylist %} - {{ item }} {% endfor %} {% else %} The list is empty. {% endif %} ``` ### Variable Lookups So far we've mostly used simple variable lookups in `variable` tags, but the template system is capable of a lot more. Complex structures can be evaluated using the dot (`.`) character. The dot can be used for list index lookup (note that list lookup is `0`\-indexed): ```django The first item is {{ mylist.0 }}, and the fifth item is {{ mylist.4 }}. ``` It can also be used for key lookups: ```django The hash value is {{ myhash.mykey }}. ``` And it can retrieve properties from object instances: ```django The object property is {{ myobj.myprop }}. ``` ### Filters Filters can further affect the result of including a variable in a template. Filters are separated by the pipe (`|`) character. ```django Name is {{ name }}, and name in uppercase is {{ name|upper }}. ``` Which is rendered as: > Name is Alice, and name in uppercase is ALICE. Note that filters may be combined with dot-lookup. For example, if `people` is a list of `Person` objects, and `Person` objects have `name` properties: ```django First person's name: {{ people.0.name|upper }}. ``` Rendered as: > First person's name: BOB. Filters may also be chained. Here, 'Claire' is first uppercased, then lowercased: ```django Name is {{ name|upper|lower }} ``` Rendered as: > Name is claire. Filters may take one string argument, which is delimited by a colon (`:`). If `peoplestring` contains `"Dave and Ellen and Frank"`, we can cut the string `and` : ```django The people are {{ peoplestring|cut:"and " }} ``` Rendered as: > The people are Dave Ellen Frank. Internal filters include: * `upper` - Converts text to uppercase * `lower` - Converts text to lowercase * `slice` - Returns a slice of the list * `truncatewords` - Truncates a string after a number of words * `join` - Joins a list with a string For more filters, see the [Django template built-in filters documentation](https://docs.djangoproject.com/en/dev/ref/templates/builtins/#built-in-filter-reference). ### Auto-Escaping in Templates When creating HTML output, it's necessary to consider escaping data inserted into the template. HTML escaping involves replacing characters like `<` with `<` and `&` with `&` to prevent them from being interpreted as HTML markup. The template engine automatically escapes string input before adding it to the output. This is relevant when writing a variable from the context into the template. If the context object `companies` is a list containing (`Burger King`, `Ben & Jerry's`, `Ford`), and it is used in a template such as: ```django {% for company in companies %} - {{ company }} {% endfor %} ``` The output would be: > * Burger King > * `Ben & Jerry's` > * Ford Notice that the `&` has been replaced with `&`, as is appropriate for HTML output. Use the `|safe` filter to get the unescaped content of the string: ```django {% for company in companies %} - {{ company|safe }} {% endfor %} ``` It is also possible to turn this auto-escaping feature off for a block in a template: ```django {% autoescape off %} ... {% endautoescape %} ``` This would not escape the content between the `autoescape` and `endautoescape` tags. This should only be used for content which is actually already safe. For more information, see the [Django template auto-escaping documentation](https://docs.djangoproject.com/en/dev/ref/templates/language/#automatic-html-escaping). # Hidden features Some features are tucked away to keep the interface clean and easy to use. They don’t fit into the UI without adding clutter and are only needed by a small number of users. Good news: you can still use them by editing your .tps file (it’s a simple XML file) in any text editor. > **Warning:** **Important note** TexturePacker does not automatically reload the .tps file. After editing, close the window and re-open the file to apply your changes. ## Ignoring files and directories By default, TexturePacker adds all image files it finds in a folder. Sometimes you might want to exclude certain files — for example, .psd files. Locate the following section in your .tps file: ```xml ignoreFileList ``` This example ignores all files in a folder called **test**, and all files ending with **.psd**: ```xml ignoreFileList *.psd */test/* ``` Create one `...` for each entry. The expressions support Unix wildcards. On the command line, use [`--ignore-files`](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md#input-output) instead. ## Replacing file names and removing full path You can replace parts of file names or remove directory prefixes by adjusting the following section in your .tps file. Locate this section: ```xml replaceList ``` Replace it with these lines to remove all path segments from the sprite names: ```xml replaceList .*/= ``` You can add multiple replacements — make a separate `...` for each. The format is `REGEXP=STRING`. Replacements use Perl-compatible regular expressions. On the command line, use [`--replace`](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md#input-output) instead. ## Heuristic mask The heuristic mask replaces a solid background color in a sprite with transparency. It works well in most cases. To enable it, locate the following section in your .tps file: ```xml heuristicMask ``` …and replace it with: ```xml heuristicMask ``` On the command line, use [`--heuristic-mask`](https://www.codeandweb.com/texturepacker/documentation/commandline/parameters.md#sheet-layout) instead.