Skip to main content
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

1

Generate default file

fastpack init
Creates a project.fpsheet in the current directory with all default settings.
2

Customize settings

Edit the file to configure your packing settings.
3

Use in commands

fastpack pack --project atlas.fpsheet
fastpack watch --project atlas.fpsheet
CLI flags override project file values when both are provided.

​
Full example

# 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

​
[[sources]]

Multiple [[sources]] blocks are allowed. Each adds a set of sprites to the pack.
Root directory to search. Defaults to "sprites".
[[sources]]
path = "assets/sprites"
Glob pattern relative to path. Defaults to "**/*.png".
[[sources]]
path = "sprites"
filter = "**/*.{png,jpg}"

​
[layout]

Controls atlas dimensions and packing behavior.
Maximum atlas width in pixels. Default 4096.
[layout]
max_width = 2048
Maximum atlas height in pixels. Default 4096.
[layout]
max_height = 2048
Force an exact width, overriding max_width.
[layout]
fixed_width = 1024
Force an exact height, overriding max_height.
[layout]
fixed_height = 1024
Pixels of empty space around the atlas edge. Default 2.
[layout]
border_padding = 4
Pixels of empty space between sprites. Default 2.
[layout]
shape_padding = 1
Allow 90° sprite rotation to improve fit. Default true.
[layout]
allow_rotation = false
Packing algorithm effort level:
  • "fast" — Single-pass strip packer; fastest, largest atlas
  • "good" — MaxRects single pass; good density
  • "best" — Width search; densest result (default)
[layout]
pack_mode = "best"
Constrain atlas to square dimensions. Default false.
[layout]
force_square = true
Valid atlas dimension modes:
  • "any_size" — No constraint (default)
  • "pot" — Power of two
  • "multiple_of_4" — Divisible by 4
  • "word_aligned" — Divisible by 2
[layout]
size_constraint = "pot"

​
[sprites]

Controls sprite pre-processing.
How to handle transparent borders:
  • "none" — Pack full image
  • "trim" — Strip borders; store offset (default)
  • "crop" — Crop to opaque region
  • "crop_keep_pos" — Crop with negative offsets
  • "polygon" — Convex hull polygon
[sprites]
trim_mode = "trim"
Alpha ≤ this value is treated as transparent. Range 0–255. Default 1.
[sprites]
trim_threshold = 5
Transparent pixels kept around the trim edge. Default 0.
[sprites]
trim_margin = 1
Edge pixels to repeat outward before packing. Default 0.
[sprites]
extrude = 2
Deduplicate pixel-identical sprites. Default true.
[sprites]
detect_aliases = false
Fallback pivot for all sprites. Default { x = 0.0, y = 0.0 }.
[sprites]
default_pivot = { x = 0.5, y = 0.5 }
Round trimmed dimensions up to the nearest multiple. 0 disables. Default 0.
[sprites]
common_divisor_x = 4
common_divisor_y = 4

​
[output]

Controls output files and formats.
Base filename without extension. Default "atlas".
[output]
name = "game_sprites"
Output directory path. Default "output".
[output]
directory = "build/assets"
Image compression format:
  • "png" — Lossless PNG (default)
  • "jpg" — Lossy JPEG; no alpha
  • "webp" — WebP
[output]
texture_format = "webp"
Pixel encoding. Default "RGBA8888".
[output]
pixel_format = "RGB565"
Metadata format:
  • "json_hash" — Generic JSON object (default)
  • "json_array" — JSON array
  • "phaser3" — Phaser 3 format
  • "pixijs" — PixiJS format
[output]
data_format = "phaser3"
Lossy encoding quality, 0–100. Default 95.
[output]
quality = 85
Multiply RGB by alpha before encoding. Default false.
[output]
premultiply_alpha = true
String prepended to texture filenames in data files. Default "".
[output]
texture_path_prefix = "assets/"

​
[algorithm]

Selects and configures the packing algorithm. 
[algorithm]
type      = "max_rects"
heuristic = "best_short_side_fit"
Available heuristics:
  • best_short_side_fit
  • best_long_side_fit
  • best_area_fit
  • bottom_left_rule
  • contact_point_rule

​
[[variants]]

Each [[variants]] block produces an independent set of output files at the specified scale.
Scale factor. 0.5 halves dimensions; 2.0 doubles them. Default 1.0.
[[variants]]
scale = 0.5
suffix = "@0.5x"
Appended to output filenames before the extension. Empty by default.
[[variants]]
scale = 2.0
suffix = "@2x"
Resampling filter:
  • "smooth" — Lanczos3; high quality (default)
  • "fast" — Nearest-neighbour; crisp pixel art
[[variants]]
scale = 2.0
scale_mode = "fast"

​
[[sprite_overrides]]

Per-sprite metadata overrides.
Sprite ID: relative path without extension, forward-slash separated.
[[sprite_overrides]]
id = "ui/button"
Normalized anchor point.
[[sprite_overrides]]
id = "player/idle"
pivot = { x = 0.5, y = 1.0 }
Border widths in source pixels.
[[sprite_overrides]]
id = "ui/panel"
nine_patch = { top = 8, right = 8, bottom = 8, left = 8 }

​
Multiple variants example

Generate multiple resolution variants in a single pack: 
# Full resolution
[[variants]]
scale = 1.0
suffix = "@1x"
scale_mode = "smooth"

# Half resolution for mobile
[[variants]]
scale = 0.5
suffix = "@0.5x"
scale_mode = "smooth"

# Double resolution for retina displays
[[variants]]
scale = 2.0
suffix = "@2x"
scale_mode = "smooth"
This produces:

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us