gdext

Rust bindings for Godot 4

4,416

279

4,416

Quick Overview

Godot-rust/gdext is a Rust binding for the Godot game engine, allowing developers to write Godot games and tools in Rust. It provides a high-level API for interacting with Godot's features and functionality, enabling the use of Rust's safety and performance benefits in Godot game development.

Pros

Combines Rust's safety and performance with Godot's powerful game development features
Provides a high-level, idiomatic Rust API for Godot
Supports automatic code generation for Godot classes and methods
Offers seamless integration with Godot's editor and export system

Cons

Requires knowledge of both Rust and Godot, which may increase the learning curve
May have limitations compared to GDScript for certain Godot-specific features
Documentation and community support might be less extensive than GDScript or C#
Potential performance overhead due to language interop in some cases

Code Examples

Registering a custom class:

#[derive(GodotClass)]
#[class(base=Node)]
struct Player {
    #[base]
    base: Base<Node>,
    speed: f32,
}

#[godot_api]
impl INode for Player {
    fn init(base: Base<Node>) -> Self {
        Self { base, speed: 100.0 }
    }
}

Implementing a custom method:

#[godot_api]
impl Player {
    #[func]
    fn move_player(&mut self, delta: f64) {
        let input = Input::singleton();
        let mut velocity = Vector2::ZERO;
        
        if input.is_action_pressed("move_right".into()) {
            velocity.x += 1.0;
        }
        if input.is_action_pressed("move_left".into()) {
            velocity.x -= 1.0;
        }
        
        self.base_mut().translate(velocity * self.speed * delta as f32);
    }
}

Connecting a signal:

#[godot_api]
impl Player {
    #[func]
    fn _ready(&mut self) {
        let timer = self.base().get_node("Timer").unwrap().cast::<Timer>();
        timer.connect("timeout".into(), self.base().callable("on_timer_timeout"));
    }

    #[func]
    fn on_timer_timeout(&mut self) {
        godot_print!("Timer timed out!");
    }
}

Getting Started

Install Rust and Cargo
Install Godot 4.x
Create a new Godot project
Add the following to your Cargo.toml:

[dependencies]
godot = { git = "https://github.com/godot-rust/gdext", branch = "master" }

Create a lib.rs file in your src directory with:

use godot::prelude::*;

struct MyExtension;

#[gdextension]
unsafe impl ExtensionLibrary for MyExtension {}

Compile your Rust code and link it with Godot

For detailed instructions, refer to the official godot-rust/gdext documentation.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Rust bindings for Godot 4

godot-rust is a library to integrate the Rust language with Godot 4.

Godot is an open-source game engine, focusing on a productive and batteries-included 2D and 3D experience.
Its GDExtension API allows integrating third-party languages and libraries.

Philosophy

The Rust binding is an alternative to GDScript, with a focus on type safety, scalability and performance.

The primary goal of godot-rust is to provide a pragmatic Rust API for game developers.

Recurring workflows should be simple and require minimal boilerplate. APIs are designed to be safe and idiomatic Rust wherever possible. Due to interacting with Godot as a C++ engine, we sometimes follow unconventional approaches to provide a good user experience.

Motivating example

The following Rust snippet registers a Godot class Player, showcasing features such as inheritance, field initialization and signals.

use godot::classes::{ISprite2D, ProgressBar, Sprite2D};
use godot::prelude::*;

// Declare the Player class inheriting Sprite2D.
#[derive(GodotClass)]
#[class(init, base=Sprite2D)] // Automatic initialization, no manual init() needed.
struct Player {
    // Inheritance via composition: access to Sprite2D methods.
    base: Base<Sprite2D>,

    // #[class(init)] above allows attribute-initialization of fields.
    #[init(val = 100)]
    hitpoints: i32,

    // Access to a child node, auto-initialized when _ready() is called.
    #[init(node = "Ui/HealthBar")] // <- Path to the node in the scene tree.
    health_bar: OnReady<Gd<ProgressBar>>,
}

// Implement Godot's virtual methods via predefined trait.
#[godot_api]
impl ISprite2D for Player {
    // Override the `_ready` method.
    fn ready(&mut self) {
        godot_print!("Player ready!");

        // Health bar is already initialized and straightforward to access.
        self.health_bar.set_max(self.hitpoints as f64);
        self.health_bar.set_value(self.hitpoints as f64);

        // Connect type-safe signal: print whenever the health bar is updated.
        self.health_bar.signals().value_changed().connect(|hp| {
            godot_print!("Health changed to: {hp}");
        });
    }
}

// Implement custom methods that can be called from GDScript.
#[godot_api]
impl Player {
    #[func]
    fn take_damage(&mut self, damage: i32) {
        self.hitpoints -= damage;
        godot_print!("Player hit! HP left: {}", self.hitpoints);

        // Update health bar.
        self.health_bar.set_value(self.hitpoints as f64);

        // Call Node methods on self, via mutable base access.
        if self.hitpoints <= 0 {
            self.base_mut().queue_free();
        }
    }
}

Development status

The library has evolved a lot since 2023 and is now in a usable state for projects such as games, editor plugins, tools and other applications based on Godot. See ecosystem to get an idea of what users have built with godot-rust.

Keep in mind that we occasionally introduce breaking changes, motivated by improved user experience or upstream changes. These are usually minor and accompanied by migration guides. Our crates.io releases adhere to SemVer, but lag a bit behind the master branch. See also API stability in the book.

The vast majority of Godot APIs have been mapped to Rust. The current focus lies on a more natural Rust experience and enable more design patterns that come in handy for day-to-day game development. To counter bugs, we use an elaborate CI suite including clippy, unit tests, engine integration tests and memory sanitizers. Even hot-reload is tested!

At the moment, there is experimental support for Wasm, Android and iOS, but documentation and tooling is still lacking. Contributions are very welcome!

Getting started

The best place to start is the godot-rust book. Use it in conjunction with our API Docs.
We also provide practical examples and small games in the demo-projects repository.

If you need help, join our Discord server and ask in the #help channel!

License

We use the Mozilla Public License 2.0. MPL tries to find a balance between permissive (MIT, Apache, Zlib) and copyleft licenses (GPL, LGPL).

The license provides a lot of freedom: you can use the library commercially and keep your own code closed-source, i.e. game development is not restricted. The main condition is that if you change godot-rust itself, you need to make those changes available (and only those, no surrounding code).

Contributing

Contributions are very welcome! If you want to help out, see Contributing.md for some pointers on getting started.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot