Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

使用 .NET 编译

需求

  • .NET SDK 8.0+

    你可以运行 dotnet --info 这个命令，来查看当前电脑上已经安装了哪些版本的 .NET SDK。

启用 .NET 模块

备注

历史上，Godot 的 C# 支持一直使用的是 Mono （Runtime），而不是现在的 .NET <https://github.com/dotnet/runtime>`_ 。因此，在引擎内部，许多东西依然沿用了 mono 这个命名，而不是 dotnet ，或者在其他地方也依然被称作 mono。

默认情况下，编译时 .NET 模块是关闭的。如果想要启用它，你需要在 SCons 的命令行中加入 module_mono_enabled=yes 这个选项，其他操作步骤则照常按照编译目标 Godot 程序的流程进行即可。

生成胶水代码

托管库的部分源代码是从 ClassDB（Godot 内部的类数据库）中自动生成的。因此，在编译托管库之前，必须先完成这些源文件的生成工作。你可以通过任意一个开启了 .NET 支持的 Godot 编辑器程序来生成它们，只需要在运行时加上 --headless --generate-mono-glue 参数，并在后面跟上输出目录的路径即可。这个输出路径必须指定为 Godot 源码目录下的 modules/mono/glue 文件夹。

<godot_binary> --headless --generate-mono-glue modules/mono/glue

这个命令会指示 Godot 在 modules/mono/glue/GodotSharp/GodotSharp/Generated 目录下生成 Godot API 的 C# 绑定代码，并在 modules/mono/glue/GodotSharp/GodotSharpEditor/Generated 目录下生成编辑器工具的 C# 绑定代码。一旦这些文件生成完毕，你就可以直接为你想要的所有目标平台编译 Godot 的托管库了，而且以后不需要再重复执行这一步骤。

<godot_binary> 指的是你编译出来的、启用了 .NET 模块的编辑器二进制文件。它的具体名称会根据你的系统和配置有所不同，但格式应该是 bin/godot.<platform>.editor.<arch>.mono 这样的形式，例如 bin/godot.linuxbsd.editor.x86_64.mono 或者 bin/godot.windows.editor.x86_32.mono.exe 。请务必特别注意文件名里的 .mono 后缀！ 如果你之前编译过不带 .NET 支持的 Godot，可能会看到名字非常相似但缺少这个后缀的程序文件。那些不带后缀的文件是无法用来生成 .NET 胶水代码（.NET glue）的。

备注

每次ClassDB注册的API更改时, 都必须重新生成胶水源码. 即, 例如, 当将新方法注册到脚本API时, 或该方法的参数之一发生更改时. 如果ClassDB和胶水源码之间的API不匹配,Godot将在启动时打印一条错误.

构建托管库

一旦你生成了 .NET 胶水代码（.NET glue），就可以使用 build_assemblies.py 这个脚本来编译托管库（managed libraries）了：

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin

如果一切顺利，bin 目录中应该已经创建了包含托管库的 GodotSharp 目录。

备注

默认情况下，所有的开发版构建（development builds）都会共用一个相同的版本号，这可能会导致 NuGet 程序包的缓存出现一些问题。为了解决这个问题，你可以选择以下两种方法之一：要么使用 GODOT_VERSION_STATUS 给每一个构建赋予一个独一无二的版本号；要么在每次构建结束后，手动删除 GodotNuGetFallbackFolder 文件夹，以此来彻底清空程序包缓存。

与 "传统" 的 Godot 编译方式不同，在启用 .NET 模块进行编译时（并且视具体目标平台而定），系统可能会为编辑器以及导出的项目生成一个数据目录。这个目录对程序的正常运行至关重要，因此在分发 Godot 时必须一并带上。关于这个目录的更多细节，请查看： Data directory。

编译平台

请提供 --godot-platform=<platform> 参数，来控制具体为哪个平台编译库文件。如果省略该参数，就会默认为你当前的系统环境进行编译。

目前，这仅仅只是控制是否包含对 Visual Studio 作为外部编辑器的支持，除此以外，这两个库是完全一模一样的。

