GDNative bindings for Rust

Website | User Guide | Stable Docs | Latest Docs

godot-rust is a Rust library that implements native bindings for the Godot game engine. This allows you to develop games or other applications in Godot, while benefiting from Rust's strengths, such as its type system, scalability and performance.

Stability

The bindings cover most of the exposed API of Godot 3.4, 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. godot-rust adheres to Cargo's semantic versioning.

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:

• Godot 3.4 (works out-of-the-box)
• Godot 3.3 (needs api.json adjustment)
• Godot 3.2 (needs api.json adjustment)

For versions 3.2 and 3.3, some extra steps are needed, see Custom builds below.

The bindings do not support in-development Godot 4 versions at the moment. Support is planned as the native extensions become more stable.

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.

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!

'Header not found' errors

When building the library, bindgen may produce errors that look like this:

godot-rust\gdnative-sys/godot_headers\gdnative/string.h:39:10: fatal error: 'wchar.h' file not found

This means that bindgen was unable to find the C system headers for your platform. If you can locate the headers manually, you may try setting the C_INCLUDE_PATH environment variable so libclang could find them. If on Windows, you may try building from the Visual Studio "developer console", which should setup the appropriate variables for you.

Usage

Latest master version + Godot 3.4

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

[dependencies]
gdnative = { git = "https://github.com/godot-rust/godot-rust.git" }

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

Godot 3.2.3-stable

To access the last released version on crates.io, use the following. If you are starting, we recommend using the master version at this point, as there have been significant API changes since v0.9.3.

[dependencies]
gdnative = "0.9.3"

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

Custom builds

To use the bindings with a non-default Godot version or a custom build, see Using custom builds of Godot in the user guide.

In short, you will need to generate api.json manually, using godot --gdnative-generate-json-api api.json to replace the file in the gdnative-bindings directory.

Async / yield support

Async support is a work-in-progress, with a low-level API available in the gdnative-async crate. This crate is re-exported as gdnative::tasks, if the async feature is enabled on gdnative. See this page in the book for an introduction to use the async feature with Tokio.

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

IMPORTANT NOTE

Before launching the examples in the godot editor, you must first run cargo build and wait for the build operations to finish successfully.

At startup, the Godot editor tries to load all resources used by the project, including the native binary. If it isn't present, the editor skips properties or signals associated with the missing NativeScripts in the scene. This will cause the scene tree to be non-functional for any sample that relies on properties or signals configured in the editor.

The /examples directory contains several ready to use examples, complete with Godot projects and setup for easy compilation from Cargo:

• hello_world - Your first project, writes to the console.
• spinning_cube - Spin our own node in place, exposing editor properties.
• scene_create - Load, instance and place scenes using Rust code.
• array_export - Export more complex properties (here arrays) from Rust.
• dodge_the_creeps - A Rust port of the little Godot game.
• signals - Connect and emit signals.
• resource - Create and use custom resources.
• rpc - Simple peer-to-peer networking.
• native_plugin - Create custom node plugins.

Third-party resources

See also (work-in-progress): Third-party projects in the book.

Tools and integrations

• godot-egui (setzer22, jacobsky) - combine the egui library with Godot
• ftw (macalimlim) - manage your godot-rust projects from the command line

Open-source games

• Action RPG (MacKarp) - this Godot tutorial ported to Rust.
• Air Combat (paytonrules) - this Godot tutorial ported to Rust.
• Simple single-player Blackjack (paytonrules)
• Pong (you-win)

Tutorials

• Step by step guide - Up and running with Rust and Godot: A basic setup

Contributing

See the contribution guidelines.

License

Any contribution intentionally submitted for inclusion in the work by you shall be licensed under the MIT license, without any additional terms or conditions.