C# 基础

前言

警告 引擎 GitHub 页面 上报告Godot中C#的问题, 并在 文档 GitHub 页面 上报告任何文档问题. 如何使用特定功能, 阅读有关 C#和GDScript API 之间的差异 并(重新)访问逐步教程的 编写脚本部分. 兼容性 页面. 注解 不是 一个关于C#语言整体的全面教程. 如果你还不熟悉其语法或功能, 请参阅 Microsoft C #指南 或在其他地方寻找合适的介绍.

为Godot设置C

先决条件

.NET Core SDK (撰写时为3.1). 从Godot 3.2.3开始, 安装Mono SDK不再是一个要求, 除非你是从源码开始构建引擎, 则需要安装Mono SDK. csproj 格式来构建C#项目, 因此Godot 3.2.3+需要使用.NET Core SDK. 和 支持Mono的Godot版本.

补充说明

如果您使用64位版本的Godot, 请务必安装64位版本的SDK. Mono , 并确保按照 使用 Mono 编译 页面中概述的步骤在构建中启用Mono支持.

配置外部编辑器

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 . 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). Editor → Editor Settings 菜单中:
  • Mono -> Editor -> External Editor 为 Visual Studio Code . 在 Visual Studio Code 中:
  • C # 扩展.
  • Mono Debug 扩展。
  • C# Tools for Godot 扩展. 注解 https://www.mono-project.com/download/stable/#download-lin> 才能使用 C# 工具插件。 创建 launch.json文件 。从下拉菜单中选择 C# Godot 。那么，当你在VS Code中启动调试器时，你的Godot项目将运行。

    Visual Studio (仅限Windows)

    Visual Studio . 如果你选择了正确的工作负载,Visual Studio将包含所需的SDK, 所以你不需要手动安装 “预先告知” 部分列出的内容. 在安装Visual Studio时, 选择这些工作负载:
  • 使用.NET进行移动开发
  • .NET Core跨平台开发 Editor → Editor Settings 菜单中:
  • Mono -> Editor -> External Editor 为 Visual Studio . here 下载Godot Visual Studio扩展。双击下载的文件，并按照安装过程进行安装。

    创建C#脚本

    附加脚本 时, 应该看到以下选项: Scripting languages. 虽然在文档中缺乏详细的C#示例, 但大部分概念都能够在GDScript轻松地阐述清楚.

    项目设置和工作流程

    .sln )和项目文件( .csproj ), 以及一些实用程序文件和文件夹( Properties/AssemblyInfo.cs 和 .mono). 除了 .mono 之外的所有这些都很重要, 应该被保存在您的版本控制系统中. 而 .mono 可以安全地添加到VCS的忽略列表中. 在进行故障排除时, 删除 .mono 文件夹并让它重新生成, 有时可能会有所帮助.

    示例

    这是一个空白的C#脚本, 带有一些注释, 以演示其工作方式.
    1. 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.    }}
    print 函数)可在 GD 类中使用, 该类是 Godot 命名空间的一部分. 有关 GD 类中方法的列表, 请参见 @GDScript 和 @GlobalScope 的类参考页. 注解 .cs 文件具有相同的名称. 否则, 您将收到以下错误, 并且将无法运行场景: “无法找到类XXX, 对应脚本res://XXX.cs”

    C#和GDScript之间的一般差异

    PascalCase 而不是GDScript / C++中使用的 snake_case . 在可能的情况下, 字段和getters/setters已转换为属性. 一般来说,C#Godot API一贯力求尽可能合理. C# API 与 GDScript 的差异 页面. 警告 Build 来手动触发。你也可以点击编辑器窗口底部的 Mono 来显示Mono面板，然后点击 Build Project 按钮。 你还需要重新构建项目集, 以应用 “工具” 脚本中的更改.

    目前的陷阱和已知问题

    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>        <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />    </ItemGroup>    ...</Project>
    从Godot 3.2.3开始，Godot在下次构建项目时自动下载并设置新添加的NuGet包。

    分析 C# 代码

  • Monon日志分析器(Mono log profiler) 可用于Linux和macOS . 由于Mono的变化, 它目前在Windows上无法使用.
  • JetBrains dotTrace 使用方法在 这里.