Skip to main content
fastpack is the headless command-line interface. Running it without arguments opens the GUI. Use subcommands for headless operation.

​
Available subcommands

Pack sprites into a texture atlas.
fastpack pack <inputs...> [flags]

​
fastpack pack

Pack one or more directories (or individual files) of sprites into a single texture atlas. 
fastpack pack <INPUT>... [OPTIONS]

​
Arguments

INPUT — One or more paths. Directories are searched recursively for image files (png, jpg, jpeg, bmp, tga, webp, tiff, gif). Files are added directly.

​
Common options

-o, --output <dir> (default: output)Output directory for the texture and data files. Created if it does not exist.--name <basename> (default: atlas)Base filename for output files without extension. Produces <name>.png and <name>.json.--project <file>Load settings from a .fpsheet project file. CLI flags override project file values.
--max-width <n> (default: 4096)Maximum atlas width in pixels.--max-height <n> (default: 4096)Maximum atlas height in pixels.--pack-mode <fast|good|best> (default: good)Compression effort:
  • fast — Single-pass basic strip packer; fastest, largest atlas
  • good — MaxRects single-pass; good density, moderate speed
  • best — MaxRects width search; densest atlas, slowest
--size-constraint <any|pot|multiple-of-4|word-aligned> (default: any)Constraint applied to atlas dimensions.--force-squareForce the atlas to be square (width == height).--allow-rotation (default: true)Allow 90° sprite rotation to improve packing density.--border-padding <n> (default: 2)Transparent pixels added around the atlas edge.--shape-padding <n> (default: 2)Transparent gap between adjacent sprites.
--trim-mode <none|trim|crop|crop-keep-pos|polygon> (default: trim)How to strip transparent borders from sprites:
  • none — Pack the full image including transparent borders
  • trim — Strip transparent borders; store offset for engine reconstruction
  • 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 <n> (default: 0)Pixels of transparent margin to keep around trimmed edges.--trim-threshold <n> (default: 1)Alpha threshold: pixels at or below this value are considered transparent (0–255).--extrude <n> (default: 0)Pixels of border extrusion added to each sprite edge.--detect-aliases (default: true)Deduplicate pixel-identical sprites as aliases.
--scale <factor> (default: 1.0)Scale factor applied to output (e.g. 0.5 produces a half-resolution atlas).--suffix <text> (default: "")Suffix appended to output filenames (e.g. @2x produces [email protected]).--scale-mode <smooth|fast> (default: smooth)Resampling filter:
  • smooth — Lanczos3 resampling; high quality
  • fast — Nearest-neighbour; crisp pixel art, no blurring
--data-format <json-hash|json-array|phaser3|pixijs> (default: json-hash)Output data format:
  • json-hash — Generic JSON object keyed by sprite name
  • json-array — JSON array of frame objects
  • phaser3 — Phaser 3 multi-atlas format
  • pixijs — PixiJS sprite sheet format
--texture-format <png|jpeg|webp|dxt1|dxt5> (default: png)Output texture format:
  • png — Lossless PNG
  • 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 <rgba8888|rgb888|rgb565|rgba4444|rgba5551|alpha8> (default: rgba8888)Pixel bit depth. Floyd-Steinberg dithering is applied when not rgba8888.--premultiply-alphaPremultiply RGB channels by alpha before compression.
--multipackEmit additional sheets when sprites overflow the first atlas.--pivot-x <x> and --pivot-y <y>Default pivot coordinates (0.0–1.0). Both are required together.

​
Examples

fastpack pack sprites/ --output build/atlas --name ui --max-width 2048
Writes build/atlas/ui.png and build/atlas/ui.json.

​
Sprite IDs

Each frame’s ID is the file path relative to the input directory, without extension, with forward slashes as the separator. For a file at sprites/player/idle.png loaded from root sprites/, the ID is player/idle.
When individual files are passed as inputs, the ID is the filename without extension (no directory component).

​
Output files

<name>.json — Atlas metadata in JSON Hash format. Contains frames (one entry per sprite) and a meta block with atlas dimensions, image filename, pixel format, and scale. <name>.png — Lossless PNG texture. Pixel format is RGBA8888.

​
Exit codes

Exit code is 0 on success. Exit code is non-zero when:
  • No images are found
  • All images fail to load
  • The packer fails
If overflow occurs (sprites that could not fit), a warning is printed to stderr. The atlas is still written with the sprites that did fit.

​
Technical notes

Phase 1 uses the MaxRects algorithm with BestShortSideFit heuristic, allow_rotation = true, and shape_padding = 2. Sprites are trimmed with TrimMode::Trim and alpha threshold 1. These settings are not yet configurable via flags; full flag coverage is planned for Phase 2.

​
TexturePacker compatibility

fastpack pack accepts a subset of the flags TexturePacker CLI exposes. Full compatibility mapping (including --format, --data, --sheet) is planned for Phase 6.

Build docs developers (and LLMs) love

Get started for freeTalk to us