Skip to main content

​
Overview

A .fpsheet file is a TOML document that stores all packer settings for a project. Instead of passing flags on every run, write them once to an .fpsheet and reference it with --project.

​
Creating a project file

Generate a default .fpsheet in the current directory: 
fastpack init
Reference it when packing or watching: 
fastpack pack --project atlas.fpsheet
fastpack watch --project atlas.fpsheet
CLI flags override project file values when both are provided.

​
Full example

atlas.fpsheet
# Input sources
[[sources]]
path   = "sprites"
filter = "**/*.png"

# Atlas layout
[layout]
max_width      = 4096
max_height     = 4096
border_padding = 2
shape_padding  = 2
allow_rotation = true
pack_mode      = "best"

# Sprite pre-processing
[sprites]
trim_mode      = "trim"
trim_threshold = 1
trim_margin    = 0
extrude        = 0
detect_aliases = true
default_pivot  = { x = 0.0, y = 0.0 }

# Output
[output]
name                = "atlas"
directory           = "output"
texture_format      = "png"
pixel_format        = "RGBA8888"
data_format         = "json_hash"
quality             = 95
premultiply_alpha   = false
texture_path_prefix = ""

# Algorithm
[algorithm]
type      = "max_rects"
heuristic = "best_short_side_fit"

# Scale variants
[[variants]]
scale      = 1.0
suffix     = ""
scale_mode = "smooth"

# Per-sprite overrides
[[sprite_overrides]]
id         = "ui/button"
pivot      = { x = 0.5, y = 0.5 }
nine_patch = { top = 8, right = 8, bottom = 8, left = 8 }

​
Field reference

​
[meta]

​
version
string
default:"1"
Project file format version. Current version is "1".

​
[[sources]]

Multiple [[sources]] blocks are allowed. Each adds a set of sprites to the pack.
​
path
string
default:"sprites"
Root directory to search for sprite files. Relative to the project file location.
​
filter
string
default:"**/*.png"
Glob pattern relative to path. Matches files to include as sprites.Examples:
  • **/*.png - All PNG files recursively (default)
  • *.png - PNG files in root only
  • characters/**/*.png - PNG files in characters subdirectory

​
Example: Multiple sources

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

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

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

​
[layout]

Controls atlas dimensions and packing algorithm.
​
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.
​
fixed_width
integer
Force an exact width, overriding max_width. Sprites that don’t fit are dropped (or overflow if multipack is enabled).
​
fixed_height
integer
Force an exact height, overriding max_height. Sprites that don’t fit are dropped (or overflow if multipack is enabled).
​
border_padding
integer
default:"2"
Pixels of empty space around the atlas edge. Helps prevent texture bleeding at atlas boundaries.
​
shape_padding
integer
default:"2"
Pixels of empty space between sprites. Helps prevent texture bleeding between adjacent sprites.
​
allow_rotation
boolean
default:"true"
Allow 90° sprite rotation to improve packing density. Rotation data is included in output metadata.
​
pack_mode
string
default:"best"
Packing algorithm quality level.Values:
  • "fast" - Basic strip packer; fastest, largest atlas
  • "good" - MaxRects single-pass; good density, moderate speed
  • "best" - MaxRects width search; densest atlas, slowest (default)
​
force_square
boolean
default:"false"
Constrain atlas to square dimensions (width == height). Useful for engines that require square textures.
​
size_constraint
string
default:"any_size"
Valid atlas dimension modes.Values:
  • "any_size" - 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

​
Example: Power-of-two square atlas

[layout]
max_width       = 2048
max_height      = 2048
size_constraint = "pot"
force_square    = true

​
[sprites]

Controls sprite pre-processing and trimming.
​
trim_mode
string
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 reconstruction (default)
  • "crop" - Crop tightly to the opaque region
  • "crop_keep_pos" - Like crop but offsets may be negative to preserve registration
  • "polygon" - Build convex hull polygon; pack its bounding box
