Spritesheet guide
Turn a spritesheet into ordered Aseprite frames
Slice an exact spritesheet grid or use supported atlas JSON metadata to rebuild frames, timing, trimming, and placement in Aseprite.
A spritesheet stores multiple rendered frames in one image. This converter supports two deliberately different paths: an exact rectangular grid and a PNG paired with supported frame metadata. Choose based on how the sheet was packed, not merely on the file extension.
Exact grid slicing
Grid mode requires positive whole-number values for frame width, frame height, rows, and columns. The calculated grid must equal the image dimensions exactly:
frame width × columns = spritesheet width
frame height × rows = spritesheet heightFor a synthetic 256×128 sheet with four columns and two rows, every frame is 64×64 and the output contains eight frames. A 257×128 version does not fit that grid because the extra horizontal pixel would be left over; the importer rejects it rather than cropping or guessing.
Row-major and column-major order
Row-major order reads left to right across the first row, then continues on the next row. Column-major order reads top to bottom down the first column, then moves right. Both use the same pixels; only the mapping from cell position to frame index changes.
| Order | Frame positions |
|---|---|
| Row-major | (row 0, col 0), (0,1), (0,2), (1,0), (1,1), (1,2) |
| Column-major | (row 0, col 0), (1,0), (0,1), (1,1), (0,2), (1,2) |
Padding and spacing are pixel data
Uniform transparent padding inside every cell is safe because it becomes part of each frame. Outer margins, separator lines, or uneven gaps are not automatically recognized. If those pixels make the grid dimensions fail, crop or repack the source. If they fit inside cells, they will appear in the generated cels.
Grid mode has no setting for arbitrary per-frame rectangles. Do not force a trimmed or tightly packed atlas into an invented grid.
Metadata-driven atlas mode
PNG + JSON mode accepts a supported root-level frames array or object map. Each entry supplies an in-bounds rectangle and may supply a positive duration. Aseprite-style metadata can also preserve the supported frame-tag name, range, and direction fields.
TexturePacker-style entries may use the supported 90-degree clockwise packing convention. When trimmed is true, complete and consistent sourceSize and spriteSourceSize data let the importer restore the pixels onto a transparent full-size frame. Incomplete placement data is rejected because guessing would introduce animation jitter.
| Question | Grid mode | PNG + JSON mode |
|---|---|---|
| Frame boundaries | Equal cells from rows, columns, width, and height | One validated rectangle per metadata entry |
| Ordering | Row-major or column-major | Metadata array order or object entry order |
| Timing | 100 ms default | Supported per-frame duration, otherwise default |
| Trimming | No automatic reconstruction | Restored only with complete supported placement metadata |
| Rotation | No | Supported documented convention |
| Original layers | Not present | Not present |
Practical workflow
- Choose grid mode for one uniformly divided PNG, or PNG + JSON for an exporter-produced pair.
- In grid mode, inspect the overlay and exact-fit status before converting.
- In JSON mode, select the matching image and metadata together. Similar filenames do not prove they are a pair.
- Verify output canvas size, frame count, order, transparency, and at least one edge or trimmed frame.
- For JSON, also verify a short and long duration, a rotated frame if present, and frame tags if the metadata contains them.
Why conversion fails
- The grid product does not equal the decoded image dimensions.
- A frame rectangle is zero-sized, negative, fractional where an integer is required, or outside the PNG.
- The JSON schema is nested or otherwise outside the supported atlas families.
- Trimmed placement metadata is missing or inconsistent across frames.
- Rotation or tag metadata contains an unsupported value.
- The JSON belongs to another image.
If every frame is available separately, a PNG sequence is the simplest fallback. For ambiguous validation, consult troubleshooting rather than deleting metadata fields at random.