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#

先决条件

Install the latest stable version of .NET Core SDK (3.1 as of writing).

From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, except it is required if you are building the engine from source.

Godot bundles the parts of Mono needed to run already compiled games, however Godot does not include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

In summary, you must have installed .NET Core SDK and the Mono-enabled version of Godot.

补充说明

Be sure to install the 64-bit version of the SDK(s) if you are using the 64-bit version of Godot.

If you are building Godot from source, install the latest stable version of Mono, and make sure to follow the steps to enable Mono support in your build as outlined in the 使用Mono编译 page.

配置外部编辑器

C# support in Godot's built-in 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

See the following sections for how to configure an external editor:

JetBrains Rider

After reading the "Prerequisites" section, you can download and install JetBrains Rider.

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to JetBrains Rider.

  • Set Mono -> Builds -> Build Tool to dotnet CLI.

在Rider中:

  • Set MSBuild version to .NET Core.

  • 安装 Godot supportGodot 支持 )插件。

Visual Studio Code

After reading the "Prerequisites" section, you can download and install Visual Studio Code (aka VS Code).

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio Code.

In Visual Studio Code:

Next, follow the instructions found in the 配置Visual Studio Code进行调试 section below.

Visual Studio (Windows only)

Download and install the latest version of Visual Studio. Visual Studio will include the required SDKs if you have the correct workloads selected, so you don't need to manually install the things listed in the "Prerequisites" section.

While installing Visual Studio, select these workloads:

  • Mobile development with .NET

  • .NET Core cross-platform development

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio.

Next, follow the instructions found in the VS2019 调试配置 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 文件夹并让它重新生成,有时可能会有所帮助。

示例

这是一个空白的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 与 GDScript 的差异 页面。

警告

每当您想在编辑器中查看新的导出变量或信号时,都需要(重新)构建项目程序集。可以通过单击编辑器窗口底部的 ** Mono ** 单词以显示Mono面板,然后单击 ** Build Project ** 按钮来手动触发此构建。

你还需要重新构建项目集,以应用 "工具 "脚本中的更改。

目前的陷阱和已知问题

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

  • 编写编辑器插件是可能的,但是目前相当复杂。

  • 热重载时,当前状态不被保存和恢复,导出变量除外。

  • 附加C#脚本需要引用一个类,该类名需要匹配其文件名。

  • Get()/Set()Call()/CallDeferred() 等方法,以及信号连接方法 Connect() 都依赖于Godot的 snake_case API命名规范。所以, CallDeferred("AddChild") 无法调用 AddChild ,因为API需要原始 snake_case 版本的 add_child 。不过,自定义属性和方法没有此限制。

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中修复。)

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

msbuild /t:restore

分析 C# 代码

VS2019 调试配置

注解

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

  1. 安装 VS2019 时选中工作负载项 .NET 桌面开发使用 C++ 的桌面开发 (已安装VS2019的可以在 Visual Studio Installer中选择修改,确保安装即可)。

  2. 确保没有安装 Xamarin。 不要选中 使用 .NET的移动开发 工作负载项。Xamarin为了使用MonoDebugger (Mono调试器)更改了 DLLs(动态链接库) ,而这样做是会破坏调试的。

  3. 安装 VSMonoDebugger extension(VSMonoDebugger 扩展)

  4. 在 VS 2019 --> Extensions --> Mono --> Settings:

    • 选择 Debug/Deploy to local Windows

    • 清空 Local Deploy Path 项。

    • 设置 Mono Debug Port 和 Godot --> 项目 --> 项目设置 --> Mono --> Debugger Agent 中的Port相同的数值。

    • 同时在Mono选项表中,启用 Wait for DebuggerMono Debugger Enabler 这个Godot 小工具 可能有帮助。

  5. 在Godot中运行游戏。在等待连接到调试器时,它应该挂起在启动屏幕。

  6. 在 VS 2019, 打开你的项目选择 Extensions --> Mono --> Attach to Mono Debugger.

配置Visual Studio Code进行调试

要配置调试,打开Visual Studio Code,从微软下载Mono Debug扩展和由Ignacio制作的Godot扩展。然后在VS Code中打开Godot项目文件夹。进入 "运行 "选项卡,点击 创建launch.json文件 。从下拉菜单中选择 C# Godot 。现在,当你在VS Code中启动调试器时,你的Godot项目将会运行。