• Editor
  • Spine editor and runtime version management

When a new version of Spine is available, it will ask at start up if you want to update to the new version. Before clicking Yes, you should consider what runtimes you are using (if any). Often Spine versions have features that are not yet supported by all official runtimes. In other cases, you may be using a 3rd party runtime or a game toolkit whose dev team integrates Spine on their own (such as GameMaker) and they are unlikely to immediately support all the features of a new Spine release.


Animators should freeze their Spine editor version to match the Spine version supported by the runtime being used. Only when the runtime is updated to support a newer Spine version should animators update their Spine editor version to match.

For the official Spine rutimes, each runtime webpage tells what Spine version is supported and lists any caveats for that runtime. Note that spine-libgdx is the reference runtime implementation and it is always up to date for every Spine release, since Spine uses it internally.

People have asked why we release a new Spine version before runtime support is available. Doing this gives animators the option to begin using new features as soon as possible. Not all animators are blocked by runtime support and they don't mind continuing their work until the runtimes are updated. Also, some animators are exporting to images/video and don't need runtimes at all. Even if we did delay Spine releases until the runtimes are ready, it would still take some time for 3rd parties to update their game toolkits, so many of you would still need to be aware of when you should update your Spine version.

When you have a dependency on other tools and software, there is just no getting around being weary about when you update the dependency. There may be bugs or other unforeseen problems that can cause a disturbance and equate to lost time and money. When you do update your Spine editor and runtimes versions, it is always smart to check to make sure your app is working as it should. If not, please report the problem and while we fix it you can revert back to the last versions that were working for you, with no time lost and no be blocked waiting for us.

Sometimes users are not aware of how this versioning works. They update Spine to the latest, do a lot of work, then find that the runtimes don't support their animations. We are working on ways to make versioning more clear, eg by showing informational messages inside Spine. The kicker is that old versions of Spine can't open projects saved with newer Spine versions (but newer versions of Spine can open projects saved with any older version).

If this has happened to you, first remember that Spine saves a backup every time a project is saved. It also saves a backup every X minutes, if you have that enabled. You can go back to a previous version of your project by finding the last backup that was made with the older Spine version. If you have done too much work in the new Spine version that you don't want to lose by using a project backup, then we have written a small tool that will help.

The JsonRollback tool converts the latest JSON data so it can be imported into an older version of Spine. It does this by adding, modifying, and/or deleting parts of the data. This can be destructive, since features like shear or paths that don't exist in older versions of Spine have to be deleted. It should be used with caution.

Edit: As of Spine version 4.0.68-beta, the JsonRollback tool is no longer needed. Instead, you can choose an older version when exporting JSON. This is equivalent to using the JsonRollback tool, but is easier. Going back to an older version may still lose data and may still require manual fix up, such as deleting attachments or constraints that do not exist in the older version. Exporting to an older version is still not a recommended workflow, it is provided only to help recover work after from the catastrophic situation where a newer Spine version was used unintentionally.

The process works like this:

  • Open your project with the newer version of Spine you were using.
  • Export your project as JSON data. Make sure you check Nonessential data.
  • Run the JsonRollback tool.
  • Change your Spine version to the older version you want to use.
  • Import the JSON data.

The JsonRollback tool is distributed along with the Skeleton Viewer. Download the skeleton viewer JAR file, then run it like this (where the "to" version can be 3.8, 3.7, or 2.1):

java -cp skeletonViewer.jar com.esotericsoftware.spine.JsonRollback input.json 3.7 output.json

Java is required to run the tool.

Please note that we are actively working on the runtimes and expect them to be done in the next couple weeks. We are also expanding the Spine team, though that has unfortunately taken slightly longer than expected which is why we are currently so far behind on the runtimes. We'll get a handle on things again soon and everything will be much more awesome than before.


Edit: We have updated the JsonRollback tool in Skeleton Viewer 4.0.54-beta to support specifying a version of 3.8 to go from 4.0.xx to 3.8.99. However, there are some drawbacks: all curves will become linear, separate translate, scale, shear, and color timelines are lost, and constraint translate Y and shear Y are lost.


Edit: As of Spine version 4.0.68-beta, the JsonRollback tool is no longer needed. Instead, you can choose an older version when exporting JSON. This is equivalent to using the JsonRollback tool, but is easier. Going back to an older version may still lose data and may still require manual fix up, such as deleting attachments or constraints that do not exist in the older version. Exporting to an older version is still not a recommended workflow, it is provided only to help recover work after from the catastrophic situation where a newer Spine version was used unintentionally.

