本文于2025-10-16译自官方的Spine-Unity 4.2 to 4.3 Upgrade Guide, 由原文作者 @Harald 授权翻译, 本译本随官方文档更新.
This Guide was translated from Spine-Unity 4.2 to 4.3 Upgrade Guide, authorized by guide writer @Harald at 2025-10-16. Update simultaneously with original post.
本文为4.3版运行时的完整官方升级指南.
[Original Post Updated at 2026-06-25, 中文版更新于 2026-10-25.]
重新导出 skeleton 并升级 spine-unity 运行时文件
请查阅以下 spine-unity 文档章节:
spine-unity 运行时文档: 更新 spine-unity 运行时
spine-unity 运行时文档: 更新扩展 UPM 软件包
其中介绍了诸如重新导出 skeleton、跨多个 spine-unity 版本进行升级, 以及如何安全地升级 spine-unity 运行时文件等必要步骤.
⚠️ 4.3 重大变更概览
spine-unity 4.3 引入了两组重大破坏性变更, 你需要按顺序逐一处理:
1. spine-csharp API 变更: 底层的 C# 运行时引入了全新的姿态(pose)系统, 这会改变你访问骨骼、槽位和约束属性的方式. 在处理组件变更之前, 你需要先把现有代码更新为使用新的 API.
2. spine-unity 组件拆分(在上述 API 变更之后处理): 主要的 skeleton 组件已被拆分为独立的渲染组件和动画组件. 虽然场景/预制件被打开时组件会自动升级, 但脚本中的组件引用可能会丢失, 需要手动迁移.
➡ 请阅读 4.3 模块化组件迁移指南 ⬅
重要提示: 请先按下文完成 spine-csharp API 变更的代码更新, 然后再处理组件拆分迁移. 这个顺序能确保在应对组件引用问题之前, 你的代码已经可以正确编译通过.
┌─────────────────────────────────────────────────────┐
│ 1. 让代码适配 spine-csharp 4.3 的 API 变更
└─────────────────────────────────────────────────────┘
如需查看排版更佳、内容完整的 API 变更清单, 请参阅 Changelog 中的 C# 和 Unity 两节.
影响 Unity 的主要 C# API 变更包括全新的姿态(pose)系统, 具体包含以下破坏性变更. 对于遇到的每个编译错误, 你都能在下表中检索到如何用新的迁移属性替换旧代码:
1. 颜色属性 .R .G .B .A 已由 .GetColor() 和 .SetColor() 取代:
2. Bone 的本地变换属性已移至 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 的世界变换和实际变换(applied)属性已移至 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 的属性已移至 SlotPose, 即 Slot.AppliedPose:
-
Slot.Attachment → Slot.AppliedPose.Attachment
-
Slot.R, .G, .B, .A → Slot.AppliedPose.GetColor() 和 SetColor()
-
Slot.R2, .G2, .B2 → Slot.AppliedPose.GetDarkColor() 和 SetDarkColor()
-
Slot.HasSecondColor → Slot.AppliedPose.HasDarkColor
-
Slot.Deform → Slot.AppliedPose.Deform
-
Slot.SequenceIndex → Slot.AppliedPose.SequenceIndex
5. Constraint 的属性已移至 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 的属性已移至 ConstraintData.GetSetupPose():
-
IkConstraintData.Mix → IkConstraintData.GetSetupPose().Mix
-
其余所有约束数据的属性与类型(TransformConstraintData、PathConstraintData、PhysicsConstraintData)均有类似变更
-
ConstraintData.XX → ConstraintData.GetSetupPose().XX
7. SkeletonData 现在提供单一的 IConstraintData 列表 SkeletonData.Constraints, 取代原先按约束类型划分的多个列表:
-
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 现在提供 SkeletonData.FindConstraint<ConstraintData>(), 取代原先按约束类型划分的多个查找方法:
-
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. setup pose 相关方法重命名:
-
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 已直接移至 Spine 命名空间下的 Physics:
-
在 Unity 中可能与 UnityEngine.Physics 冲突
-
Spine 物理: UpdateWorldTransform(Skeleton.Physics.Update) → UpdateWorldTransform(Spine.Physics.Update)
-
UnityEngine 物理: Physics.gravity → UnityEngine.Physics.gravity
11. EventData 的取值属性已移至 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 的类型已由 ExposedList<Slot> 改为 DrawOrder 类:
13. TrackEntry 移除的属性及 AnimationState hold 机制的变更:
14. Skin.SkinEntry.Name 已重命名为 Skin.SkinEntry.Placeholder:
15. AttachmentLoader API 变更, 影响自定义的 AttachmentLoader 子类:
-
AttachmentLoader 的 NewRegionAttachment、NewMeshAttachment、NewBoundingBoxAttachment、NewClippingAttachment、NewPathAttachment 和 NewPointAttachment 方法现在多了 string placeholder 参数. 请相应更新所有自定义的 AttachmentLoader 实现
-
从公共接口中移除了 AtlasAttachmentLoader.FindRegion(string name). 改为新增 protected AtlasRegion FindRegion(string name, string path), 派生自定义子类时可重写该方法
16. AnimationState 方法重命名:
17. 其他破坏性变更:
-
Bone 现在继承 PosedActive, 将姿态(pose)、约束后(constrained)和实际应用(applied)三种状态分开保存
-
Bone 不再提供 Bone.Skeleton 属性, 构造函数也不再接收 skeleton 参数
-
时间轴的 Apply() 方法现在多了 appliedPose 参数
-
Animation.Apply() 和 Timeline.Apply() 现在接收 MixFrom 值, 取代原先的布尔参数 fromSetup. 请将 true 改为 MixFrom.Setup, 将 false 改为 MixFrom.Current
-
时间轴 PropertyIds 的类型已由 string[] 改为 ulong[]. Animation.HasTimeline() 的参数以及时间轴构造函数也相应变更
-
附件的 ComputeWorldVertices() 方法现在多了 skeleton 参数
-
时间轴的约束索引方法已重命名, 统一改用 ConstraintIndex 属性
-
AnimationState.SetCurrent() → AnimationState.SetTrack(), 以及 AnimationState.GetCurrent() → AnimationState.GetTrack()
-
移除了 BoneLocal 类. BonePose 现在直接实现 IPose<BonePose> 并包含全部本地姿态字段. 请将所有 BoneLocal 的用法替换为 BonePose
-
IkConstraintData.Uniform 已由 IkConstraintData.ScaleY 取代. IkConstraint.Apply() 方法现在接收 ScaleY 而非 bool uniform 参数
-
MeshAttachment.ParentMesh 已重命名为 MeshAttachment.SourceMesh
18. Unity 特有的破坏性变更:
-
Spine Examples 中的示例 skeleton 现改用 straight alpha texture 和 material, 以更好地兼容线性(Linear)色彩空间
-
默认的 atlas texture 工作流已从 PMA 改为 straight alpha texture, 以更好地同时兼容伽马(Gamma)和线性色彩空间
-
attachment.GetRemappedClone(params) → attachment.Copy(); attachment.SetRegion(params); 移除了 AttachmentCloneExtensions 类, SetRegion 方法现位于 AttachmentRegionExtensions
-
ToAtlasRegionPMAClone() → ToAtlasRegionWithNewPMATexture()
-
ToRegionAttachmentPMAClone() → ToRegionAttachmentWithNewPMATexture()
-
SkeletonRenderer.maskInteraction → SkeletonRenderer.MaskInteraction
-
移除了 Spine Timeline 中 Spine Animation State Clip 的 Hold Previous 属性. 新的 AnimationState hold 系统会自动计算所需的状态值
-
移除了中途加入(仅存在于 4.3-beta 分支)的 SkeletonAnimation 回调 MainThreadStart、MainThreadInterrupt、MainThreadEnd、MainThreadDispose、MainThreadComplete 和 MainThreadEvent. 现在 SkeletonAnimation.AnimationState 和 TrackEntry 的事件会自动在主线程处理, 因此无需改动用户代码, 且在启用线程化动画时也能直接使用 TrackEntry 事件
-
SkeletonGraphic 的 CustomSlotMaterials 属性现在会正确地直接指定覆盖用的 material, 而不再是指定覆盖 material 的 texture(那样用处不大). 现在可以指定诸如 SkeletonGraphicAdditive-Straight 这类兼容 SkeletonGraphic 的 material
-
移除了几个相当无用的旧菜单项, 如 GameObject - Spine - SkeletonRenderer 等. 这些菜单项会生成一个带有空 SkeletonRenderer 组件的 GameObject, 但未分配 SkeletonDataAsset, 因而处于未初始化状态
-
移除了对早已废弃的第三方资源 "2D Toolkit"(Unikron Software 的 TK2D)的支持
┌───────────────────────────────────────────────┐
│ 2. 适配 spine-unity 模块化组件架构
└───────────────────────────────────────────────┘
在完成上述 spine-csharp API 变更的代码更新后, 你还需要处理组件拆分相关的变更:
主要的 skeleton 组件已被拆分为独立的渲染组件和动画组件. 这一变更带来了全新的灵活组合方式(例如用 SkeletonMecanim 做动画、用 SkeletonGraphic 做渲染), 但也需要对现有项目进行迁移.
简而言之: 在 4.3 中, SkeletonAnimation 和 SkeletonMecanim 现在只负责与动画相关的功能, 而渲染相关的功能则由 SkeletonRenderer 或 SkeletonGraphic 处理. SkeletonGraphic 不再包含任何与动画相关的内容, 而 SkeletonAnimation 和 SkeletonMecanim 也不再负责渲染.
在 Unity 编辑器中打开场景/预制件时, 组件会自动升级:
-
SkeletonAnimation → SkeletonAnimation + SkeletonRenderer 组件
-
SkeletonMecanim → SkeletonMecanim + SkeletonRenderer 组件
-
SkeletonGraphic → SkeletonAnimation + SkeletonGraphic 组件
但是, 自定义脚本中的现有引用可能会丢失, 因为组件类型已不再匹配(例如 SkeletonAnimation 不再是 SkeletonRenderer 的子类).
重要: 请勿跳过详细的模块化组件迁移指南
➡ 请阅读 4.3 模块化组件迁移指南 ⬅
该指南给出了模块化 SkeletonAnimation + SkeletonRenderer / SkeletonGraphic 组件的迁移步骤. 该指南亦提供英文和日文原文.
该指南包含:
-
分步迁移说明
-
用于更新脚本的代码示例
-
防止组件引用丢失的解决方案
-
可选的从 4.2 起两步式迁移路径
默认值的变更
-
默认 texture 工作流已变更: 从 PMA 改为 straight alpha texture, 以更好地兼容线性色彩空间(Unity 的默认设置). PMA Vertex Color 与此无关, 为了单次绘制的 additive 渲染仍应启用.
-
新增 Spine 首选项 Switch Texture Workflow 功能, 可快速切换到对应的 PMA 或 straight-alpha texture 与 material 预设.
结构调整非破坏性
官方支持的 Unity 版本: 2017.1-6000.1
你可以从下载页面获取新的 unitypackage: spine-unity 下载页
如果你发现有任何内容应当补充或记录到本指南中, 欢迎在下方回帖告知, 以便我们让所有人都能尽可能轻松、无痛地完成升级.
我们清楚本次更新需要投入相当多的迁移工作, 但希望这种将动画与渲染组件独立组合所带来的灵活性, 以及全新的线程化功能能够弥补这一点. 详情请参阅 CHANGELOG.
希望你会喜欢全新的 Spine 4.3-beta, 以及它改进后的架构与性能特性! 🙂