Skip to main content

​
Overview

The split command reverses the packing process by extracting individual sprite images from a packed atlas using its metadata file. This is useful for recovering source sprites, debugging atlases, or converting atlases from other tools.

​
Basic usage

fastpack split <ATLAS> <DATA> [OPTIONS]

​
Examples

fastpack split atlas.png atlas.json

​
Arguments

​
ATLAS
path
required
Path to the packed atlas PNG file. This is the texture file generated by fastpack pack.
​
DATA
path
required
Path to the JSON Hash data file produced by fastpack. This file contains sprite coordinates and metadata.
The split command currently only supports the json-hash data format. If your atlas uses a different format (json-array, phaser3, pixijs), you’ll need to convert the metadata first.

​
Options

​
--output-dir
path
default:"sprites"
Output directory for extracted sprite files. The directory will be created if it doesn’t exist.Short form: -o

​
Output

Successful splitting prints: 
Split 147 sprite(s) → sprites

​
Behavior

​
Directory structure

Extracted sprites preserve the directory structure from their original sprite IDs: 
sprites/
├── characters/
│   ├── player.png
│   └── enemy.png
├── ui/
│   ├── button.png
│   └── icon.png
└── effects/
    ├── explosion.png
    └── smoke.png

​
Sprite reconstruction

The split command reconstructs sprites with:
  • Trimmed regions - If the atlas was packed with trimming, transparent borders are restored
  • Rotation - Rotated sprites are automatically un-rotated
  • Original dimensions - Sprites are restored to their pre-pack dimensions
  • Transparent padding - Border and shape padding is removed

​
Alias handling

When the atlas contains aliases (deduplicated sprites):
  • Each alias is extracted as a separate file
  • All aliases reference the same pixel data
  • The output contains duplicate files for each alias

​
Use cases

​
Recover lost sources

If you’ve lost original sprite files but have a packed atlas: 
fastpack split game-atlas.png game-atlas.json -o recovered-sprites/

​
Debug packing issues

Verify that packed sprites match your expectations: 
# Pack sprites
fastpack pack sprites/ --output build/

# Split them back out
fastpack split build/atlas.png build/atlas.json -o debug/

# Compare original vs split
diff -r sprites/ debug/

​
Convert from other tools

Convert atlases from other texture packers to individual sprites: 
# If you have a compatible JSON format
fastpack split external-atlas.png external-atlas.json -o sprites/

​
Extract variant scales

Split different scale variants separately: 
# Extract high-res variant
fastpack split [email protected] [email protected] -o sprites-2x/

# Extract standard variant
fastpack split [email protected] [email protected] -o sprites-1x/

​
Limitations

​
Data format support

Only json-hash format is currently supported. Other formats require conversion: 
# This works
fastpack pack sprites/ --data-format json-hash
fastpack split atlas.png atlas.json

# This doesn't work directly
fastpack pack sprites/ --data-format phaser3
fastpack split atlas.png atlas.json  # Error: unsupported format

​
Lossy information

Some information may be lost during pack/split cycles:
  • Extrusion - Extruded borders are baked into the atlas and can’t be removed during split
  • Texture format - JPEG or WebP compression artifacts remain in split sprites
  • Pixel format - Dithering from reduced bit depth is permanent

​
Metadata requirements

The JSON file must contain:
  • Frame coordinates (x, y, w, h)
  • Source size (original sprite dimensions)
  • Rotation flag (if sprites were rotated)
The split command uses frame coordinates to extract sprites and source size to restore transparent borders.

​
File naming

Extracted sprites use their sprite ID as the filename:
  • Sprite ID: characters/player → File: sprites/characters/player.png
  • Forward slashes in IDs become directory separators
  • All extracted sprites are PNG files regardless of source format

​
Technical notes

​
Trimming reconstruction

When splitting trimmed atlases: 
Original: 128×128 with transparent borders
  ↓ pack with --trim-mode trim
Atlas: 64×64 (trimmed region only)
  ↓ split
Output: 128×128 (transparent borders restored)
The metadata contains both:
  • frame - Position in atlas (trimmed region)
  • sourceSize - Original dimensions before trimming
  • spriteSourceSize - Offset of trimmed region

​
Rotation handling

Rotated sprites in the atlas: 
Atlas: Sprite rotated 90° clockwise
  ↓ split
Output: Sprite un-rotated to original orientation
The rotated boolean in the metadata determines whether to rotate back.

​
Example workflow

# Start with source sprites
ls sprites/
# characters/player.png, ui/button.png, etc.

# Pack them into an atlas
fastpack pack sprites/ --output dist/ --trim-mode trim

# Split the atlas back to verify
fastpack split dist/atlas.png dist/atlas.json -o verify/

# Compare (should be identical after trim restoration)
diff -r sprites/ verify/

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us