GDNative的Rust绑定库

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（默认参数）的映射不是1:1，因此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。

入门指南

详细的设置说明在本书的《入门指南》部分。如有问题，也请考虑阅读常见问题解答（FAQ）。

最新发布版本

这是使用godot-rust的推荐方式。安装了bindgen依赖项和当前Godot版本后，将gdnative存储库作为依赖项添加，并将存储库类型设置为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功能，则提供了一个低级API在gdnative::tasks中。有关如何使用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手动操作，或使用方便的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 - 一个 Rust 版本的小 Godot 游戏。
• signals - 连接和发射信号。
• resource - 创建和使用自定义资源。
• rpc - 简单的端到端网络。
• native-plugin - 创建自定义节点插件。

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

第三方项目

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

贡献

查看贡献指南。

许可证

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