spine-unity

入门

spine-unity 运行时文档

下载

spine-unity 4.1

spine-unity unitypackage

  • spine-unity 4.1 (更新于 2023-11-28, changelog)
    适用于Spine 4.1.00或更高版本, 以及Unity 2017.1-2023.1.
    使用git URL添加包: (各URL分别为spine-csharp, spine-unity 和示例文件)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.1 https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine#4.1 https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine Examples#4.1

URP Shaders UPM包 com.esotericsoftware.spine.urp-shaders

  • Unity 2019.3-2023.1: spine.urp-shaders 4.1 (更新于 2023-10-26)
    适用于spine-unity 4.1, 以及Unity 2019.3-2023.1.
    使用git URL添加包: (适用于通过UPM安装的spine-unity)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.urp-shaders#4.1

LWRP Shaders UPM包 com.esotericsoftware.spine.lwrp-shaders

  • Unity 2019.1: spine.lwrp-shaders 4.1 (更新于 2022-07-01)
    适用于spine-unity 4.1, 以及Unity 2019.1.
  • Unity 2019.2: spine.lwrp-shaders 4.1 (更新于 2022-07-01)
    适用于spine-unity 4.1, 以及Unity 2019.2.
    使用git URL添加包: (适用于通过UPM安装的spine-unity)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.lwrp-shaders#4.1

时间轴插件(Timeline Extensions) UPM包 com.esotericsoftware.spine.timeline

spine-unity 4.2-beta

spine-unity unitypackage

  • spine-unity 4.2-beta (更新于2023-12-05, changelog)
    适用于Spine 4.2.00-beta或更高版本, 以及Unity 2017.1-2023.1.
    使用git URL添加包: (各URL分别为spine-csharp, spine-unity 和示例文件)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-csharp/src#4.2-beta https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine#4.2-beta https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Assets/Spine Examples#4.2-beta

URP Shaders UPM包 com.esotericsoftware.spine.urp-shaders

  • Unity 2019.3-2023.1: spine.urp-shaders 4.2-beta (更新于 2023-11-17)
    适用于spine-unity 4.2-beta, 以及Unity 2019.3-2023.1.
    使用git URL添加包: (适用于通过UPM安装的spine-unity)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.urp-shaders#4.2-beta

LWRP Shaders UPM包 com.esotericsoftware.spine.lwrp-shaders

  • Unity 2019.1: spine.lwrp-shaders 4.2-beta (更新于 2023-11-21)
    适用于spine-unity 4.2-bete, 以及Unity 2019.1.
  • Unity 2019.2: spine.lwrp-shaders 4.2-beta (更新于 2023-11-21)
    适用于spine-unity 4.2-beta, 以及Unity 2019.2.
    使用git URL添加包: (适用于通过UPM安装的spine-unity)
    https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.spine.lwrp-shaders#4.2-beta

时间轴插件(Timeline Extensions) UPM包 com.esotericsoftware.spine.timeline

在新项目中安装spine-unity

  1. 创建一个空白的新项目.
  2. 导入你下载的spine-unity.unitypackage组件包. (双击它就可以让Unity打开).

若你还不熟悉spine-unity, 请移步spine-unity 运行时文档的入门章节来了解更多信息.

在现有项目中更新

  • 就像Unity的更新一样, 建议你在进行更新前备份整个Unity项目.
  • 在更新你的Spine运行时之前, 一定要与你的主程和TA做好确认. Spine运行时是开源的, 并允许用户根据不同的项目需求进行修改. 你项目的Spine运行时可能已经被程序员修改过了. 在这种情况下, 更新到最新的运行时也需要将这些修改重新应用于新版本运行时中.
  • 阅读unitypackage中包含的CHANGELOG.md文件或浏览github页面. 当过时的函数方法被新方法所取代时, 可以在此找到相关的细节表述.

就地更新 (通过.unitypackage)

