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 中:

To configure a project for debugging 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.

Visual Studio (仅限Windows)

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

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

  • 使用.NET进行移动开发

  • .NET Core跨平台开发

在Godot的 Editor → Editor Settings 菜单中:

  • 设置 Mono -> Editor -> External Editor 为 Visual 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#脚本,带有一些注释,以演示其工作方式.

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

警告

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 Build in the top right corner of the editor. You can also click Mono at the bottom of the editor window to reveal the Mono panel, then click the Build Project button.

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

目前的陷阱和已知问题

由于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>

As of Godot 3.2.3, Godot automatically downloads and sets up newly added NuGet packages the next time it builds the project.

分析 C# 代码