The order of the parameters is important. Some parameters are used by later parameters, like -i and -o, while others are "terminal" and perform an action, like -e. When -e is encountered the export is performed, so it uses the output path in the .export.json file rather than the path specified with -o. We'll see about making it an error to specify non-terminal parameters at the end of the parameter list.

When Spine needs to render images it uses OpenGL (and similar technology) and has to setup nearly everything needed to run the editor as normal. When exports don't require OpenGL, they are run "headless" and exporting is a lot faster. Since you are packing an atlas, unfortunately the export takes long. It will be faster in v4 though.

Nick wrote

You may want to consider reading all the parameters into a dictionary first and parse accordingly to eliminate the ordering restriction.

Order is important by design. You can write export scripts like this:
spine-runtimes/export.sh at 3.8

Nick wrote

Can you add a new parameter, say -skin, to override the skin export checkbox values and have command line being able to export certain skin to certain folder?

The could be useful. Maybe we could make it more general purpose, allowing any values in the settings JSON to be overwritten. Eg something like:

spine -i project.spine -o dir 

---

set skin=something 

---

set packAtlas/rotation=false -e settings.export.json

Ah, I thought you meant to choose a skin for image of video export. You mean instead to export JSON or binary data, but only for a single skin? Exporting a partial skeleton is not a workflow we recommend. Can you please explain your needs for this?

Your kids project binary export is 92KB and 56.7KB zipped. Exporting the same but just one skin is 13-33KB zipped. That is not much savings per skeleton and actually makes the total amount of data larger, as some data is duplicated in each skeleton. 56KB is already very small, eg it is common to see multiple images on a website that size or larger. Other projects may have larger exports, but are still likely to be small enough to not be worth the extra trouble of exporting the skeleton for each skin.

The skeleton data is very small and I haven't yet seen a use case where it makes sense to do a partial export of the skeleton.

Loading that much data at runtime is also unlikely to make a difference. Note you don't need to load the images for the unused skins.

Nick wrote

Can't just consider the skeleton export file size without the texture...Content updates could be including both binary data and texture.

Understood, but the skeleton data file is separate from the images. The images are generally much larger and it can make sense to break them up per skin, or however else is needed. That can be done while keeping a single skeleton data file, which I still think is the simplest and easiest solution.

Nick wrote

In my game, almost each character, except those mix and match player heroes, are saved under its own folder along with their other configuration files. I just found this much easier to work when they are grouped properly.

It makes sense to organized the images this way. Are there reasons using a single skeleton data file would be problematic with this organization?

I don't mean to be argumentative, I just want to fully understand the use case. Interrogation like this is helpful not just for considering this feature, but when thinking about the whole application.

Nick wrote

It would be very appreciated if such command can be added.

By adding such a feature, it will encourage the export of partial skeletons. For us to do that, it needs to be a workflow we want to encourage, or at the very least we think makes sense in some cases even if it is generally suboptimal in most.

For example, since the beginning of Spine we've gotten requests to export a skeleton to multiple files, for example each animation in a separate file. Usually the rationale is to be able to update a skeleton piecemeal. This is a Bad Idea for a number of reasons: it's a prematurely optimization since the entire skeleton data is small, but mostly that it will be difficult to manage (ie a huge mess) because the animations have dependencies on the skeleton data. We declined to add such an export and Spine's usage benefits from the simplicity.

Your exporting each skin as a separate skeleton is of course a different solution than that, it was just an example where sometimes it's better for us not to enable a workflow. If you are adamant about your solution, it may be easiest to write a tool that takes an export containing all the skins and saves a file for each skin that contains the entire skeleton but only that skin. Writing a tool for JSON is easier than binary, so you could process the JSON, then use the Spine CLI to convert the JSON files to binary. Here's some Java that manipulates skeleton JSON, it could be used as a base for such a tool.

Nick wrote

the runtime will give me error because the SAME_SKELETON_FILE always failed to find some sprites due to the texture file only contain sprites from selected skin. That's why I concluded that the skeleton file need to be precise to only export with skins used for it to load correctly.

See here:
Loading Skeleton Data - Spine Runtimes Guide: JSON and binary data

SkeletonJson/SkeletonBinary load the skeleton data. When an attachment is encountered, an AttachmentLoader is used to create and partially configure the attachment. It is most common to use AtlasAttachmentLoader, which uses the attachment's path to find a texture region in a texture atlas. If it can't find a region, it throws an error, which is likely what you encountered.

Using AtlasAttachmentLoader is not mandatory. You can provide your own AttachmentLoader when the SkeletonJson/SkeletonBinary is created. This allows you to:

1) Customize how attachments are created. For example, you could subclass an attachment class to store additional data or modify its behavior.

2) Do any preparation necessary to render the attachment later. For example, AtlasAttachmentLoader sets the RegionAttachment rendererObject and MeshAttachment rendererObject to the region from the texture atlas (note it also gives the region to the attachment to set the UVs), then rendering code specific to the game toolkit in use gets the renderer object and knows how to draw it.

Your AttachmentLoader can customize this. For example, you don't have to use a texture atlas, you could prepare SVG or do whatever else you need. Note that you may need to also customize the skeleton rendering to match.

Finally getting around to the point of all this fantastic storytelling, your AttachmentLoader doesn't have to set the renderer object at all. Note that the attachment's skin is passed to the AttachmentLoader. You could copy/paste AtlasAttachmentLoader and modify it to skip looking up atlas regions except for a particular skin. Of course you probably won't be able to render attachments with no renderer object, but that can be OK if you know you don't want to render those anyway, or you could resolve the renderer object later.

