repository·master·Indexed 26 days ago
https://github.com/godot-rust/gdextRust bindings for Godot 4 (version 0.5.4) using the GDExtension API. It provides a type-safe, high-performance alternative to GDScript for games, editor plugins, and Godot-based applications. Key features include the #[derive(GodotClass)] attribute for defining Godot classes in Rust, support for virtual methods via traits, and thread-safe object access using GdCellBlocking.
To begin using godot-rust, refer to the following resources:
If you encounter issues, you can join the community Discord and ask questions in the #help channel.
To create a Godot class, use the #[derive(GodotClass)] attribute on a struct. You can specify inheritance using the #[class(base=BaseClassName)] attribute and enable automatic initialization with #[class(init)].
Key features include:
base: Base<BaseClassName> field.#[init(val = value)] to set default values for fields.#[init(node = "path/to/node")] with an OnReady<Gd<T>> type to automatically fetch a child node when _ready() is called.ISprite2D) and marking the implementation with #[godot_api].#[func] attribute on methods within an #[godot_api] implementation block to make them callable from GDScript.use godot::classes::{ISprite2D, ProgressBar, Sprite2D};
use godot::prelude::*;
// Declare the Player class inheriting Sprite2D.
#[derive(GodotClass)]
#[class(init, base=Sprite2D)]
struct Player {
base: Base<Sprite2D>,
#[init(val = 100)]
hitpoints: i32,
#[init(node = "Ui/HealthBar")]
health_bar: OnReady<Gd<ProgressBar>>,
}
#[godot_api]
impl ISprite2D for Player {
fn ready(&mut self) {
godot_print!("Player ready!");
self.health_bar.set_max(self.hitpoints as f64);
self.health_bar.set_value(self.hitpoints as f64);
self.health_bar.signals().value_changed().connect(|hp| {
godot_print!("Health changed to: {hp}");
});
}
}
#[godot_api]
impl Player {
#[func]
fn take_damage(&mut self, damage: i32) {
self.hitpoints -= damage;
godot_print!("Player hit! HP left: {}", self.hitpoints);
self.health_bar.set_value(self.hitpoints as f64);
if self.hitpoints <= 0 {
self.base_mut().queue_free();
}
}
}godot-bindings crate is an internal crate of godot-rust. Do not depend on this crate directly. Instead, use the godot crate for your development. No SemVer or other guarantees are provided for godot-bindings.If your crate depends on other GDExtension libraries, you must specify the main extension implementor using the GDRUST_MAIN_EXTENSION environment variable during build. This ensures all classes are loaded and callbacks are managed correctly.
Example build command:
GDRUST_MAIN_EXTENSION="MyExtension" cargo buildRequirements for dependencies:
rlib. In their Cargo.toml, they should have crate-type = ["cdylib", "rlib"] or no [lib] section at all.ExtensionLibrary implementor must be unique across your workspace and its dependencies.godot-core crate is an internal crate used by the gdext library. It does not provide SemVer or other stability guarantees. End-users should depend on the godot crate for all development to ensure API stability and access to the intended public surface.When defining a Godot class using #[derive(GodotClass)], you can expose struct fields to the Godot engine using the #[var] and #[export] attributes.
#[var]: Registers a field as a Godot property. You can specify custom getters, setters, renaming, and property hints.#[export]: A shorthand that automatically registers a field as an exported property in the Godot Inspector. If used without #[var], it infers the necessary property registration.Properties can be organized into groups and subgroups using the group/subgroup metadata provided by the attributes.
Every GDExtension Rust library must implement the ExtensionLibrary trait. This trait serves as the entry point for your extension, handling initialization, deinitialization, and lifecycle hooks. You must use the #[gdextension] proc-macro attribute on your implementation.
By default, gdext automatically registers all classes marked with #[derive(GodotClass)] and handles necessary setup.
use godot::init::*;
struct MyExtension;
#[gdextension]
unsafe impl ExtensionLibrary for MyExtension {}If your .gdextension file specifies a custom entry_symbol in the [configuration] section, you must specify it in the attribute:
#[gdextension(entry_symbol = custom_name)]
unsafe impl ExtensionLibrary for MyExtension {}To simplify your imports, you can use the prelude which contains frequently used symbols:
use godot::prelude::*;You can define Godot Remote Procedure Call (RPC) methods in Rust using the #[rpc] attribute. This attribute allows you to specify how the method is called across the network.
There are two ways to configure an RPC:
You can pass individual configuration parameters directly into the attribute:
#[rpc(rpc_mode, transfer_mode, call_local, channel = N)]
rpc_mode: Use RpcMode::AnyPeer or RpcMode::Authority.transfer_mode: Use TransferMode::Reliable, TransferMode::Unreliable, or TransferMode::UnreliableOrdered.call_local: A boolean indicating if the method should be called on the local instance.channel: A u32 specifying the network channel.You can pass a pre-defined RpcConfig object using the config key:
#[rpc(config = RPC_CFG)]
You can control how the extension API and GDExtension interface are loaded by enabling specific Cargo features in your Cargo.toml:
api-custom: Regenerates all files by locating the Godot executable and reading its version and JSON files.api-custom-json: Generates files based on user-provided JSON files.When using these features, the following functions become available to load the necessary metadata:
load_extension_api_json(watch: &mut StopWatch) -> Cow<'static, str>load_gdextension_interface_json(watch: &mut StopWatch) -> Cow<'static, str>To target WebAssembly, you must explicitly opt-in using the experimental-wasm feature.
wasm32-unknown-unknown target to be compiled with "-C", "link-args=-pthread". This must match Godot's Web export threading settings.experimental-wasm-nothreads feature (which requires experimental-wasm). This must be kept in sync with Godot's Web export setting (threading disabled) and should not use the -pthread link argument.