spine-godot 运行时文档

Licensing

将官方的Spine运行时整合到你的应用程序中前请务必阅读 Spine 运行时许可协议 .

入门篇

安装

spine-godot运行时是作为自定义C++引擎模块实现的. 这需要自行构建Godot编辑器和Godot导出模板. 我们为最新的 Godot 3.5 和 4.x 分支代码提供了预构建的编辑器和二进制导出模板:

注意: 所有编辑器的构建都需要64位支持. Windows、Linux和macOS的导出模板也需要64位支持. 由于Apple的限制, iOS设备的导出模板则只支持64位ARM设备.

请从上文的链接中下载适合你操作系统的Godot编辑器及Godot导出模板.

Windows和Linux的用户, 只需解压.zip文件并将解压后的可执行文件放在任意目录即可开始工作. 对于macOS用户, 则需要解压.zip文件并将Godot.app放入你的/Applications/文件夹. 如果你有一个已存在的Godot安装副本, 你可以重命名Godot.app包来继续安装流程.

要安装导出模板所用的.tpz文件, 请打开Godot编辑器, 然后进入Editor > Manage export templates .... 点击Install from file, 选中你从上文的链接中下载的.tzp文件. 然后就可以像其他引擎一样为Windows、Linux、macOS、iOS、Android和网站导出项目了. 你也可以在Godot编辑器中使用Godot的one-click deploy(一键部署)功能, 直接将项目部署在Android设备和网站上.

示例

spine-godot运行时附带了许多功能演示的示例. 可执行如下步骤来检视示例工程:

1. 通过上文中安装一节内附的链接下载适合你操作系统的预构建Godot编辑器.
2. 克隆spine-runtimes Git代码库. 如果你不想使用Git, 则可以下载最新版本的ZIP压缩文件并解压之.
3. 打开Godot编辑器点击Import, 然后导入选中的 spine-runtimes/spine-godot/example/project.godot 文件.

文件包含了如下示例项目:

• 01-helloworld: 演示了如何使用SpineSprite节点来显示Spine skeleton并播放Spine skeleton动画.
• 02-animation-state-listener: 演示了如何通过信号监听SpineSprite的动画状态变化.
• 03-mix-and-match. 演示了如何由其他皮肤组合出一个新的自定义皮肤, 该功能也用在了创建混搭(mix-and-match)场景中的角色上.
• 04-simple-input: 演示了如何播放动画以响应输入事件.
• 05-mouse-following: 演示了如何手动让SpineSprite skeleton中的骨骼跟随鼠标或触摸事件.
• 06-bone-following: 演示了如何在SpineSprite上使用SpineBoneNode来让子节点跟随skeleton中的骨骼.
• 07-slot-node: 演示了如何使用SpineSlotNode让子节点跟随skeleton中的一个槽位, 同时将子节点置入SpineSprite的正确渲染顺序.
• 08-animation-player: 演示了如何使用SpineAnimationTrack节点, 通过Godot的AnimationPlayer用户界面创建过场动画.
• 09-custom-material: 演示了如何通过SpineSlotNode将自定义material应用于整个SpineSprite或某个槽位中.
• 10-2d-lighting: 演示了如何将带有法线贴图的 SpineSprite应用于Godot的2D光照系统.
• 11-bone-node: 演示了使用SpineBoneNode实例通过Godot物理引擎驱动SpineSprite的骨骼.

注意: 由于Godot 3.x和4.x所用的GDScript并不兼容, 因此我们为Godot 4.x建立了单独的项目文件夹example-v4. example-v4中的项目使用最新的Godot 4.0.x保存, 但也能被Godot 4.1.x打开.

通过源代码编译Godot编辑器和导出模板

如果你需要自己编译Godot编辑器和导出模板, 例如: 你需要使用特定Godot版本, 有某些定制C++模块, 或者想更改spine-godot运行时行为, 针对这些情况我们提供了shell脚本来简化编译流程.

