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:
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);
withSlotData slot = skeletonData.FindSlot(slotName); int index = slot != null ? slot.Index : -1;
Replace:
int index = skeleton.FindBoneIndex(boneName);
withBone 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! 🙂
