GDNative绑定库

godot-rust 是一个实现Godot游戏引擎本地绑定的Rust库。这允许你在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库与你的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 构建”。

异步/yield 支持

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

示例

一个典型的用例是暴露您的自己的 Native Class，一个可以从 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 - 使用Rust重写的小Godot游戏.
• signals - 连接和发出信号。
• resource - 创建和使用自定义资源。
• rpc - 简单的端到端网络。
• native-plugin - 创建自定义节点插件。

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

第三方项目

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

贡献

请参阅贡献指南。

许可证

您提交的任何贡献，如需包含在作品中，应按照MIT许可证授权，没有任何额外的条款或条件。