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

[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. 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 类:

Skeleton.DrawOrder → Skeleton.DrawOrder.AppliedPose 用于渲染
Skeleton.DrawOrder → Skeleton.DrawOrder.Pose 用于更改渲染顺序

13. TrackEntry 移除了以下属性:

移除了 TrackEntry.HoldPrevious 和 TrackEntry.InterruptAlpha 属性. 新的 AnimationState 属性包含了系统自动计算的状态值

14. 将 Skin.SkinEntry.Name 重命名为了 Skin.SkinEntry.Placeholder:

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. 其他破坏性变更:

Bone 不再包含 Bone.Skeleton 属性, 其构造函数不再接受 skeleton 参数
时间轴(Timeline)的 Apply() 方法现在可额外传入 appliedPose 参数
时间轴(Timeline)的 PropertyIds 类型从 string[] 改为 ulong[]. 同时影响 Animation.HasTimeline() 参数和时间轴类的构造函数
附件(Attachment)的 ComputeWorldVertices() 方法方法现在可额外传入 skeleton 参数
时间轴约束索引方法已重命名, 统一使用 ConstraintIndex 属性
已移除 BoneLocal 类. BonePose 现在直接实现了 IPose<BonePose> 并包含了所有本地 pose 字段. 请将代码中的所有 BoneLocal → BonePose 类
IkConstraintData.Uniform 已被 IkConstraintData.ScaleY 替代. IkConstraint.Apply() 方法现可传入 ScaleY 参数, bool uniform 参数已被废弃
MeshAttachment.ParentMesh 重命名为了 MeshAttachment.SourceMesh

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

Spine 示例项目中的示例 skeletons 现在使用 straight alpha textures 和 materials, 以更好地兼容线性颜色空间
默认的 atlas texture 工作流已从 PMA 改为了 straight alpha textures 以同时兼容伽马和线性两种颜色空间
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 属性包含了系统自动计算的状态值
移除了 SkeletonAnimation (仅在 4.3-beta 分支中) 临时添加的 MainThreadStart, MainThreadInterrupt, MainThreadEnd, MainThreadDispose, MainThreadComplete 和 MainThreadEvent 回调. 现在 SkeletonAnimation.AnimationState 和 TrackEntry 事件将自动在主线程中处理, 因此无需更改用户代码, 且即使启用了线程化动画 TrackEntry 事件仍然可以直接使用
SkeletonGraphic 属性 CustomSlotMaterials 现在能正确地直接赋值覆盖 material, 而不再只是赋值覆盖 material 的 texture(这一行为基本毫无用处). 现在可以为其赋予兼容 SkeletonGraphic 的 material, 例如 SkeletonGraphicAdditive-Straight
移除了旧的鸡肋菜单项, 如 GameObject - Spine - SkeletonRenderer 等. 这些菜单项会在场景中生成一个挂载了空 SkeletonRenderer 组件的 GameObject, 但并未为其分配 SkeletonDataAsset, 导致组件处于未初始化状态
移除了由 Unikron Software 开发且长期弃置的第三方资产 "2D Toolkit" (TK2D) 的支持

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

wiige

在 4.3-beta 分支上刚刚引入了新的破坏性更新, 以修复 mask interaction updates at runtime 问题：

skeletonRenderer.maskInteraction 属性已改为 skeletonRenderer.MaskInteraction

此更改已添加至 4.3-split-component-upgrade-guide.

RadiantFly

After the upgrade, when the character's materials are automatically replaced with trimmed materials, some materials fail to be replaced—this worked fine in previous versions.

Harald

RadiantFly Sorry to hear you're having troubles. What do you mean by "trimmed materials"? How are you replacing materials? Or do you mean materials for Mask Interaction Mode Inside Mask or Outside Mask?

In general we are not aware of any such issue, our tests worked without problems. Could you please send us a minimal Unity project which still shows this issue? You can send it as a zip file to contact@esotericsoftware.com, briefly mentioning this forum thread URL so that we know the context. Then we can have a look at what's going wrong.

RadiantFly

In 4.2,I use more than 2 atlasAssets,and only use 1 in begin,other atlasAssets add in when use.In 4.2 is all fine.But in 4.3,the other atlasAssets is wrong in maskmode,because this function can't get these atlasAssets.I must deal with this problem.Or is there any other way to reduce the number of materials loaded for the first time？

Harald

RadiantFly In 4.2 is all fine.But in 4.3,the other atlasAssets is wrong in maskmode,because this function can't get these atlasAssets.

Please describe what you mean by "atlasAssets is wrong". If you receive errors or warning, could you please show what exact error/warning message you see in the console? Are you getting a null-reference exception? Or what is the result that you see, compared to what you expected to see.

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.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 later to integrate these changes as well.

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.