Rust bindings to the Godot game engine.

API Documentation

• Note that this generally matches the Godot API but you have to do casting between classes and subclasses manually.

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.

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.1.1-stable. Changes to this will be considered a breaking change, and will be called out in the release notes.

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.

After bindgen dependencies are installed, add the gdnative crate as a dependency, and set the crate type to cdylib:

[dependencies]
gdnative = "0.8"

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

The bindings are currently generated from the API description of Godot 3.2 by default. To use the bindings with another version or a custom build, one currently has to use the bindings as a local dependency:

# Clone the repository and check out version 0.8.0
git clone https://github.com/GodotNativeTools/godot-rust/
cd godot-rust
git checkout 0.8.0

# Update the API description file
godot --gdnative-generate-json-api bindings_generator/api.json

Then, add the gdnative crate as a local dependency instead:

[dependencies]
gdnative = { path = "path/to/godot-rust/gdnative" }

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.

(The following section is a very quick-and-dirty rundown of how to get started with the Rust bindings. For a more complete and detailed introduction see the Godot documentation page.)

As is tradition, a simple "Hello World" should serve as an introduction. A copy of this "hello world" project can be found in the examples folder.

Starting with an empty Godot 3.2 project, a cargo project can be created inside the project folder.

cargo init --lib

To use the GDNative bindings in your project you have to add the gdnative crate as a dependency.

[dependencies]
gdnative = "0.8"

Since GDNative can only use C-compatible dynamic libraries, the crate type has to be set accordingly.

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

In the src/lib.rs file should have the following contents:

use gdnative::*;

/// The HelloWorld "class"
#[derive(NativeClass)]
#[inherit(Node)]
pub struct HelloWorld;

// __One__ `impl` block can have the `#[methods]` attribute, which will generate
// code to automatically bind any exported methods to Godot.
#[methods]
impl HelloWorld {
    
    /// The "constructor" of the class.
    fn _init(_owner: Node) -> Self {
        HelloWorld
    }
    
    // In order to make a method known to Godot, the #[export] attribute has to be used.
    // In Godot script-classes do not actually inherit the parent class.
    // Instead they are"attached" to the parent object, called the "owner".
    // The owner is passed to every single exposed method.
    #[export]
    fn _ready(&self, _owner: Node) {
        // The `godot_print!` macro works like `println!` but prints to the Godot-editor
        // output tab as well.
        godot_print!("hello, world.");
    }
}

// Function that registers all exposed classes to Godot
fn init(handle: gdnative::init::InitHandle) {
    handle.add_class::<HelloWorld>();
}

// macros that create the entry-points of the dynamic library.
godot_gdnative_init!();
godot_nativescript_init!(init);
godot_gdnative_terminate!();

After building the library with cargo build, the resulting library should be in the target/debug/ folder.

All NativeScript classes live in a GDNative library. To specify the GDNative library, a GDNativeLibrary resource has to be created. This can be done in the "Inspector" panel in the Godot editor by clicking the "new resource" button in the top left.

With the GDNativeLibrary resource created, the path to the generated binary can be set.

NOTE: Resources do not autosave, so after specifying the path, make sure to save the GDNativeLibrary resource by clicking the "tool" button in the Inspector panel in the top right.

Now the HelloWorld class can be added to any node by clicking the "add script" button. In the popup-select the "NativeScript" option and set the class name to "HelloWorld".

NOTE: After creation, the NativeScript resource does not automatically point to the GDNativeLibrary resource. Make sure to set click the "library" field in the Inspector and "load" the library.

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.

Several third-party resources have been created for the bindings. Open a PR to have yours included here!

• In depth Hello World tutorial - Gorgeous Godot games in Rust
• Step by step guide - Up and running with Rust and Godot: A basic setup

• Pong - https://github.com/you-win/godot-pong-rust

• Auto Setup Script (as git dependency) - https://gitlab.com/ardawan-opensource/gdnative-rust-setup

See the contribution guidelines

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.