Sources and outputs

Sources

Packrat scans input folders and their subfolders for PNG, BMP, TGA, .ase, and .aseprite files. It flattens Aseprite frames and uses tags to form animation groups. Tilemap cels are unsupported. For APNG files, it reads only the first image.

Numbered files such as run_0.png and run_1.png form an animation. Formats that identify frames by a single key use names such as run_0000. LibGDX and Pure C store the base name and frame index separately. Static images have an index of -1.

Subfolders remain in exported names. You can also include the input folder's name by enabling root prefixes. Keep these logical paths unique across input folders: two files with the same exported name can conflict even if they are in different input folders.

Identical images normally share an atlas position while keeping separate frame entries. Active manual companion images disable this deduplication so each sprite can have different effects.

Trimming

Trimming removes transparent pixels around a frame. The exported size and offset determine whether your runtime can restore its original placement.

Mode	Pixels written to the atlas	Size recorded in metadata	Offset
None	Full source canvas	Original size	Zero
Trim	Alpha bounds plus margin	Original size	Preserved
Crop (Keep Position)	Alpha bounds plus margin	Original size	Preserved
Crop	Alpha bounds plus margin	Cropped size	Zero

The alpha threshold determines which pixels count toward the bounds. Margin keeps extra transparent pixels around those bounds. Padding separates packed frames, border leaves space at the page edge, and extrusion repeats edge pixels.

Use the original size and trim offset to draw the packed pixels where they appeared in the source canvas. The format pages explain the coordinate convention for each exporter.

Manual effects

Place a glow or normal image beside its base image. Use the same extension and canvas dimensions, with .glow or .normal before the extension:

sprite_name.png
sprite_name.glow.png
sprite_name.normal.png

Enable Glow or Normal under GENERATE. Save the project to use those settings in CLI builds. A matching companion replaces generation for that frame; frames without a companion still use the generator.

• Normal maps use the base sprite's crop and atlas position. Glow can extend beyond the source canvas and may need a different packing layout.
• Both effects use the base scale. Generator settings do not change manual pixels.
• The browser lists companions as effect sources. They are never packed as separate sprites, including when disabled or unmatched.
• Browser labels identify effects loaded from files and effects generated by Packrat.
• Ignore a companion to use generation again. An enabled companion with different canvas dimensions causes the build to fail.

Output files

Each export contains atlas images and data describing the frames. The selected format determines the data files and how they refer to the images. Choose PNG, BMP, or TGA according to what your runtime can load.

For PNG, encoding quality trades compression time for file size. TGA uses raw pixels with Fast quality and run-length encoding otherwise. The quality setting has no effect on BMP.

Output	Base filenames
One page	atlas
Multiple page images	atlas_1, atlas_2, ...
Sprites and glow	atlas and atlas_glow
Sprites and normal	atlas and atlas_normal
Glow and normal, with sprites disabled	atlas for glow; atlas_normal for normal
One effect only	atlas for that effect
CLI scale variants	atlas@0.5x, atlas@1x, atlas@2x

Each effect has its own frame data. Glow rectangles can differ from sprite rectangles, so load the metadata for the effect you are drawing. Some formats list all pages in one file; others write a data file for each page. See the format table.

Each file is replaced as a whole. If an export writes several files and a later write fails, earlier files may already have been updated. Rerun a failed export before distributing its files.

Limits

A decoded raster image can use at most 256 MiB. Aseprite cel storage has the same limit per document. Packrat does not enforce a project-wide memory limit. CLI --strict fails if active sources have reported issues.

Size diagnostics use the full source canvas, which may be larger than the trimmed frame. Rotated packing and manual page assignment are currently disabled. Effect settings must be finite; blur sigma and normal softness must be no greater than 21.