​
trim_threshold
integer
default:"1"
Alpha threshold: pixels at or below this value (0-255) are considered transparent during trimming.
​
trim_margin
integer
default:"0"
Transparent pixels kept around the trim edge. Useful for effects that need some transparency.
​
extrude
integer
default:"0"
Edge pixels to repeat outward before packing. Helps prevent texture bleeding during filtering.
​
detect_aliases
boolean
default:"true"
Deduplicate pixel-identical sprites. Aliases reference the same atlas region, saving space.
​
default_pivot
object
default:"{ x = 0.0, y = 0.0 }"
Fallback pivot point for all sprites. Format: { x = float, y = float } where 0.0 is top/left and 1.0 is bottom/right.
​
common_divisor_x
integer
default:"0"
Round trimmed width up to the nearest multiple. 0 disables. Useful for alignment requirements.
​
common_divisor_y
integer
default:"0"
Round trimmed height up to the nearest multiple. 0 disables. Useful for alignment requirements.

​
Example: Aggressive trimming

[sprites]
trim_mode      = "trim"
trim_threshold = 10      # Treat alpha ≤ 10 as transparent
trim_margin    = 1       # Keep 1px transparent border
extrude        = 2       # Extrude 2px to prevent bleeding

​
[output]

Controls output files and formats.
​
name
string
default:"atlas"
Base filename without extension. Produces files like atlas.png and atlas.json.
​
directory
string
default:"output"
Output directory path. Relative to the project file location or absolute.
​
texture_format
string
default:"png"
Output texture format.Values:
  • "png" - Lossless PNG (default)
  • "jpg" or "jpeg" - Lossy JPEG; no alpha channel
  • "webp" - WebP (lossless or lossy depending on pack mode)
​
pixel_format
string
default:"RGBA8888"
Pixel encoding. 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); dithered
  • "RGBA4444" - 16-bit RGBA (4 bits per channel); dithered
  • "RGBA5551" - 16-bit RGBA (5-5-5-1); dithered, alpha thresholded at 128
  • "ALPHA8" - 8-bit alpha only
​
data_format
string
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
​
quality
integer
default:"95"
Lossy encoding quality, 0-100. Applies to JPEG and WebP. Higher values mean better quality and larger files.
​
premultiply_alpha
boolean
default:"false"
Multiply RGB channels by alpha before encoding. Improves blending quality in some engines.
​
texture_path_prefix
string
default:""
String prepended to texture filenames in data files. Useful for CDN URLs or relative paths.Example: "assets/" produces "assets/atlas.png" in the JSON.

​
Example: Optimized mobile output

[output]
name           = "mobile-atlas"
directory      = "dist/mobile/"
texture_format = "webp"
pixel_format   = "RGBA4444"
quality        = 85

​
[algorithm]

Controls the core packing algorithm.

​
MaxRects (default)

​
type
string
default:"max_rects"
Set to "max_rects" for the MaxRects algorithm.
​
heuristic
string
default:"best_short_side_fit"
MaxRects heuristic to use.Values:
  • "best_short_side_fit" - Minimize leftover short side (default)
  • "best_long_side_fit" - Minimize leftover long side
  • "best_area_fit" - Minimize leftover area
  • "bottom_left_rule" - Pack from bottom-left corner
  • "contact_point_rule" - Maximize edge contact
[algorithm]
type      = "max_rects"
heuristic = "best_short_side_fit"

​
Grid

​
type
string
Set to "grid" for the grid algorithm.
​
cell_width
integer
default:"0"
Width of each grid cell. 0 auto-sizes to the largest sprite width.
​
cell_height
integer
default:"0"
Height of each grid cell. 0 auto-sizes to the largest sprite height.
[algorithm]
type        = "grid"
cell_width  = 64
cell_height = 64

​
Basic

​
type
string
Set to "basic" for the basic strip packer.
[algorithm]
type = "basic"

​
[[variants]]

Each [[variants]] block produces an independent set of output files at the specified scale. This enables multi-resolution atlases for different display densities.
​
scale
float
default:"1.0"
Scale factor. 0.5 halves all sprite dimensions; 2.0 doubles them.
​
suffix
string
default:""
Appended to output filenames before the extension. For example, "@2x" produces [email protected].
​
scale_mode
string
default:"smooth"
Resampling filter used when scaling sprites.Values:
  • "smooth" - Lanczos3 resampling; high quality (default)
  • "fast" - Nearest-neighbor; crisp pixel art, no blurring

​
Example: Multi-resolution output

# High density (Retina, 2x)
[[variants]]
scale      = 2.0
suffix     = "@2x"
scale_mode = "smooth"

