Spine-Unity 3.8 to 4.0 Upgrade Guide

Harald

As the official 4.0 release is a few days away, you can find the officially compiled Upgrade Guide below.

If you are upgrading from an older version of spine-unity than 3.8, please see the respective upgrade guide on how to adjust your code and assets accordingly:
Spine-Unity 3.7 to 3.8 Upgrade Guide
Spine-Unity 3.6 to 3.7 Upgrade Guide

Re-export your skeleton data
Note: Json and binary skeleton data files exported from Spine 3.8 will not be readable by the Spine-Unity 4.0 runtime!
The skeleton data files need to be re-exported using Spine 4.0.

If you have many projects, we suggest automating exporting your project files:
Export - Spine User Guide: Command line
For example, here is a script we use to export all the Spine example projects and to create texture atlases:
https://github.com/EsotericSoftware/spine-runtimes/blob/4.0/examples/export/export.sh

Recommended upgrade steps for upgrading from 3.8 to 4.0:

Create a backup of your 3.8 project to be on the safe side.
Close all open scenes and create a new blank scene, and have nothing selected. This is to make sure there are no active Spine objects.
Note any custom changes you made to your Spine-Unity runtime.
Delete your old "Spine" and "Spine Examples" folders.
Close the project and Unity.
Replace the old exported 3.8 skeleton assets with their re-exported 4.0 counterparts. Do not remove any .meta files.
Open Unity and your project again.
Import the latest Spine-Unity 4.0 unitypackage.
In the Project panel select RightMouseButton - Reimport All (or select Reimport on the folder containing your skeleton assets).

Adapting your code to 4.0 API changes
For notable changes to the API, please see the Changelog, sections C# and Unity
https://github.com/EsotericSoftware/spine-runtimes/blob/4.0/CHANGELOG.md#c-2

Some methods have been renamed or replaced in 4.0.
If you receive compile errors from your own code because of using renamed and no-longer existing methods, the following points from the changelog will help to perform the required steps to make your own code compatible again:

All Spine.Unity.AttachmentTools.SkinUtilities Skin extension methods have been removed, these are replaced by the new Skin API. To fix any compile errors, replace any usage of Skin extension methods with their counterparts, e.g. replace occurrances of skin.AddAttachments() with skin.AddSkin(). If you are using UnshareSkin() you can replace it as follows:
```
skeletonAnimation.Skeleton.UnshareSkin();
// replace by the following code:
Skin customSkin = new Skin("custom skin");
customSkin.AddSkin(skeletonAnimation.Skeleton.Skin);
```
Please see the example scene Mix and Match Skins on how to use the new Skin API to combine skins, or the updated old example scenes Mix and Match and Mix and Match Equip on how you can update an existing project that was using the old workflow.
Replace any occurrances of Skin.GetAttachments() by Skin.Attachments. The return type has been changed to ICollection<SkinEntry>.
Spine.Unity.AttachmentTools.AttachmentCloneExtensions extension methods have been removed. Replace any occurrances of Attachment.GetCopy() with Attachment.Copy(), and Attachment.GetLinkedMesh() with Attachment.NewLinkedMesh().
Removed Spine.Unity.AttachmentTools.AttachmentRegionExtensions extension methods Attachment.GetRegion(). Use Attachment.RendererObject as AtlasRegion instead.
Removed redundant Spine.SkeletonExtensions extension methods:
Replace:
- Skeleton.SetPropertyToSetupPose()
- Skeleton.SetDrawOrderToSetupPose()
- Skeleton.SetSlotAttachmentsToSetupPose()
- Skeleton.SetSlotAttachmentToSetupPose()
with Skeleton.SetSlotsToSetupPose().
Replace:
- Slot.SetColorToSetupPose()
- Slot.SetAttachmentToSetupPose()
with Slot.SetToSetupPose().
Also removed less commonly used extension methods:
TrackEntry.AllowImmediateQueue(), Animation.SetKeyedItemsToSetupPose() and Attachment.IsRenderable().
Removed SkeletonData and Skeleton methods: FindBoneIndex, FindSlotIndex. Bones and slots have an Index field that should be used instead. Be sure to check for e.g. slot == null accordingly before accessing slot.Index where necessary.
Replace:
- int index = skeletonData.FindSlotIndex(slotName);
  with