Some projects have thousands of attachments and they use an AttachmentLoader that doesn't load any images. Later, they configure all their skeletons with the attachments based on the game state, then they load the images needed only for those attachments (you may want to also consider attachments set by animations). Some projects even pack an atlas at runtime containing only the necessary images (spine-unity has utility functions to do this).

You might notice the AttachmentLoader methods say you can return null to skip loading the attachment completely. This could save you a little bit of memory and load faster, since it won't bother creating and populating attachment objects for attachments you know you won't render. Be wary of doing this for meshes though, if null is returned for a source mesh, all linked meshes for that source mesh should also return null. Since you only get the skin, name, and path of the mesh, there's not actually enough information to know if it's a source mesh. We should improve this.

Nick wrote

What does "partial skeleton" means?

I mean that the data export is a configuration of the skeleton that differs from the project file. Your use case at least has the whole skeleton and the difference is just which skins are included, so it's not as bad as, for example, exporting animations to separate files.

Nick wrote

If those skin export check boxes are evil, they should not be exist in the first place

It's a pretty different scenario to see a skin in the editor and not want it exported for reasons versus exporting the same skeleton many times with different skins.

Nick wrote

what you mentioned about writing a tool to parse and extract the json and doing binary conversion, that sounds like a lot of work

Neither are terribly hard really. The JsonRollback tool almost does what is needed already. It's more about whether setting the skin export flag from the CLI is the right thing to add, as well as us having thousands of not terribly hard things on top of the many hard things we are working on.

I certainly understand not having enough time in the day! A custom AttachmentLoader is normal Spine Runtimes usage though. Maybe it sounded more complex than it is, as I wanted to give an understanding of the whole thing. The simplest thing you can do is copy/paste AtlasAttachmentLoader and simply not throw an error if the region is not found in the atlas. That way you can load your skeleton data with an atlas that only has images for one skin. I would recommend this rather than skin export checkboxes or JSON processing.

Modifying AtlasAttachmentLoader would work yeah. Or you can pass the attachment loader when you create the SkeletonJson or SkeletonBinary. There is a constructor that takes an AttachmentLoader.

Nick wrote

I don't see I could pass a new AtlasAttachmentLoader to the runtime. It is making its instance internally.

Coming back after some time to make this part clear. If you create a SkeletonJson or SkeletonBinary with the constructor taking a TextureAtlas, then it uses AtlasAttachmentLoader:

var textureAtlas = ...
var loader = new SkeletonJson(textureAtlas); // Uses AtlasAttachmentLoader.

However, you can provide your own AttachmentLoader to the constructor. Eg:

var loader = new SkeletonJson(new MyCustomAttachmentLoader());

That way your AttachmentLoader implementation is in your codebase and you don't need to modify the runtimes. You can pass your AttachmentLoader any number of atlases or whatever is necessary.

Also, I've reading through this thread again. I think the best solution is to pack each atlas and use your own AttachmentLoader. For example, if your images are like this:

images/skin1/head/red.png
images/skin2/head/green.png

Then you might want to run the packer on each skin folder. That would give you multiple atlases and names in each atlas relative to the packed folder, eg head/red.png or head/green.png.

Next, the AtlasAttachmentLoader has this code to find a mesh's atlas region (varies a little per runtime):

public MeshAttachment newMeshAttachment (Skin skin, String name, String path) {
   AtlasRegion region = atlas.findRegion(path);
   if (region == null) throw new RuntimeException("Region not found in atlas: " + path + " (mesh attachment: " + name + ")");
   MeshAttachment attachment = new MeshAttachment(name);
   attachment.setRegion(region);
   return attachment;
}

That won't find any regions because the name parameter will be the name in Spine, which is relative to the images folder, eg skin1/head/red.png while our atlas has the name head/red.png. However, the skin is passed in, so we could easily fix it by changing this line (in a copy of AtlasAttachmentLoader):

AtlasRegion region = atlas.findRegion(skin.getName() + "/" + path);

Next, if needed we can customize how to handle a region not being found. We could throw an error, as the code above does, or we could do something like, like look in additional atlases.

Or, we could return null, which means the skeleton will not have the mesh attachment at all. Note that if the mesh is a source mesh and you need to use one of its linked meshes, it will cause an error to return null.

Or, we could just return the attachment without setting its region. That is the safest, as you can still use its linked meshes, but it means trying to render the regionless attachment will fail. That is probably fine, since if you don't have a region for the attachment, it's probably because you won't be rendering it.

I don't see customizing AttachmentLoader as being a complex solution. It requires changing only a few lines of code and is the way we have designed for the runtimes to be customized for exactly situations like yours. We provide a default solution (for using a single atlas) and customizing AttachmentLoader is the path to take if you want something else. I'm all for making things simpler for you, but there are many ways users might want to customize how attachments and atlas regions are resolved beyond using a single atlas.

Let's explore what it would look like to provide you with something out of the box that solves your problem without customizing AttachmentLoader yourself. I think you'd pack an atlas per skin, as I described above, then you'd use an AtlasSkinAttachmentLoader which 1) prefixes skin + "/" to the name and 2) doesn't set regions on attachments when no region is found. To be clear, your code would look like:

var loader = new SkeletonJson(new AtlasSkinAttachmentLoader(atlas));

We could do this, but I'm not sure how many people could make use of that exact behavior. Also, if you need anything even slightly different, you'd need to customize AttachmentLoader yourself anyway.

Note the above solution does not require a -skin CLI parameter. I am not convinced it is a good idea to export the JSON or binary skeleton data multiple times, with each export only containing a subset of skins. The duplication isn't great and the solution only helps a specific use case. Instead of reducing the data in the skeleton data so AtlasAttachmentLoader can be used, I think it is better to customize AttachmentLoader.