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 the .NET SDK, previously known as the .NET Core SDK.

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

Godot bundles the parts of Mono needed to run already compiled games. However, Godot does not bundle the tools required to build and compile games, such as MSBuild and the C# compiler. These are included in the .NET SDK, which needs to be installed separately.

In summary, you must have installed the .NET SDK and the Mono-enabled version of 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 Editor 为 JetBrains Rider .

  • 设置 Mono -> Builds -> Build Tool 为 dotnet CLI .

在Rider中:

  • 设置 MSBuild version 为 .NET Core .

  • 安装 Godot支持 插件.

Visual Studio Code

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

在Godot的 Editor → Editor Settings 菜单中:

  • 设置 Mono -> Editor -> External Editor 为 Visual Studio Code .

  • 设置 Mono -> Builds -> Build Tool 为 dotnet CLI .

在 Visual Studio Code 中:

备注

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

要配置一个用于调试的项目，请在 VS Code 中打开 Godot 项目文件夹。进入运行选项卡，点击添加配置…。从下拉菜单中选择 C# Godot。打开创建的 tasks.json 和 launch.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 Editor 为 Visual Studio .

  • 设置 Mono -> Builds -> Build Tool 为 dotnet CLI .

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

备注

The option to debug your game in Visual Studio may not appear after installing the extension. To enable debugging, there is a workaround for Visual Studio 2019. There is a separate issue about this problem in Visual Studio 2022.

备注

If you see an error like “Unable to find package Godot.NET.Sdk”, your NuGet configuration may be incorrect and need to be fixed.

A simple way to fix the NuGet configuration file is to regenerate it. In a file explorer window, go to %AppData%\NuGet. Rename or delete the NuGet.Config file. When you build your Godot project again, the file will be automatically created with default values.

创建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#脚本, 带有一些注释, 以演示其工作方式.

  1. using Godot;
  2. using System;
  4. public class YourCustomClass : Node
  5. {
  6.     // Member variables here, example:
  7.     private int a = 2;
  8.     private string b = "textvar";
  10.     public override void _Ready()
  11.     {
  12.         // Called every time the node is added to the scene.
  13.         // Initialization here.
  14.         GD.Print("Hello from C# to Godot :)");
  15.     }
  17.     public override void _Process(float delta)
  18.     {
  19.         // Called every frame. Delta is time since the last frame.
  20.         // Update game logic here.
  21.     }
  22. }

如您所见, 通常在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 按钮。

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

目前的陷阱和已知问题

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

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

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

  • 附加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#的性能

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

在Godot中使用NuGet包

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

  1.     <ItemGroup>
  2.         <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
  3.     </ItemGroup>
  4.     ...
  5. </Project>

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

分析 C# 代码