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);
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! 🙂