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
Reimporton 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.SkinUtilitiesSkin extension methods have been removed, these are replaced by the new Skin API. To fix any compile errors, replace any usage of
Skinextension methods with their counterparts, e.g. replace occurrances of
skin.AddSkin(). If you are using
UnshareSkin()you can replace it as follows:skeletonAnimation.Skeleton.UnshareSkin();Please see the example scene
// replace by the following code:
Skin customSkin = new Skin("custom skin");
Mix and Match Skinson how to use the new Skin API to combine skins, or the updated old example scenes
Mix and Matchand
Mix and Match Equipon 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.AttachmentCloneExtensionsextension methods have been removed. Replace any occurrances of
Attachment.RendererObject as AtlasRegioninstead.
- Removed redundant
Also removed less commonly used extension methods:
FindSlotIndex. Bones and slots have an
Indexfield that should be used instead. Be sure to check for e.g.
slot == nullaccordingly before accessing
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;
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
allowMultipleCanvasRenderersis true. Instead, a new custom component
SkeletonSubmeshGraphicis 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
Linearcolor space as in the Spine Editor with
Linear blendingSpine 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 Additivewhich 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
Premultiply Alphablend mode (including URP and LWRP packages). Previously vertex color alpha was premultiplied again, even though
Premultiply Alphablend 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 Colorsyou can now re-enable this parameter, also allowing for rendering Additive slots in a single pass.
- Corrected all
Outlineshaders outline thickness when
Advanced - Sample 8 Neighbourhoodis disabled (thus using
4 Neighbourhood). To restore the previous outline thickness adjust the
Outline Thresholdparameter through adding a
/4at outline shaders where
Sample 8 Neighbourhoodis 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 Directorprovided that can be enabled for each Timeline clip.
- Fixed Timeline
Spine AnimationState Clipsignoring empty space on the Timeline after a clip's end. Timeline clips now also offer
Don't End with Clipand
Clip End Mix Out Durationparameters 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 Clipto 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 Durationto 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!