使用 C# 设置 spine-godot

October 2nd, 2023

本文简要介绍了开始使用 C# 和 spine-godot 的步骤,以及它与使用 GDScript 有何不同。


安装

你可以从spine-godot 运行时文档下载我们预构建的 Godot 4.1 编辑器并导出支持 C# 的模板二进制文件。请阅读那里的文档了解基本安装说明。


C# 项目设置

要使用支持 C# 的 Godot 编辑器二进制文件,你在设置新的 Godot 项目时需要执行一个额外步骤:

1. 创建一个 Godot 项目

首先,使用下载的支持 C# 的 Godot 编辑器二进制文件创建一个新 Godot 项目。

无法加载 .NET 运行时

如果 Godot 编辑器无法加载 .NET 运行时,启动时会出现以下错误消息:

如消息中所述,请从微软官方下载站点安装 .NET SDK 6.0 或更高版本,然后重启 Godot。


2. 创建一个 godot-nuget 文件夹

关闭 Godot 并打开你的项目文件夹。在根目录中,创建一个名为godot-nuget的新文件夹。


3. 复制 C# 程序集

将 Godot C# 程序集复制到godot-nuget文件夹中。如果你使用的是 Windows 或 Linux,可在下载的 Godot 编辑器 ZIP 文件中找到程序集:

  • Windows: godot-editor-windows-mono.zip\GodotSharp\Tools\
  • Linux: godot-editor-linux-mono.zip/GodotSharp/Tools/

如果你使用的是 macOS:

  • macOS: 在 Finder 中右键单击Godot.app文件,导航至 Godot.app/Contents/Resources/GodotSharp/Tools/,选择显示包内容,然后导航至 Contents/Resources/GodotSharp/Tools/

将以下文件复制到你的godot-nuget文件夹中:

  • 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


4. 创建一个 nuget.config 文件

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

<configuration>
<packageSources>
    <!-- package source is additive -->
    <add key="godot-nuget" value="./godot-nuget" />
</packageSources>
</configuration>

这会将godot-nuget目录配置为 NuGet 包的包源。不从 NuGet 包注册表获取官方 Godot C# 程序集,而是使用godot-nuget目录中的程序集,其中还包含 spine-godot 运行时的 C# 绑定。


你现在可以在 Godot 中打开项目并使用 Godot 和 spine-godot C# API,而不是 GDScript!


使用 C# 设置骨架动画

以下是使用附加到 SpineSprite节点的 C# 脚本对一个 Spine 骨架设置动画的简单示例代码:

C#:

using Godot;
using System;

public partial class SpineSprite : SpineSprite {
   public override void _Ready () {
      GetAnimationState().SetAnimation("run", true, 0);
   }
}

与使用 GDScript 编写的相同代码相比,除了 API 使用 PascalCase 并且根据 C# 代码约定需要在末尾添加分号之外,几乎没有什么区别。

GDScript:

extends SpineSprite

func _ready():
   get_animation_state().set_animation("run", true, 0)

在 GDScript 中,你可以使用 @onready注释在函数外获取骨架。在 C# 中,你无法在类定义中调用 API,因此你必须在函数内获取它。以下是翻转骨架和排队动画的 C# 和 GDScript 代码的比较:

C#:

using Godot;
using System;

public partial class SpineSprite : SpineSprite {
   private SpineSkeleton spineSkeleton;
   private SpineAnimationState spineSpriteAnimState;

   public override void _Ready () {
      spineSkeleton = GetSkeleton();
      spineSpriteAnimState = GetAnimationState();
      spineSkeleton.SetScaleX(-1);
      spineSpriteAnimState.SetAnimation("idle", true, 0);
      spineSpriteAnimState.AddAnimation("run", 2, true, 0);
   }
}

GDScript:

extends SpineSprite

@onready var spineSkeleton : SpineSkeleton = get_skeleton()
@onready var spineSpriteAnimState : SpineAnimationState = get_animation_state()

func _ready():
   spineSkeleton.set_scale_x(-1)
   spineSpriteAnimState.set_animation("idle", true, 0)
   spineSpriteAnimState.add_animation("run", 2, true, 0)

有关 API 如何从 GDScript 映射到 C# 的详细信息,请参阅Godot C# 文档


C# 示例

要查看并试验这些 spine-godot 的 C# 示例:

  1. 克隆 spine-runtimes Git 存储库以 ZIP 形式下载最新版本并解压它。
  2. 打开spine-runtimes/spine-godot/example-v4-csharp/文件夹,然后单击project.godot文件将其打开。

你可以在 FileSystem 停靠栏的examples文件夹下找到使用 C# 的各种示例场景和脚本。


如果你在使用支持 C# 的 spine-godot 时遇到问题,请随时在 Spine 论坛上发布你的问题!