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

先决条件

安装最新的稳定版 .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 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 .

在 Visual Studio Code 中:

注解

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

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

接下来，你需要从github here 下载Godot Visual Studio扩展。双击下载的文件，并按照安装过程进行安装。

创建C#脚本

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

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

请注意, 虽然在某些细节上有所差别, 使用C#编写代码时, 大多数概念的工作方式是相通的. 如果您是刚接触Godot的新手, 此时您可能需要按照以下教程 Scripting languages. 虽然在文档中缺乏详细的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# 代码