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...

关于 godot-cpp

godot-cpp 是官方的 C++ GDExtension 绑定，作为 Godot 项目的一部分进行维护。

godot-cpp 基于 GDExtension 系统构建，其访问 Godot 的方式与 C++ 模块几乎一致：您可以直接在 godot-cpp 项目中复用大量引擎代码，几乎无需修改。

特别是，godot-cpp 能够访问 GDScript 和 C# 的所有功能，并额外提供一些更底层的快速数据访问接口，以及与 Godot 更深度的集成能力。

godot-cpp 与 C++ 模块的区别

你可以使用 godot-cpp 和 C++ 模块在 Godot 项目中执行 C/C++ 代码。

它们都可以用来将第三方库集成进 Godot。选用哪一个取决于你的需求。

godot-cpp 的优势

与模块不同，godot-cpp（以及一般意义上的 GDExtensions）无需编译引擎源码，这可以让你的作品更易于分发。GDExtension 可以让你访问 GDScript 和 C# 中大多数可用的API，让你在编写游戏逻辑时能够完全掌控性能，是你在资产库中以插件形式分发高性能代码的理想选择。

并且：

你可以在编辑器和导出项目中使用相同的编译后的 godot-cpp 库。而对于 C++ 模块，如果你想在运行时使用相关功能，就必须重新编译所有想要使用的导出模板。
godot-cpp 只需编译你自己的库，而无需编译整个引擎。这与 C++ 模块不同，后者会被静态编译进引擎中。每修改一次模块，你就需要重新编译整个引擎。即使使用增量构建，这一过程也比编译 Godot-C++ 要慢。

C++ 模块的优点

如果 godot-cpp（或其他 GDExtension 系统）无法满足需求，我们推荐使用 C++ 模块：

C++ 模块提供了与引擎更深层次的集成。GDExtension 的访问能力不如静态模块那般深入。
使用 C++ 模块为项目提供额外功能，就可以免去携带原生库文件的麻烦。同样也适用于导出的项目。

备注

如果你发现某些特定功能在 godot-cpp 中不可用，在自定义模块中却可用，欢迎在 godot-cpp 仓库上提交新问题，探讨实现该等缺失功能的技术途径。

版本兼容性

我们的长期目标是，确保旧版 GDExtension 能在后续版本中持续兼容，反之则不可行。例如，一个面向 Godot 4.2 的 GDExtension 应当在 Godot 4.3 中正常运作，但面向 Godot 4.3 的则不能在 Godot 4.2 中运作。

因此，在创建 GDExtension 时，你应该以具备你所需功能的最低版本 Godot 为目标，而非最新版本的 Godot。这可使你免于为不同版本的 Godot 创建多个构建。

有一个例外：针对 Godot 4.0 的扩展将无法在 Godot 4.1 及更高版本中运行（参见将 GDExtension 更新到 4.1）。

GDExtension 的兼容性还要求引擎构建版本与扩展编译时使用的浮点数精度级别必须一致，即如果你使用支持双精度浮点数的引擎构建版本，则插件也必须针对双精度浮点数进行编译。并且必须使用你的自定义引擎构建生成的 extension_api.json 文件。有关详细信息，请参见：大世界坐标。

通常来说，如果你构建了自定义版本的 Godot，应该为你的 GDExtensions 生成对应的 extension_api.json，因为它可能与官方 Godot 构建版本存在一些差异。有关使用自定义 extension_api.json 文件的流程的更多信息，请参阅 build system section。