Rust的GDNative绑定

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

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

稳定性

这些绑定覆盖了Godot 3.5的大部分公开API，并被用于多个开发中的项目，但我们仍预计在未来的版本中API会有非平凡的破坏性更改。godot-rust遵循Cargo的语义版本控制。

最低支持的Rust版本（MSRV）是1.63。我们使用Rust 2021版。

引擎兼容性

由于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绑定。

入门

详细的设置说明在书籍的“入门”部分中。如有问题，请考虑阅读常见问题解答（FAQ）。

最新发布版本

这是使用 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 构建。

异步/yield 支持

异步支持还在进行中，如果启用了 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 - 使用构建器 API 导出。
• property-export - 导出复杂属性，例如集合。
• dodge-the-creeps - 一个 little Godot 游戏 的 Rust 版本。
• signals - 连接和发出信号。
• resource - 创建和使用自定义资源。
• rpc - 简单的点对点网络。
• native-plugin - 创建自定义节点插件。

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

第三方项目

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

贡献

查看 贡献指南。

许可证

您提交的任何贡献，只要包含在作品中，就应按照 MIT 许可证 许可，不附加任何额外条款或条件。