注意: 在尝试该方法前, 请确保已按照Godot的官方说明安装了所有构建所需的依赖项.

Godot 3.5.x

要构建Godot编辑器二进制文件, 请先克隆spine-runtimes 代码库. 在你克隆到本地的Spine Runtimes目录中, 通过Bash shell中运行以下命令(在Windows中可使用Git Bash):

setup.sh的第一个参数是构建所需Godot编辑器的Godot代码库分支(repository branch)或提交哈希(commit hash). 第二个参数指定你是否要编译开发版的编辑器. 可选值为true或false. 若置为true, 且将LIVEPP环境变量设置为了Live++的安装目录, 则构建时将添加对Windows版Live++的支持, 并禁用一些模块以加快编译速度.

build.sh的第一个参数指定了生成二进制文件的优化级别. 若值为debug则允许完全调试编辑器, 但由于缺少优化可能会很慢; release_debug则一般用于Godot编辑器的发布版构建.

编译过程生成的Godot编辑器二进制文件可在spine-godot/godot/bin中找到.

要构建特定平台的导出模板, 需要在Bash shell中运行以下命令(在Windows中可使用Git Bash):

setup.sh的第一个参数是构建所需Godot编辑器的Godot代码库分支(repository branch)或提交哈希(commit hash). 第二个参数必须置为false.

built-templates.sh的第一个参数是导出模板所面向的平台. 可用值包括windows、linux、macos、web、android和ios. 注意, macOS和iOS的导出模板只能在运行macOS的计算机上构建. 详情见Godot的官方说明.

编译过程生成的Godot导出模板二进制文件可在spine-godot/godot/bin中找到.

Godot 4.x

要构建Godot编辑器二进制文件, 请先克隆spine-runtimes 代码库. 在你克隆到本地的Spine Runtimes目录中, 通过Bash shell中运行以下命令(在Windows中可使用Git Bash):

setup.sh的第一个参数是构建所需Godot编辑器的Godot代码库分支(repository branch)或提交哈希(commit hash). 第二个参数指定你是否要编译开发版的编辑器. 可选值为true或false. 若置为true, 且将LIVEPP环境变量设置为了Live++的安装目录, 则构建时将添加对Windows版Live++的支持, 并禁用一些模块以加快编译速度.

编译过程生成的Godot编辑器二进制文件可在spine-godot/godot/bin中找到.

要构建特定平台的导出模板, 需要在Bash shell中运行以下命令(在Windows中可使用Git Bash):

setup.sh的第一个参数是构建所需Godot编辑器的Godot代码库分支(repository branch)或提交哈希(commit hash). 第二个参数必须置为false.

built-templates-v4.sh的第一个参数是导出模板所面向的平台. 可用值包括windows、linux、macos、web、android和ios. 注意, macOS和iOS的导出模板只能在运行macOS的计算机上构建. 详情见Godot的官方说明.

编译过程生成的Godot导出模板二进制文件可在spine-godot/godot/bin中找到.

支持C#的Godot 4.x

Note: 支持C#的Godot 4.x目前仅适用于Windows、Linux和macOS. 一旦上游的Godot发布了对移动设备和网站部署的支持, spine-godot运行时也将尽快跟进适配.

要构建支持C#的Godot编辑器二进制文件, 请先克隆spine-runtimes 代码库. 在你克隆到本地的Spine Runtimes目录中, 通过Bash shell中运行以下命令(在Windows中可使用Git Bash):

setup.sh的第一个参数是构建所需Godot编辑器的Godot代码库分支(repository branch)或提交哈希(commit hash). 第二个参数指定你是否要编译开发版的编辑器. 可选值为true或false. 若置为true, 且将LIVEPP环境变量设置为了Live++的安装目录, 则构建时将添加对Windows版Live++的支持, 并禁用一些模块以加快编译速度. 第三个参数是可选参数, 用于指定是否支持C#. 可选值为true或false. 在本例中参数置为了true以启用C#支持.

