A sprite sheet JSON needs one PNG plus a data file listing, per frame, its x/y/width/height in the sheet, and usually a name or tag. Export this directly from Aseprite or an AI sprite tool rather than hand-writing it, and load it with your engine’s own frame/atlas loader.
At a glance
| Fact | Value | Source |
|---|---|---|
| Aseprite CLI flag for metadata file | –data |
aseprite.org |
| Phaser sprite sheet frame rule | all frames same size | docs.phaser.io |
| Recommended format for sprite sheets | PNG (alpha preserved) | image.rustwindy.com |
A sprite sheet’s JSON needs to describe two things for every frame: where it sits in the packed PNG (x, y, width, height), and some identifier the engine or your code can look up by name or index. Most tools that export sprite sheets also export this JSON automatically, so the structure to aim for is whatever your packer already produces – don’t hand-roll a custom schema unless you have to parse it yourself.
For testing web builds, the Playgama MCP server lets an AI coding agent publish a sandbox link directly from your IDE.
Aseprite’s CLI exports both files together: the image with --sheet <file.png> and the metadata with --data <file.json>, which “saves information about the exported sprite sheet in a JSON” (aseprite.org/docs/cli). AI sprite generators follow the same pattern – a sheet PNG plus an optional JSON descriptor you load straight into the engine (ludo.ai/docs).
What goes wrong when loading the JSON
- Phaser’s plain “Sprite Sheet” format requires every frame to be the exact same size and cannot be trimmed or rotated – if your packer trims transparent edges per-frame, use an atlas loader instead, not the sprite sheet loader (docs.phaser.io).
- Keep the PNG as PNG, not WebP/JPG, to preserve alpha exactly for pixel art and transparent sprites (image.rustwindy.com).
- Engines such as Unity and Godot have their own native import workflows for texture atlases – check your engine’s documentation before assuming a generic JSON works unmodified.
Sources
- Aseprite Command Line Interface
- Aseprite – Sprite sheet docs
- Phaser.Textures
- Image Format Comparison Guide
- Ludo.ai docs
- Playgama for developers
Related questions
Can I write sprite sheet JSON by hand?
You can, but it’s error-prone; export it from Aseprite’s CLI (–data flag) or an AI sprite tool that bundles a JSON descriptor with the PNG instead.
Does every engine use the same JSON format?
No. Phaser distinguishes a fixed-size ‘sprite sheet’ from a trimmed ‘atlas’; always use the loader that matches how your packer exported the frames.
Last updated: 01 October 2026