当需要大版本升级时(例如从3.8升级到4.0), 请参阅spine-unity文档中的更新章节. 如果是小版本升级(例如从4.0到新的4.0包), 请按以下步骤进行更新:

  1. 打开Unity项目.
  2. 双击unitypackage文件或将其拖入Unity编辑器的项目视图, 即可将.unitypackage导入你的项目.
  3. 导入对话框将显示哪些文件会更新, 即使你在上次导入后移动了位置.

    若修改或替换了元文件(meta), 改功能可能无法正常工作. 在这种情况下, 你可能必须在导入unitypackage前删除旧版运行时.

要了解更多的更新方法, 请参见spine-unity文档页的更新章节.

安装插件UPM包

  1. 在spine-unity下载页面中找到所需的UPM包, 也可以在Git仓库的spine-runtimes/spine-unity/Packages子目录下找到它们.
  2. 若已打开了某个Unity项目, 建议你 a) 关闭Unity或 b) 关闭当前包含了Spine组件的场景 (例如, 可以打开一个新的空场景来执行安装).
  3. 在解压了UPM包(如果使用git则复制文件)后 a) 把包的内容文件复制到你的项目中的Packages目录. Unity会自动加载它 b) 把包的内容复制到 Assets 目录以外的任何地方, 然后在Unity中打开 Package Manager (Window > Package Manager), 选择 + 图标, 单击 Add package from disk..., 定位并选择 package.json 文件.
  4. 现在可以在 Project 面板中的Packages下就会显示出你刚安装的包, 比如Spine Lightweight RP Shaders条目. 如果该条目没有在 Project 面板中列出, 你可能需要重启一下Unity.

更新当前的UPM包

就地更新 (通过.zip文件或git更新)

  1. 若已打开了某个Unity项目, 建议你 a) 关闭Unity或 b) 关闭当前包含了Spine组件的场景 (例如, 可以打开一个新的空场景来执行安装).
  2. 将新的UPM包的zip文件或git目录的内容复制到现有的目录下. 根据你安装UPM包的不同方式,目录可能是你项目中的 project_root/Packages/package_name 目录, 或者是 Assets 目录外的任意目录, 可以通过 Add package from disk.. 来加载它.
  3. 如果你已经关闭了Unity, 那请在Unity中再次打开你的项目.
  4. Unity将会导入新的资产并显示一个加载进度条.

已知问题:

  • SkeletonData资产为空的时候, 是无法把它拖入层级视图中的. 你只能将它们放入场景视图, 或者在拖入层级视图前创建一个空GameObject.