build-v4.sh的参数也是可选的, 用于指定是否支持C#. 可选值为true或false. 在本例中参数置为了true以启用C#支持.

编译过程生成的Godot编辑器二进制文件可在spine-godot/godot/bin中找到.

此外你还会在 spine-godot/godot/bin 目录下发现一个文件夹 GodotSharp, 其中包含了Godot API相关的所有C#程序集实现, 同时也包括了spine-godot运行时的API. 创建新项目时你需要通过NuGet来链接这些程序集. 请阅读下文中的C#项目设置一节了解更多信息.

要构建特定平台的导出模板, 需要在Bash shell中运行以下命令(在Windows中可使用Git Bash):

setup.sh的第一个参数是构建所需Godot编辑器的Godot代码库分支(repository branch)或提交哈希(commit hash). 第二个参数必须置为false.

built-templates-v4.sh的第一个参数是导出模板所面向的平台. 可用值包括windows、linux、macos、web、android和ios. 注意, macOS和iOS的导出模板只能在运行macOS的计算机上构建. 详情见Godot的官方说明.

编译过程生成的Godot导出模板二进制文件可在spine-godot/godot/bin中找到.

使用GitHub Actions构建Godot编辑器和导出模板

spine-runtimes代码库里的几个文件包含了各自的GitHub 工作流(workflow), 分别为 .github/workflows/spine-godot.yml、.github/workflows/spine-godot-v4.yml 和 . github/workflows/spine-godot-v4-all.yml, 它们能通过GitHub Actions构建所有版本的Godot编辑器和导出模板二进制文件, 包括Godot 3.5.x、Godot 4.0.x 和 Godot 4.1.x .若要使用GitHub工作流, 请执行以下操作:

1. 克隆spine-runtimes代码库
2. 在克隆的代码库里启用GitHub工作流(workflow)
3. 手动触发spine-godot, spine-godot-v4, 或spine-godot-v4-all 工作流.

生成的二进制文件将作为工件(artifact)附加到运行成功的工作流中.

spine-godot-v4-all会构建支持C#的Godot 4.0、4.1和4.1 .使用spine-godot-v4工作流, 则构建一个指定版本的Godot 4.x (可选是否支持C#). 手动触发此工作流时, 需要指定Godot代码库标签(如4.1-stable)、Godot版本(如 4.1.stable)以及是否包含C#支持(勾选或取消mono复选框).

C#项目设置

如果使用了支持C#的Godot编辑器, 那么在建立Godot新项目时, 需要多做一步设置.

首先, 应使用从上文安装一节中下载的支持C#的Godot编辑器创建Godot项目.

然后, 关闭Godot并打开项目文件夹. 在项目根目录下新建一个名为godot-nuget的文件夹.

并且将Godot编辑器ZIP文件里的Godot C#程序集复制到该文件夹里. 你需要复制的文件如下:

• GodotSharpEditor.<version>.snupkg
• Godot.NET.Sdk.<version>.nupkg
• Godot.SourceGenerators.<version>.nupkg
• GodotSharp.<version>.nupkg
• GodotSharp.<version>.snupkg
• GodotSharpEditor.<version>.nupkg

<version>取决于您从本页下载的 Godot 版本，例如 4.1.1.

下载并解压Godot编辑器的ZIP文件后, 可在以下文件夹中找到这些文件:

• Windows: godot-editor-windows-mono.zip\GodotSharp\Tools\
• Linux: godot-editor-linux-mono.zip/GodotSharp/Tools/
• macOS: Godot.app/Contents/Resources/GodotSharp/Tools, 或右键单击Finder中的Godot.app文件选择Show Package Contents, 然后导航至Contents/Resources/GodotSharp/Tools/

最后, 在项目根目录下新建一个名为nuget.config的文件, 其内容如下:

该配置文件把godot-nuget目录配置为NuGet软件包的源. 你将使用godot-nuget目录中的程序集, 它包含了spine-godot运行时的C#绑定, 而非从NuGet包存储库中获取官方的Godot C#程序集.

