简介

警告

C#支持是3.0版本的一项新功能。因此,您仍然可能会遇到一些问题,或是发现文档中某些需要改进的地方。请在 引擎 GitHub 页面 上报告Godot中C#的问题,并在 文档 GitHub 页面 上报告任何文档问题。

这个页面简单介绍了C#是什么,以及如何在Godot中使用C#。然后,您可能想看看 如何使用特定功能,阅读有关 C#和GDScript API之间的差异 并(重新)访问逐步教程的 编写脚本部分

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with the Mono 6.x .NET framework, including full support for C# 8.0. Mono is an open source implementation of Microsoft’s .NET Framework based on the ECMA standards for C# and the Common Language Runtime. A good starting point for checking its capabilities is the Compatibility page in the Mono documentation.

注解

不是 一个关于C#语言整体的全面教程。如果您还不熟悉其语法或功能,请参阅 Microsoft C#指南 或在其他地方寻找合适的介绍。

为Godot设置C#

Windows

下载并安装最新版本的 Visual Studio不是 Visual Studio Code),它包含在Godot中使用C#会用到的工具。如果你不打算用Visual Studio IDE的话,也可以仅下载 Visual Studio构建工具 。确保至少安装了.NET Framework 4.5目标包,您可以使用 单个组件 选项卡中上面提到的任何安装程序来获取它。

macOS及Linux

下载并安装最新版本的 Mono SDK 。对于Godot 3.1 beta 3,下载的哪个版本都无所谓,因为Godot自身就捆绑了Mono 5.18的安装。我们只需要为NuGet和MSBuild安装Mono就可以,那正是Godot中C#需要的。

注解

要在macOS上下载Mono,请使用 Mono下载页面 中的 稳定通道(Stable Channel) 链接。Visual Studio通道是Mono的早期版本,将无法使用。

补充说明

您的Godot版本必须启用了Mono支持,因此请确保下载Godot的 Mono版本。如果您是从源代码构建Godot,请确保按照 使用Mono编译 页面内概述的步骤启用Mono支持。

总之,您必须安装Visual Studio或Mono(取决于您使用的操作系统) 启用了Mono支持的版本的Godot。

配置外部编辑器

C# support in Godot’s script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Mono. Under Mono, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

  • Visual Studio 2019
  • Visual Studio Code
  • MonoDevelop
  • Mac版的Visual Studio
  • JetBrains Rider

注解

如果你在使用Visual Studio Code,请确保下载并安装 C# 扩展 以启用诸如语法高亮和智能感知(IntelliSense)的特性。

注解

If you are using Visual Studio 2019, you must follow the instructions found in the “Configure VS2019 for Debugging” section below.

创建C#脚本

成功为Godot设置C#之后,在场景的节点的上下文菜单中选择 附加脚本 时,应该看到以下选项:

../../../_images/attachcsharpscript.png

请注意,虽然在某些细节上有所差别,使用C#编写代码时,大多数概念的工作方式是相通的。如果您是刚接触Godot的新手,此时您可能需要按照以下教程 编写脚本。虽然在文档中缺乏详细的C#示例,但大部分概念都能够在GDScript轻松地阐述清楚。

项目设置和工作流程

当您创建第一个C#脚本时,Godot会为您的Godot项目初始化C#项目文件。这包括生成C#解决方案( .sln )和项目文件( .csproj ),以及一些实用程序文件和文件夹( Properties/AssemblyInfo.cs.mono)。除了 .mono 之外的所有这些都很重要,应该被保存在您的版本控制系统中。而 .mono 可以安全地添加到VCS的忽略列表中。在进行故障排除时,删除 .mono 文件夹并让它重新生成,有时可能会有所帮助。

请注意,目前Godot和C#项目存在一些不同步的问题;如果删除、重命名或移动C#脚本,所做的更改可能不会反映在C#项目文件中。在这种情况下,您将必须手动编辑C#项目文件。

例如,如果您创建了一个脚本(例如 Test.cs)并在Godot中将其删除,则编译将会失败,因为C#项目文件仍期望该文件存在。现在,您可以简单地打开 .csproj 文件并查找 ItemGroup,其中应该包含如下所示的一行:

<ItemGroup>
    <Compile Include="Test.cs" />
    <Compile Include="AnotherTest.cs" />
</ItemGroup>

只需删除该行,您的项目就可以再次正确构建。同样适用于对于重命名和移动内容,只需在项目文件中重命名并移动它们(如果需要)。