Unity的限制:

  • Unity的物理组件不支持动态分配的顶点, 所以它们不能用于镜像骨重(bone-weighted)和变形(deformed) BoundingBoxAttachments. 然而BoundingBoxAttachments的内部顶点数据在运行时内仍然可被正确变形, 你可以自己写代码来进行碰撞检测.
  • UnityEngine.UI.MaskableGraphic不支持多个texture, 所以SkeletonGraphic的只能使用单atlas页/texture的skeleton. 通过使用遮罩(masking), 出现了一种将其分割成多个UI对象的实验性SkeletonGraphic, 可以在这里找到: [spine-unity experimental SkeletonGraphicMultiObject 3.6 2018-04-19] (https://zh.esotericsoftware.com/files/runtimes/unity/spine-unity-experimental-SkeletonGraphicMultiObject-3_6-2018-04-19.unitypackage).
  • Spine动画不会作为Unity.AnimationClip对象被导入. Unity使用了不同的曲线方案(curve scheme), 而且其功能与Spine动画的功能不能很好地兼容. 相反, spine-unity使用核心C# Spine.Animation对象制作动画, 这些对象保留了Spine的所有动画特性. 这意味着一些便利功能可能无法保留, 比如在Unity的编辑模式下无法用动画面板来回放动画.
  • Unity不能识别所有的文件类型, 所以atlas需要导出为.atlas.txt格式. 同样, 二进制文件也需要导出为.skel.bytes. 关于导入Spine资产的更多信息, 请参阅文档的入门部分
  • Unity长期在多material/多子网格、排序和动态batching方面有个毛病. 若使用多种materials的skeleton有许多副本, Unity的动态batching系统会尝试batch类似的materials, 但它在batching有类似materials的子网格的过程中, 会破坏skeleton内的排序. 要解决Unity的这个毛病, 可以在你的Spine GameObject中添加一个Sorting Group组件. 然而若你的skeleton只使用一种texture和material, 它的性能还是要更好.

兼容性须知

  • 运行时只能加载与Spine编辑器版本一致的二进制导出文件(新旧版本均应执行重导出).
  • Json导出文件更稳定, 有更大可能与未来版本兼容, 但并非万无一失.
  • 如果你想避免出现与某个既定运行时版本的不兼容, 你可以选择一个与专门匹配该运行时的Spine编辑器版本. 你可以在Spine的Settings...窗口中搞定.
    欲知更多详情, 请参见论坛中的这篇帖子.

早期版本

spine-unity unitypackages

spine-unity 4.0 for Unity 2017.1-2022.1
spine-unity 4.0 2022-09-26
(最近更新时间: UTC - 2022 Sep 26)

spine-unity 3.8 for Unity 2017.1-2020.3
spine-unity 3.8 2021-11-10
(最近更新时间: UTC - 2021 Nov 10)

spine-unity 3.7 for Unity 5.6-2018.4
spine-unity 3.7 2019-08-05
(最近更新时间: UTC - 2019 Aug 05)

spine-unity 3.6 for Unity 5.6-2018.2:
spine-unity 3.6 2019-05-13
(最近更新时间: UTC - 2019 May 13)

spine-unity 3.5 for Unity 5.4-2017.1:
spine-unity 3.5 (Unity 5.4)
(最近更新时间: UTC - 2017 June 18)

spine-unity 3.0 for Unity 4.6:
spine-unity 3.0 (Unity 4.6)
(最近更新时间: UTC - 2017 May 9)

UPM包

URP Shaders UPM包 com.esotericsoftware.spine.urp-shaders
spine.urp-shaders 4.0 2022-05-25 - Unity 2019.3-2022.1
适用于spine-unity 4.0, 以及Unity 2019.3-2022.1.

spine.urp-shaders 3.8 2021-03-04 - Unity 2019.3-2020.3
适用于2019-12-20之后的spine-unity 3.8或更高版本, 以及Unity 2019.3-2020.3.

LWRP Shaders UPM包 com.esotericsoftware.spine.lwrp-shaders
spine.lwrp-shaders 4.0 2021-07-01 - Unity 2019.1
适用于spine-unity 4.0, 以及Unity 2019.1.
spine.lwrp-shaders 4.0 2021-07-01 - Unity 2019.2
适用于spine-unity 4.0, 以及Unity 2019.2.

spine.lwrp-shaders 3.8 2021-03-04 - Unity 2019.1
适用于spine-unity 3.8, 以及Unity 2019.1.

spine.lwrp-shaders 3.8 2021-03-04 - Unity 2019.2
适用于spine-unity 3.8, 以及Unity 2019.2.

时间轴插件(Timeline Extensions) UPM包 com.esotericsoftware.spine.timeline
spine.timeline 4.0 2022-06-01 for spine-unity unitypackage
若通过unitypackage(默认)安装spine-unity, 请使用该包. 适用于spine-unity 4.0, 以及Unity 2017.1-2022.1.
备选方案: spine.timeline 4.0 2022-06-01 for spine-unity UPM
若通过包管理器通过UPM软件包安装spine-unity而非unitypackage, 请使用该包. 适用于spine-unity 4.0, 以及Unity 2017.1-2022.1.

spine.timeline 3.8 2021-03-19
适用于2019-10-3之后的spine-unity 3.8或更高版本, 以及Unity 2017.1-2020.3.

spine.timeline 3.8 2019-08-05
适用于2019-10-3之前的spine-unity 3.8, 以及Unity 2017.1-2019.2.