- Modifié
Spine-Unity 3.7 to 3.8 Upgrade Guide
- Modifié
Re-export your skeleton data
Note: Json and binary skeleton data files exported from Spine 3.7 will not be readable by the Spine-Unity 3.8 runtime!
The skeleton data files need to be re-exported using Spine 3.8.
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:
spine-runtimes/export.sh at 3.8
Recommended upgrade steps for upgrading from 3.7 to 3.8:
-
Create a backup of your 3.7 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.7 skeleton assets with their re-exported 3.8 counterparts.
-
Open Unity and your project again.
-
Import the latest Spine-Unity 3.8 unitypackage.
Adapting your code to 3.8 API changes
For notable changes to the API, please see the Changelog, sections C#
and Unity
spine-runtimes/CHANGELOG.md at 3.8
Some methods have been renamed or replaced in 3.8.
If you receive compile errors from your own code because of using renamed and no-longer existing methods, the following steps will help to quickly make your own code compatible again:
-
Replace any usage of
Skin.AddAttachment()
withSkin.SetAttachment()
. -
Replace any usage of
Skin.FindAttachmentsForSlot()
andSkin.FindNamesForSlot()
with the combinedSkin.GetAttachments(int slotIndex, List<SkinEntry> attachments)
method:// replace this code: List<Attachment> attachments = new List<Attachment>(); List<string> names = new List<string>(); skin.FindAttachmentsForSlot(slot, attachments); skin.FindNamesForSlot(slot, names); string name = names[index]; string attachment = attachments[index]; // with this code: List<Skin.SkinEntry> entries = new List<Skin.SkinEntry>(); skin.GetAttachments(slot, entries); string name = entries[index].Name; string attachment = entries[index].Attachment;
-
PoseSkeleton()
andPoseWithAnimation()
extension methods were removed. As a replacement you can useAnimationState.ClearTrack(0);
followed byvar entry = AnimationState.SetAnimation(0, animation, loop); entry.TrackTime = time
to achieve similar behaviour. -
Replace usage of
Attachment.GetClone()
withAttachment.Copy()
and usage ofMeshAttachment.GetLinkedClone()
withMeshAttachment.NewLinkedMesh()
. -
Replace usage of
Attachment.GetClone(bool cloneMeshesAsLinked)
withAttachment.GetCopy(bool cloneMeshesAsLinked)
-
SkeletonDataAsset.atlasAssets
is now an array of the base classAtlasAssetBase
instead ofSpineAtlasAsset
, which provides anIEnumerable<> Materials
instead of aList<> materials
. So replace any access viaatlasAsset.materials[0]
withatlasAsset.Materials.First()
and add ausing System.Linq;
statement at the top of your file. -
Replace using statements of
using Spine.Unity.Modules.AttachmentTools;
withusing Spine.Unity.AttachmentTools;
. You can removeusing Spine.Unity.Modules;
statements when ausing Spine.Unity
statement is already present in the file.
For a complete list of changes, see the spine-runtimes/CHANGELOG.md at 3.8.
Timeline Support has been moved to a separate UPM (Unity Package Manager) Package
See the changelog for more info:
spine-runtimes/CHANGELOG.md at 3.8
Changes of default values
-
SkeletonMecanim
'sLayer Mix Mode
now defaults toMixMode.MixNext
instead ofMixMode.MixAlways
. Consider this when creating newSkeletonMecanim
instances, existing ones are not affected. Note: for a short time, the default value was changed toMixMode.SpineStyle
.MixMode.SpineStyle
is now renamed toMixMode.Hard
. BlendModeMaterialAsset
and it's instanceDefault BlendModeMaterials.asset
now haveApply Additive Material
set totrue
by default in order to apply all blend modes by default.
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!
Thanks @Harald
Hey guys - I'm assuming I can follow this guide to upgrade from Spine-Unity 3.6 to 3.8, am I correct? Or do I need to upgrade to 3.7 first?
The basic steps of both upgrades can be combined to a single upgrade from 3.6 to 3.8.
Of course you have to adapt to code changes that happened from 3.6 to 3.7 as well, e.g. if you were using SkeletonAnimator
in code, change it to SkeletonMecanim
.
Just have a look at the changes that were introduced from 3.6 to 3.7 here:
Spine-Unity 3.6 to 3.7 Upgrade Guide
Thank you Harald!
After updating to 3.8, I got a lot of errors.
Updated your Spine-Unity runtime to 3.8 according to your guide.
Most of the problems have been solved successfully, but there is one problem.
Like the attached image, there are a lot of errors in "Assets \ Spine \ Runtime \ spine-unity \ Components \ SkeletonGraphic.cs" and I can't test the game.
Do you know this issue?
How can I solve this problem?
And I'm currently using Unity version 2019.3.0a5.
If the cause is in the Unity version, is there a version you recommend?
A couse of error is that class or namespace "MaskableGraphic" does't exist in Asset.
PandMEntertm a écritAnd I'm currently using Unity version 2019.3.0a5.
Sorry to hear that you are facing problems. Thanks for providing the version info, that is exactly the reason why you receive these errors: Unity 2019.3 alpha is not supported by Spine yet. That is the reason why we state Compatible with Spine 3.8.x and Unity 2017.1-2019.2
on the download page and in the changelog.
We recommend using Unity 2019.2 in your case, but in general any Unity version listed as supported will be a good choice.
Dear Harald,
As you advised, I downgraded Unity.
A large amount of Prefab data has been corrupted, but the Spine animation can now be played back safely.
Thank you for your constant support.
I hope that all versions of Unity will be supported over time.
Also, I will take care not to inadvertently update Unity.
Prefab data has been corrupted by your Unity downgrade? That sounds terrible, sorry to hear that.
In general we will always strive to support the latest non-beta (and non-alpha) Unity versions when they are released. Unfortunately alpha versions will be too unstable for us (API wise it might change) to depend our code on too early.
Hello,
I'm unity3d c# programmer, but I have few spine animation, from different versions 3.7 and 3.8. How I can use it in one project without re-export. I dont have Spine, I ordered this animations. Thanks for a reply)
I'm afraid you must export from the version of Spine that matches the version of the runtime you are using. You could try using the JsonRollback tool to make 3.8 JSON compatible with 3.7 runtimes, but this is not officially supported:
Open project in an older version
Also please note that using the Spine Runtimes without a Spine license has restrictions: all users of your application will need their own Spine license. Read more here:
Spine Runtimes License Agreement
Thank you always, Harald.
My prefab was able to be restored with almost no damage the way I found it on the net.
But I still have problems.
I have a license for the latest version of Spine.
If you try to import a character created with it into Unity 2019.2.01f by drag and drop, Unity will crash.
However, deleting the imported file from Windows Explorer will no longer crash.
This problem happen only the case of Spine exported files, not other files(for example, png files).
Do you know how to solve this problem?
Did you also recognize this issue?
Please give me some advice.
P.S.
My problem is the same case of below URL:
Unity Crashes when importing spine files
Sorry to hear that. Unfortunately I could not reproduce this problem, using the latest unitypackage (spine-unity-3.8-2019-08-15.unitypackage
) and data exported from Spine 3.8.60.
Which version of Spine did you use to export your files, was it also 3.8.60?
My problem is the same case of below URL:
Unity Crashes when importing spine files
Please note that the problem in the above thread was caused by mixing Spine versions: assets exported from Spine 3.7, imported in Spine-Unity 3.8 runtime.
Does this happen every time you are importing the asset via drag and drop? If yes, could you please send us your problematic exported assets as a zip file, to contact@esotericsoftware.com? Then we can have a look at it.
Dear Harald,
Thank you for your reply.
I tried as many times as I could until I received your reply, but I couldn't solve the problem.
Some data was lost, but I found an older version of Spine data in the backup data.
I will wait for the runtime to support Unity 2019.3x.
Hi,
I'm updating from Spine 3.6 to 3.8 and using Unity 2019.1.9f1.
I have a custom implementation of the mix and match script and I get the following error:
'AtlasAssetBase' does not contain a definition for 'materials' and no accessible extension method 'materials' accepting a first argument of type 'AtlasAssetBase' could be found (are you missing a using directive or an assembly reference?)
referring to the following code in Start():
skeletonAnimation = GetComponent<SkeletonAnimation>();
if (sourceMaterial == null)
{
if (skeletonAnimation != null)
sourceMaterial = skeletonAnimation.SkeletonDataAsset.atlasAssets[0].Materials[0];
}
What could be the issue?
Sorry for the trouble.
For some reason the error message does not completely fit the code (uppercase M vs lowercase m), however I assume that the problem is as follows:
The SkeletonDataAsset.atlasAssets
array now holds an array of the base class AtlasAssetBase
instead of SpineAtlasAsset
, which provides an IEnumerable<> Materials
instead of a List<> materials
. Therefore the error should be resolved by replacing the access materials[0]
with Materials.First()
as follows:
// Add this using statement at the top of your file:
using System.Linq;
...
// replace this line:
// sourceMaterial = skeletonAnimation.SkeletonDataAsset.atlasAssets[0].Materials[0];
// with this line:
sourceMaterial = skeletonAnimation.SkeletonDataAsset.atlasAssets[0].Materials.First();
Thanks for reporting this problem, I have added an entry to the changelog and the list at the top.
Hi Harald,
No worries. Thanks!
Hi Harald,
Im having an issue for some days i cannot resolve.
I updated to spine 3.8, using Unity 2019.2. Re exported all spines.
and i keep getting this error:
InvalidCastException: Specified cast is not valid.
Spine.Unity.Editor.SpineEditorUtilities.IssueWarningsForUnrecommendedTextureSettings (System.String texturePath) (at Assets/Spine/Editor/spine-unity/Editor/Utility/SpineEditorUtilities.cs:172)
And cannot edit the spine object (the skeleton animation component is broken).
Am i missing something here?
thanks a lot
We are sorry that you are having trouble!
Which version of the Spine-Unity runtime (name of the unitypackage as downloaded from here) are you using, and which version of the Spine Editor?
If using git, please note that the 3.8-beta branch has been replaced by the non-beta 3.8 branch in the meantime.
If both are latest available version (runtime spine-unity-3.8-2019-08-28.unitypackage
and Spine 3.8.68), please send us a minimal Unity project that still shows the problem as a zip file. You can send it to contact@esotericsoftware.com.
Hi Herald!
Thanks for responding.
I exported the file using Spine 3.8.68, and using the unity package "spine-unity-3.8-2019-08-23".
I will send you a zip file.
Thanks again
Thanks for the reproduction package - there was indeed a different bug involved that triggered when it found a file with extension ".atlas1.txt".
This issue has been fixed now, new unitypackages have been uploaded.
You can download it here as usual:
Spine Unity Download
Thanks again for reporting and sorry for the trouble!
Hello,
We are updating to spine 3.8 - was the Ragdoll and the Kinematics Shadow Modules removed from the integration completely?
Got error in scripts using those two, since they no longer exist. Is there a substitute in the pkg?
It seems their namespace has been changed, see the notes on SkeletonRagdoll2D
etc. in the CHANGELOG spine-runtimes/CHANGELOG.md at 3.8
- Modifié
A short note on a change committed today regarding SkeletonMecanim:
SkeletonMecanim
'sLayer Mix Mode
enum nameMixMode.SpineStyle
has been renamed toMixMode.Hard
. This is most likely not set via code and thus unlikely to be a problem. Serialized scenes and prefabs are unaffected.SkeletonMecanim
'sLayer Mix Mode
now defaults toMixMode.MixNext
. Note: for a short time, the default value was changed to MixMode.SpineStyle (MixMode.Hard). This was unfortunately less intuitive in behaviour and has thus been changed.
I have also added extensive documentation of the MixMode parameters to the spine-unity documentation pages here:
spine-unity Runtime Documentation: SkeletonMecanim Component
The respective sections have been added in the top-most posting as well.
We hope that these changes make SkeletonMecanim more intuitive and easier to use .
Finally upgraded to Spine 3.8! Aside from fixing the changed method/variable names, it went pretty smoothly. Only one issue spotted so far and it's related to Attachment's "GetRemappedClone". On Spine 3.7, region attachments would copy any color tinting, but mesh attachments wouldn't. So I had code like this:
Spine.Attachment newAttachment = templateAttachment.GetRemappedClone(atlasRegion, true, true, skeletonDataAsset.scale);
if (newAttachment == null)
Debug.Log("clone attachment failed for " + originalSkin + " " + regionName + " " + slot + " " + templateAttachmentName);
if (templateAttachment.GetType() == typeof(Spine.MeshAttachment))
{
Spine.MeshAttachment newAttachmentCasted = (Spine.MeshAttachment)newAttachment;
Spine.MeshAttachment oldAttachment = (Spine.MeshAttachment)templateAttachment;
newAttachmentCasted.R = oldAttachment.R;
newAttachmentCasted.G = oldAttachment.G;
newAttachmentCasted.B = oldAttachment.B;
newAttachmentCasted.A = oldAttachment.A;
}
But I noticed in Spine 3.8, a bunch of our attachments were appearing white suddenly. So it turns out we need to also do this check for RegionAttachments now:
if (templateAttachment.GetType() == typeof(Spine.MeshAttachment))
{
Spine.MeshAttachment newAttachmentCasted = (Spine.MeshAttachment)newAttachment;
Spine.MeshAttachment oldAttachment = (Spine.MeshAttachment)templateAttachment;
newAttachmentCasted.R = oldAttachment.R;
newAttachmentCasted.G = oldAttachment.G;
newAttachmentCasted.B = oldAttachment.B;
newAttachmentCasted.A = oldAttachment.A;
}
else if (templateAttachment.GetType() == typeof(Spine.RegionAttachment))
{
Spine.RegionAttachment newAttachmentCasted = (Spine.RegionAttachment)newAttachment;
Spine.RegionAttachment oldAttachment = (Spine.RegionAttachment)templateAttachment;
newAttachmentCasted.R = oldAttachment.R;
newAttachmentCasted.G = oldAttachment.G;
newAttachmentCasted.B = oldAttachment.B;
newAttachmentCasted.A = oldAttachment.A;
}
I'm not sure if this is intended but it's something I came across.
Thanks very much for reporting!
This issue has just been fixed. New unitypackages can be downloaded here as usual:
Spine Unity Download
MeshAttachment was already copying color, so you should now be able to remove the complete code block.
I'm having trouble getting the timeline package to work. I've installed the spine 3.8 UPM and fixed all compile errors related to that (we are upgrading from 3.7). But when bringing in the timeline package (I can't find a UPM, only a zip) I'm getting new errors stating that various spine namespaces can't be found. Could I be installing it incorrectly? I just unzipped the archive to the packages folder in my unity project. I tried importing the zip with the package importer, but it gives me an error that states that all of the files already exist in my project (they don't).
Any thoughts?
I'm also seeing an issue with certain meshes not displaying properly for re-exported skeleton files; it seems that some weighted meshes appear to have negative scaling or are skewed or something, although there is nothing on the bone rotation/scaling to suggest why this would be happening. Any help would be greatly appreciated.
Unity version is 2019.4.9f1
Please note that our resident Unity expert, Harald, is currently on vacation. He'll catch up to forum posts and everything else ASAP when he's back. I can try to help, but I apologize if only in a basic way.
There should not be any errors after installing, so that is a clue something went wrong early on. Did you get spine-unity from the download page? You should remove the old files first, otherwise you could have a mix of old and new files which would cause problems.
Thanks Nate, any help is appreciated. I completely removed all spine files and reinstalled (the spine-unity upm and timeline package are both from the downloads page). In the process of reinstalling, I've noticed that the namespace compile errors are only popping up when 'SPINE_TK2D' is defined. As soon as it's disabled, they disappear. Could there be a compatibility issue with the timeline package and tk2d support? Hopefully that helps to narrow it down.
Oy, it very well could be an issue with Toolkit2D. It is not as popular as using straight Unity, so likely sees less testing. I'm afraid this is Harald's domain, we may need to wait for him to return.
Sorry for the late reply and sorry for the inconvenience!
The problem is that the com.esotericsoftware.spine.timeline
package comes with asmdef
files. The quick fix is to remove (or change the extension from .asmdef
to .txt
) the two asmdef files:
com.esotericsoftware.spine.timeline\Editor\spine-timeline.asmdef
com.esotericsoftware.spine.timeline\Runtime\spine-timeline-editor.asmdef
Note: the "TK2D Support" - "Enable" button does something similar with the asmdef files of spine-unity, but it does not (and cannot easily) cover those in imported packages.
Is there no plan to make spine-unity 3.8 for Unity 5.6? It seems my artist was on auto update and now I have no ability to import the new assets into our 5.6 game due to the lack of package support.
I can understand removing Unity 5.6 support with the upgrade to 4.0, but I did not expect it with 3.8. Is there a way that I can downgrade the 3.8 files she made to 3.7 if there is not going to be a Unity package compatible with Unity 5.6 for Spine 3.8?
Riku a écritI can understand removing Unity 5.6 support with the upgrade to 4.0, but I did not expect it with 3.8.
With the arrival of spine-unity 3.8 (non-beta around 07/2019 if I recall correctly), we already dropped official support for Unity 5.6 (you can also see it in this posting). Support has not been dropped recently. This does not mean that the first 3.8 spine-unity unitypackages did not compile any more. Perhaps you have continued to use the unsupported Unity 5.6 version without noticing, since it did not break immediately?
Riku a écritIs there no plan to make spine-unity 3.8 for Unity 5.6?
No. While you should likely be able to use earlier spine-unity 3.8 packages without problems, it is not recommended as many bugfixes followed.
Riku a écritIt seems my artist was on auto update and now I have no ability to import the new assets into our 5.6
In general: don't auto-update when in a project. Stay on a fixed version, no-one shall upgrade before asking everyone.
Then your skeleton assets are on version 4.0, not on 3.8, right? spine-unity 3.8 won't help with 4.0 assets.
Riku a écritIs there a way that I can downgrade the 3.8 files she made to 3.7
Yes.
Versioning - Spine User Guide: Recovering work from a newer version
Thank you so much, it looks like I can export the 3.8 version files using 4.0 (as 3.8 does not have versioned exports that I can find) and import without issue to 3.7. I think she updated recently, thankfully, but I have requested she set her projects to 3.7 so we won't have any further issues.
Glad to hear, thanks for letting us know!