CLI: frame tags incorrect when exporting a spritesheet from multiple files

[alexgorcrom]

While running the bellow command (via gitbash for the path niceties) over two different files, each with a single layer and multiple tags:

 ~/Downloads/Aseprite-v1.2.40/Aseprite-v1.2.40/Aseprite.exe -b king.aseprite silver_knight.aseprite --sheet ../spritesheets/characters.png --scale 2 --sheet-pack --list-tags --filename-format {tag}_{tagframe} --format json-array --data ../spritesheets/characters.json

The produced json has all the frames in the array, however the produces frame tags section in the meta object is problematic:

{
  ...
  "meta": {
    ...
    "frameTags": [
      { "name": "king_idle", "from": 0, "to": 7, "direction": "forward" },
      { "name": "king_run", "from": 8, "to": 15, "direction": "forward" },
      { "name": "king_death", "from": 16, "to": 21, "direction": "forward" },
      { "name": "king_attack1", "from": 22, "to": 25, "direction": "forward" },
      { "name": "king_attack2", "from": 26, "to": 29, "direction": "forward" },
      { "name": "king_attack3", "from": 30, "to": 33, "direction": "forward" },
      { "name": "king_hit", "from": 34, "to": 37, "direction": "forward" },
      { "name": "silver_knight_idle", "from": 0, "to": 10, "direction": "forward" },
      { "name": "silver_knight_run", "from": 11, "to": 18, "direction": "forward" },
      { "name": "silver_knight_attack1", "from": 19, "to": 25, "direction": "forward" },
      { "name": "silver_knight_attack2", "from": 26, "to": 32, "direction": "forward" },
      { "name": "silver_knight_death", "from": 33, "to": 43, "direction": "forward" },
      { "name": "silver_knight_hit", "from": 44, "to": 47, "direction": "forward" }
    ]
  }
}

From the above it is both the king_idle and silver_knight_idle have overlapping from->to frame numbers. This makes it pretty much impossible to extract which frames in the array are meant to be for which tag, when attempting to do something as follows (in peudo code):

json frames = json_get_array( root, "frames );
json frame_tags = json_get_array( json_get_obj( root, "meta" ), "frameTags")

for( tag in frame_tags ) {
  int from, to;
  if( tag.name == "<tag>" ) {
    from = tag.from;
    to = tag.to;
  } 
  for( i = from; i <= to; i++ ) {
    extract_frame( frames, i );
  }
}

Aseprite and System version

• Aseprite version: 1.2.40, portable
• System: Windows

[Gasparoken]

Thanks for this report! Yes, the meta info won't be useful since the tag frame range is referred to the original sprite frame ranges.
The solution could be accumulate the frame count along all the sprites, but this will work in a few special case:

• Sprite sheet as result of sprite concatenation of sprites AND
• One layer on each sprite, or don't no use --split-layers (the order of the array won't be as expected) AND
• Don't use --split-tags if empty cels are present on one of your sprites (the order of the array won't be as expected)

So, I think a more general approach to extract a frame sequence of a particular tag is doing:

