- Editado
Spine-Unity 3.8 to 4.0 Upgrade Guide
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 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 of Skin 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(); // 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 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()
with
Skeleton.SetSlotsToSetupPose()
.
Replace:-
Slot.SetColorToSetupPose()
-
Slot.SetAttachmentToSetupPose()
with
Slot.SetToSetupPose()
.
Also removed less commonly used extension methods:
TrackEntry.AllowImmediateQueue()
,Animation.SetKeyedItemsToSetupPose()
andAttachment.IsRenderable()
. -
-
Removed SkeletonData and Skeleton 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);
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 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!
How to upgrade if the .spine file is lost
You can use Spine
- Import Data..
and Texture Unpacker
in the Spine Editor to import from .json
or .skel.bytes
assets, then you can save your project and re-export.
If you have a lot of projects to convert, you might want to use the Spine command line interface as described here:
How to automate version migration of binary assets?
[编辑]
现在有一个新的中文版spine-unity 3.8到4.0升级指南,由@wiige用户慷慨提供:
[Edit]
There is now a new Chinese version of the spine-unity 3.8 to 4.0 Upgrade Guide available here, generously provided by user @wiige:
[ZH-CN]Spine-Unity 3.8 to 4.0升级指南
I just added one item to the Behavioural Changes list above which was missing:
-
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.
Hello all!
I am currently transitioning from Spine 3.8 to 4.0, and we have hundreds of spine assets that stopped working and needed to be exported again. We wanted to get a away to automate that. Do we really need to go through the export process? Isn't there any tool that translates 3.8 jsons to 4.0 ones? What would be the best course of action to perform this version transition in my project?
Thank you in advance!
There is such a tool: Spine! See here:
Command line interface - Spine User Guide: Export
For example, one of these:
spine -u 4.0.xx -i your-project.spine -o path/to/output/folder -e json
spine -u 4.0.xx -i your-project.spine -o path/to/output/folder -e binary
spine -u 4.0.xx -i your-project.spine -o path/to/output/folder -e settings.export.json
The first two use default settings to export JSON or binary, the third uses your settings JSON file you can save with Spine. The 4.0.xx
gives you the latest 4.0 version.
You can specify many actions with one Spine invocation, eg (this shows 2, but can be any number):
spine -u 4.0.xx -i project1.spine -o path/to/output/folder -e json -i project2.spine -o path/to/output/folder -e json
You can write a shell script to process many files at once. Here's a recent thread with some scripts:
Spine Export Script
If you don't have the .spine
files (you really should keep them safe!), you can generate them with Spine but you need to specify the editor version that matches the data:
spine -u 3.8.99 -i your-3.8-data.json -o your-4.0-project.spine -r
This isn't ideal because the resulting .spine
file may be missing some nonessential information (eg bone icons, internal mesh edges if nonessential was unchecked when the data was exported, etc), but that's usually not a huge problem.
Thank you Nate for your very fast and useful reply!
I was already able to get .sprites from .json files, and then trying to generate new .json for spine 4.0. However, when I try to open in unity, unity lunches warnings to tell that he can't find the atlas, nor the images for it.
Does this migration process also require the atlas json to be re-exported, as well as the png which contains all the images? Because Unity seems to not be able to link them (and when I try to set them "by hand", Unity expects an Atlas Asset Base, which I think is a different type than the old atlas asset).
I hope I was clear enough, is just that I'm trying to test this migration process without having access to the artist's original assets, so I really wanted to understand the whole set of files that need to be re-exported for this 3.8 to 4.0 transition. Thank you!
You don't need to export your atlases with 4.0, you can use atlases from older versions of Spine with the 4.0 runtimes. The 4.0 texture packer may pack slightly more efficiently and uses a new atlas format that is smaller, but the 4.0 runtimes can read both the new and older formats (which are text but not JSON).
It sounds like you may have a configuration problem in Unity. That is not my area of expertise, so we'll likely need Harald's assistance. He'll want to know what you tried and what errors you got, if any. He'll also expect that you've read the documentation:
spine-unity Runtime Documentation
@DurvalFP Mixing 4.0 .json
files with 3.8 atlas.txt
files is expected to work. Could you please send us the problematic files, either attached to a forum posting or via email to contact@esotericsoftware.com, then we can have a look at what's going wrong.
Nate escreveuBecause Unity seems to not be able to link them (and when I try to set them "by hand", Unity expects an Atlas Asset Base, which I think is a different type than the old atlas asset).
There is no incompatible difference here, AtlasAssetBase
is just the base class name which is used instead of the concrete subclass.
what about the Unity Timeline integration? I see there's a 4.0 version of the timeline integration. Would upgrading to 4.0 break my existing 3.8 timelines, or is it a smooth transition?
Upgrading the spine-unity Timeline UMP package from 3.8 to 4.0 will not break your existing timelines in general. It will change the behaviour of the timeline clips as listed in the last entry of the Changes in behaviour from 3.8 to 4.0
in the topmost posting (and in the changelog):
- 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.
Another added Timeline feature to adjust old vs new Timeline clip pause behaviour better:
[Edit:] Removed since it has been replaced by a better solution soon after.
Hi,
I went according to the recommended upgrade steps for upgrading from 3.8 to 4.0
but after importing to the latest spine 4.0 the 4.0 files did not automatically create the atlas, skeletonData and Material files
and since I have hundreds of spine files I don't want to go manually and fix every single one of them,
Am I missing a step?
Do you mean that you replaced your old 3.8 skeleton assets (the .json
/.skel.bytes
and .atlas.txt
files) with their 4.0 counterparts, and that it then did not automatically reimport those? If yes, then please either select RMB - Reimport All
in the Project panel, or select the folder where all your skeleton assets are contained and select RMB - Reimport
to reimport all assets contained therein.
[Edit:] Somehow I incorrectly assumed that this line was already present. I just noticed that this step is missing in the upgrade steps list above and is necessary in this upgrade, very sorry about that!
Thank you Harald for the quick response,
I actually did end up using "Reimport" but it didn't fix up the missing references in the skeletons in my scene
Is that an expected behavior? is there a way to avoid breaking references to all of the skeletons across my app and resolve it automatically? if not, do you have any recommendations on how to tackle this problem without manually fixing each and every one of the skeletons in my project?
thanks for the help!
Sorry to hear that, you should never be losing any references in your scenes after any upgrade, this would be terrible. Are you sure that you haven't accidentally deleted any .meta files
, e.g. of the SkeletonDataAssets
?
you're right! that was the issue
I ran a script that replaces all of the old spine files with the new ones removing by mistake the SkeletonDataAssets with them, I did it in a test environment so no harm was done,
consider clarifying in step 6 to not remove the material, atlas, and skeletonDataAsset files when replacing the old files with the new ones
Thanks for the help!
You're welcome, glad to hear you've figured it out! We will add a remark to step 6.
We have just added a Timeline bugfix to the list above, including workarounds to achieve the old 3.8 behaviour:
-
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.
Hi, I have having some materials bugs with the demo "Sprite Shaders". Is this demo only working on 3.x version of Spine ? Or did I miss something with the migration ? Thanks a lot.
If you are using the Universal Render Pipeline (URP) you need to use the respective spine URP shaders (2D or 3D depending on your renderer), the normal standard multi-pass shaders don't work with URP.
spine-unity Runtime Documentation: URP Shaders Extension UPM Package
Please note the following recently removed methods, added as (currently item (6) in the list on top):
-
Removed SkeletonData and Skeleton 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);
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;
Hi. We are transitioning to spine 4.0.46 in a big unity project. Why do I get 4 different materials created in Unity? how can I get rid of the ones I don't need ?