Skip to main content

​
Overview

The pack command reads sprite images from input directories or files and packs them into optimized texture atlases with accompanying metadata files.

​
Basic usage

fastpack pack [INPUT...] [OPTIONS]

​
Examples

fastpack pack sprites/

​
Arguments

​
INPUT
path[]
Input directories or files to search for sprites. When using --project, this argument is optional and overrides the project’s sources.

​
Options

​
Project

​
--project
path
Load settings from a .fpsheet project file. When specified, most options come from the project file. CLI flags override project settings.See config-reference for project file format.

​
Output

​
--output
path
default:"output"
Output directory for the generated atlas and data file.
​
--name
string
default:"atlas"
Base name for output files (without extension). Produces files like atlas.png and atlas.json.

​
Layout

​
--max-width
integer
default:"4096"
Maximum atlas width in pixels. The packer will try to fit sprites within this constraint.
​
--max-height
integer
default:"4096"
Maximum atlas height in pixels. The packer will try to fit sprites within this constraint.
​
--pack-mode
enum
default:"good"
Compression effort level that controls packing algorithm quality and speed.Values:
  • fast - Single-pass basic strip packer; fastest, largest atlas
  • good - MaxRects single-pass; good density, moderate speed (default)
  • best - MaxRects width search; densest atlas, slowest
​
--size-constraint
enum
default:"any"
Constraint applied to atlas dimensions.Values:
  • any - No constraint; smallest rectangle that fits (default)
  • pot - Width and height must be powers of two (e.g., 512, 1024, 2048)
  • multiple-of-4 - Width and height must each be divisible by 4
  • word-aligned - Width and height must each be divisible by 2
​
--force-square
boolean
default:"false"
Force the atlas to be square (width == height). Useful for some engines that require square textures.
​
--allow-rotation
boolean
default:"true"
Allow 90° sprite rotation to improve packing density. Rotation data is included in the output metadata.

​
Padding

​
--border-padding
integer
default:"2"
Transparent pixels added around the atlas edge. Helps prevent texture bleeding at atlas boundaries.
​
--shape-padding
integer
default:"2"
Transparent gap between adjacent sprites. Helps prevent texture bleeding between sprites.

​
Trimming

​
--trim-mode
enum
default:"trim"
How to strip transparent borders from sprites.Values:
  • none - Pack the full image including transparent borders
  • trim - Strip transparent borders; store offset for engine reconstruction (default)
  • crop - Crop tightly to the opaque region
  • crop-keep-pos - Like crop but offsets may be negative to keep original registration
  • polygon - Build convex hull polygon; pack its bounding box
​
--trim-margin
integer
default:"0"
Pixels of transparent margin to keep around trimmed edges. Useful for effects that need some transparency.
​
--trim-threshold
integer
default:"1"
Alpha threshold: pixels at or below this value (0-255) are considered transparent during trimming.

​
Processing

​
--extrude
integer
default:"0"
Pixels of border extrusion added to each sprite edge. Edge pixels are repeated outward to prevent texture bleeding.
​
--detect-aliases
boolean
default:"true"
Deduplicate pixel-identical sprites as aliases. Aliases reference the same atlas region, saving space.
​
--multipack
boolean
default:"false"
Emit additional sheets when sprites overflow the first atlas. Produces atlas_1.png, atlas_2.png, etc.

​
Pivot points

​
--pivot-x
float
Default pivot X coordinate (0.0-1.0) for all sprites. Requires --pivot-y. Value of 0.0 is left edge, 1.0 is right edge.
​
--pivot-y
float
Default pivot Y coordinate (0.0-1.0) for all sprites. Requires --pivot-x. Value of 0.0 is top edge, 1.0 is bottom edge.

​
Scaling

​
--scale
float
default:"1.0"
Scale factor applied to output. For example, 0.5 produces a half-resolution atlas, 2.0 produces a double-resolution atlas.
​
--suffix
string
default:""
Suffix appended to output filenames before the extension. For example, @2x produces [email protected].
​
--scale-mode
enum
default:"smooth"
Resampling filter used when scaling sprites.Values:
  • smooth - Lanczos3 resampling; high quality for general use (default)
  • fast - Nearest-neighbor; crisp pixel art, no blurring

​
Output formats

​
--data-format
enum
default:"json-hash"
Output data format for sprite metadata.Values:
  • json-hash - Generic JSON object keyed by sprite name (default)
  • json-array - JSON array of frame objects
  • phaser3 - Phaser 3 multi-atlas format
  • pixijs - PixiJS sprite sheet format
​
--texture-format
enum
default:"png"
Output texture format.Values:
  • png - Lossless PNG (default)
  • jpeg - Lossy JPEG; no alpha channel
  • webp - WebP (lossless or lossy depending on pack mode)
  • dxt1 - DXT1 / BC1 hardware compression; no per-pixel alpha
  • dxt5 - DXT5 / BC3 hardware compression; full alpha channel
​
--pixel-format
enum
default:"rgba8888"
Pixel bit depth. Floyd-Steinberg dithering is applied when not rgba8888.Values:
  • rgba8888 - 32-bit RGBA (8 bits per channel); no dithering (default)
  • rgb888 - 24-bit RGB (8 bits per channel, alpha forced to 255)
  • rgb565 - 16-bit RGB (5-6-5); Floyd-Steinberg dithering applied
  • rgba4444 - 16-bit RGBA (4 bits per channel); Floyd-Steinberg dithering applied
  • rgba5551 - 16-bit RGBA (5-5-5-1); Floyd-Steinberg dithering; alpha thresholded at 128
  • alpha8 - 8-bit alpha only
​
--premultiply-alpha
boolean
default:"false"
Premultiply RGB channels by alpha before compression. Improves blending quality in some engines.

​
Output

Successful packing prints atlas statistics: 
Packed 147 sprites (23 aliases) → 1024×1024 atlas → output/atlas.png (342.5 KB)
Saved output/atlas.json (8451 bytes)
If sprites don’t fit within constraints: 
warning: 12 sprite(s) did not fit and were dropped
Use --multipack to emit multiple sheets instead of dropping sprites.

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us