Skip to main content
The split subcommand is the inverse of packing. It reads an atlas image and its data file, then writes each sprite back out as a separate PNG file. Use it to extract sprites from a legacy atlas, inspect packed output, or feed sprites into an editing tool.

​
Usage

fastpack split <ATLAS> <DATA> --output-dir <DIR>
  • <ATLAS> — Path to the packed atlas PNG
  • <DATA> — Path to the JSON Hash data file
  • --output-dir — Directory for extracted sprites (default: sprites)

​
CLI flags

FlagDescriptionDefault
-o, --output-dir <DIR>Directory where extracted sprite PNGs are writtensprites

​
Examples

1

Basic extraction

Extract sprites to the default sprites/ directory:
fastpack split output/atlas.png output/atlas.json
2

Custom output directory

Extract sprites to a specific directory:
fastpack split output/atlas.png output/atlas.json --output-dir extracted/

​
Output structure

Extracted sprites are placed in subdirectories matching their sprite ID path: 
extracted/
  player/
    idle.png
    walk_01.png
  ui/
    button.png
    panel.png

​
Technical details

The splitter reads the atlas PNG and JSON Hash data file. For each frame:
  1. Crops the atlas region using the frame rect
  2. Rotates the sprite 270° if rotated is true
  3. Restores the original canvas size if the sprite was trimmed by placing the cropped region at spriteSourceSize.x, y on a canvas of sourceSize.w × h
  4. Writes the result to <output_dir>/<id>.png
Intermediate directories are created as needed.
Sprites are extracted using the frame rect from the data file, which points at the trimmed region in the atlas. When trimmed is true, the splitter reconstructs the full original dimensions including transparent padding by compositing the trimmed region onto a canvas of sourceSize dimensions at the spriteSourceSize offset.
Alias sprites (those with an aliasOf field) are written as separate files; each gets the pixels of the atlas frame they point to. The alias relationship is not preserved in the extracted files.

​
TexturePacker compatibility

TexturePacker includes a similar “Unpack Sprites” command. Both tools extract sprites from the frame rect and handle trimmed sprite reconstruction in the same way.

Build docs developers (and LLMs) love

Get started for freeTalk to us