- Edited
Spine-Unity 3.6 to 3.7 Upgrade Guide
- Edited
Recommended upgrade steps for upgrading from 3.6 to 3.7:
- 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. Make a backup if it was changed.
- Delete your old "Spine" folder.
- Import the latest Spine-Unity 3.7 unitypackage.
- Optionally: close the project and Unity, and open it again.
- If you were using SkeletonAnimator in code, change it to "SkeletonMecanim". See more detailed changes below.
Json skeleton data exported from Spine 3.6 will be readable with the 3.7 runtime.
Binary skeleton data needs to be re-exported using Spine 3.7.
Notable changes:
- SkeletonMecanim
SkeletonAnimator
has been renamed toSkeletonMecanim
This is to make it easier to identify as a glance, and to maximize code completion utility when using one and not the other.
Existing prefabs and scenes should stay intact. But code needs to be updated to use "SkeletonMecanim" instead of "SkeletonAnimator".
Note this is NOT SkeletonAnimation.
SkeletonAnimation is still SkeletonAnimation.
Only SkeletonAnimator was renamed to SkeletonMecanim.
Those are different components.
- Shaders
Spine-Unity's basic shaders now allow straight-alpha textures by checking the "Straight Alpha Texture" checkbox in the Material inspector. This will compile the shader as a shader variant (keyword_STRAIGHT_ALPHA_INPUT
).
Spine/SkeletonGraphic (Premultiply Alpha)
was renamed to Spine/SkeletonGraphic
Spine/SkeletonGraphic Tint Black (Premultiply Alpha)
was renamed to Spine/SkeletonGraphic Tint Black
The old dedicated straight alpha shaders were removed.
Runtime and Editor, and Assembly Definition
If you want to utilize the new folder arrangement with the recommended assembly definition files, you can delete your old Spine-Unity runtime folder and import the latest unitypackage.
As usual, make sure you back up your project in case you lose some changes or something breaks in the process.SpineAtlasAsset
AtlasAsset
has been renamed toSpineAtlasAsset
. This clarifies that the atlas source is a Spine/libGDX atlas, rather than something else. Coming soon is the option to use Unity's SpriteAtlas for packing, as well as other atlas source options.
Existing fields on components, prefabs and assets should remain intact.Skeleton.FlipX/FlipY is now Skeleton.ScaleX/ScaleY
The Skeleton class now has ScaleX and ScaleY which replaces FlipX and FlipY.
Here is a summary to get an equivalent of the old behavior:
// To get the value
bool flipX = skeleton.ScaleX < 0;
// To set the value.
skeleton.ScaleX = flipX ? -1f : 1f;
the FlipX/FlipY properties are in the beta and marked as Obsolete, but will be removed on release.
SetPosition is now SetLocalPosition
TheBone.SetPosition
extension was renamed toBone.SetLocalPosition
for extra clarity.SkeletonDataModifiers and BlendModeMaterials asset
SkeletonDataAssets now have an extensible asset system for doing extra processing to SkeletonData after it is loaded. This is called SkeletonDataModifier assets.
One of these is the BlendModeMaterials asset. This asset type uses replacement Materials for attachments in slots that have special blend modes. It does this by generating the necessary Materials using the template materials stored in the asset.
It generates Materials needed for Screen and Multiply (and optionally, Additive) blend mode slots, then assigns those generated materials to the Attachments that are defined in a slot with special blend modes.
Compared to 3.6, BlendModeMaterials assets stand as a more performant solution that better-handles multi-texture cases compared to the old SlotBlendModes
component. SlotBlendModes is still useful for when you need to do instance-level material customization, and will not be removed from the runtime. However, in most basic cases, the BlendModeMaterials asset will be all you need.
This new module comes with a default "Default BlendModeMaterials" asset, as well as Materials which will work out of the box. To use it, just add this "Default BlendModeMaterials" asset to your SkeletonDataAsset's new "Skeleton Data Modifiers" list in the inspector.
If you want more advanced settings, you can duplicate that default asset or create a new one, then set your own custom materials and shaders to use as templates.
If you have multiple slots that share the same blend mode, and multiple attachments that are found in the same atlas, they will share the same generated Material.
As usual, multiple blend modes will cause your rendered skeleton mesh to use multiple Materials. With that comes more draw calls and other associated behaviors that come with multi-material MeshRenderers in Unity.
// MORE TO FOLLOW...
You can download the beta unitypackage now from the download page: Spine Unity Download
For more info on the changes, see : spine-runtimes/CHANGELOG.md at 3.7
Is there a chance to upgrade from 3.6 without exporting everything again?
- Edited
@forrestuv, I'm afraid not. The compatibility between Spine versions is handled at the Spine project level, not at the JSON data level. This keeps the Spine Runtimes loading of the data as simple as possible.
Note you can use Spine's command line export to export all your projects in one go.
Export - Spine User Guide: Command line
After upgrading to 3.7, I followed your instructions. Everything works fine, but after I did Reimort All in Unity, I had the following errors.
The line referenced in the error message indicates that the file at skeletonDataPath cannot be read:
TextAsset spineJson = (TextAsset)AssetDatabase.LoadAssetAtPath(skeletonDataPath, typeof(TextAsset));
This most likely means that the .asset file for your data was not found because it has not been generated.
Can it be that the atlas file was exported with the extension ".atlas" instead of ".atlas.txt"? You can find this in the export options on the Spine editor side. That would explain it.
When saving a project in Unity, it is reset in the state of animation: (For example, I have an animation "Idle", and when I save it, it is reset in the state "None" And this does not always happen!
Thanks for your description, I can now reproduce the error.
You can follow the issue at the following ticket url: [unity] Error upon Reimport All 路 #1248
I just fixed the "Reimport All" error, you can download the update here: Spine Unity Download.
However the second reported issue might still be remaining.
I have created a separate ticket for the SkeletonGraphic related issue: [unity] Error at SkeletonGraphic upon Reimport 路 #1252
Unfortunately, in my message above, nothing has changed: ( When you save the project, the animation is reset to the state "None"
I thought so, the bugfix only fixed the Reimport all it seams. I'm working on the other issue, I'll let you know once it's resolved.
Ticket link as above: [unity] Error at SkeletonGraphic upon Reimport 路 #1252
Harald wroteI thought so, the bugfix only fixed the Reimport all it seams. I'm working on the other issue, I'll let you know once it's resolved.
Ticket link as above: [unity] Error at SkeletonGraphic upon Import 路 #1252
Tell me please, did you manage to solve the problem?
I solved this problem:
For example, I have an animation "Idle", and when I save it, it is reset in the state "None"
However, during testing it was showing that the second related problem which leads to the error message Skeleton JSON file not set for ...
still persists. I discovered the cause of the problem in flawed behaviour of the Unity asset management system, unfortunately the solution took the whole week already since none of the numerous workarounds turned out to fix the problem.
Since so much time has passed already, I will publish the first part of the bugfix for you, so that the starting animation is no longer reset to None
and will continue with the other part of the bugfix separately.
I have just uploaded new packages with your bugfix as described above, you can download them here as usual:
Spine Unity Download
We can happily announce that the second remaining error (yielding the error message Skeleton JSON file not set for ...
) has just been fixed.
You can download the latest unitypackage from here as usual:
Spine Unity Download
Harald wroteI solved this problem:
For example, I have an animation "Idle", and when I save it, it is reset in the state "None"
However, during testing it was showing that the second related problem which leads to the error message
Skeleton JSON file not set for ...
still persists. I discovered the cause of the problem in flawed behaviour of the Unity asset management system, unfortunately the solution took the whole week already since none of the numerous workarounds turned out to fix the problem.Since so much time has passed already, I will publish the first part of the bugfix for you, so that the starting animation is no longer reset to
None
and will continue with the other part of the bugfix separately.
I have just uploaded new packages with your bugfix as described above, you can download them here as usual:
Spine Unity Download
We can happily announce that the second remaining error (yielding the error message
Skeleton JSON file not set for ...
) has just been fixed.You can download the latest unitypackage from here as usual:
Spine Unity Download
Thank you!
So, I followed the upgrade steps exactly, but then had 86 errors in the Unity console... however after some digging around I found out it's just the new texture warning system. It was causing Spine not to compile (and thus not link into Visual Studio scripts). After doing a bunch of reading I figured out I could turn off the texture warnings in preferences, but then after that I had to clear console and then go alter one of my scripts to cause a recompile.
The warnings looked like this:
But my materials are using Sprites/Default so I am not using premultiply alpha.. seems like a warning about this stuff is okay, but an error that causes Spine not to compile is intended?
Thanks.
Thanks very much for reporting this issue and sorry for the inconvenience!
I have just commited a bugfix for the exception Material doesn't have a float or range property '_StraightAlphaInput'
. I also removed the warnings in case of non-Spine shaders. So you should be able to enable the warnings again in the Spine Settings and receive neither errors nor warnings.
It will be included in the next unitypackage, published in the next few days.
Harald wroteThanks very much for reporting this issue and sorry for the inconvenience!
I have just commited a bugfix for the exception
Material doesn't have a float or range property '_StraightAlphaInput'
. I also removed the warnings in case of non-Spine shaders. So you should be able to enable the warnings again in the Spine Settings and receive neither errors nor warnings.It will be included in the next unitypackage, published in the next few days.
Awesome, thanks for the quick response! Will it be in the 3.7 package or is it something in 3.8 beta?
Thanks again!