You can find the officially compiled Upgrade Guide for version 4.3 below.
Note: Chinese and Japanese translations of this upgrade guide are available as well.
Re-exporting skeletons and upgrading the spine-unity runtime files
Please check out the spine-unity documentation sections below:
spine-unity Runtime Documentation: Updating the spine-unity Runtime
spine-unity Runtime Documentation: Updating an Extension UPM Package
They describe necessary steps like re-exporting your skeletons, upgrading across multiple spine-unity versions and how to safely upgrade the spine-unity runtime files.
⚠️ Overview of Major Changes in 4.3
spine-unity 4.3 introduces two major sets of breaking changes that you need to address in order:
1. spine-csharp API changes: The underlying C# runtime introduces a new pose system that affects how you access bone, slot, and constraint properties. You'll need to update your existing code to use the new API before dealing with component changes.
2. spine-unity component split (handle after API changes above): Main skeleton components have been split into separate rendering and animation components. While components are automatically upgraded when scenes/prefabs are opened, your component references in scripts may be lost and require migration.
Important: Start by updating your code for the spine-csharp API changes below, then handle the component split migration. This order ensures your code compiles correctly before dealing with component reference issues.
┌─────────────────────────────────────────────────────┐
│ 1. Adapting your code to spine-csharp 4.3 API changes
└─────────────────────────────────────────────────────┘
For the complete list of API changes with better formatting, please see the Changelog, sections C# and Unity.
The main C# API changes that affect Unity include the new pose system with these breaking changes. For each compile error you receive, you should be able to search the listing below to find how to replace the old code with the new moved properties:
1. Color properties .R .G .B .A are replaced by .GetColor() and .SetColor():
2. Bone local transform properties moved to Bone.Pose:
-
Bone.X → Bone.Pose.X
-
Bone.Y → Bone.Pose.Y
-
Bone.Rotation → Bone.Pose.Rotation
-
Bone.ScaleX → Bone.Pose.ScaleX
-
Bone.ScaleY → Bone.Pose.ScaleY
-
Bone.ShearX → Bone.Pose.ShearX
-
Bone.ShearY → Bone.Pose.ShearY
3. Bone world and applied transform properties moved to Bone.AppliedPose:
-
Bone.AX → Bone.AppliedPose.X
-
Bone.AY → Bone.AppliedPose.Y
-
Bone.ARotation → Bone.AppliedPose.Rotation
-
Bone.AScaleX → Bone.AppliedPose.ScaleX
-
Bone.AScaleY → Bone.AppliedPose.ScaleY
-
Bone.AShearX → Bone.AppliedPose.ShearX
-
Bone.AShearY → Bone.AppliedPose.ShearY
-
Bone.WorldX → Bone.AppliedPose.WorldX
-
Bone.WorldY → Bone.AppliedPose.WorldY
-
Bone.WorldRotationX → Bone.AppliedPose.WorldRotationX
-
Bone.WorldRotationY → Bone.AppliedPose.WorldRotationY
4. Slot properties moved to SlotPose, i.e. Slot.AppliedPose:
-
Slot.Attachment → Slot.AppliedPose.Attachment
-
Slot.R, .G, .B, .A → Slot.AppliedPose.GetColor() and SetColor()
-
Slot.R2, .G2, .B2 → Slot.AppliedPose.GetDarkColor() and SetDarkColor()
-
Slot.HasSecondColor → Slot.AppliedPose.HasSecondColor
-
Slot.Deform → Slot.AppliedPose.Deform
-
Slot.SequenceIndex → Slot.AppliedPose.SequenceIndex
5. Constraint properties moved to Constraint.Pose:
IkConstraint:
-
IkConstraint.Mix → IkConstraint.Pose.Mix
-
IkConstraint.Softness → IkConstraint.Pose.Softness
-
IkConstraint.BendDirection → IkConstraint.Pose.BendDirection
-
IkConstraint.Compress → IkConstraint.Pose.Compress
-
IkConstraint.Stretch → IkConstraint.Pose.Stretch
TransformConstraint:
-
TransformConstraint.MixRotate → TransformConstraint.Pose.MixRotate
-
TransformConstraint.MixX → TransformConstraint.Pose.MixX
-
TransformConstraint.MixY → TransformConstraint.Pose.MixY
-
TransformConstraint.MixScaleX → TransformConstraint.Pose.MixScaleX
-
TransformConstraint.MixScaleY → TransformConstraint.Pose.MixScaleY
-
TransformConstraint.MixShearY → TransformConstraint.Pose.MixShearY
PathConstraint:
-
PathConstraint.Position → PathConstraint.Pose.Position
-
PathConstraint.Spacing → PathConstraint.Pose.Spacing
-
PathConstraint.MixRotate → PathConstraint.Pose.MixRotate
-
PathConstraint.MixX → PathConstraint.Pose.MixX
-
PathConstraint.MixY → PathConstraint.Pose.MixY
PhysicsConstraint:
-
PhysicsConstraint.Mix → PhysicsConstraint.Pose.Mix
-
PhysicsConstraint.Gravity → PhysicsConstraint.Pose.Gravity
-
PhysicsConstraint.Strength → PhysicsConstraint.Pose.Strength
-
PhysicsConstraint.Damping → PhysicsConstraint.Pose.Damping
-
PhysicsConstraint.MassInverse → PhysicsConstraint.Pose.MassInverse
-
PhysicsConstraint.Wind → PhysicsConstraint.Pose.Wind
6. ConstraintData properties moved to ConstraintData.GetSetupPose():
-
IkConstraintData.Mix → IkConstraintData.GetSetupPose().Mix
-
Similar changes for all other constraint data properties and types (TransformConstraintData, PathConstraintData, PhysicsConstraintData)
-
ConstraintData.XX → ConstraintData.GetSetupPose().XX
7. SkeletonData now provides a single IConstraintData list SkeletonData.Constraints instead of separate lists per constraint type:
-
SkeletonData.IkConstraints → SkeletonData.Constraints.OfType<IkConstraintData>()
-
SkeletonData.TransformConstraints → SkeletonData.Constraints.OfType<TransformConstraintData>()
-
SkeletonData.PathConstraints → SkeletonData.Constraints.OfType<PathConstraintData>()
-
SkeletonData.PhysicsConstraints → SkeletonData.Constraints.OfType<PhysicsConstraintData>()
8. SkeletonData now provides SkeletonData.FindConstraint<ConstraintData>() instead of single find methods per constraint type:
-
SkeletonData.FindIkConstraint(name) → SkeletonData.FindConstraint<IkConstraintData>(name)
-
SkeletonData.FindTransformConstraint(name) → SkeletonData.FindConstraint<TransformConstraintData>(name)
-
SkeletonData.FindPathConstraint(name) → SkeletonData.FindConstraint<PathConstraintData>(name)
-
SkeletonData.FindPhysicsConstraint(name) → SkeletonData.FindConstraint<PhysicsConstraintData>(name)
9. Renamed setup pose methods:
-
Skeleton.SetToSetupPose() → Skeleton.SetupPose()
-
Skeleton.SetBonesToSetupPose() → Skeleton.SetupPoseBones()
-
Skeleton.SetSlotsToSetupPose() → Skeleton.SetupPoseSlots()
-
Bone.SetToSetupPose() → Bone.SetupPose()
-
Slot.SetToSetupPose() → Slot.SetupPose()
-
IkConstraint.SetToSetupPose() → IkConstraint.SetupPose()
10. Skeleton.Physics was moved to Physics directly in Spine namespace:
-
May clash with UnityEngine.Physics in Unity
-
Spine Physics: UpdateWorldTransform(Skeleton.Physics.Update) → UpdateWorldTransform(Spine.Physics.Update)
-
UnityEngine Physics: Physics.gravity → UnityEngine.Physics.gravity
11. Other breaking changes:
-
Bone no longer provides a Bone.Skeleton property, constructor no longer takes a skeleton parameter
-
Timeline Apply() methods now take an additional appliedPose parameter
-
Attachment ComputeWorldVertices() methods now take an additional skeleton parameter
-
Renamed timeline constraint index methods to use unified ConstraintIndex property
12. Unity-specific breaking changes:
-
Example skeletons in Spine Examples are now using straight alpha textures and materials for better compatibility with Linear colorspace
-
Changed default atlas texture workflow from PMA to straight alpha textures for better compatibility with both Gamma and Linear color space
┌───────────────────────────────────────────────┐
│ 2. Adapting to spine-unity Component Architecture Split
└───────────────────────────────────────────────┘
After updating your code for the spine-csharp API changes above, you need to handle the component split changes:
Main skeleton components have been split into separate rendering and animation components. This change enables new flexible combinations (like using SkeletonMecanim for animation with SkeletonGraphic for rendering) but requires migration of existing projects.
Components will be automatically upgraded when scenes/prefabs are opened in the Unity Editor:
-
SkeletonAnimation → SkeletonAnimation + SkeletonRenderer components
-
SkeletonMecanim → SkeletonMecanim + SkeletonRenderer components
-
SkeletonGraphic → SkeletonAnimation + SkeletonGraphic components
However, existing references in your custom scripts may be lost because the component types no longer match (e.g., SkeletonAnimation is no longer a subclass of SkeletonRenderer).
📖 Please read the detailed migration guide:
4.3 Split Component Upgrade Guide. Available in Chinese and Japanese as well.
This guide contains:
- Step-by-step migration instructions
- Code examples for updating your scripts
- Solutions for preventing lost component references
- Optional two-step migration path from 4.2
Changes of default values
-
Default texture workflow changed: From PMA to straight alpha textures for better compatibility with Linear color space (Unity's default). PMA Vertex Color is independent of this and should still be enabled for single-pass additive rendering.
-
Added Spine Preferences Switch Texture Workflow functionality to quickly switch to the respective PMA or straight-alpha texture and material presets.
Restructuring (Non-Breaking)
-
Spine Examples have been moved and are now part of the main spine-unity UPM package. To import, select the spine-unity Runtime package in the Package Manager window, and in the Samples tab and hit Import.
Officially supported Unity versions: 2017.1-6000.1
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're aware that this update requires significant migration effort, but we hope that the gained flexibility of combining animation and rendering components independently and the new threading features make up for this. Check out the CHANGELOG for details.
We hope that you like the new Spine 4.3-beta with its improved architecture and performance features! 🙂