示例

这是一个空白的C#脚本,带有一些注释,以演示其工作方式。

using Godot;
using System;

public class YourCustomClass : Node
{
    // Member variables here, example:
    private int a = 2;
    private string b = "textvar";

    public override void _Ready()
    {
        // Called every time the node is added to the scene.
        // Initialization here.
        GD.Print("Hello from C# to Godot :)");
    }

    public override void _Process(float delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

如您所见,通常在GDScript中的全局作用域内的函数(如Godot的 print 函数)可在 GD 类中使用,该类是 Godot 命名空间的一部分。有关 GD 类中方法的列表,请参见 @GDScript@GlobalScope 的类参考页。

注解

请记住,您希望附加到节点上的类应与 .cs 文件具有相同的名称。否则,您将收到以下错误,并且将无法运行场景: “无法找到类XXX,对应脚本res://XXX.cs”

C#和GDScript之间的一般差异

C#API使用 PascalCase 而不是GDScript / C++中使用的 snake_case 。在可能的情况下,字段和getters/setters已转换为属性。一般来说,C#Godot API一贯力求尽可能合理。

有关更多信息,请参见 与GDScript的API差异 页面。

目前的陷阱和已知问题

由于C#支持对Godot来说是比较新,因此仍有一些成长的痛苦和事情需要解决。以下是在Godot中使用C#时应注意的最重要问题的列表,但是如果有疑问,还可以查看官方的 Mono问题的问题追踪器

  • 如上所述,当在Godot中删除、重命名、或移动内容时,C#项目并不总是自动保持同步(#12917)。
  • 编写编辑器插件是可能的,但是目前相当复杂。
  • 热重载时,当前状态不被保存和恢复,导出变量除外。
  • 仅桌面平台(Linux、Windows和macOS)支持导出Mono项目。目前Android、iOS、HTML5和UWP不支持(#20267#20268#20270#20271)。
  • 附加C#脚本需要引用一个类,该类名需要匹配其文件名。
  • Get()/Set()Call()/CallDeferred() 等方法,以及信号连接方法 Connect() 都依赖于Godot的``snake_case``API命名规范。所以,CallDeferred("AddChild")``无法调用``AddChild ,因为API需要原始``snake_case``版本的``add_child``。不过,自定义属性和方法没有此限制。

在Godot中C#的性能

根据一些初步的 基准测试 ,C#在Godot中的性能——虽然通常处于相同的数量级——但在某些天真的情况下大约是使用GDScript的 ~4×。C++仍然要快一些; 具体情况将根据您的用例而有所不同。对于大多数常规脚本工作负载而言,GDScript可能足够快。C#速度更快,但与Godot通信时需要进行一些昂贵的编组(marshalling)。

在Godot中使用NuGet包

NuGet 包可以与Godot一起安装和使用,就像任何C#项目一样。许多IDE都可以直接添加软件包。也可以通过在项目根目录下的 .csproj 文件中添加软件包引用来手动添加它们:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2"/>
    </ItemGroup>
    ...
</Project>

每当添加或修改软件包时,请在项目目录的根目录中运行 nuget restore。为确保 NuGet 软件包可供 msbuild 使用,请运行:

msbuild /t:restore

Profiling your C# code

Configuring VS 2019 for debugging

注解

Godot has built-in support for workflows involving several popular C# IDEs. Built-in support for Visual Studio will be including in future versions, but in the meantime, the steps below can let you configure VS 2019 for use with Godot C# projects.

  1. Install VS 2019 with .NET desktop development and Desktop development with C++ workloads selected.
  2. Ensure that you do not have Xamarin installed. Do not choose the Mobile development with .NET workload. Xamarin changes the DLLs used by MonoDebugger, which breaks debugging.
  3. Install the VSMonoDebugger extension.
  4. In VS 2019 –> Extensions –> Mono –> Settings:
    • 选择 Debug/Deploy to local Windows
    • Leave Local Deploy Path blank.
    • Set the Mono Debug Port to the port in Godot –> Project –> Project Settings –> Mono –> Debugger Agent.
    • Also select Wait for Debugger in the Godot Mono options. This Godot Addon may be helpful.
  5. Run the game in Godot. It should hang at the Godot splash screen while it waits for your debugger to attach.
  6. In VS 2019, open your project and choose Extensions –> Mono –> Attach to Mono Debugger.