# Standard density (1x)
[[variants]]
scale      = 1.0
suffix     = "@1x"
scale_mode = "smooth"

# Low density (0.5x)
[[variants]]
scale      = 0.5
suffix     = "@0.5x"
scale_mode = "smooth"
This generates:

​
[[sprite_overrides]]

Per-sprite metadata overrides. Each [[sprite_overrides]] block customizes settings for a specific sprite.
​
id
string
required
Sprite ID: relative path without extension, forward-slash separated.Example: For file sprites/characters/player.png, the ID is "characters/player".
​
pivot
object
Custom pivot point for this sprite. Format: { x = float, y = float } where 0.0 is top/left and 1.0 is bottom/right.
​
nine_patch
object
Nine-patch border widths in source pixels. Format: { top = int, right = int, bottom = int, left = int }.Defines stretchable regions for UI elements like buttons and panels.

​
Example: Sprite overrides

# Player sprite with centered pivot
[[sprite_overrides]]
id    = "characters/player"
pivot = { x = 0.5, y = 0.5 }

# Enemy sprite with bottom-center pivot
[[sprite_overrides]]
id    = "characters/enemy"
pivot = { x = 0.5, y = 1.0 }

# UI button with nine-patch borders
[[sprite_overrides]]
id         = "ui/button"
pivot      = { x = 0.5, y = 0.5 }
nine_patch = { top = 8, right = 8, bottom = 8, left = 8 }

# Dialog panel with asymmetric nine-patch
[[sprite_overrides]]
id         = "ui/panel"
nine_patch = { top = 16, right = 16, bottom = 24, left = 16 }

​
excludes

​
excludes
array
Array of glob patterns to exclude from packing. Matches against sprite IDs.Example:
excludes = ["temp/**", "**/draft_*"]

​
Complete example

Here’s a production-ready configuration with all major features:
game-atlas.fpsheet
[meta]
version = "1"

# Input from multiple directories
[[sources]]
path   = "assets/sprites/characters"
filter = "**/*.png"

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

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

# Optimize layout for mobile
[layout]
max_width       = 2048
max_height      = 2048
size_constraint = "pot"       # Power of two for GPU compatibility
force_square    = true         # Square atlas for some engines
allow_rotation  = true
pack_mode       = "best"       # Densest packing
border_padding  = 2
shape_padding   = 2

# Aggressive optimization
[sprites]
trim_mode       = "trim"
trim_threshold  = 5            # Trim nearly-transparent pixels
trim_margin     = 0
extrude         = 1            # Prevent texture bleeding
detect_aliases  = true         # Deduplicate identical sprites
default_pivot   = { x = 0.5, y = 0.5 }

# Optimized output
[output]
name                = "game-atlas"
directory           = "dist/assets/"
texture_format      = "webp"
pixel_format        = "RGBA8888"
data_format         = "json_hash"
quality             = 90
premultiply_alpha   = false
texture_path_prefix = "assets/"

# MaxRects algorithm
[algorithm]
type      = "max_rects"
heuristic = "best_short_side_fit"

# Multi-resolution variants
[[variants]]
scale      = 2.0
suffix     = "@2x"
scale_mode = "smooth"

[[variants]]
scale      = 1.0
suffix     = ""
scale_mode = "smooth"

# Per-sprite customization
[[sprite_overrides]]
id    = "characters/player"
pivot = { x = 0.5, y = 0.8 }

[[sprite_overrides]]
id         = "ui/button"
pivot      = { x = 0.5, y = 0.5 }
nine_patch = { top = 8, right = 8, bottom = 8, left = 8 }

# Exclude work-in-progress assets
excludes = [
  "**/wip_*",
  "temp/**"
]

​
TexturePacker compatibility

The .fpsheet format is FastPack-specific TOML. TexturePacker uses its own .tps XML format. Settings map closely between the two tools but the file formats are not interchangeable.

​
Migration from TexturePacker

When migrating from TexturePacker:
  1. Run fastpack init to create a starting .fpsheet
  2. Map your TexturePacker settings:
    • Algorithm → pack_mode and [algorithm]
    • Size Constraints → size_constraint
    • Trim Mode → trim_mode
    • Extrude → extrude
  3. Test the output and iterate on settings

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us