现在你可以再在Godot中打开项目, 并使用Godot和spine-godot C# API替代GDScript了！

更多详情请阅读Godot C#官方文档.

更新spine-godot运行时

在更新项目中的spine-godot运行时之前, 请先阅读Spine 编辑器和运行时版本管理指南.

当你准备好更新到最新的spine-godot运行时后, 请按以下步骤执行操作:

1. 从上文的安装一节中下载最新的预编译Godot编辑器和运行时二进制文件.
2. 从上文的安装一节中下载最新的预编译Godot导出模板二进制文件.
3. 打开Godot编辑器安装导出模板, 具体做法是导航至Editor > Manage export templates ..., 单击Install from file后选中下载的.tzp文件.
4. 如果要从一个Spine主版本切换到另一个版本, 应使用与Spine运行时版本匹配的Spine编辑器版本重新导出Spine项目, 并替换Godot项目中的旧版导出文件. 在Godot中打开Godot项目将自动触发更新文件的重导入.
5. 如果你在Godot中使用C#, 请按上文所述, 将新版编辑器GodotSharp目录中的新程序集复制到项目的godot-nuget/目录中.

或者你也可如上文所述, 编译Godot编辑器和支持新版Spine的导出模板, 然后按需执行步骤4.

使用 spine-godot

spine-godot运行时是Godot的一个自定义C++模块, 支持加载、播放和操作由Spine创建的动画. spine-godot运行时是用C++编写的, 基于通用的spine-cpp运行时. spine-godot运行时包装了spine-cpp的类和函数, 并将其暴露给GDScript. 除了暴露大部分spine-cpp API外, spine-godot运行时还提供了Godot节点, 以方便显示Spine skeleton并与之交互.

请查阅Spine 运行时指南 以了解Spine运行时架构的详细信息.

资产管理

为Godot导出资产

请遵循Spine用户指南中的步骤操作, 以了解如何:

1. 导出 skeleton & 动画数据
2. 导出包含skeleton图像的texture atlases

导出skeleton数据和texture atlas将生成以下文件:

1. skeleton-name.spine-json 或 skeleton-name.skel, 包含了skeleton和动画数据.
2. skeleton-name.atlas, 包含了texture atlas相关的信息.
3. 一张或多张.png图像文件, 每个文件代表了texture atlas中的一页, 而texture atlas包含了skeleton所需的全部图片.

注意: 建议选择二进制格式导出而非JSON导出, 因为二进制格式文件尺寸更小, 加载更快. 如果你必须使用JSON, 请确保文件扩展名为.spine-json而非.json. 若现有项目仍然使用.json导出文件, 可以使用该Python脚本将其扩展名转换为.spine-json.

spine-godot运行时可以将这些文件导入为Godot特定的资源文件类型.

注意: 由于Godot的技术限制, spine-godot运行时目前不支持使用预乘alpha导出的atlas. 因为Godot默认对非预乘的texture图像执行出血裁切(bleed)操作. 一般来说这足以避免使用预乘alpha时常出现的显示瑕疵.

导入至Godot

1. 在Godot编辑器中打开Godot项目.
2. 将.skel/.spine-json, .atlas和.png文件拖动到选中的文件夹中.

资产导入器将为.skel或.spine-jsonskeleton文件创建SpineSkeletonFileResource, 为.atlas文件创建SpineAtlasAssetResource, 为atlas中的每个.png文件创建Godot texture资源文件.

