Spine-Unity 4.2 to 4.3 Upgrade Guide

Harald

You can find the officially compiled Upgrade Guide for version 4.3 below.
[Updated 2026-05-08]

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.

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. EventData value properties moved to EventData.SetupPose:

EventData.Int → EventData.SetupPose.Int
EventData.Float → EventData.SetupPose.Float
EventData.String → EventData.SetupPose.String
EventData.Volume → EventData.SetupPose.Volume
EventData.Balance → EventData.SetupPose.Balance

12. Skeleton.DrawOrder type changed from ExposedList<Slot> to DrawOrder class:

Skeleton.DrawOrder → Skeleton.DrawOrder.AppliedPose for rendering
Skeleton.DrawOrder → Skeleton.DrawOrder.Pose for changing the draw order

13. TrackEntry removed properties:

Removed TrackEntry.HoldPrevious and TrackEntry.InterruptAlpha. The new AnimationState hold system automatically calculates the required state values

14. Renamed Skin.SkinEntry.Name to Skin.SkinEntry.Placeholder:

Skin.SkinEntry.Name → Skin.SkinEntry.Placeholder

15. AttachmentLoader API changes, affecting custom AttachmentLoader subclasses:

AttachmentLoader methods NewRegionAttachment, NewMeshAttachment, NewBoundingBoxAttachment, NewClippingAttachment, NewPathAttachment, and NewPointAttachment now take an additional string placeholder parameter. Update any custom AttachmentLoader implementations accordingly
Removed AtlasAttachmentLoader.FindRegion(string name) from public interface. Added protected AtlasRegion FindRegion(string name, string path) instead which may be overridden when deriving your own subclass

16. 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
Timeline PropertyIds type changed from string[] to ulong[]. Animation.HasTimeline() parameter and Timeline constructors changed accordingly
Attachment ComputeWorldVertices() methods now take an additional skeleton parameter
Renamed timeline constraint index methods to use unified ConstraintIndex property
Removed BoneLocal class. BonePose now directly implements IPose<BonePose> and contains all local pose fields. Replace any use of BoneLocal → BonePose
IkConstraintData.Uniform replaced by IkConstraintData.ScaleY. IkConstraint.Apply() methods now take ScaleY instead of a bool uniform parameter
MeshAttachment.ParentMesh renamed to MeshAttachment.SourceMesh

17. 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
attachment.GetRemappedClone(params) → attachment.Copy(); attachment.SetRegion(params); Removed AttachmentCloneExtensions class, SetRegion methods are now in AttachmentRegionExtensions
ToAtlasRegionPMAClone() → ToAtlasRegionWithNewPMATexture()
ToRegionAttachmentPMAClone() → ToRegionAttachmentWithNewPMATexture()
SkeletonRenderer.maskInteraction → SkeletonRenderer.MaskInteraction
Removed Spine Timeline Spine Animation State Clip property Hold Previous. New AnimationState hold system automatically calculates the required state values
Removed intermediately added (4.3-beta branch only) SkeletonAnimation callbacks MainThreadStart, MainThreadInterrupt, MainThreadEnd, MainThreadDispose, MainThreadComplete and MainThreadEvent. Instead SkeletonAnimation.AnimationState and TrackEntry events are now automatically processed on the main thread, so no user code change is required, and TrackEntry events can be utilized directly even with threaded animation enabled
SkeletonGraphic property CustomSlotMaterials now properly assigns the override material directly instead of assigning the texture of the override material (which was of little use). You can now assign a SkeletonGraphic-compatible material like SkeletonGraphicAdditive-Straight
Removed the rather useless old menu entries GameObject - Spine - SkeletonRenderer and the like, which spawned a GameObject with an empty SkeletonRenderer component without SkeletonDataAsset assigned and thus uninitialized
Removed support for the long-abandoned third-party asset "2D Toolkit" (TK2D) by Unikron Software

┌───────────────────────────────────────────────┐
│ 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! 🙂

Harald

Update: The linked machine-translated Chinese and Japanese versions of the 4.3-split-component-upgrade-guide documents have been replaced by manually translated versions. A big thank you 🙇 to @wiige and @Misaki!

zf3d

导致之前很多脚本需要重新写,狠麻烦,不过还是改了

Harald

Sorry to hear it was cumbersome.

Please note that there is also a Chinese version of this 4.2 to 4.3 upgrade guide available:
https://esotericsoftware.com/forum/d/29263-zh-cnspine-unity-42-to-43%E5%8D%87%E7%BA%A7%E6%8C%87%E5%8D%97

Harald

There has just been an additional breaking change on the 4.3-beta branch to fix mask interaction updates at runtime:

skeletonRenderer.maskInteraction is replaced by Property skeletonRenderer.MaskInteraction.

This has also been added to the 4.3-split-component-upgrade-guide.

wiige

duplicated, moved to https://esotericsoftware.com/forum/d/16518-spine-runtime-40-zh-cn-translation/354

