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 selectReimport
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 ofSkin
extension methods with their counterparts, e.g. replace occurrances ofskin.AddAttachments()
withskin.AddSkin()
. If you are usingUnshareSkin()
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");
customSkin.AddSkin(skeletonAnimation.Skeleton.Skin);Mix and Match Skins
on how to use the new Skin API to combine skins, or the updated old example scenesMix and Match
andMix and Match Equip
on how you can update an existing project that was using the old workflow. - Replace any occurrances of
Skin.GetAttachments()
bySkin.Attachments
. The return type has been changed toICollection<SkinEntry>
. -
Spine.Unity.AttachmentTools.AttachmentCloneExtensions
extension methods have been removed. Replace any occurrances ofAttachment.GetCopy()
withAttachment.Copy()
, andAttachment.GetLinkedMesh()
withAttachment.NewLinkedMesh()
. - Removed
Spine.Unity.AttachmentTools.AttachmentRegionExtensions
extension methodsAttachment.GetRegion()
. UseAttachment.RendererObject as AtlasRegion
instead. - Removed redundant
Spine.SkeletonExtensions
extension methods:
Replace:
-
Skeleton.SetPropertyToSetupPose()
-
Skeleton.SetDrawOrderToSetupPose()
-
Skeleton.SetSlotAttachmentsToSetupPose()
-
Skeleton.SetSlotAttachmentToSetupPose()
Skeleton.SetSlotsToSetupPose()
.
Replace:
-
Slot.SetColorToSetupPose()
-
Slot.SetAttachmentToSetupPose()
Slot.SetToSetupPose()
.
Also removed less commonly used extension methods:
TrackEntry.AllowImmediateQueue()
,Animation.SetKeyedItemsToSetupPose()
andAttachment.IsRenderable()
. -
- Removed
SkeletonData
andSkeleton
methods:FindBoneIndex
,FindSlotIndex
. Bones and slots have anIndex
field that should be used instead. Be sure to check for e.g.slot == null
accordingly before accessingslot.Index
where necessary.
Replace:int index = skeletonData.FindSlotIndex(slotName);
SlotData slot = skeletonData.FindSlot(slotName); int index = slot != null ? slot.Index : -1;
Replace: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
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 componentSkeletonSubmeshGraphic
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 withColor 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 tofalse
, as it is the more intuitive default value. You can enable the old behaviour by setting this parameter totrue
. - Corrected blending behaviour of all
Sprite
shaders inPremultiply Alpha
blend mode (including URP and LWRP packages). Previously vertex color alpha was premultiplied again, even thoughPremultiply 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 disablingAdvanced - 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 whenAdvanced - Sample 8 Neighbourhood
is disabled (thus using4 Neighbourhood
). To restore the previous outline thickness adjust theOutline Threshold
parameter through adding a/4
at outline shaders whereSample 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 offerDon't End with Clip
andClip 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 ofClip End Mix Out Duration
. SetDon'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, setClip 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!
