Цей сайт найкраще переглядати в сучасному браузері з включеним JavaScript.

Spine-Unity 4.2 to 4.3 Upgrade Guide

Harald

You can find the officially compiled Upgrade Guide for version 4.3 below.

Note: Chinese and Japanese translations of this upgrade guide will be available soon. If you require a translated version, you may want to wait before upgrading.

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():

Color properties .R .G .B .A are replaced by .GetColor() and .SetColor()
Dark color properties .R2 .G2 .B2 are replaced by .GetDarkColor() and .SetDarkColor()

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! 🙂

Spinebot

The upgrade from Spine-Unity 4.2 to 4.3 involves significant changes, including updates to the spine-csharp API and a split in the spine-unity component architecture. The API changes introduce a new pose system, requiring updates to how bone, slot, and constraint properties are accessed. The component split separates rendering and animation components, which may lead to lost references in custom scripts. It's crucial to first adapt your code to the API changes before addressing the component split. The upgrade guide provides detailed instructions and code examples to assist with this transition, and translations in Chinese and Japanese will be available soon.