C# 基础

前言

警告

C# support is a new feature available since Godot 3.0. As such, you may still run into some issues, or find spots where the documentation could be improved. Please report issues with C# in Godot on the engine GitHub page, and any documentation issues on the documentation GitHub page.

这个页面简单介绍了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#

先决条件

安装最新的稳定版 .NET Core SDK (撰写时为3.1).

从Godot 3.2.3开始, 安装Mono SDK不再是一个要求, 除非你是从源码开始构建引擎, 则需要安装Mono SDK.

Godot捆绑了运行已经编译好的游戏所需的Mono部分, 但Godot不包括构建和编译游戏所需的工具, 如MSBuild, 这些工具需要单独安装. 所需工具包含在.NET Core SDK中. MSBuild也包含在Mono SDK中, 但它不能用新的 csproj 格式来构建C#项目, 因此Godot 3.2.3+需要使用.NET Core SDK.

综上所述, 你必须安装了.NET Core SDK 支持Mono的Godot版本.

补充说明

如果您使用64位版本的Godot, 请务必安装64位版本的SDK.

如果你是从源码编译Godot, 请安装最新的稳定版 Mono , 并确保按照 使用 Mono 编译 页面中概述的步骤在构建中启用Mono支持.

配置外部编辑器

Godot内置的脚本编辑器对C#的支持是最小的. 考虑使用外部IDE或编辑器, 如 Visual Studio Code 或MonoDevelop. 这些都为C#提供了自动完成, 调试和其他有用的功能. 要在Godot中选择一个外部编辑器, 点击 Editor → Editor Settings , 向下滚动到 Mono . 在 Mono 下, 点击 Editor , 然后选择您的外部编辑器.Godot目前支持以下外部编辑器:

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Mac版的Visual Studio

  • JetBrains Rider

关于如何配置外部编辑器, 请参见以下章节:

JetBrains Rider

阅读完 "预备知识" 部分, 就可以下载安装 JetBrains Rider .

在Godot的 Editor → Editor Settings 菜单中:

  • 设置 Mono -> Editor -> External EditorJetBrains Rider .

  • 设置 Mono -> Builds -> Build Tooldotnet CLI .

在Rider中:

  • 设置 MSBuild version.NET Core .

  • 安装 Godot支持 插件.

Visual Studio Code

看完 "预备知识" 部分, 就可以下载安装 Visual Studio Code (又名VS Code).

在Godot的 Editor → Editor Settings 菜单中:

  • 设置 Mono -> Editor -> External EditorVisual Studio Code .

在 Visual Studio Code 中:

备注

如果你使用的是 Linux,需要安装 Mono SDK <https://www.mono-project.com/download/stable/#download-lin> 才能使用 C# 工具插件。

要配置一个用于调试的项目,请在 VS Code 中打开 Godot 项目文件夹。进入运行选项卡,点击添加配置...。从下拉菜单中选择 C# Godot。打开创建的 tasks.jsonlaunch.json 文件。将 launch.json 中的可执行文件设置以及 tasks.json 中的命令设置修改为你的 Godot 可执行文件路径。这样,当你在 VS Code 中启动调试器时,就会运行你的 Godot 项目。

Visual Studio (仅限Windows)

下载并安装最新版本的 Visual Studio . 如果你选择了正确的工作负载,Visual Studio将包含所需的SDK, 所以你不需要手动安装 "预先告知" 部分列出的内容.

在安装Visual Studio时, 选择这些工作负载:

  • 使用.NET进行移动开发

  • .NET Core跨平台开发

在Godot的 Editor → Editor Settings 菜单中:

  • 设置 Mono -> Editor -> External EditorVisual Studio .

Next, you need to download the Godot Visual Studio extension from github here. Double click on the downloaded file and follow the installation process.

创建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 的差异 页面.

警告

每当你想在编辑器中看到新导出的变量或信号时,你都需要重新构建项目。这种构建可以通过点击编辑器右上角的 Build 来手动触发。你也可以点击编辑器窗口底部的 Mono 来显示Mono面板,然后点击 Build Project 按钮。

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

目前的陷阱和已知问题

As C# support is quite new in Godot, there are some growing pains and things that need to be ironed out. Below is a list of the most important issues you should be aware of when diving into C# in Godot, but if in doubt, also take a look over the official issue tracker for Mono issues.

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

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

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

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

导出 Mono 项目支持桌面平台(Linux、Windows 和 macOS)、Android、HTML5 和 iOS,唯一还不支持的平台是 UWP。

在Godot中C#的性能

According to some preliminary benchmarks, the performance of C# in Godot — while generally in the same order of magnitude — is roughly ~4× that of GDScript in some naive cases. C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads. C# is faster, but requires some expensive marshalling when talking to Godot.

在Godot中使用NuGet包

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

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

从Godot 3.2.3开始,Godot在下次构建项目时自动下载并设置新添加的NuGet包。

分析 C# 代码