注意: 在SpineAtlasResource的导入设置中, 你还可以指定每个atlas页所用法线贴图的前缀. 默认情况下前缀是`n'. 法线贴图是启用2D光照所必需的, 但也是可选设置.

在导入源文件后, 现在可以创建一个SpineSkeletonDataResource, 它结合了SpineSkeletonFileResource和 SpineAtlasResource以供SpineSprite使用.

在Godot编辑器的文件系统面板上, 右击你放置Spine资产的文件夹, 然后选择New Resource.... 在弹出的对话框中, 选择 SpineSkeletonDataResource后点击Create给资源起个名字, 最后点击Save.

双击新创建的资源, 使其在检查器面板中显示. 为skeleton分配先前导入的atlas资源和skeleton文件资源. skeleton数据资源也存储了可在检查器中修改的动画mix时间.

注意: 一个结合了某个skeleton文件和atlas的skeleton数据资源可以被所有显示该组合的SpineSprite的全部实例共享. 不要将skeleton数据资源定义为SpineSprite中的内联(inline)资源, 因为这将成倍增大游戏所需要加载的数据量.

更新Spine资产

在开发过程中, 你可能会经常更新你的Spine skeleton数据和texture atlas文件. 你只要简单地覆盖这些源文件(.spine-json, .skel, .atlas, .png)--从Spine编辑器重新导出文件, 并替换Godot项目中的现有文件--即可完成更新.

Godot编辑器将检测到这些源文件的更改, 并自动重导入对应资产, 并在此过程中更新引用这些资产的其他资源. 如果Godot编辑器不能识别自动源文件的变化, 也可以在Godot编辑器中文件的导入设置面板中手动地强制执行重新导入操作.

节点

spine-godot运行时提供了一组节点, 来显示从Spine导出的skeleton、播放skeleton动画并对其进行修改.

SpineSprite 节点

SpineSprite节点显示存储在SkeletonDataResource中的skeleton数据和atlas. 该节点暴露了一个动画状态API, 通过它可以播放和设置skeleton动画. 你可以通过SpineSprite.get_animation_state()来访问SpineAnimationState. 该节点还通过SpineSprite.get_skeleton()暴露了skeleton实例(SpineSkeleton), 通过它你可以查询到skeleton的所有属性, 包括骨骼、槽位、附件、皮肤和约束.

创建SpineSprite

创建SpineSprite节点只需点击场景面板上的+按钮并选择SpineSprite. 然后将SpineSprite节点需显示的SkeletonDataResource分配给检查器中的相应属性即可, 如上图所示.

你可以使用相应的工具和键盘快捷键在Godot编辑器视口中自由变换SpineSprite节点. skeleton在Godot编辑器中SpineSprite的边界框, 与skeleton在Spine编辑器的设置模式下的边界框完全一致.

检视骨骼, 槽位和附件

一旦你为SpineSprite分配了一个SkeletonDataResource, 就可以检视skeleton的骨骼、槽位和附件.

在编辑器视口中选中SpineSprite. 在Debug属性面板里就能选中欲检查的skeleton组件.

你可以在编辑器视口中将鼠标悬停在你感兴趣的组件上, 这时将显示其名称.

预览动画

通过设置Preview属性面板, 可以在编辑器视口中直接回放动画.

当勾选了Preview Frame时, 将显示动画在当前Preview Time的帧. 你可以拖动Preview Time滑块来浏览动画.

设置自定义material

Materials属性面板可以为每个Spine blend模式单独设置自定义material. 这些material将应用于SpineSprite中的所有槽位及其附件.

可以使用SpineSlotNode来设置某个特定槽位的material, 它将覆盖SpineSprite上设置的自定义material.

详情参见示例项目中的example/09-custom-material场景.

设置更新模式

默认情况下, SpineSprite会在每一帧中尽快地更新其底层数据. 可以设置Update Mode属性来改变这种行为.

默认值的是Process模式, 其更新频率依赖于帧率. Physics模式以固定的时间间隔更新SpineSprite(默认为每秒60次), 当你需要编写与Godot物理引擎互操作的代码时该模式就能发挥价值了. Manual模式则禁用了所有自动更新. 当使用Manual模式后, 在重写_process(delta)或_physics_process(delta)时, 需要调用SpineSprite.update_skeleton()来手动更新SpineSprite. 改模式可以完全控制SpineSprite的更新时机.

更多详情请参见Godot官方文档中的Idle and Physics Processing 一章.

SpineSprite动画

SpineSprite的动画效果是通过GDScript或C#代码实现的. 下文中包含了使用GDScript编写的示例代码, 这些代码也可直接转换为 spine-godot C# API. 可查看Godot C# 文档进一步了解如何从GDScript将API映射为C#代码.

SpineSprite通过get_animation_state()函数暴露了SpineAnimationState对象. 请见Spine运行时指南中的应用动画一章以获得更深入的信息, 特别是关于动画轨道和队列动画的内容.

要在SpineSprite的轨道0上设置某个动画, 应调用SpineAnimationState.set_animation():

第一个参数是动画的名称, 第二个参数是指定是否循环播放动画, 最后一个参数是指定应该在哪个轨道上播放动画.

用动画状态方法也能队列动画:

add_animation()的第一个参数是动画名称. 第二个参数指定了播放延迟时间(单位为秒), 延迟后该动画将取代轨道上的前一个动画. 第三个参数指定是否需要循环播放该动画. 最后一个参数是指定应该在哪个轨道上播放动画.

当设置或添加某个动画到动画状态轨道时, 会返回一个SpineTrackEntry实例, 它可以进一步修改该的动画播放时的属性. 例如, 你可以将轨道条目设置为逆向播放动画:

注意: 应在函数内封装SpineTrackEntry实例. 由于轨道条目会被多次重用, 因此一旦其所代表的动画播放完成, 实例就会失效.

可使用set_empty_animation()和add_empty_animation()在一条动画轨道上设置或队列空动画, 以便将skeleton丝滑地重置到setup pose:

set_empty_animation()的第一个参数指定了轨道. 第二个参数则指定mix时长(单位为秒), 该时长用于以mix的方式淡出之前的动画并淡入到"空"动画.

add_empty_animation()的第一个参数指定了轨道. 第二个参数指定了mix时长(单位为秒), 该时长用于以mix的方式淡出之前的动画并淡入到"空"动画. 第三个参数表示延迟时间(单位为秒), 延迟后"空"动画将以mix的方式取代轨道上的前一个动画.

可以通过clear_track(track_id)立即清空一条轨道上的所有动画. 要一次性清空全部轨道, 可调用clear_tracks(). 清空动画将保持skeleton最后所处的姿态.

要将skeleton的姿态重置为setup pose, 可以使用SpineSprite.get_skeleton().set_to_setup_pose(). 这将把骨骼和槽位重置为setup pose中的配置. 使用SpineSprite.get_skeleton().set_slots_to_setup_pose()则只将槽位重置为setup pose中的配置.

信号(Signals)

SpineSprite暴露了多个信号, 通过信号可在SpineSprite的生命周期内响应事件.

为响应动画状态的更改, 可以连接如下信号:

• animation_started, 当动画开始时触发.
• animation_interrupted, 当清空动画轨道或设置了某个新动画时触发.
• animation_completed, 当某条轨道上的动画完成了一个循环时触发.
• animation_ended, 当不再应用某个动画时触发.
• animation_disposed, 当销毁动画轨道条目时触发.
• animation_event, 当用户定义的事件发生时触发.

除了动画状态事件, SpineSprite还提供了其高级生命周期事件的信号:

• before_animation_state_update, 在以当前delta时间更新动画状态前触发.
• before_animation_state_apply, 在skeleton姿态应用动画状态前触发.
• before_world_transforms_change, 在skeleton的世界变换(world transforms)被更新前触发.
• world_transforms_changed, 在skeleton的世界变换(world transforms)更新后触发.

这些信号在手动更新骨骼或其他skeleton组件时可以派上用场. 一般来说, 建议使用SpineBoneNode或SpineSlotNode节点, 因为它们省去了复杂的手动更新操作, 同时覆盖了99%的用例--比如根据鼠标光标位置放置骨骼.

详见示例项目中的example/02-animation-state-listeners场景.

Mix-and-match 皮肤

许多应用程序和游戏允许其用户用许多独立部件自定义组合出虚拟形象, 比如头发、眼睛、裤子, 或耳环或包等配饰. 在Spine中, 这可以通过Mix-and-match皮肤来实现.

你可以通过其他皮肤组合出自定义的皮肤, 方法如下:

首先使用SpineSprite.new_skin(name)创建自定义皮肤. 接下来从由SpineSprite管理的SpineSkeletonData中获取SpineSkeletonData. 通过它就能用SpineSkeletonData.find_skin()来按名称查找皮肤. 通过SpineSkin.add_skin()添加所有需要组合的皮肤. 最后通过SpineSkeleton.set_skin()给skeleton设置新的皮肤.

详见示例项目中的example/03-mix-and-match场景.

获取和设置骨骼变换

SpineSprite包装了Spine运行时skeleton, 它由骨骼、槽位、附件和约束构成. skeleton在Spine编辑器中管理着以skeleton原点为基准的坐标系的骨骼变换.

SpineSprite类提供了辅助方法get_global_bone_transform(name)和set_global_bone_transform(name, transform), 你可在Godot画布空间中获取和设置骨骼变换. 注意, 检索或设置变换不会保存骨骼倾斜(skew).

如果想手动设置骨骼变换, 必须在SpineSprite每次更新骨骼的世界变换前完成. 你可以响应before_world_transforms_change信号来适时地介入生命周期.

直接设置骨骼变换的另一个方法是使用SpineBoneNode.

SpineBoneNode

SpineBoneNode可以跟随一个skeleton的骨骼, 也可以驱动其变换. 当你想根据某些输入(例如鼠标位置)控制骨骼变换, 请使用SpineBoneNode的驱动模式; 如果你想让另一个节点跟随skeleton中的某骨骼, 例如将CollisionShape附加到SpineSprite的骨骼上, 则须使用SpineBoneNode的跟随模式.

创建SpineBoneNode的方法是: 右击需要附加节点的SpineSprite, 并选中Add child node.... 从可用的节点类型列表中选择 SpineBoneNode并为其命名. 然后便可在检查器中修改该节点的设置.

注意: SpineBoneNode必须始终是SpineSprite的直接子节点, 否则它将无法找到需跟随或驱动的骨骼.

Bone Name属性下拉框会显示所有可用的骨骼以供选择. Bone Mode指定了节点应该跟随SpineSprite中的骨骼还是驱动它. 该节点可以随时启用和禁用, 以便按需开关跟随和驱动功能.

SpineBoneNode也将显示在编辑器视口中. Debug面板中的属性定义了其外观.

若需了解如何使用鼠标移动来让SpineBoneNode驱动SpineSprite的骨骼, 请查看example/05-mouse-following场景.

若需了解如何使用SpineBoneNode来跟随SpineSprite的骨骼, 请查看example/06-bone-following场景. 该示例中的SpineBoneNode包含一个子节点, 它将显示在SpineSprite中被跟随骨骼.

注意: SpineSprite不会正确排序子节点的绘制顺序. 当你想在SpineSprite多个组件的绘制顺序中插入任意的节点时, SpineSlotNode是更适合的选择.

SpineSlotNode

SpineSlotNode可以在SpineSprite的绘制顺序中插入任意节点. 它用于将粒子系统、自定义精灵(Sptite)、甚至其他SpineSprite节点附加到skeleton的特定槽位上. SpineSlotNode的子节点将被渲染在该槽位的所有活动附件之上. 你也可以使用SpineSlotNode来覆盖某个特定槽位的material.

创建SpineSlotNode的方法是: 右击需要附加节点的SpineSprite, 并选中Add child node.... 从可用的节点类型列表中选择 SpineSlotNode并为其命名. 然后便可在检查器中修改该节点的设置.

注意: SpineSlotNode必须始终是SpineSprite的直接子节点, 否则它将无法找到其所属槽位.

Slot Name属性下拉框会显示所有可用的槽位以供选择. Materials面板可设置materials, 它用于覆盖该槽位的默认material.

若需了解如何使用 SpineSlotNode在 SpineSprite的绘制顺序中插入节点的例子, 请查看example/07-slot-node场景.

若需了解如何使用SpineSlotNode来覆盖SpineSprite中某个槽位的material, 请查看example/09-custom-material场景.

SpineAnimationTrack

注意: 由于Godot的动画引擎的诸多限制, 第三方插件尚无法完整支持其诸如导入3D角色动画等功能, 所以 SpineAnimationTrack仍为具有高度实验性的功能.

SpineAnimationTrack节点可通过Godot的动画播放器和强大的动画编辑器对SpineSprite进行动画制作. 它非常适合使用Godot动画编辑器来创建过场场景, 摆脱了通过代码手工制作场景的繁琐.

创建SpineAnimationTrack的方法是: 右击需要附加节点的SpineSprite, 并选中Add child node.... 从可用的节点类型列表中选择 SpineAnimationTrack并为其命名. 然后便可在检查器中修改该节点的设置.

注意: SpineAnimationTrack必须始终是SpineSprite的直接子节点, 否则它将无法找到其所属槽位.

当创建SpineAnimationTrack时会自动附加一个AnimationPlayer节点作为其子节点.

然后key好SpineAnimationTrack和其子节点AnimationPlayer就能播放SpineSprite动画. 你通过key入子节点AnimationPlayer来设置动画的播放. 要修改动画的属性, 比如是否循环播放、是否反向播放等等, 可以key入SpineAnimationTrack属性.

这种双层设置可使动画编辑器显示子节点AnimationPlayer中key入动画的持续时间, 这让创建复杂的动画序列变得更加容易. 它还允许在动画编辑器中拖动时间轴预览动画.

注意: 由于Godot动画编辑器的技术限制, 无法在编辑器中预览SpineSkeletonDataResource中定义的mix时间.

你可以在一个SpineSprite上附加多个SpineAnimationTrack节点. 这可以叠加多个动画. 每个SpineAnimationTrack都有一个轨道索引号. 如果key入了相同的skeleton属性, 那么索引号较高的轨道上的动画会覆盖较索引号上的动画行为.

更多示例请查看example/08-animation-player场景. 该场景根节点上的AnimationPlayer包含两个动画, 它们key了 SpineAnimationTrack节点及其AnimationPlayer子节点. slow-moonwalk动画阐明了SpineAnimationTrack的基本原理. 而cutscene动画则是一个更复杂的动画, 演示了如何使用多轨key和复杂动画序列.

2D光照

spine-godot集成了Godot的2D光照系统.

要使用Godot的2D光照系统, 你需要为texture atlas提供法线贴图. 构成texture atlas页的每个.png都须在其旁边放置一张对应的.png法线贴图. 法线贴图文件须有统一的前缀. 默认前缀为n_. 例如, 一张名为raptor.png的texture atlas页图像旁边必须有一张名为n_raptor.png的法线贴图.

在导入texture atlas时, spine-godot将尝试为每个texture atlas的页查找并加载法线贴图. 你可以在texture atlas的导入视图中设置自定义的法线贴图前缀.

一旦成功导入texture atlas页和法线贴图, 你就可以将Godot的2D光照系统用于SpineSprite节点上.

详见示例中的10-2d-lighting场景.

访问Spine运行时API

spine-godot将几乎所有的Spine运行时API都映射到了GDSCript. 由SpineSprite返回的对象, 如通过SpineSprite.get_skeleton()返回的SpineSkeleton均为spine-cpp API到GDScript的1:1翻译. 因此你可以将Spine运行时指南中几乎所有通用操作以GDScripts实现.

但由于GDScript的特性, 有一些已知的限制:

• 任何返回的数组或映射(map)均为内部数组的副本. 修改它们不会无任何影响.
• 你不能在某个SpineTrackEntry对象上设置监听器. 只能在SpineSprite上设置信号.
• 你不能直接创建、添加或删除骨骼、槽位和其他Spine对象.
• 附件和时间线的C++类层次结构没有暴露给GDScript.