Quick start

This guide will walk you through creating your first texture atlas with FastPack. You can use either the GUI or the CLI depending on your workflow.

Using the GUI

The fastest way to get started is with FastPack’s native GUI interface.

Launch FastPack

Start the GUI by running the command with no arguments:

fastpack

The GUI window will open with an empty project.

Add sprites

Click “Add Sources” or drag and drop a folder containing your sprite images
FastPack supports PNG, JPEG, BMP, TGA, WebP, and TIFF formats
Your sprites will appear in the collapsible sprite tree with thumbnail previews

Configure settings

Adjust packing options in the settings panel:

Max dimensions: Set atlas width/height limits (default: 4096x4096)
Trim mode: Choose how to handle transparent borders
Pack mode: Select Good (balanced) or Best (densest)
Data format: Choose your export format (JSON Hash, Phaser 3, PixiJS, etc.)

Preview and pack

View the real-time atlas preview as you adjust settings
Click “Pack” to generate your atlas
Choose an output directory when prompted

Save your project

Save your settings as a .fpsheet project file for future use:

File → Save Project
This stores all your configuration for easy reuse

Enable Watch mode in the GUI to automatically repack your atlas whenever source files change.

Using the CLI

For automation and CI/CD workflows, use the command-line interface.

Basic packing

Pack a directory of sprites with default settings:

fastpack pack sprites/ --output output/

This creates:

output/atlas.png — The packed texture atlas
output/atlas.json — Frame data in JSON Hash format

Pack with custom options

Customize the packing process with command-line flags:

fastpack pack sprites/ --output output/ \
  --max-width 2048 --max-height 2048 \
  --trim-mode trim \
  --data-format phaser3 \
  --allow-rotation

fastpack pack sprites/ --output output/ \
  --max-width 2048 \
  --max-height 2048 \
  --pack-mode best \
  --trim-mode trim \
  --shape-padding 2 \
  --border-padding 2

Using project files

Create a project file to store your configuration:

Generate a default project file

fastpack init --output atlas.fpsheet

This creates a .fpsheet file with default settings.

Edit the project file

Open atlas.fpsheet in your text editor and customize the settings:

atlas.fpsheet

[meta]
version = "1"

[output]
name = "atlas"
directory = "output/"
texture_format = "png"
data_format = "json_hash"

[layout]
max_width = 2048
max_height = 2048
allow_rotation = true
pack_mode = "best"
border_padding = 2
shape_padding = 2

[sprites]
trim_mode = "trim"
trim_threshold = 1
detect_aliases = true

[[sources]]
path = "sprites/"
filter = "**/*.png"

Pack using the project file

fastpack pack --project atlas.fpsheet

Project files are in TOML format and provide a clean way to version control your atlas configuration. Learn more in the Project files documentation.

Watch mode

Automatically repack your atlas when source files change:

fastpack watch sprites/ --output output/

Watch mode is perfect for development workflows. FastPack monitors the input directory and repacks whenever you add, modify, or remove sprite files.

Advanced CLI commands

Split an atlas

Extract individual sprites from a packed atlas:

fastpack split atlas.png atlas.json --output-dir sprites/

This is useful for:

Recovering original sprites from a packed atlas
Converting between atlas formats
Extracting sprites from third-party atlases

Multi-resolution variants

Generate multiple resolution variants of your atlas:

atlas.fpsheet

[[variants]]
scale = 1.0
suffix = "@1x"
mode = "smooth"

[[variants]]
scale = 2.0
suffix = "@2x"
mode = "smooth"

[[variants]]
scale = 0.5
suffix = "@0.5x"
mode = "smooth"

Then pack with:

fastpack pack --project atlas.fpsheet

This generates:

[email protected] and [email protected]
[email protected] and [email protected]
[email protected] and [email protected]

Common options reference

Here are the most frequently used CLI options:

Option	Description	Default
`--output`	Output directory	`output`
`--name`	Base name for output files	`atlas`
`--max-width`	Maximum atlas width in pixels	`4096`
`--max-height`	Maximum atlas height in pixels	`4096`
`--pack-mode`	Compression effort: fast, good, best	`good`
`--trim-mode`	Transparent border handling	`trim`
`--allow-rotation`	Allow 90° sprite rotation	`true`
`--shape-padding`	Gap between sprites in pixels	`2`
`--border-padding`	Padding around atlas edge	`2`
`--data-format`	Export format: json-hash, json-array, phaser3, pixijs	`json-hash`
`--texture-format`	Image format: png, jpeg, webp, dxt1, dxt5	`png`
`--detect-aliases`	Deduplicate identical sprites	`true`

When using --allow-rotation, make sure your game engine supports rotated sprites. Most modern engines like Phaser and PixiJS handle this automatically.

Example workflow

Here’s a complete example workflow for packing game sprites:

Organize your sprites

Create a directory structure:

game-sprites/
├── characters/
│   ├── player.png
│   └── enemy.png
├── items/
│   ├── coin.png
│   └── powerup.png
└── ui/
    ├── button.png
    └── icon.png

Create a project file

fastpack init --output game.fpsheet

Configure for Phaser 3

Edit game.fpsheet:

[output]
name = "game-atlas"
directory = "assets/atlases/"
data_format = "phaser3"

[[sources]]
path = "game-sprites/"
filter = "**/*.png"

Pack the atlas

fastpack pack --project game.fpsheet

Load in Phaser 3

this.load.multiatlas(
  'game-atlas',
  'assets/atlases/game-atlas.json'
);

Troubleshooting

Sprites don’t fit in atlas

If you see errors about sprites not fitting:

Increase --max-width and --max-height
Use --multipack to split across multiple atlases
Reduce sprite sizes or use fewer sprites
Try --pack-mode best for better density

Texture bleeding

If you see color bleeding between sprites at runtime:

Increase --shape-padding (default: 2)
Increase --border-padding (default: 2)
Use --extrude 1 to duplicate edge pixels

Watch mode not detecting changes

If watch mode doesn’t repack on file changes:

Ensure the input path is correct
Check file system permissions
Try saving files to a new location (some editors use atomic writes)

Next steps

CLI reference

Explore all CLI commands and options

Project files

Deep dive into .fpsheet configuration

Export formats

Learn about supported data formats

Packing algorithms

Understand the different packing strategies

Get Started

Guides

Packing

Export Formats

Features

Using the GUI

Using the CLI

Basic packing

Pack with custom options

Using project files

Watch mode

Advanced CLI commands

Split an atlas

Multi-resolution variants

Common options reference

Example workflow

Troubleshooting

Sprites don’t fit in atlas

Texture bleeding

Watch mode not detecting changes

Next steps

CLI reference

Project files

Export formats

Packing algorithms

Build docs developers (and LLMs) love

Get Started

Guides

Packing

Export Formats

Features

​Using the GUI

​Using the CLI

​Basic packing

​Pack with custom options

​Using project files

​Watch mode

​Advanced CLI commands

​Split an atlas

​Multi-resolution variants

​Common options reference

​Example workflow

​Troubleshooting

​Sprites don’t fit in atlas

​Texture bleeding

​Watch mode not detecting changes

​Next steps

CLI reference

Project files

Export formats

Packing algorithms

Build docs developers (and LLMs) love

Using the GUI

Using the CLI

Basic packing

Pack with custom options

Using project files

Watch mode

Advanced CLI commands

Split an atlas

Multi-resolution variants

Common options reference

Example workflow

Troubleshooting

Sprites don’t fit in atlas

Texture bleeding

Watch mode not detecting changes

Next steps