[ZH-CN]Spine-Unity 4.2 to 4.3升级指南

wiige

本文于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版运行时的完整官方升级指南.

重新导出 skeleton 并升级 spine-unity 运行时文件
请查阅以下 spine-unity 文档章节:
spine-unity 运行时文档: 更新 spine-unity 运行时
 spine-unity 运行时文档: 更新 UPM 扩展包
以上文档详细阐述了操作所需步骤, 包括重导出 skeletons、spine-unity 的跨版本升级, 以及如何安全地升级 spine-unity 运行时文件.

⚠️ spine-unity 4.3 的主要变更概览
spine-unity 4.3 引入了两项重大的破坏性变更, 请务必按下文所述依序处理:

1. spine-csharp API 变更: 底层的 C# 运行时采用了全新的姿态(pose)系统, 显著地改变了访问骨骼、槽位和约束属性的方式. 你必须先更新已有代码以适配新 API, 才能开始着手处理组件更改.

2. spine-unity 组件模块化(split) (请在改完 API 后再着手更新): 核心的 skeleton 组件被拆分为了相互独立的渲染组件与动画组件. 虽然在打开场景/预制件(Prefab)时会自动升级组件, 但在脚本中引用的组件可能丢失引用，需进行迁移操作.

重要提示: 请首先根据下文中的 spine-csharp API 变更列表更新你的代码, 再迁移至模块化组件. 严格遵守这一更新顺序才能确保你的代码在触及组件引用问题前仍保持正常编译.

┌─────────────────────────────────────────────────────┐
│ 1. 更改代码以适配 spine-csharp 4.3 API 变更
└─────────────────────────────────────────────────────┘
如需查阅格式齐整的完整 API 变更列表, 请访问 Github 上变更日志(Changelog)中的 C# 和 Unity 一节.

如遇编译错误, 均可在下文中查找如何用新属性替换旧代码. 影响 Unity 的主要 C# API 变更便是新的姿态(pose)系统, 具体破坏性变更如下:

1. 颜色属性 .R .G .B .A 已被 .GetColor() 和 .SetColor() 替代:

颜色属性 .R .G .B .A 已被 .GetColor() 和 .SetColor() 替代
暗色(Dark color)属性 .R2 .G2 .B2 已被 .GetDarkColor() 和 .SetDarkColor() 替代

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 的世界变换与应用变换属性已迁移至 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.HasSecondColor
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 Physics: UpdateWorldTransform(Skeleton.Physics.Update) → UpdateWorldTransform(Spine.Physics.Update)
UnityEngine Physics: Physics.gravity → UnityEngine.Physics.gravity

11. 其他破坏性变更:

Bone 不再使用 Bone.Skeleton 属性, 构造函数也不再接受 skeleton 参数
时间轴(Timeline)的 Apply() 方法现在可传入一个额外参数 appliedPose
附件(Attachment)的 ComputeWorldVertices() 方法现在可传入一个额外参数 skeleton
时间轴约束索引方法已重命名, 统一使用 ConstraintIndex 属性

12. 仅涉及 Unity 的破坏性变更:

Spine 示例项目中的示例 skeletons 现在使用 straight alpha textures 和 materials, 以更好地兼容线性颜色空间
默认的 atlas texture 工作流已从 PMA 改为了 straight alpha textures 以同时兼容伽马和线性两种颜色空间

┌───────────────────────────────────────────────┐
│ 2. 适配 spine-unity 模块化组件架构
└───────────────────────────────────────────────┘
在完成上述 spine-csharp API 变更后, 便可开始处理组件模块化变更:

核心的 skeleton 组件被拆分为了相互独立的渲染组件与动画组件. 这一变更使得更灵活的组合方式 (例如, 使用 SkeletonMecanim 控制动画, 同时使用 SkeletonGraphic 执行渲染) 成为可能, 但这也要求你迁移已有的项目.

组件将在 Unity 编辑器中打开场景/预制件时会自动执行升级:

SkeletonAnimation → SkeletonAnimation + SkeletonRenderer 组件
SkeletonMecanim → SkeletonMecanim + SkeletonRenderer 组件
SkeletonGraphic → SkeletonAnimation + SkeletonGraphic 组件

然而它却可能导致你的脚本丢失引用, 因为组件类型已被变更(例如 SkeletonAnimation 不再是 SkeletonRenderer 的子类).

📖 请阅读详细的模块化组件迁移指南:
spine-unity 4.3 模块化组件迁移指南. 该指南亦提供中文版和日文版.

该指南包含:

迁移操作的逐步骤详细说明
用于更新脚本的代码示例
防止丢失组件引用的解决方案
(可选的) 从4.2升级至4.3的两阶段迁移路径

默认值变更

Texture 默认工作流变更: 已从 PMA 改为 straight alpha textures, 以更好地兼容 Unity 默认的线性颜色空间. PMA Vertex Color 与此变更无关, 应仍保持启用以支持单通道 additive 渲染.
Spine Preferences 中添加了 Switch Texture Workflow 功能, 用以在 PMA 或 straight-alpha 的 texture 与 material 预设间快速切换.

重构 (非破坏性变更)

Spine 示例现已迁移入 spine-unity UPM包中. 如需导入, 请在 Unity 包管理器窗口中选择 spine-unity Runtime 包, 并在 Samples 选项卡中点击 Import 按钮.

官方支持的 Unity 版本: 2017.1-6000.1

你可从下载页面获取新的 unitypackage: spine-unity 下载页

如果你发现有什么解释得含混不清的地方, 或者指南中存在内容错漏, 请毫不犹豫地在此跟帖来痛陈高见, 这样我们才能让大家的升级之旅尽可能的更无脑&更无痛.

我们深知本次更新会带来巨大的迁移工作量, 但我们相信, 独立的模块化动画和渲染组件带来的灵活性, 以及全新的多线程功能定会让你不虚此行. 更多详情请查阅运行时的变更日志(CHANGELOG).

真心希望你能喜欢经历了架构改进与性能提升后的 Spine 4.3-beta! 🙂

Harald

Thank you so much again for your super fast translation! 🙇