C# 基础

简介

警告

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

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

C#是由Microsoft开发的一种高级编程语言。在Godot中,它是使用Mono 6.x .NET框架实现的,其中包括对C# 8.0的完全支持。Mono是Microsoft .NET Framework的开源实现,基于C#的ECMAC标准和公共语言运行时。检查其功能的一个很好的起点是Mono文档中的 兼容性 页面。

注解

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

为Godot设置C#

Windows (Visual Studio)

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

Windows (JetBrains Rider)

JetBrains Rider 包含了配套的 MSBuild,所以不需要其他额外软件。确保偏好与下列设定一致:

  • In Godot's Editor Settings:

    • Set Mono External Editor to JetBrains Rider.
    • set Mono Build Tool to JetBrains Mono.
  • 在Rider中:

    • Set MSBuild version to either Bundled with Rider or .NET Core.
    • Install the Godot support plugin.

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。

配置外部编辑器

Godot的脚本编辑器对C#支持很少。因此建议您使用考虑使用外部IDE或编辑器,例如 Visual Studio CodeMonoDevelop。它们为C#提供自动代码补全、调试、和其他有用的功能。要在Godot中选择外部编辑器,请单击 编辑器 → 编辑器设置 并向下滚动到 Mono。在 Mono 下,单击 编辑器,然后选择您指定的外部编辑器。Godot 当前支持以下的外部编辑器:

  • 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 :ref:doc_c_sharp_configuring_vs_2019_for_debugging section below.

创建C#脚本

After you successfully set up C# for Godot, you should see the following option when selecting Attach Script in the context menu of a node in your scene:

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

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

项目设置和工作流程

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

示例

这是一个空白的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一贯力求尽可能合理。

有关更多信息,请参见 C# API differences to GDScript 页面。

警告

You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the word Mono at the bottom of the editor window to reveal the Mono panel, then clicking the Build Project button.

You will also need to rebuild the project assemblies to apply changes in "tool" scripts.

目前的陷阱和已知问题

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

  • 编写编辑器插件是可能的,但是目前相当复杂。
  • 热重载时,当前状态不被保存和恢复,导出变量除外。
  • 附加C#脚本需要引用一个类,该类名需要匹配其文件名。
  • Get()/Set()Call()/CallDeferred() 等方法,以及信号连接方法 Connect() 都依赖于Godot的``snake_case``API命名规范。所以,CallDeferred("AddChild")``无法调用``AddChild ,因为API需要原始``snake_case``版本的``add_child``。不过,自定义属性和方法没有此限制。

As of Godot 3.2.2, exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is UWP.

在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</Version>
        </PackageReference>
    </ItemGroup>
    ...
</Project>

注解

默认情况下,诸如NuGet之类的工具将``Version``作为```PackageReference```节点 的属性。你必须如上所述手动创建版本节点。 这是因为所使用的MSBuild版本需要这样做。(这将在Godot 4.0中修复。)

Whenever packages are added or modified, run nuget restore (not dotnet restore) in the root of the project directory. To ensure that NuGet packages will be available for msbuild to use, run:

msbuild /t:restore

Profiling your C# code

Configuring VS 2019 for debugging

注解

Godot 有内置的工作流程支持包括几种流行的C# IDE(C#集成开发环境)。内置的对于 Visual Studio 的支持包括其未来版本,但与此同时,以下步骤允许您配置 VS 2019 以用于 Godot C# 项目。

  1. 安装 VS2019 时选中工作负载项``.NET 桌面开发`` 和``使用 C++ 的桌面开发``(已安装VS2019的可以在 Visual Studio Installer中选择修改,确保安装即可)。
  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. 安装 VSMonoDebugger extension(VSMonoDebugger 扩展)
  4. 在 VS 2019 --> Extensions --> Mono --> Settings:
    • 选择 Debug/Deploy to local Windows
    • 清空``Local Deploy Path``项。
    • 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. 在 VS 2019, 打开你的项目选择 Extensions --> Mono --> Attach to Mono Debugger.

Configuring Visual Studio Code for debugging

To configure debugging, open Visual Studio Code and download the Mono Debug extension from Microsoft and the Godot extension by Ignacio. Then open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. Now, when you start the debugger in VS Code your Godot project will run.