- SlotData slot = skeletonData.FindSlot(slotName); int index = slot != null ? slot.Index : -1;
Replace:
- int index = skeleton.FindBoneIndex(boneName);
  with
- Bone bone = skeleton.FindBone(boneName); int index = bone != null ? bone.Index : -1;

Changes in behaviour from 3.8 to 4.0
For a full list of changes in behaviour, please again see the Changelog, sections C# and Unity
https://github.com/EsotericSoftware/spine-runtimes/blob/4.0/CHANGELOG.md#c-2

Constraints no longer reset changes made by other constraints. In 3.8, a constraint may revert the changes made by another constraint. In 4.0, this no longer happens. If your project happened to rely on the behavior in 3.8, then when you move to 4.0 you may have a constraint affecting your bones unexpectedly.
SkeletonGraphic now no longer uses a RawImage component at each submesh renderer GameObject when allowMultipleCanvasRenderers is true. Instead, a new custom component SkeletonSubmeshGraphic is used which is more resource friendly. Replacement of these components will be performed automatically through editor scripting, saving scenes or prefabs will persist the upgrade.
Linear color space: Previously Slot colors were not displayed the same in Unity Linear color space as in the Spine Editor with Color management - Linear blending Spine Editor settings. This is now fixed at all shaders, including URP and LWRP shaders. If you have tweaked Slot colors to compensate for the incorrect display, you might want to adjust the tweaked colors.
Additive Slots have always been lit before they were written to the target buffer. Now all lit shaders provide an additional parameter Light Affects Additive which defaults to false, as it is the more intuitive default value. You can enable the old behaviour by setting this parameter to true.
Corrected blending behaviour of all Sprite shaders in Premultiply Alpha blend mode (including URP and LWRP packages). Previously vertex color alpha was premultiplied again, even though Premultiply Alpha blend mode assumes PMA texture and PMA vertex color input. Slot-alpha blending will thus be correctly lighter after upgrading to 4.0. If you have compensated this problem by disabling Advanced - PMA Vertex Colors you can now re-enable this parameter, also allowing for rendering Additive slots in a single pass.
Corrected all Outline shaders outline thickness when Advanced - Sample 8 Neighbourhood is disabled (thus using 4 Neighbourhood). To restore the previous outline thickness adjust the Outline Threshold parameter through adding a /4 at outline shaders where Sample 8 Neighbourhood is disabled to make the threshold 4 times smaller.
Fixed Timeline not pausing (and resuming) clip playback on Director pause, this is now the default behaviour. If you require the old behaviour (e.g. to continue playing an idle animation during Director pause), there is now an additional parameter Don't Pause with Director provided that can be enabled for each Timeline clip.
Fixed Timeline Spine AnimationState Clips ignoring empty space on the Timeline after a clip's end. Timeline clips now also offer Don't End with Clip and Clip End Mix Out Duration parameters if you prefer the old behaviour of previous versions. By default when empty space follows the clip on the timeline, the empty animation is set on the track with a MixDuration of Clip End Mix Out Duration. Set Don't End with Clip to true to continue playing the clip's animation instead and mimic the old 3.8 behaviour. If you prefer pausing the animation instead of mixing out to the empty animation, set Clip End Mix Out Duration to a value less than 0, then the animation is paused instead.

You can download the new unitypackages from the download page: Spine Unity Download

If you find anything that should be noted or added to the guide, please do not hesitate to post it below so that we can make upgrading as easy and painless as possible for everyone.

We hope that you like the new Spine release and are able to create even more incredible games with it! 🙂

handbig

How to upgrade if the .spine file is lost

Harald

You can use Spine - Import Data.. and Texture Unpacker in the Spine Editor to import from .json or .skel.bytes assets, then you can save your project and re-export.

If you have a lot of projects to convert, you might want to use the Spine command line interface as described here:
How to automate version migration of binary assets?

[编辑]
现在有一个新的中文版spine-unity 3.8到4.0升级指南，由@wiige用户慷慨提供：
[Edit]
There is now a new Chinese version of the spine-unity 3.8 to 4.0 Upgrade Guide available here, generously provided by user @wiige:
[ZH-CN]Spine-Unity 3.8 to 4.0升级指南

