GDNative bindings for Rust
Rust bindings to the Godot game engine.
Website | User Guide | API Documentation
Stability
The bindings cover most of the exposed API of Godot 3.2, and are being used on a number of projects in development, but we still expect non-trivial breaking changes in the API in the coming releases.
Engine compatibility
We are serious about engine compatibility. We are committed to keeping compatibility with the latest stable patch releases of all minor versions of the engine, starting from Godot 3.2.
The current minimum compatible version, with api.json replacement, is Godot 3.2-stable. Changes to this will be considered a breaking change, and will be called out in the release notes.
The bindings do not support Godot 4.0 (master branch) currently.
Requirements
The generator makes use of bindgen, which depends on Clang. Instructions for installing bindgen's dependencies for popular OSes can be found in their documentation: https://rust-lang.github.io/rust-bindgen/requirements.html.
bindgen may complain about a missing llvm-config binary, but it is not actually required to build the gdnative crate. If you see a warning about llvm-config and a failed build, it's likely that you're having a different problem!
Usage
Godot 3.2.3-stable
After bindgen dependencies are installed, add the gdnative crate as a dependency, and set the crate type to cdylib:
[dependencies]
gdnative = "0.9.3"
[lib]
crate-type = ["cdylib"]
Other versions or custom builds
The bindings are currently generated from the API description of Godot 3.2.3-stable by default. To use the bindings with another version or a custom build, see Using custom builds of Godot in the user guide.
Example
The most general use-case of the bindings will be to interact with Godot using the generated wrapper classes, as well as providing custom functionality by exposing Rust types as NativeScripts.
NativeScript is an extension for GDNative that allows a dynamic library to register "script classes" to Godot.
As is tradition, a simple "Hello World" should serve as an introduction. For a full tutorial, check out "Getting Started" from the user guide!
use gdnative::prelude::*;
#[derive(NativeClass)]
#[inherit(Node)]
pub struct HelloWorld;
#[methods]
impl HelloWorld {
fn new(_owner: &Node) -> Self {
HelloWorld
}
#[export]
fn _ready(&self, _owner: &Node) {
godot_print!("hello, world.");
}
}
fn init(handle: InitHandle) {
handle.add_class::<HelloWorld>();
}
godot_init!(init);
Further examples
The /examples directory contains several ready to use examples, complete with Godot projects and setup for easy compilation from Cargo:
- /examples/hello_world - Your first project, writes to the console
- /examples/spinning_cube/ - Spinning our own node in place, exposing editor properties.
- /examples/scene_create - Shows you how to load, instance and place scenes using Rust code
- /examples/signals - Shows you how to handle signals.
- /examples/resource - Shows you how to create and use custom resources.
- /examples/native_plugin - Shows you how to create custom node plugins.
Third-party resources
Tutorials
- Step by step guide - Up and running with Rust and Godot: A basic setup
Open-source projects
- Pong - https://github.com/you-win/godot-pong-rust
- Air Combat - https://github.com/paytonrules/AirCombat - This Godot Tutorial ported to Rust.
- Action RPG - https://github.com/MacKarp/Rust_Action_RPG_Tutorial - This Godot Tutorial ported to Rust.
- Simple Single-Player Blackjack - https://github.com/paytonrules/Blackjack
Tools
- ftw - https://github.com/macalimlim/ftw - manage your godot-rust projects!
Contributing
See the contribution guidelines
License
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed under the MIT license, without any additional terms or conditions.
![[ios] Unable to load GDNative library on iOS simulator](https://avatars.githubusercontent.com/u/5222190?v=4)
![Add missing tests to #[methods] macro](https://avatars.githubusercontent.com/u/3255651?v=4)
1 Jan 4, 2022
80 Dec 31, 2022
174 Nov 22, 2022
2.2k Jan 5, 2023
567 Jan 7, 2023
226 Nov 17, 2022
21 May 5, 2022
5 Jul 13, 2017
65 Jan 8, 2023
1 Apr 14, 2022
8 Jun 6, 2022
2 Sep 29, 2022
12 Jan 20, 2023
18 Apr 15, 2023
43 Jul 22, 2022
3 Mar 3, 2022
28 Dec 25, 2022
12 Oct 13, 2022