[4.2.43] Atlas Assets list in SkeletonData usage

AlejMC

Hello! The short question is: is there a way to make Atlas Assets resolve the texture it's going to use from "top to bottom", meaning try to use the atlas asset on top and if it can't resolve one specific skin there go to the next as a fallback?

Our use case is the following:

We have one big Spine file with all skins (basically all our characters, enemies, npcs, and everything that share the same bone structure are in that main file + then some more as character sizes sizes are just stacked 'bones' animations)
Every time we export and pack from spine it gets large and long and overwrites too much on the Unity side (overrides texture names, uses 'default' namings usually the Spine's file name, etc)

So we have started to use CLI tools, they work great, that way we can pack new textures to new folders and just allow artists to work completely separate on their photoshop files, run PSD jsx export scripts from there while a technical artist can run packer routines by calling Spine runtime in batch mode on pack said new folders.
This last step creates a 'packed' atlased textures with the corresponding .atlas.txt files. So far so good.

Importing this file in Unity properly detects the regions and creates the corresponding material.

Now here is the part where we got stuck... original spine at some point was exported with the packing option, per folder mode, so it has some of the atlases on its default atlas.txt files, however we would like to use that only as a fallback and start using the 'separate' atlases that the spine runtime routine can create.
In our current case the spine file picks atlas region bounds that seem outdated or wrong, definitely not respecting the material that we are assigning on the new one either because removing a corresponding material found on the 'default/fallback' atlas asset it turns pink even though it properly exists on the 'added on top' atlas asset.

Does that make sense and is it even possible? Can the Atlas Asset list be used like this?

Thanks a lot in advance, great tool, our latest games are using it to our best understanding.

Misaki

AlejMC Our Unity expert, Harald, is currently on vacation, but I believe he will respond as soon as he returns, so I would appreciate it if you could wait for a detailed response.

Harald

AlejMC Now here is the part where we got stuck... original spine at some point was exported with the packing option, per folder mode, so it has some of the atlases on its default atlas.txt files, however we would like to use that only as a fallback and start using the 'separate' atlases that the spine runtime routine can create.

Unfortunately I'm not quite sure I understand why you want to "use that as a fallback" if you have CLI export scripts in place, could you please describe that part in more detail what you have in mind? In general you would normally export using your atlas export CLI scripts and arrange everything as desired, then assign the atlas assets at the SkeletonDataAsset under Atlas Assets, in the desired order.

If you want to avoid manual assignment, You could create a custom SkeletonDataModifierAsset and sort the assigned AtlasAssets as needed.

AlejMC In our current case the spine file picks atlas region bounds that seem outdated or wrong [..]

If you get wrong outdated atlas regions, this sounds as if the .atlas.txt file does not fit the atlas .png textures, like a partial commit e.g. only updating the .png files.

[..] definitely not respecting the material that we are assigning on the new one either [..]

In general you should never assign an atlas texture at a Material, these are automatically assigned upon import. This sounds like a potential source of error (which would explain incorrect regions used) if you accidentally assign an atlas page texture at the wrong material (like assigning texture with "2" in the name at material "1"). At the AtlasAsset, it's crucial that the material order is also not set to anything other than the ascending order.

[..] because removing a corresponding material found on the 'default/fallback' atlas asset it turns pink even though it properly exists on the 'added on top' atlas asset.

The AtlasAssets are just queried in order (atlas asset at Element 0 before Element 1, and so on) for the required region, in the .atlas.txt file has the required region, the material at the respective index is simply assigned. If you assign null at the respective Material element, null is assigned at the MeshRenderer for the respective submesh, which is not what you want.

Spinebot

When multiple Atlas Assets are assigned to a SkeletonData asset, the spine-unity runtime searches through them in the order they are listed to resolve regions. However, there is no built-in "fallback" priority system where it tries the first atlas, and if a region isn't found there, falls through to the next. Instead, all atlases are searched and the first match found wins — so if a region name exists in more than one atlas, the one listed first takes precedence.

The missing-region / pink material issue you're describing is most likely a path/name mismatch between what your skeleton data file expects and what the .atlas.txt file actually contains. As noted regarding this kind of setup:

If you get missing regions, it's likely the paths which are incorrect due to different top- and subdirectories used, like the .atlas.txt file containing subdir/image1 while the skeleton data file requires topdir/subdir/image1 (or the other way round). You would need to check what your .atlas.txt file contains by opening it in a text editor.

So the first thing to do is open both .atlas.txt files in a text editor and compare the region names listed there against what the skeleton data file actually references. If your CLI-packed atlas uses different subdirectory prefixes than the original export, the runtime won't be able to match them even if the image content is identical.

A few practical suggestions for your workflow:

Check region name prefixes carefully. When using Spine's CLI packer, make sure the input directory structure produces region names that exactly match what was baked into the skeleton's .json/.skel file at export time.
Put the more specific / newer atlas first in the Atlas Assets list on the SkeletonData asset, so its regions take priority over the fallback default atlas.
Remove regions from the fallback atlas that are now covered by the new atlas, to avoid ambiguity and stale UV data being picked up from the old atlas.
Use the Spine export CLI's --atlasSubdirectory or equivalent flags to control the path prefix embedded in the .atlas.txt, ensuring it matches what the skeleton file expects.

If after verifying the region names everything looks correct but you're still getting pink attachments, it may help to fully delete and reimport the affected atlas assets in Unity so that no stale cached material/texture references remain.

AlejMC

Hello! Sorry for this very late reply, I wasn't receiving notifications as I realized they were disabled on the profile settings.

Alright, let me get a second look and run on this, I think the SpineBot reply might have something there.

I'll try to come back with pictures for better explaining, but it goes like this:
Let's suppose a spine file that contains the Player Skins, a "Gunner" enemy, and a "Light Soldier" enemy.

The Spine file is called: "MainSpine.spine"
We export the Spine file (via CLI) it packs all textures (per folder mode)
- This creates the SkeletonAsset, atlas asset, a bunch of textures (MainSpine_1.png, MainSpine_2.png, etc), and materials
- This is quite unsustainable as is, so we actually rename all those textures (MainSpine_PlayerSkinX, MainSpine_LightSoldier.png, etc) and change the atlas.txt files to point to those and note "1", "2", "_N" generic naming (this is automated)
- We do have a custom shader that handles normals, extra data channels, etc so we create a base material and the ones assigned to the skins are material variants of that base material but with the properly assigned expected '_MainTex' for a skin. That's properly assigned on the spine material assets list (the one that finds the pages and all)

So far so good, this works and is great.

Now suppose that an artist creates a new enemy, "Heavy Soldier" skin, it's on Spine visible and working, it happens to use another skin as it's base for meshes, animations, etc, so it's pretty much automatic.

I was trying to:

Pack this Heavy Soldier skin on its own: this creates a "MainSpine_HeavySoldier.png" file and .atlas.txt file
Export the updated Spine file, but only the Spine, no texture packing at all.
Then in Unity the MainSpine_PlayerSkinX, MainSpine_LightSoldier.png, would continue using what they had already working, the new Heavy Soldier (which wasn't there before) would use the recently packed and exported one.
- Now, sure thing I could start by splitting the previous working ones and separate them again, however, if one extra standalone atlas asset wasn't working for me yet didn't want to break what's already working.

Hope that's more clear, but let me do some extra tests later on with the provided extra info and explanations.

Appreciated the replies, very helpful and sorry again for getting back so late afterwards.

Harald

AlejMC This is quite unsustainable as is, so we actually rename all those textures (MainSpine_PlayerSkinX, MainSpine_LightSoldier.png, etc) and change the atlas.txt files to point to those and note "1", "2", "_N" generic naming (this is automated)

This sounds as if you are using the exporter wrong. It is not intended workflow to rename single atlas pages and modify the .atlas.txt file accordingly each time, as this would be quite a terrible workflow.

Instead it would be easier to use the Spine Command Line Interface (CLI) and set the -n or --name parameter to your desired texture atlas name.

-n, --name Texture atlas name, the prefix for the atlas and PNG files.

You can checkout the export script of the spine example assets here
e.g. one of the chained export commands there is this:
-i $UNITY_BASE_DIR/raptor/images -o $UNITY_BASE_DIR/raptor/export -n raptor-pma -p atlas-1.0-square-pma.json
which exports with atlas name raptor-pma.

AlejMC Now, sure thing I could start by splitting the previous working ones and separate them again, however, if one extra standalone atlas asset wasn't working for me yet didn't want to break what's already working.

I'm not sure I understand this part. In general there should be no problem having multiple atlas assets and assigning them to the list of Atlas Assets at the SkeletonDataAsset, or did you run into problems there?

Regarding "breaking what's already working" I would say that while your workflow might currently work under some circumstances, it might get really annoying and labour intensive at scale. It might even be overall limiting in that you can't as easily do certain things dynamically via code then, be it Unity Editor code for import and build or packaging automation, or runtime code for dynamically loading / assigning atlas assets, if you should need something like that.