I just added one item to the Behavioural Changes list above which was missing:

Fixed Timeline not pausing (and resuming) clip playback on Director pause, this is now the default behaviour. If you require the old behaviour (e.g. to continue playing an idle animation during Director pause), there is now an additional parameter Don't Pause with Director provided that can be enabled for each Timeline clip.

DurvalFP

Hello all!

I am currently transitioning from Spine 3.8 to 4.0, and we have hundreds of spine assets that stopped working and needed to be exported again. We wanted to get a away to automate that. Do we really need to go through the export process? Isn't there any tool that translates 3.8 jsons to 4.0 ones? What would be the best course of action to perform this version transition in my project?

Thank you in advance!

Nate

There is such a tool: Spine! 😃 See here:
Command line interface - Spine User Guide: Export

For example, one of these:

spine -u 4.0.xx -i your-project.spine -o path/to/output/folder -e json
spine -u 4.0.xx -i your-project.spine -o path/to/output/folder -e binary
spine -u 4.0.xx -i your-project.spine -o path/to/output/folder -e settings.export.json

The first two use default settings to export JSON or binary, the third uses your settings JSON file you can save with Spine. The 4.0.xx gives you the latest 4.0 version.

You can specify many actions with one Spine invocation, eg (this shows 2, but can be any number):

spine -u 4.0.xx -i project1.spine -o path/to/output/folder -e json -i project2.spine -o path/to/output/folder -e json

You can write a shell script to process many files at once. Here's a recent thread with some scripts:
Spine Export Script

If you don't have the .spine files (you really should keep them safe!), you can generate them with Spine but you need to specify the editor version that matches the data:

spine -u 3.8.99 -i your-3.8-data.json -o your-4.0-project.spine -r

This isn't ideal because the resulting .spine file may be missing some nonessential information (eg bone icons, internal mesh edges if nonessential was unchecked when the data was exported, etc), but that's usually not a huge problem.

DurvalFP

Thank you Nate for your very fast and useful reply!

I was already able to get .sprites from .json files, and then trying to generate new .json for spine 4.0. However, when I try to open in unity, unity lunches warnings to tell that he can't find the atlas, nor the images for it.

Does this migration process also require the atlas json to be re-exported, as well as the png which contains all the images? Because Unity seems to not be able to link them (and when I try to set them "by hand", Unity expects an Atlas Asset Base, which I think is a different type than the old atlas asset).

I hope I was clear enough, is just that I'm trying to test this migration process without having access to the artist's original assets, so I really wanted to understand the whole set of files that need to be re-exported for this 3.8 to 4.0 transition. Thank you!

Nate

You don't need to export your atlases with 4.0, you can use atlases from older versions of Spine with the 4.0 runtimes. The 4.0 texture packer may pack slightly more efficiently and uses a new atlas format that is smaller, but the 4.0 runtimes can read both the new and older formats (which are text but not JSON).

It sounds like you may have a configuration problem in Unity. That is not my area of expertise, so we'll likely need Harald's assistance. He'll want to know what you tried and what errors you got, if any. He'll also expect that you've read the documentation: 🙂
spine-unity Runtime Documentation

Harald

@DurvalFP Mixing 4.0 .json files with 3.8 atlas.txt files is expected to work. Could you please send us the problematic files, either attached to a forum posting or via email to contact@esotericsoftware.com, then we can have a look at what's going wrong.

Nate wrote
Because Unity seems to not be able to link them (and when I try to set them "by hand", Unity expects an Atlas Asset Base, which I think is a different type than the old atlas asset).

There is no incompatible difference here, AtlasAssetBase is just the base class name which is used instead of the concrete subclass.

gofiguregames

what about the Unity Timeline integration? I see there's a 4.0 version of the timeline integration. Would upgrading to 4.0 break my existing 3.8 timelines, or is it a smooth transition?

Harald

Upgrading the spine-unity Timeline UMP package from 3.8 to 4.0 will not break your existing timelines in general. It will change the behaviour of the timeline clips as listed in the last entry of the Changes in behaviour from 3.8 to 4.0 in the topmost posting (and in the changelog):