json frames = json_get_array( root, "frames );
string tagToextract = <tag name to extract>;
json tagFramesToExtract = {};
for (frame in frames) {
  if (frame.name.find(tagToextract)) {
    tagFramesToExtract.push_back(frame);
  }
}
for(int i = 0; i < tagFramesToExtract.size(); i++) {
  extract_frame( tagFramesToExtract, i );
}

Note: If you use --split-layers you should add more code to compose the layers found on tagFramesToExtract

I'm not sure if we should add a special option to adapt the tag index to match the frame array. @dacap what do you think?

[dacap]

Hi @alexgorcrom, in your specific case, as you are creating a texture atlas from several sprites, I'd suggest to use --filename-format "{title}_{tag}_{tagframe}" so you can find the name of the original sprite + the tag + tagframe (so you can know to which sprite the tag belongs).

[dacap]

Just in case I forgot to say, in the specific case of texture atlases, you should match the frame of the tag with the tagframe in the filename field (you cannot use the index of the general json frames array directly).

[alexgorcrom]

Hello @dacap and @Gasparoken, I agree that the more general solution is indeed to use the name field in the frame to find the frames to extract. Initially I was struggling to see the value in having the frame counter be reset for each sprite, but if the mentality is that it is used in the filename, unlike how I approached the problem, then it does indeed make sense for it to behave that way.

Having said that I do somewhat feel that it defeats the purpose of being able to represent the frames as an array, since looping through an array (especially where the order of frames is not guaranteed as you seem to imply) looking for a particular string is going to be far worse performance wise (admittedly at scale) than simply constructing the expected string and finding the name within the json object (map) via what I would presume any decent json handling library will store internally as a hash. Whereas (in my opinion) the value of arrays, lies primarily in their ability to be directly indexed. And if I were to personally design a file format around the ability to represent data as either an array or a map, I would be looking to maximize the strengths that each representation provide - granted such a design would come at the cost of uniformity.

I guess an argument could be made that representing the frames in a texture atlas as an array is useful if you simply want to extract all frames without needing/caring upfront about the details. But this appears to be a very narrow use case of arrays.

[dacap]

@alexgorcrom I think the "from" and "to" field are correct, in a way that they represent the original information of each sprite (useful information in the gameengine), but not useful information to consume the json array data, probably we could add an extra field in the "frameTags" for each tag, e.g. something like this (this new "baseIndex" field should appear only for "json-array" and when multiple sprites are specified as input of the sprite sheet, which is only possible through the CLI at the moment):

{
  ...
  "meta": {
    ...
    "frameTags": [
      { "name": "king_idle", "from": 0, "to": 7, "baseIndex": 0, "direction": "forward" },
      { "name": "king_run", "from": 8, "to": 15, "baseIndex": 0, "direction": "forward" },
      { "name": "king_death", "from": 16, "to": 21, "baseIndex": 0, "direction": "forward" },
      { "name": "king_attack1", "from": 22, "to": 25, "baseIndex": 0, "direction": "forward" },
      { "name": "king_attack2", "from": 26, "to": 29, "baseIndex": 0, "direction": "forward" },
      { "name": "king_attack3", "from": 30, "to": 33, "baseIndex": 0, "direction": "forward" },
      { "name": "king_hit", "from": 34, "to": 37, "baseIndex": 0, "direction": "forward" },
      { "name": "silver_knight_idle", "from": 0, "to": 10, "baseIndex": 38, "direction": "forward" },
      { "name": "silver_knight_run", "from": 11, "to": 18, "baseIndex": 38, "direction": "forward" },
      { "name": "silver_knight_attack1", "from": 19, "to": 25, "baseIndex": 38, "direction": "forward" },
      { "name": "silver_knight_attack2", "from": 26, "to": 32, "baseIndex": 38, "direction": "forward" },
      { "name": "silver_knight_death", "from": 33, "to": 43, "baseIndex": 38, "direction": "forward" },
      { "name": "silver_knight_hit", "from": 44, "to": 47, "baseIndex": 38, "direction": "forward" }
    ]
  }
}

In this way we should be able to access to the specific frame as:

frames[ (frameTags[i].baseIndex ?? 0) + frameTags[i].from ]

Without breaking backward compatibility with developers that are using the current from/to data.

[alexgorcrom]

@dacap I totally agree that this is probably the most elegant way of handling the indexing of the json array use case.

@Gasparoken also raised an interesting point in the first comment, and that is when multiple layers are present in a single sprite and --list-layers is used. In this case I guess the number of total frames that need to be extracted (assuming all layers are required) would be some multiple of the layer count. The current implementation seems to interleave by tag rather than by layer, and if this is guaranteed to be the case then it should be easy enough to address the frames as:

frames[ (frameTags[i].baseIndex ?? 0) + frameTags[i].to * LayerNumber + frameTags[i].from )

Having run a quick test of the command in the initial comment along with --list-layers appended resulted in a situation where all the layers are added to the layers array with no information regarding which sprite the layers come from. This particular scenario would not only impact the current discussion but it would appear to also impact the more "traditional" approach of searching for frames by name (either in array or map mode), as if you had the set of layers [layer_1 /*file1*/, bob /*file2*/, joe /*file2*/] then someone trying to construct the string base on sprite + layer + tag + ... would end up in a situation where you would be searching for bob and joe in file1, and layer_1 in file2 potentially causing errors on import.

In line with the adding a baseIndex to the tags section, an origin field could be added to the layers objects when multiple sprites are merged together via the cli, or even at all times to make it easy for software to examine it regardless of whether it was constructed via the GUI or CLI (though I will admit this will probably appear odd to anyone examining the JSON in the usual use cases), and since we are discussing adding additional fields there could also be a layerNumber field on the layers objects only in the case of the frames being stored in the array, to better facilitate the indexing from above

[Gasparoken]

To accomplish all requirement you mentioned the better approach is to use

• --filename-format "{title}_{layer}_{tag}_{tagframe}".

You have all the information in any case. Anyway, I think the new base index is a perfect option for the common NO split layers case.

Clarification:

• --list-layers: when using json, it adds a layers field in the meta field with the names of the layers.
• --split-layers : when using json, it splits the the frame set for each layer into the json frames array (example: if you have an 8 frame sprite with 2 layers, the total number of items in the array frames using --split-layers + NOT ignore-empty will be 16).

So you can have multiple layers in your sprites, the only requirement to match array indices to frames is not to use --split-layers (--list-layer has no influence on the array ).

[alexgorcrom]

Apologies, I think I misunderstood your initial comment, but in my comment I was indeed talking about --list-layers and the metadata that is generated. My point in the final paragraph is that the {title}_{layer}_{tag}_{tagFrame} is somewhat broken when there are multiple layers involved (no matter whether the frames are stored as a json-array or a json-obj).

For the concrete details of the test, there were two files:

• king.aseprite (1 layer, king)
• silver_knight.aseprite (2 layers, knight & "Layer 1")

--list-layers was used to produce the layers metadata, and the resulting metadata is as follows:

{
  ...
  "meta" : {
    ...
    "layers": [
      { "name": "king", "opacity": 255, "blendMode": "normal" },
      { "name": "knight", "opacity": 255, "blendMode": "normal" },
      { "name": "Layer 1", "opacity": 255, "blendMode": "normal" }
    ]
  }
}

Now when constructing the {title}_{layer}_{tag}_{tagFrame} format string it is unclear to which title, layer belongs as in the case of king.aseprite you will start looking for the strings of the form king_king_..., king_knight_... and king_Layer 1_..., while for silver_knight.aseprite you will end up with silver_knight_king_..., silver_knight_knight... and silver_knight_Layer 1_.... Obvious in the case of king the knight and Layer 1 strings would be invalid, while for silver_knight the king strings would be invalid. Actually thinking about it, it doesn't matter whether it is a single layer in each sprite file, or some combination of number of layers this will break because at the very least for every sprite file there will be at a minimum a missing layer in the other sprite files.

If a game engine is used to building the strings with the above pattern and is relatively strict with having to find all information this will generate a whole class of errors. In the case where the metadata is generated via the GUI (and by virtue of the fact that only a single sprite exists in the metadata) everything "just works" because there is the inbuilt assumption that the layers metadata can only come from a single sprite file.

[Gasparoken]

To distinguish title, layer and tag you can create your own separator convention. Examples:

• --filename-format "title§{title}_layer§{layer}_tag§{tag}_{tagframe}"
• --filename-format "{title}_${layer}_${tag}_{tagframe}"
• --filename-format "{title}___{layer}___{tag}___{tagframe}"

If your custom separator is not used in the title, layer and tag names, this will be unequivocal.

Anyway, I'll keep the topic open if other game developers want to give an impression on this topic.

In summary, you wish to have more info in the meta field, so that you can choose the correct frame in the frames array without checking every frame.name (this task is mostly relevant when using CLI with multiple aseprite files).

[alexgorcrom]

@Gasparoken You are totally missing my point. I am well aware that the format string can be modified as one would desire, so that the string construction/parsing can be done with whatever format one would like.

My point is that the layers metadata is invalid for all cases where the layers array is present and the texture atlas is composed of more than one sprite (aseprite file). The format of the name is irrelevant (it does need to contain the layer name), and also the method of storing the frame data is irrelevant. As I (attempted to) describe above the issue is that there is no information in the layer objects to distinguish from which sprite it comes from thus leading to either having to construct all possible string names and tolerate not finding some, which is indistinguishable from actually missing frames.

If you are arguing that one should effectively read through the name of every frame, parse the string into the individual items, and then perform manual groupings of the items (title, layer, tag, etc.), then my question to you is what is the point of having metadata in the first place since all the information one could possibly need is in the frame name?

[dacap]

@alexgorcrom we're going to review the atlas generator because it's not ready to fully work on all cases (mainly with tags, and split layers as you saw). To finally "fix" this issue I think we should provide a way to import a JSON file created from several files, and converting it to their respective original sprites.

In a perfect world we should have in the UI:

1. A way to specify several sprites in the "Export Sprite Sheet" dialog and create the texture atlas + JSON file
2. A way to import that same JSON to create the original sprites

I think the only way to finally provide a working "texture atlas" generation is being able to provide the 2 point. I'll write a new issue about this point this one for this specific case.

Two possible inmmediate "easy to implement" fixes:

1. Provide the "baseIndex" field for tags
2. Provide a "sprite" field for each layer with the title of the original file name (or probably customized filename format, or something that can be used to match layer <-> sprite sheet item)