NuGet 程序包

API 程序集、源生成器（source generators）以及自定义的 MSBuild 项目 SDK，都是以 NuGet 程序包的形式进行分发的。这一切对普通用户来说都是完全透明的（无感知的），但在开发过程中，它可能会让事情变得有些复杂。

为了将Godot与这些包的开发版本一起使用，必须在 MSBuild 可以找到它们的地方创建一个本地 NuGet 源代码。

首先，为你的本地 NuGet 源选择一个存放位置。如果你没有特别的偏好，可以在以下推荐的任意位置创建一个空文件夹：

  • 在 Windows 系统中，C:\Users\<username>\MyLocalNugetSource

  • 在Linux上， *BSD, etc., ~/MyLocalNugetSource

这个路径在后面的内容里会被称作 <my_local_source>.。

选好一个文件夹之后，接下来只要运行这条 .NET CLI 命令，就能让 NuGet 知道并使用你的本地源啦：

dotnet nuget add source <my_local_source> --name MyLocalNugetSource

当你运行 build_assemblies.py 脚本时，请将 <my_local_source> 作为参数传递给 --push-nupkgs-local 选项：

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source>

这个选项能确保生成的程序包会被添加到指定的本地 NuGet 源中，并且会把 NuGet 缓存里存在冲突的旧版本程序包给清理掉。强烈建议在开发过程中编译 C# 解决方案时，始终使用这个选项，以免踩坑。

在不依赖已弃用功能的情况下构建（NO_DEPRECATED）

当编译 Godot 时不包含已弃用的类和方法（即在 scons 编译时加上 deprecated=no 参数），托管库（managed libraries）也必须在不依赖这些弃用代码的情况下进行编译。这可以通过传入 --no-deprecated 参数来实现：

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --no-deprecated

双精度支持 (REAL_T_IS_DOUBLE)

当使用双精度支持（即在 scons 编译时加上 precision=double 参数）来编译 Godot 时，必须通过传入 --precision=double 参数来相应地调整托管库（managed libraries），以确保两者匹配。

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --precision=double

示例

示例（Windows）

# Build editor binary
scons platform=windows target=editor module_mono_enabled=yes
# Build export templates
scons platform=windows target=template_debug module_mono_enabled=yes
scons platform=windows target=template_release module_mono_enabled=yes

# Generate glue sources
bin/godot.windows.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Build .NET assemblies
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=windows

示例 (Linux, *BSD)

# Build editor binary
scons platform=linuxbsd target=editor module_mono_enabled=yes
# Build export templates
scons platform=linuxbsd target=template_debug module_mono_enabled=yes
scons platform=linuxbsd target=template_release module_mono_enabled=yes

# Generate glue sources
bin/godot.linuxbsd.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Generate binaries
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=linuxbsd

数据目录

数据目录是启用 .NET 模块编译的 Godot 可执行文件的必要依赖项。它包含了 Godot 正常运行所需的重要文件，因此必须随 Godot 可执行文件一起分发。

编辑器

Godot 编辑器的数据目录名称将始终是 GodotSharp。该目录下包含一个 Api 子目录，里面存放着 Godot 的 API 程序集；以及一个 Tools 子目录，里面存放着编辑器所需的各类工具，比如 GodotTools 程序集及其相关依赖项。

在 macOS 系统上，如果 Godot 编辑器是以应用程序包（bundle）的形式发布的，那么 GodotSharp 目录可以放在该应用程序包内部的 <bundle_name>.app/Contents/Resources/ 目录下。

导出模板

导出项目的数据目录是由编辑器在导出过程中自动生成的。它的命名格式为 data_<APPNAME>_<ARCH>，其中 <APPNAME> 是你在项目设置 application/config/name 中指定的应用名称，而 <ARCH> 则是当前导出平台的系统架构。

在多体系结构导出的情况下，将生成多个这样的数据目录。

命令行选项

以下是在启用 .NET 模块进行编译时，可用的命令行选项列表：

  • module_mono_enabled =yes | no

    • 启用 .NET 模块来编译 Godot。