[ZH-CN]Spine-Unity 3.8 to 4.0升级指南

wiige

本文于2021-11-18译自官方的Spine-Unity 3.8 to 4.0 Upgrade Guide, 由作者@"Harald"#7956授权翻译, 本译本随官方文档更新.

This Guide was translated from official Spine-Unity 3.8 to 4.0 Upgrade Guide, authorized by the writer @"Harald"#7956 at 2021-11-18.Update simultaneously with original post.

距Spine 4.0的正式发布还有几天时间, 本文将在此提供平滑升级spine-unity运行时的必要信息.

如果你升级自比spine-unity 3.8更早的版本, 请另查看以下升级指南, 了解如何调整代码和资产:
Spine-Unity 3.7 to 3.8升级指南
 Spine-Unity 3.6 to 3.7升级指南

重新导出Skeleton数据
注意: 从Spine 3.8导出的Json和二进制skeleton数据文件将无法被Spine-Unity 4.0运行时正确读取!
Skeleton数据文件应使用Spine 4.0重新导出.

如果你有大量项目需要导出, 建议使用命令行脚本自动导出项目文件:
Export - Spine User Guide: Command line
这里有一份示例脚本, 我们用它来导出全部官方Spine示例项目并自动创建纹理atlas:
https://github.com/EsotericSoftware/spine-runtimes/blob/4.0/examples/export/export.sh

从spine-unity 3.8升级至4.0的建议步骤:

为防升级中的横灾飞祸, 应为3.8版项目先创建一份备份.
关闭所有已打开的场景并创建一个新的空白场景, 并保持项目中的对象均未被选中. 这是为了确保没有活动的Spine对象.
记录下你对Spine-Unity运行时做的全部自定义修改. 这是为了升级后可以恢复你自己的更改.
删除现有的 "Spine" 和 "Spine Examples" 文件夹.
关闭项目和Unity.
用重新导出的4.0版的skeleton资产文件替换掉原来的3.8版文件. 切记不要删除旁边的 .meta文件.
打开Unity和项目.
导入最新的Spine-Unity 4.0 unitypackage.
在项目面板上选择 RightMouseButton - Reimport All(或在包含Skeleton资产的文件夹上右键选择 Reimport).

调整代码以适配4.0版的API
要了解API的主要变化, 请参见Changelog中的 C# 和 Unity 两节.
https://github.com/EsotericSoftware/spine-runtimes/blob/4.0/CHANGELOG.md#c-2

在4.0版运行时中重命名或替换了某些方法.
如果你在自己的代码中因为使用了重命名和不再存在的方法而收到编译错误, 那么changelog中的以下几点将有助于你查找病因, 使你可以修改代码来适配API:

所有的Spine.Unity.AttachmentTools.SkinUtilities 皮肤(Skin)扩展方法均被移除, 这些方法被新的Skin API所取代. 要修复这类编译错误, 可以把全部http://zh.esotericsoftware.com/spine-api-reference#Skin扩展方法都替换成其等效方法, 例如可以用skin.AddSkin() 替换 skin.AddAttachments() . 如果你使用了 UnshareSkin(), 可以按如下方法替换之:
```
skeletonAnimation.Skeleton.UnshareSkin();
//替换为以下代码
Skin customSkin = new Skin("custom skin");
customSkin.AddSkin(skeletonAnimation.Skeleton.Skin);
```
关于如何使用新的Skin API来组合皮肤, 请参见示例场景Mix and Match Skins ; 关于如何更新使用旧工作流程的已有项目, 请参见旧示例场景 Mix and Match 和 Mix and Match Equip .
可用 Skin.Attachments 替换掉全部的 Skin.GetAttachments() . 其返回值类型已改为 ICollection<SkinEntry> .
Spine.Unity.AttachmentTools.AttachmentCloneExtensions 扩展方法已被移除. 用Attachment.Copy() 替换掉全部的 Attachment.GetCopy() , 用 Attachment.NewLinkedMesh() 替换掉全部的 Attachment.GetLinkedMesh() .
移除了 Spine.Unity.AttachmentTools.AttachmentRegionExtensions 的扩展方法Attachment.GetRegion() . 可使用 Attachment.RendererObject 来替代 AtlasRegion.
移除了冗余的 Spine.SkeletonExtensions 扩展方法:
可使用 Skeleton.SetSlotsToSetupPose() 替换：
- Skeleton.SetPropertyToSetupPose()
- Skeleton.SetDrawOrderToSetupPose()
- Skeleton.SetSlotAttachmentsToSetupPose()
- Skeleton.SetSlotAttachmentToSetupPose()
可使用 Slot.SetToSetupPose() 替换：
- Slot.SetColorToSetupPose()
- Slot.SetAttachmentToSetupPose()
且移除了不常用的扩展方法:
TrackEntry.AllowImmediateQueue() 、Animation.SetKeyedItemsToSetupPose() 和 Attachment.IsRenderable() .
移除了的 SkeletonData 和 Skeleton 方法: FindBoneIndex, FindSlotIndex. Skeleton和槽位有一个 索引 字段, 应该该成员字段即可. 在访问 slot.Index 之前, 请提前检查空引用 slot == null.
可使用
- SlotData slot = skeletonData.FindSlot(slotName); int index = slot != null ? slot.Index : -1;
替换：
- int index = skeletonData.FindSlotIndex(slotName);
可使用
- Bone bone = skeleton.FindBone(boneName); int index = bone != null ? bone.Index : -1;
替换：
- int index = skeleton.FindBoneIndex(boneName);