Harald

There has just been an additional breaking change on the 4.3-beta branch for this issue ticket.

attachment.GetRemappedClone(params) → attachment.Copy(); attachment.SetRegion(params);
ToAtlasRegionPMAClone() → ToAtlasRegionWithNewPMATexture()
ToRegionAttachmentPMAClone() → ToRegionAttachmentWithNewPMATexture()

When using the Unity Package Manager to update, be sure to re-import the spine-unity package samples after updating to make the Spine Examples code compile again.

The topmost posting has just been updated accordingly as well, it already contains the migration lines above.

Harald

There have been some additional breaking changes on the 4.3-beta branch in the last week for spine-csharp and spine-unity. From the CHANGELOG.md:

spine-csharp:

Renamed Skin.SkinEntry.Name to Skin.SkinEntry.Placeholder (note: was intermediately renamed to PlaceholderName) to better match Spine editor terminology.
Removed TrackEntry.HoldPrevious and TrackEntry.InterruptAlpha. New AnimationState hold system automatically calculates the required state values.
Removed BoneLocal class. BonePose now directly implements IPose<BonePose> and contains all local pose fields. Replace any use of BoneLocal → BonePose.
EventData no longer stores Int, Float, String, Volume, and Balance properties directly. Use EventData.SetupPose to access the setup pose Event which provides these properties instead.
- EventData.Int → EventData.SetupPose.Int
- EventData.Float → EventData.SetupPose.Float
- EventData.String → EventData.SetupPose.String
- EventData.Volume → EventData.SetupPose.Volume
- EventData.Balance → EventData.SetupPose.Balance
Timeline.PropertyIds type changed from string[] to ulong[]. Animation.HasTimeline() parameter and Timeline constructors changed accordingly.
Skeleton.DrawOrder type changed from ExposedList<Slot> to DrawOrder class. Use Skeleton.DrawOrder.AppliedPose for rendering and Skeleton.DrawOrder.Pose for changing the draw order.

spine-unity

Removed Spine Timeline Spine Animation State Clip property Hold Previous. New AnimationState hold system automatically calculates the required state values.

The topmost posting will be updated soon to integrate these changes as well.

abuki

I see that also TrackEntry.MixBlend was removed. Can you please elaborate on that? Especially in the context of my previous question here: https://esotericsoftware.com/forum/d/28817-mixblend-behavior/2

Nate

Sure! It's now better AND simpler. Be sure to see the beta API reference, which is up to date:
https://esotericsoftware.com/spine-api-reference-beta#Animation-apply

MixBlend is now boolean fromSetup for the Animation apply and Timeline apply methods. True means alpha transitions from setup pose to the animation pose. False means alpha transitions from the current pose to the animation pose.

MixDirection is new boolean out. True means mixing out, false means mixing in. This only matters for a few timeline types.

This makes for more booleans in the apply methods, which is harder to read, but it's already a low level API with many parameters so it wasn't exactly easy to before. The simpler concepts allow the logic in every timeline type to be simpler. We tried enums and the mix of enums and booleans in the method signature wasn't great.

Since MixBlend no longer exists, it's gone from TrackEntry.

Also the AnimationState "hold system" that prevents dipping is more robust. It handles all scenarios and you never need to manage it manually, so the TrackEntry holdPrevious property has been removed. In 4.2 and below, certain scenarios of mixing animations on various track could cause a pose to jump instead of mix smoothly, but that shouldn't happen in 4.3+.

A bigger change is how boolean add has improved. It now respects boolean fromSetup. When fromSetup and add are true, the animation is added to the setup pose. AnimationState now uses that so additive animations are never added to the pose from the last frame. If a property hasn't been set on a lower level, the additive animation will get the setup pose plus the animation. You no longer need to have a "base" animation that sets all properties that are keyed on higher tracks by additive animations.

Finally getting around to your actual question, you don't need to set MixBlend, and can't because it's gone. You can set animations on track 1 without an animation playing on track 0 and everything should work. If not, please let us know. AnimationState no longer has special behavior for track 0. It does use an optimization: when track 0 has 1 alpha, it applies the animation more efficiently. This is functionally identical, just more efficient for a very common case.

Harald

There have been some more breaking changes on the 4.3-beta branch since last posting for spine-csharp and spine-unity. From the CHANGELOG.md:

spine-csharp:

Skin.SkinEntry.Name was intermediately renamed to PlaceholderName which has now been changed to Skin.SkinEntry.Placeholder.
MeshAttachment.ParentMesh renamed to MeshAttachment.SourceMesh
AttachmentLoader methods NewRegionAttachment, NewMeshAttachment, NewBoundingBoxAttachment, NewClippingAttachment, NewPathAttachment, and NewPointAttachment now take an additional string placeholder parameter. Update any custom AttachmentLoader implementations accordingly.

The topmost posting has been updated as well, now containing the previously missing entries of the last update posting, updating items 11. - 17.