Related Discussions
...
  • Düzenlendi

Good post!

I was tempted to make the above tool, but never got round to it. 🙂 .

Thank you.

Thanks! <3 this saved me some work today. I was so irritated I tested out a new version of Spine on a file I didn't have in source control or could even be bothered to make a backup of. Very dumb of me indeed, so I deserve the various finger waggles. I had never encountered this issue in the past so I wasn't thinking about it. We're totally looking forward to making that update to 3.3 once runtime is looking clear. Paths looks so wonderful...

When I try to follow this process, it works just fine exporting from 3.3.05 and back into 3.3.05.

However, when I export from 3.3.05 (using the same skeleton you guys sent back with fixed bones), then run the revertJson script and import into a 3.2.01 Spine executable (so I can test the model out in the Unity runtime minus the 3.3 unity features), i get the following popup:

Non-essential data was checked when I did the export.

Please let me know if I have made an error in these steps.


FYI, the source reason I did that was that exporting the -fixed (5.3.05) spine file to JSON and then importing in unity resulted in the following error, which I assumed was a runtime incompatability.

Edit; Error and investigation removed - the incompatibility was due to bone being converted to an array in 3.3.05 - which is to be expected.

When I attempted to load the output.json file into unity directly (without importing it into spine, due to the above error), the following unity error occurred:

Error reading skeleton JSON file for SkeletonData asset: Coil_SkeletonData
Cannot cast from source type to destination type.
  at Spine.SkeletonJson.ReadSkeletonData (System.IO.TextReader reader) [0x00977] in /Users/alexanderbrazie/project-sidescroller/Assets/External/spine-csharp/SkeletonJson.cs:238 
  at Spine.Unity.SkeletonDataAsset.GetSkeletonData (Boolean quiet) [0x0017e] in /Users/alexanderbrazie/project-sidescroller/Assets/External/spine-unity/Assets/spine-unity/Asset Types/SkeletonDataAsset.cs:141 
UnityEngine.Debug:LogError(Object, Object)
Spine.Unity.SkeletonDataAsset:GetSkeletonData(Boolean) (at Assets/External/spine-unity/Assets/spine-unity/Asset Types/SkeletonDataAsset.cs:147)
Spine.Unity.Editor.SkeletonDataAssetInspector:OnEnable() (at Assets/External/spine-unity/Assets/spine-unity/Asset Types/Editor/SkeletonDataAssetInspector.cs:87)

And the code associated with that error:


     // Linked meshes.
     for (int i = 0, n = linkedMeshes.Count; i < n; i++) {
        LinkedMesh linkedMesh = linkedMeshes[i];
        Skin skin = linkedMesh.skin == null ? skeletonData.defaultSkin : skeletonData.FindSkin(linkedMesh.skin);
        if (skin == null) throw new Exception("Slot not found: " + linkedMesh.skin);
        Attachment parent = skin.GetAttachment(linkedMesh.slotIndex, linkedMesh.parent);
        if (parent == null) throw new Exception("Parent mesh not found: " + linkedMesh.parent);
        if (linkedMesh.mesh is MeshAttachment) {
           MeshAttachment mesh = (MeshAttachment)linkedMesh.mesh;
              mesh.ParentMesh = (MeshAttachment)parent;
               mesh.UpdateUVs();
            } else {
               WeightedMeshAttachment mesh = (WeightedMeshAttachment)linkedMesh.mesh;
               mesh.ParentMesh = (WeightedMeshAttachment)parent;
               mesh.UpdateUVs();
            }
         }
         linkedMeshes.Clear();

Which I suspect has something to do with the MeshAttachment/WeightedMeshAttachment conflict that's I briefly read about on the forum ... probably because I'm using a razor's edge copy of the Unity runtimes. Doh!

tl;dr -

Which piece of this should be addressed?

Step 1) Unity Runtimes are not updated to handle 3.3.05 [KNOWN ISSUE - Will be fixed in the future]
Step 2) Exporting from 3.3.05 and running revertJson doesn't produce a .json file that can be imported into 3.2.01
Step 3) Unity 3.2 runtime cannot import the revertJSON's output.json
Step 4) wtf? none of these, you are over thinking this, Alex. Go the fuck to sleep and come back to this project in 2 weeks.

... until I hear back, I'm going to go back to exporting 3.3.05 and hacking the spine c-sharp runtime to support the bones[] array.

