Sprite sheet data format improvements ("frames" in exported JSON are not very convenient to use)


The current sprite sheet data has the following format:

  "frames" : {
     "<filename> (<layer>) <frame number> <extension>" : { ... } }

(e.g. “animations (main) 10 .aseprite” means the 10th frame of “main” layer in “animations.aseprite” file)

Unfortunately, this is not as easy to parse as something like this:

  "animations.aseprite": {
    "layers" : { 
        "main": {
            "frames": [ 
                    "frameNumber": 10,

Parsing filename, extension, layer name and frame number is not very convenient when you read data from JSON, so it would be pretty great if this animation wasn’t concatenated into one string.

Any thoughts? The current sprite sheet data format doesn’t seem to be documented, so maybe it can be extended in some way?

P.S. It would also be great if calling app.command.ExportSpriteSheet returned some Lua data which can be used for further custom JSON generation, so that might solve my problems with the current format in a way.

Hi @EliasDaler, yeah one downside is that the current JSON sprite sheet is not well-documented (it’s like a “de-facto standard” for sprite sheets, but I’m not sure what is the origin of the format, maybe TexturePacker).

About the JSON format you propose, I think you will find this script useful: GitHub - dacap/export-aseprite-file: Little Aseprite script to export the data inside a .aseprite (it can be adjusted to export whatever you need to export)

Yeah, it looks similar to TexturePacker’s file format, so I guess I’ll need to learn to parse it anyway. :slight_smile:

As for the script - the problem is that I want to get info about the generated package sprite sheet - I can’t extract that data unless I actually call app.command.ExportSpriteSheet and then parse the output JSON.

The JSON format is similar to the format TexturePacker writes but it is not the same. Aseprite already added lots of data which is not written by TexturePacker. And TexturePacker writes data (like the animations map) which Aseprite doesn’t write. So there is no standard and unfortunately there isn’t even a tool-specific format documentation…

There would be no harm if Aseprite would add frame number, layer and tag properties to the frame objects while keeping everything else as it is so we don’t have to parse these information from the filename.

I think this would be very helpful because when enabling Split Layers or Split Tags option during export the array indices of the frames within the JSON are not in sync with the frame indices anymore and we have to parse the filename property instead which is very complex because the format is not fixed and can be changed to anything during the export.

Just in case I don’t know if GitHub - dacap/export-aseprite-file: Little Aseprite script to export the data inside a .aseprite might help in your cases. It export all the information from .aseprite files in a custom JSON + png files. I might add an extra option to create the sprite sheet (export just one png).

In the future we might consider to integrate this script to the program (or re-implement inside Aseprite).

1 Like

I’m not sure what “export all the information” means. The JSON is the file which is actually embedded in games so it must not include all the meta data of Aseprite which only makes sense in the editor. Only the data to actually import the sprite sheet and correctly render the frames is needed. And currently this is not the case when “Split Layers” or “Split Tags” option is enabled during export. Frame numbers referenced by tags and slices are useless because the frames array/object contains multiple entries per frame and only the filename MAY contain the frame number, layer name and tag name needed to correctly parse the frames.

My suggestion is simply adding three properties to the frame object:

  • frameNumber (“frame” is already taken unfortunately). Can be omitted when sprite sheet is not split by layer or tag because then the array index is already the frame number. But doesn’t hurt to always add this property.
  • layer (Name of the layer, only present when sprite sheet is split by layer)
  • tag (Name of the tag, only present when sprite sheet is split by tag)

In my opinion there is no need to change anything else. Sure, the flat frames array/object is not an ideal representation but I think compatibility is more important. And with these three new properties we can easily transform the flat array to whatever we need.

1 Like