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:
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
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
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:
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.AddSkin(). If you are using
UnshareSkin() you can replace it as follows:
// replace by the following code:
Skin customSkin = new Skin("custom 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.Attachments. The return type has been changed to
Spine.Unity.AttachmentTools.AttachmentCloneExtensions extension methods have been removed. Replace any occurrances of
Spine.Unity.AttachmentTools.AttachmentRegionExtensions extension methods
Attachment.RendererObject as AtlasRegion instead.
Spine.SkeletonExtensions extension methods:
Also removed less commonly used extension methods:
Removed SkeletonData and Skeleton methods:
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.
int index = skeletonData.FindSlotIndex(slotName);
SlotData slot = skeletonData.FindSlot(slotName); int index = slot != null ? slot.Index : -1;
int index = skeleton.FindBoneIndex(boneName);
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
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
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.
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.
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! 🙂