Rust 的 GDNative 绑定

godot-rust 是一个 Rust 库，它实现了对 Godot 游戏引擎 的本地绑定。这允许你在 Godot 中开发游戏或其他应用程序，同时利用 Rust 的优势，如其类型系统、可扩展性和性能。

注意：如果你在寻找 GDExtension (Godot 4) 的 Rust 绑定，请查看 gdext。

维护策略

gdnative 被认为主要功能已经完成，并侧重于 API 稳定性进行维护。我们尽量避免不必要的破坏性变更，并在需要时将其对最终用户的影响降至最低。

我们遵循 Cargo 的语义版本控制 作为在版本之间传达公共 API 变化的手段。未来的版本计划将在 GitHub 上公开，使用 里程碑 功能。请注意，我们使用 breaking-change 标签来指示存在任何技术破坏，无论其对最终用户程序的影响预期如何。

如果你打算贡献力量，但不确定你想要做的事情是否在项目范围内，并且符合我们的维护政策，请在开始之前随时 与项目负责人联系。

工具链兼容性

gdnative 当前支持的最低 Rust 版本 (MSRV) 为 1.70。我们使用 Rust 2021 版本。

警告： Linux 用户：请注意您 Godot 二进制的来源！ 使用基于容器格式的 Godot 二进制分发版可能会包含与直接从您的系统构建的 GDNative 库不兼容的依赖项版本。此类格式的例子包括 Flatpak、Snap 和 AppImage。

截至 2023 年，某些包管理器可能在请求 Godot 时静默地安装这些版本之一而不是常规包，这可能导致您的 GDNative 库出现奇特的兼容性问题。我们建议使用来自 godotengine.org 的官方二进制文件，包括编辑器和导出模板。

由于 GDNative API 并不严格遵循 SemVer，以及某些概念与 Rust 不完全一一对应（默认参数），godot-rust 版本同时保持与多个 Godot 版本兼容非常困难。

但是，我们默认支持最新稳定版 Godot 3 的次要版本，并允许通过使用 custom-godot 功能标志轻松使用自定义引擎版本（见 下文）。

兼容性列表

• Godot 3.5.1（与 gdnative 0.11 兼容）
• Godot 3.4（与 gdnative 0.10 兼容，0.11 的自定义构建）
• Godot 3.3（自定义构建）
• Godot 3.2（自定义构建）

绑定不支持 Godot 4。如果您正在寻找 GDExtension（Godot 4）的 Rust 绑定，请查看 gdextension。

入门指南

详细设置说明在 书籍的 入门指南 部分。如果遇到问题，也可以考虑阅读 常见问题解答。

最新发布版本

这是使用 godot-rust 的推荐方式。在安装了 bindgen 依赖项和当前 Godot 版本后，将 gdnative crate 添加为依赖项，并将 crate 类型设置为 cdylib

[dependencies]
gdnative = "0.11"

[lib]
crate-type = ["cdylib"]

最新 GitHub 版本

如果您想从最新的特性和错误修复中受益，可以使用 GitHub 版本。我们有一个相对复杂的 CI 和测试套件来保证基本稳定性，但 GitHub 版本通常比 crates.io 发布版本更具实验性且测试较少。我们也不保证这里的 SemVer 兼容性。

[dependencies]
gdnative = { git = "https://github.com/godot-rust/godot-rust.git" }

[lib]
crate-type = ["cdylib"]

自定义构建

要使用与不同 Godot 版本或自定义构建的引擎一起使用的绑定，请参阅用户指南中的 自定义 Godot 构建。

异步/生成支持

异步支持仍在开发中，如果启用了 gdnative 上的 async 功能，则可以通过 gdnative::tasks 提供的低级别 API 使用异步支持。请参阅书籍中的此页面，了解如何使用 Tokio 使用异步功能：此页面。

示例

一个典型用例是暴露您的自己的 本地类，一个可以从 Godot 引擎调用的 Rust API。生成的本地脚本可以附加到场景树中，就像 GDScript（.gd 文件）一样。

这通过动态库和 GDNative 接口 实现，该接口将由 Godot 加载。godot-rust 在幕后完成必要的连接。一个简单的“Hello world”应用程序可能看起来像这样

use gdnative::prelude::*;

#[derive(NativeClass)]
#[inherit(Node)]
pub struct HelloWorld;

#[methods]
impl HelloWorld {
    fn new(_base: &Node) -> Self {
        HelloWorld
    }

    #[method]
    fn _ready(&self, #[base] _base: &Node) {
        godot_print!("Hello, world.");
    }
}

fn init(handle: InitHandle) {
    handle.add_class::<HelloWorld>();
}

godot_init!(init);

更多示例

重要说明

要运行或编辑示例，您首先需要为其构建本地库。否则，项目可能会损坏。您可以通过以下方式手动构建：cargo build，或者使用方便的shell脚本example.sh：使用./example.sh run hello-world运行或使用./example.sh edit hello-world进行编辑。

在/examples目录中包含几个现成的示例，包括Godot项目，并已为从Cargo轻松编译做好准备。

• hello-world - 您的第一个项目，将输出到控制台。
• spinning-cube - 在原地旋转我们的节点，暴露编辑器属性。
• scene-create - 使用Rust代码加载、实例化和放置场景。
• builder-export - 使用builder API导出。
• property-export - 导出如集合等复杂属性。
• dodge-the-creeps - Rust版本的小Godot游戏。
• signals - 连接和发出信号。
• resource - 创建和使用自定义资源。
• rpc - 简单的端到端网络。
• native-plugin - 创建自定义节点插件。

启动时，Godot编辑器尝试加载项目中使用的所有资源，包括本地库。如果后者不存在，编辑器将跳过场景中缺少本地脚本的属性或信号。这导致依赖于编辑器配置的属性或信号的任何示例的场景树都无法正常工作。

第三方项目

要查看基于godot-rust开发的游戏和集成列表，请参阅书中第三方项目列表。

贡献

请参阅贡献指南。

许可证

您提交的任何贡献，只要包含在本工作中，都必须在MIT许可证下许可，不附加任何额外条款或条件。

lib.rs:

Godot-rust绑定的内部API绑定生成器。

创建自定义绑定crate

可以通过向Api::new()传递自定义的api.json数据来创建自定义绑定crate，而无需分支仓库。可以使用以下命令从Godot生成JSON数据：

/path/to/godot--gdnative-generate-json-api/path/to/api.json

请注意，生成器是一个内部依赖。 因此，它不受主 gdnative crate 的 semver 保证。当使用自定义绑定 crate 时，必须注意确保生成器的版本与 Cargo.toml 中指定的 gdnative crate 的版本完全匹配，即使在 gdnative crate 中被认为是非破坏性的更新中也是如此。