Overview The init command generates a .fpsheet project file with default settings. Project files store all packer configuration in one place, making it easy to share settings across your team and version control.
Basic usage Examples Default
Custom filename
Custom path
# Creates project.fpsheet in current directory fastpack init
Arguments OUTPUT
path
default: "project.fpsheet"
Path where the project file will be written. Defaults to project.fpsheet in the current directory.
Output Successful initialization prints:
Generated file structure The generated .fpsheet file contains all default settings in TOML format:
[ meta ] version = "1" [ output ] name = "atlas" directory = "output/" texture_format = "png" pixel_format = "rgba8888" data_format = "json_hash" quality = 95 [ layout ] max_width = 4096 max_height = 4096 size_constraint = "any_size" force_square = false allow_rotation = true pack_mode = "good" border_padding = 2 shape_padding = 2 [ sprites ] trim_mode = "trim" trim_threshold = 1 trim_margin = 0 extrude = 0 detect_aliases = true default_pivot = { x = 0.0 , y = 0.0 } [ algorithm ] type = "max_rects" heuristic = "best_short_side_fit" [[ variants ]] scale = 1.0 suffix = "" scale_mode = "smooth" [[ sources ]] path = "sprites/" filter = "**/*.png"
Using the project file After creating a project file, reference it with the --project flag:
fastpack pack --project project.fpsheet
Editing the project file Open the generated file in any text editor and customize the settings:
[[ sources ]] path = "sprites/characters/" filter = "**/*.png" [[ sources ]] path = "sprites/ui/" filter = "**/*.png"
[ layout ] max_width = 2048 max_height = 2048 size_constraint = "pot" # Power of two dimensions force_square = true pack_mode = "best" # Densest packing
Add scale variants # High resolution [[ variants ]] scale = 2.0 suffix = "@2x" scale_mode = "smooth" # Standard resolution [[ variants ]] scale = 1.0 suffix = "@1x" scale_mode = "smooth" # Low resolution [[ variants ]] scale = 0.5 suffix = "@0.5x" scale_mode = "smooth"
Add sprite overrides # Custom pivot for player sprite [[ sprite_overrides ]] id = "characters/player" pivot = { x = 0.5 , y = 0.5 } # Nine-patch UI button [[ sprite_overrides ]] id = "ui/button" nine_patch = { top = 8 , right = 8 , bottom = 8 , left = 8 }
Benefits of project files Version control Commit the .fpsheet file to your repository so everyone on your team uses the same packing settings:
git add atlas.fpsheet git commit -m "Add sprite packing configuration"
Reproducible builds Project files ensure consistent atlas generation across different machines and environments.
Documentation The project file serves as documentation of your packing pipeline. Add comments to explain settings:
[ layout ] # Use power-of-two for WebGL compatibility size_constraint = "pot" # Allow rotation for better density allow_rotation = true
Multiple configurations Create separate project files for different environments:
fastpack init development.fpsheet fastpack init production.fpsheet fastpack init mobile.fpsheet
Then use the appropriate file:
fastpack pack --project production.fpsheet
CLI overrides CLI flags override project file settings when both are provided:
# Use project settings but override output directory fastpack pack --project atlas.fpsheet --output dist/ # Use project settings but override pack mode fastpack pack --project atlas.fpsheet --pack-mode best
The .fpsheet format uses TOML syntax. For complete documentation of all available fields, see the Configuration reference .
See also