Sorry for all the trouble Xelnath. The JsonRollback tool was not converting linkedmesh to weightedlinkedmesh. It is now and I've emailed you the JSON files so you don't have to mess around any further.

No worries. This is all typical bumps in the road for game developers. ^^

Fortunately, my artist is on break until Monday and I had plenty of time to look into this issue.

Regarding the unity runtime - I was able to patch holes in almost all of it and maintain cross-version compatibility - except for something involving vertex counts - and only in 3.3.05.


@Nate, a small error in the newly updated SkeletonViewer.jar

	args = new String[] {"C:/test/CoilGrapple.json", "C:/test/CoilGrapple-fixed.json"};

Still in there ^^

Guys, i believe you should give a caution window when the editor is going to update it self.
It must say something like:
"You are about to screw all your work and stuck for a few months without updated runtime.
Please be sure, that your runtime is already updated to this version"

Ok, good to know! I was stuck for a few hours. What would help me: As soon as Spine gets an updated just show a warning if the runtime scripts are not up to date. I mean many updates just worked like a charm. So a little reminder would be very helpful.

Thanks a lot!

  • Düzenlendi

Thank you!

@Nate: your code overwrite the arguments in command line, so the input must be "C:/test/CoilGrapple.json" and the output will be "C:/test/CoilGrapple-fixed.json"

Xelnath yazdı

@Nate, a small error in the newly updated SkeletonViewer.jar

Eek! Sorry about that, fixed now. Would've been on it quicker but the internet went out, had to go to the mainland to get it fixed.

We currently have a "do you want to update?" dialog, but I agree that it needs more info. Unfortunately doing that requires a Spine launcher update, so once we make the change people will need to download Spine and reinstall to see the new message. It would still be good for new users though.

We could do another dialog when a new version of Spine opens for the first time, maybe even show the changelog. All users would see that dialog. It would be nice to show a list of runtimes and the latest version they support.

Warning dialog on first run of a new version · Issue #66 · EsotericSoftware/spine-editor · GitHub

I took a look at the converter code - the changes seemed pretty simple.

Do you believe it will be too hard to make an in-editor "export to version 3.1... 2.1" etc?

Or would it be better to leave this kind of work for an external tool? It looks like this is the first time this incompatibility situation has happened in Spine's history. Pretty impressive!

There should be no reason to rollback JSON to an old version, except as a way to get data back to import into an old version of Spine after a mistake was made by updating to a newer Spine version. The JsonRollback tool will become outdated as more functionality is added. What if you want to go from version 5.3.01 to 3.2.01? From 4.7.05 to 4.1.03? It doesn't make sense to do this from a workflow perspective, so it isn't functionality we want to support long term. People are free to use JsonRollback or similar code to mangle their JSON data however they need to get it in an old version of Spine, but I don't think it makes sense to have it available in the editor.

Thanks for all the work and thanks for this clarifying post which makes total sense.

I've ended up in this thread because I was affected by this: Importing error

What was frustrating to me was that I thought that the runtime was supposed to support loading the latest version's JSONs but just had some bug.

I was wondering: The version number of the exporting Spine editor is written into the exported JSON files


then why doesn't the Unity runtime e.g. throw an exception (or at least log a warning) when the runtime tries to load a json file that it can't read? (Apologies if it does that and I didn't see it.)

Just trying to give some feedback to make stuff like this less frustrating for us all 🙂 Thanks for this amazing software!

Well, I forsee as Spine's popularity increases, the frequency of "oops, I updated to latest" becoming more frequent.

However, I do not believe it is a large problem, so much as it is high impact, short-term problem, caused by artists, who are frequently the least aware of versioning and most likely to trust in auto-updates.

But again, until a large studio starts using Spine and incompatible spine json data changes happen a LOT... it should be fine.

so when are you updating ?

because, new features who don't work is ok, the main problem is features who use to work who don't work anymore 😉

Bekko yazdı

if features 'don't work that use to work' they should be exported in a version to where they did work

We will likely move to "beta" updates soon. This means any update which doesn't have 100% support in ALL the official runtimes will be released as "beta". People will have to opt-in to beta updates, else they will only be prompted to update to non-beta versions. This doesn't remove the need to be wary of what version you are running, as it should still match the version that the runtimes you are using support. The benefit is that you can accept any non-beta update knowing that the runtime support is available. Our goal will be to keep the beta window as short as possible.

Doing this will require us to do a mandatory launcher update. When we do that, it means you'll need to download and reinstall Spine.

ok got it, i'm not mad guys, spine is fantastic !