从3.8升级至4.0的运行时行为更改
行为更改的完整列表, 仍请参阅Changelog中的 C# 和 Unity 两节.
https://github.com/EsotericSoftware/spine-runtimes/blob/4.0/CHANGELOG.md#c-2

约束(Constraints)不再重置其他约束作出的更改. 在3.8版本中, 施加一个约束会恢复另一个约束作出的更改. 在4.0版中再无这种情况. 如果你的项目碰巧依赖于3.8版中的这一行为, 那么迁移到4.0后, 可能会发现有多余约束条件意外地影响skeleton.
当 allowMultipleCanvasRenderers 置为true时, SkeletonGraphic现在不再在每个子网格渲染器GameObject上使用RawImage组件. 取而代之的是使用一个新的自定义组件 SkeletonSubmeshGraphic , 它更节约资源. 这些组件的替换将通过编辑器脚本自动执行, 场景或Prefab的保存操作将持久化这一更改.
线性色彩空间. 以前槽位的颜色在Unity的 Linear 颜色空间中的显示与在Spine Editor的设置 Color management - Linear blending 中的显示不一致. 这一问题现在在所有着色器中都得到了修复, 包括URP和LWRP着色器. 如果你微调了槽位的颜色来补偿色差, 你得调回去了.
Additive槽位在被写入目标缓冲区之前一直有光照(lit). 现在所有lit着色器都拥有一个额外的参数Light Affects Additive, 默认置为 false, 因为这样更加直观. 你可以将其置为 true 来恢复旧版的行为.
修正了所有Sprite着色器在Premultiply Alpha blend模式下的blending行为 (包括URP和LWRP包). 以前顶点颜色的alpha会被premultiplied, 即使 Premultiply Alpha blend模式认为输入的是PMA texture和PMA顶点颜色. 因此在升级到4.0之后, 槽位-alpha blending将正确地变亮一些. 如果你已经通过禁用 Advanced - PMA Vertex Colors 来修复问题, 现在你可以重新启用这个参数了, 以便在单pass中渲染Additive槽位.
当禁用了 Advanced - Sample 8 Neighbourhood (因而使用4 Neighbourhood)时, 修正了所有 Outline 着色器的轮廓厚度. 若要恢复以前的轮廓厚度, 可以在禁用 Sample 8 Neighbourhood 的轮廓着色器的 Outline Threshold 参数上 /4 , 使阈值缩小4倍.
修正了时间轴在Director暂停时Clip不暂停(或恢复)播放的问题, 这现在是默认行为. 如果您需要旧版行为(例如在 Director 暂停期间继续播放idle动画), 现为每个时间轴Clip新增了一个 Don't Pause with Director 参数可供使用.
修正了时间轴的 Spine AnimationState Clips 忽略了Clip结束后时间轴上的空白轴位. 如果你就是需要旧版行为, 时间轴CLip现在也新增了 Don't End with Clip 和 Clip End Mix Out Duration 参数. 默认情况下, 当时间轴上的Clip后有空白空间时, 会在轨道上设置为空动画, 其 MixDuration 值等于 Clip End Mix Out Duration. 若将 Don't End with Clip 置为 true 将继续播放Clip的动画且恢复3.8版的旧行为. 如果你喜欢暂停动画而非淡出到空动画, 那么将 Clip End Mix Out Duration 置为小于0的值, 动画就会暂停.

你可以在该页面下载最新的unitypackages: Spine Unity 下载页面

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

希望诸位喜欢新版本的Spine, 并用它创造出更多令人惊叹的游戏佳作! 🙂

Harald

非常感谢@wiige 的精彩贡献！ 🙂
Thanks so much @wiige for your awesome contributions! 🙂