Fixed Timeline not pausing (and resuming) clip playback on Director pause, this is now the default behaviour. If you require the old behaviour (e.g. to continue playing an idle animation during Director pause), there is now an additional parameter Don't Pause with Director provided that can be enabled for each Timeline clip.

Another added Timeline feature to adjust old vs new Timeline clip pause behaviour better:
[Edit:] Removed since it has been replaced by a better solution soon after.

aceex7

Hi,

I went according to the recommended upgrade steps for upgrading from 3.8 to 4.0
but after importing to the latest spine 4.0 the 4.0 files did not automatically create the atlas, skeletonData and Material files
and since I have hundreds of spine files I don't want to go manually and fix every single one of them,
Am I missing a step?

Harald

Do you mean that you replaced your old 3.8 skeleton assets (the .json/.skel.bytes and .atlas.txt files) with their 4.0 counterparts, and that it then did not automatically reimport those? If yes, then please either select RMB - Reimport All in the Project panel, or select the folder where all your skeleton assets are contained and select RMB - Reimport to reimport all assets contained therein.

[Edit:] Somehow I incorrectly assumed that this line was already present. I just noticed that this step is missing in the upgrade steps list above and is necessary in this upgrade, very sorry about that!

aceex7

Thank you Harald for the quick response,

I actually did end up using "Reimport" but it didn't fix up the missing references in the skeletons in my scene
Is that an expected behavior? is there a way to avoid breaking references to all of the skeletons across my app and resolve it automatically? if not, do you have any recommendations on how to tackle this problem without manually fixing each and every one of the skeletons in my project?

thanks for the help!

Harald

Sorry to hear that, you should never be losing any references in your scenes after any upgrade, this would be terrible. Are you sure that you haven't accidentally deleted any .meta files, e.g. of the SkeletonDataAssets?

aceex7

you're right! that was the issue
I ran a script that replaces all of the old spine files with the new ones removing by mistake the SkeletonDataAssets with them, I did it in a test environment so no harm was done,
consider clarifying in step 6 to not remove the material, atlas, and skeletonDataAsset files when replacing the old files with the new ones

Thanks for the help! 🙂

Harald

You're welcome, glad to hear you've figured it out! We will add a remark to step 6.

We have just added a Timeline bugfix to the list above, including workarounds to achieve the old 3.8 behaviour:

Fixed Timeline Spine AnimationState Clips ignoring empty space on the Timeline after a clip's end. Timeline clips now also offer Don't End with Clip and Clip End Mix Out Duration parameters if you prefer the old behaviour of previous versions. By default when empty space follows the clip on the timeline, the empty animation is set on the track with a MixDuration of Clip End Mix Out Duration. Set Don't End with Clip to true to continue playing the clip's animation instead and mimic the old 3.8 behaviour. If you prefer pausing the animation instead of mixing out to the empty animation, set Clip End Mix Out Duration to a value less than 0, then the animation is paused instead.

Nayir

Hi, I have having some materials bugs with the demo "Sprite Shaders". Is this demo only working on 3.x version of Spine ? Or did I miss something with the migration ? Thanks a lot.

Harald

If you are using the Universal Render Pipeline (URP) you need to use the respective spine URP shaders (2D or 3D depending on your renderer), the normal standard multi-pass shaders don't work with URP.
spine-unity Runtime Documentation: URP Shaders Extension UPM Package

Please note the following recently removed methods, added as (currently item (6) in the list on top):

Removed SkeletonData and Skeleton methods: FindBoneIndex, FindSlotIndex. Bones and slots have an Index field that should be used instead. Be sure to check for e.g. slot == null accordingly before accessing slot.Index where necessary.
Replace:
- int index = skeletonData.FindSlotIndex(slotName);
  with
- SlotData slot = skeletonData.FindSlot(slotName); int index = slot != null ? slot.Index : -1;
Replace:
- int index = skeleton.FindBoneIndex(boneName);
  with
- Bone bone = skeleton.FindBone(boneName); int index = bone != null ? bone.Index : -1;

danialcaraz

Hi. We are transitioning to spine 4.0.46 in a big unity project. Why do I get 4 different materials created in Unity? how can I get rid of the ones I don't need ?