Godot Rust

https://godot-rust.github.io/book
Admin
Godot Rust is a Rust binding for Godot 4 that enables developers to create games and applications...
Tokens:83,839
Snippets:623
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### ConnectBuilder example setups

Source: https://godot-rust.github.io/book/register/signals.html

Shows various ways to configure signal connections using the builder, including flags, receiver types (self, other, Gd), and sync connections. The builder methods must be called in the correct order (stages).

```rust
#![allow(unused)]
fn main() {
// Connect -> Self::log_event(&mut self, event: String)
signal.builder()
    .flags(ConnectFlags::DEFERRED | ConnectFlags::ONESHOT)
    .connect_self_mut(Self::log_event); // receive &mut self

// Connect -> Logger::log_event(&mut self, event: String)
signal.builder()
    .connect_other_mut(some_gd, Logger::log_event);

// Connect -> Logger::log_event(this: Gd<Self>, event: String)
signal.builder()
    .connect_other_gd(some_gd, Logger::log_event);

// Connect -> Logger::log_thread_safe(event: String)
signal.builder()
    .connect_sync(Logger::log_thread_safe); // associated fn, no receiver
}
```

--------------------------------

### Install Rust toolchain with rustup on Linux, Windows, and macOS

Source: https://godot-rust.github.io/book/intro/setup.html

Install the Rust toolchain via rustup on Linux, Windows, or macOS. rustup includes the compiler, standard library, Cargo, and tools like rustfmt and clippy.

```bash
# Linux (distro-independent)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows
winget install -e --id Rustlang.Rustup

# macOS
brew install rustup

```

--------------------------------

### Install nightly Rust toolchain, rust-src, and wasm32-unknown-emscripten target

Source: https://godot-rust.github.io/book/toolchain/export-web.html

Run these commands with rustup to install the nightly toolchain, add the rust-src component, and add the wasm32-unknown-emscripten target. Required because the build uses the unstable -Zbuild-std flag.

```bash
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly
rustup target add wasm32-unknown-emscripten --toolchain nightly
```

--------------------------------

### Manual Var implementation before (0.4)

Source: https://godot-rust.github.io/book/migrate/v0.5.html

An example manual Var implementation in v0.4, using get_property and set_property.

```rust
#![allow(unused)]
fn main() {
impl Var for MyType {
    fn get_property(&self) -> Self::Via {
        self.to_godot_owned()
    }
    fn set_property(&mut self, value: Self::Via) {
        *self = FromGodot::from_godot(value);
    }
}
}
```

--------------------------------

### Install Emscripten via emsdk (version 3.1.74)

Source: https://godot-rust.github.io/book/toolchain/export-web.html

Clone the emsdk repository, install and activate Emscripten 3.1.74 (recommended for Godot 4.3 or later), then source the environment script. On Linux use source ./emsdk_env.sh; on Windows run ./emsdk_env.bat. It is highly recommended to add emcc to PATH as instructed.

```bash
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 3.1.74
./emsdk activate 3.1.74

source ./emsdk_env.sh  # on Linux
run ./emsdk_env.bat    # on Windows
```

--------------------------------

### Install Godot 4 on Linux, Windows, and macOS

Source: https://godot-rust.github.io/book/intro/setup.html

Install Godot 4 on Linux, Windows, or macOS using the package manager for each platform. The commands assume Godot is available in PATH as `godot4` or via the `GODOT4_BIN` environment variable.

```bash
# --- Linux ---
# Fedora/RHEL.
dnf install godot

# Arch Linux.
pacman -Syu godot
paru -Syu godot

# Flatpak (e.g. Ubuntu, Debian, or distro-independent).
flatpak install flathub org.godotengine.Godot


# --- Windows ---
winget install -e --id GodotEngine.GodotEngine
choco install godot
scoop bucket add extras && scoop install godot


# --- macOS ---
brew install godot

```

--------------------------------

### Use Dictionary with at(), get(), and clone()

Source: https://godot-rust.github.io/book/godot-api/builtins.html

Demonstrates Dictionary's reference-counted behavior and by-value accessors: at() panics on missing keys, get() returns Option<Variant>, and clone() shares data so modifications affect the original.

```Rust
let c = vdict! {
    "str": "hello",
    "int": 42,
    "bool": true,
};

assert_eq!(c.len(), 3);
assert_eq!(c.at("str"), "hello".to_variant());    // Panics on missing key.
assert_eq!(c.get("int"), Some(42.to_variant()));  // Option<Variant>, again by value.

let mut d = c.clone();            // Increment reference-count.
d.insert("float", 3.14);          // Modify new ref.
assert!(c.contains_key("float")); // Original dict has changed.
```

--------------------------------

### Update .gdextension file for Android

Source: https://godot-rust.github.io/book/toolchain/export-android.html

Example of a .gdextension entry pointing to the compiled library for the arm64 architecture. Note the missing closing quote in the source.

```ini
android.debug.arm64="res://path/to/rust/lib/target/aarch64-linux-android/debug/{YourCrate}.so
```

--------------------------------

### Verify Rust installation with rustc --version

Source: https://godot-rust.github.io/book/intro/setup.html

Verify that rustup and the stable toolchain are working by checking the Rust compiler version. The output shows the expected format, with the version and build date.

```bash
$ rustc --version
rustc 1.88.0 (6b00bc388 2025-06-23)

```

--------------------------------

### Flat import statements example

Source: https://godot-rust.github.io/book/contribute/conventions.html

Shows preferred flat import style with separate lines for different prefixes, avoiding nested imports and `self`.

```rust
#![allow(unused)]
fn main() {
// Good:
use crate::module;
use crate::module::{Type, function};
use crate::module::nested::{Trait, some_macro};

// Bad:
use crate::module::{self, Type, function, nested::{Trait, some_macro}};
}

```

--------------------------------

### Minimal saver implementation with get_recognized_extensions

Source: https://godot-rust.github.io/book/recipes/resource-saver-loader.html

The minimal code for a saver, with all required virtual methods defined. This example overrides get_recognized_extensions to add a custom extension 'myextension'.

```rust
#![allow(unused)]
fn main() {
#[derive(GodotClass)]
#[class(base=ResourceFormatSaver, init, tool)]
struct MyAssetSaver {
    base: Base<ResourceFormatSaver>,
}

#[godot_api]
impl IResourceFormatSaver for MyAssetSaver {
    // If you want a custom extension name (e.g., resource.myextension), 
    // then override this.
    fn get_recognized_extensions(
        &self,
        res: Option<Gd<Resource>>
    ) -> PackedStringArray {
        let mut array = PackedStringArray::new();
        
        // It is also possible to add multiple extensions per Saver.
        array.push("myextension");
        array
    }
}
```

--------------------------------

### Project structure for Monster example

Source: https://godot-rust.github.io/book/register/virtual-functions.html

Shows the directory layout for a project using Rust and GDScript, with separate folders for Godot and Rust code. The Monster.tscn scene has a root node of the Rust class inheriting Node3D, to which scripts are attached.

```text
project_dir/
│
├── godot/
│   ├── .godot/
│   ├── project.godot
│   ├── MonsterGame.gdextension
│   └── Scenes
│       ├── Monster.tscn
│       ├── Orc.gd
│       └── Goblin.gd
│
└── rust/
    ├── Cargo.toml
    └── src/
        ├── lib.rs
        └── monster.rs

```

--------------------------------

### Register a basic custom Resource

Source: https://godot-rust.github.io/book/recipes/custom-resources.html

Defines a custom Resource type using #[derive(GodotClass)] with #[class(init, base=Resource)]. This is the minimal setup for a custom resource that does not export any variables.

```rust
#![allow(unused)]
fn main() {
#[derive(GodotClass)]
#[class(init, base=Resource)]
struct ResourceType {
    base: Base<Resource>,
}
}

```

--------------------------------

### Build for aarch64-linux-android

Source: https://godot-rust.github.io/book/toolchain/export-android.html

Complete example for compiling a godot-rust GDExtension for aarch64-linux-android. Assumes Android CLI in $HOME, NDK 23.2.8568313, CLI version 11076708_latest, Linux host, and Android version 34. Sets CLANG_PATH and CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER, then runs cargo build.

```bash
rustup target add aarch64-linux-android

export CLANG_PATH="$HOME/android-cli/11076708_latest/ndk/23.2.8568313/toolchains/llvm/prebuilt/linux-x86_64/bin/clang"
export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=\
"$HOME/android-cli/11076708_latest/ndk/23.2.8568313/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang"

cargo build --target=aarch64-linux-android
```

--------------------------------

### Create framework folder and copy dylib

Source: https://godot-rust.github.io/book/toolchain/export-mac-and-ios.html

Creates the .framework directory and copies the universal dylib into it.

```bash
mkdir target/release/lib{YourCrate}.macos.framework
cp target/release/lib{YourCrate}.macos.dylib \
    target/release/lib{YourCrate}.macos.framework/lib{YourCrate}.macos.dylib
```

--------------------------------

### After: Editor class with internal attribute

Source: https://godot-rust.github.io/book/migrate/v0.4.html

In godot-rust 0.4, classes with names starting with 'Editor' must be explicitly marked with the internal attribute to prevent accidental exposure in exported builds. This example shows the required change.

```rust
#![allow(unused)]
fn main() {
#[derive(GodotClass)]
#[class(base=EditorPlugin, internal)]
struct EditorMyPlugin {
    base: Base<EditorPlugin>,
}
}

```

--------------------------------

### Before: Editor class without internal attribute

Source: https://godot-rust.github.io/book/migrate/v0.4.html

In godot-rust 0.3, classes with names starting with 'Editor' were implicitly internal due to Godot's undocumented rule, which caused confusion. This example shows the old declaration.

```rust
#![allow(unused)]
fn main() {
#[derive(GodotClass)]
#[class(base=EditorPlugin)]
struct EditorMyPlugin {
    base: Base<EditorPlugin>,
}
}

```

--------------------------------

### Create .framework folder and copy dylib

Source: https://godot-rust.github.io/book/toolchain/export-mac-and-ios.html

Creates the .framework directory and copies the built .dylib into it, naming it with the .ios.framework suffix.

```bash
mkdir target/release/lib{YourCrate}.ios.framework
cp target/release/lib{YourCrate}.ios.dylib \
    target/release/lib{YourCrate}.ios.framework/lib{YourCrate}.ios.dylib
```

--------------------------------

### Example error output after compilation

Source: https://godot-rust.github.io/book/recipes/editor-plugin/inspector-plugins.html

Shows an example error that may occur after compilation, indicating that the class 'RandomInspectorPlugin' cannot be found. The troubleshooting advice is to restart the Godot Editor.

```text
Initialize godot-rust (API v4.2.stable.official, runtime v4.2.2.stable.official)
ERROR: Cannot get class 'RandomInspectorPlugin'.
   at: (core/object/class_db.cpp:392)
ERROR: Cannot get class 'RandomInspectorPlugin'.
   at: (core/object/class_db.cpp:392)
```

--------------------------------

### HelloWorld.gdextension configuration

Source: https://godot-rust.github.io/book/intro/hello-world.html

Defines the entry point, minimum Godot version, reloadability, and library paths for the Rust extension. The [configuration] section should be copied as-is; update [libraries] paths to match your compiled Rust libraries. The res:// prefix is relative to the Godot directory, and paths like .. are not supported for exports.

```ini
_
[configuration]
entry_symbol = "gdext_rust_init"
compatibility_minimum = 4.1
reloadable = true

[libraries]
linux.debug.x86_64 =     "res://../rust/target/debug/lib{YourCrate}.so"
linux.release.x86_64 =   "res://../rust/target/release/lib{YourCrate}.so"
windows.debug.x86_64 =   "res://../rust/target/debug/{YourCrate}.dll"
windows.release.x86_64 = "res://../rust/target/release/{YourCrate}.dll"
macos.debug =            "res://../rust/target/debug/lib{YourCrate}.dylib"
macos.release =          "res://../rust/target/release/lib{YourCrate}.dylib"
macos.debug.arm64 =      "res://../rust/target/debug/lib{YourCrate}.dylib"
macos.release.arm64 =    "res://../rust/target/release/lib{YourCrate}.dylib"

```

--------------------------------

### Use array!, varray!, and vdict! macros

Source: https://godot-rust.github.io/book/godot-api/builtins.html

Demonstrates constructing Array, VariantArray, and Dictionary using the array!, varray!, and vdict! macros respectively.

```Rust
let a = array![1, 2, 3];          // Array<i64>
let b = varray![1, "two", true];  // Array<Variant>
let c = vdict!{"key": "value"};   // Dictionary
```

--------------------------------

### Get enum variant name with godot_name() (v0.3)

Source: https://godot-rust.github.io/book/migrate/v0.4.html

The v0.3 pattern for getting an enum variant's Godot name uses godot_name(), which may return incorrect names if the enum has duplicate variants.

```rust
let name = MyEnum::Variant1.godot_name();
```

--------------------------------

### Array and Dictionary Construction

Source: https://godot-rust.github.io/book/godot-api/builtins.html

Shows how to construct `Array<T>`, `VariantArray`, and `Dictionary` using the `array!`, `varray!`, and `vdict!` macros.

```APIDOC
## Array and Dictionary Construction

### Description
Godot's linear collection type is `Array<T>`. It is generic over its element type `T`, which can be one of the supported Godot types (generally anything that can be represented by `Variant`). A special type `VariantArray` is provided as an alias for `Array<Variant>`, which is used when the element type is dynamically typed.
`Dictionary` is a key-value store, where both keys and values are `Variant`. Generic dictionaries are not currently supported in godot-rust.

### Construction Macros
Arrays and dictionaries can be constructed using three macros:

```rust
let a = array![1, 2, 3];          // Array<i64>
let b = varray![1, "two", true];  // Array<Variant>
let c = vdict!{"key": "value"};   // Dictionary
```
```

--------------------------------

### Create Resources folder

Source: https://godot-rust.github.io/book/toolchain/export-mac-and-ios.html

Creates the Resources folder inside the framework directory.

```bash
mkdir target/release/lib{YourCrate}.macos.framework/Resources
```

--------------------------------

### Create Info.plist for iOS framework

Source: https://godot-rust.github.io/book/toolchain/export-mac-and-ios.html

Provides the required Info.plist XML for the .framework bundle, including bundle identifier, executable name, and minimum iOS version.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleExecutable</key>
    <string>lib{YourCrate}.ios.dylib</string>
    <key>CFBundleName</key>
    <string>My App Name</string>
    <key>CFBundleDisplayName</key>
    <string>My App Name</string>
    <key>CFBundleIdentifier</key>
    <string>org.my-website.my-app</string>
    <key>NSHumanReadableCopyright</key>
    <string>Copyright (c) ...</string>
    <key>CFBundleVersion</key>
    <string>0.12.0</string>
    <key>CFBundleShortVersionString</key>
    <string>0.12.0</string>
    <key>CFBundlePackageType</key>
    <string>FMWK</string>
    <key>CSResourcesFileMapped</key>
    <true/>
    <key>DTPlatformName</key>
    <string>iphoneos</string>
    <key>MinimumOSVersion</key>
    <string>12.0</string>
</dict>
</plist>
```

--------------------------------

### Const-qualified method call before (0.4)

Source: https://godot-rust.github.io/book/migrate/v0.5.html

Example of calling get_unique_id() on a mutable binding in v0.4, which required &mut self.

```rust
#![allow(unused)]
fn main() {
let mut api: Gd<MultiplayerApi> = ...;
let id = api.get_unique_id(); // Required &mut self.
}
```

--------------------------------

### Recommended project directory structure

Source: https://godot-rust.github.io/book/intro/hello-world.html

Shows the recommended directory layout for a godot-rust project, with separate godot and rust directories. This structure is recommended for easier troubleshooting and to avoid issues with .gdignore.

```text
my-cool-project
├── godot
│   ├── project.godot
│   └── my-extension.gdextension
└── rust
    ├── Cargo.toml
    ├── src
    └── target
        └── debug
            └── (lib)?my_extension.(so|dll|dylib)
```

--------------------------------

### Run ci-sign-macos.ps1 script

Source: https://godot-rust.github.io/book/toolchain/export-mac-and-ios.html

Command to run the signing script with the framework path. Requires PowerShell installed on your Mac.

```powershell
ci-sign-macos.ps1 target/release/{YourCrate}.framework
```

--------------------------------

### Before: #[export(range = (radians))]

Source: https://godot-rust.github.io/book/migrate/v0.4.html

In godot-rust 0.3, the radians option was used, but it was deprecated in Godot itself. This example shows the old syntax.

```rust
#![allow(unused)]
fn main() {
#[export(range = (radians))]
angle: f32,
}

```

--------------------------------

### GDExtension entry point in lib.rs

Source: https://godot-rust.github.io/book/intro/hello-world.html

Replace the template in lib.rs with this code to define the GDExtension entry point. It imports the godot prelude, defines a struct MyExtension, and implements the ExtensionLibrary trait with the #[gdextension] attribute.

```rust
#![allow(unused)]
fn main() {
use godot::prelude::*;

struct MyExtension;

#[gdextension]
unsafe impl ExtensionLibrary for MyExtension {}
}
```

--------------------------------

### #[var] getter/setter semantics before (0.4)

Source: https://godot-rust.github.io/book/migrate/v0.5.html

Old behavior of #[var(get)] and #[var(set)] in v0.4, where they disabled the opposite accessor.

```rust
#![allow(unused)]
fn main() {
// Disabled setter, only getter:
#[var(get)]
my_field: i32,

// Disabled getter, only setter:
#[var(set)]
other_field: f32,
}
```

--------------------------------

### Run check.sh to mimic CI locally

Source: https://godot-rust.github.io/book/contribute/dev-tools.html

Run `./check.sh` from the project root to execute formatting, clippy, unit tests, and integration tests. Use `./check.sh --help` to see all available options.

```bash
./check.sh
```

--------------------------------

### AnyArray covariant typed/untyped array example

Source: https://godot-rust.github.io/book/migrate/v0.5.html

Shows how to use AnyArray with Deref coercion, explicit upcast, and downcast back to a typed array.

```rust
#![allow(unused)]
fn main() {
use godot::builtin::{Array, AnyArray, VarArray};

let typed: Array<i64> = array![1, 2, 3];

// Deref coercion: use typed array where AnyArray is expected.
let any_ref: &AnyArray = &typed;
assert_eq!(any_ref.len(), 3);

// Explicit upcast for owned values.
let any: AnyArray = typed.clone().upcast_any_array();

// Downcast back to typed.
let back: Array<i64> = any.try_cast_array::<i64>()
    .expect("convert back to typed");
}
```

--------------------------------

### Virtual method with raw pointer parameter (after renaming)

Source: https://godot-rust.github.io/book/migrate/v0.3.html

Example of the same virtual method after renaming to include the _rawptr suffix, as required in godot-rust 0.3.

```rust
#![allow(unused)]
fn main() {
trait IAudioStreamPlayback {
    unsafe fn mix_rawptr(&mut self, buffer: *mut AudioFrame, 
                         rate_scale: f32, frames: i32) -> i32;
}
}
```

--------------------------------

### Add web library paths to .gdextension file

Source: https://godot-rust.github.io/book/toolchain/export-web.html

Add web.debug.wasm32 and web.release.wasm32 entries under [libraries] in the .gdextension file, pointing to the compiled Wasm binaries in the target directory. Replace {YourCrate} with the actual crate name.

```ini
[libraries]
...
web.debug.wasm32 = "res://../rust/target/wasm32-unknown-emscripten/debug/{YourCrate}.wasm"
web.release.wasm32 = "res://../rust/target/wasm32-unknown-emscripten/release/{YourCrate}.wasm"
```

--------------------------------

### GFile::read_as_gstring_entire() before v0.5 (with skip_cr parameter)

Source: https://godot-rust.github.io/book/migrate/v0.5.html

Before v0.5, `GFile::read_as_gstring_entire()` required a `skip_cr` boolean parameter. This example shows the old call with `true`.

```rust
#![allow(unused)]
fn main() {
let text = gfile.read_as_gstring_entire(true)?;
}
```

--------------------------------

### Build library for both architectures

Source: https://godot-rust.github.io/book/toolchain/export-mac-and-ios.html

Builds the Rust library in release mode for x86_64 and arm64 Apple targets.

```bash
cargo build --target=x86_64-apple-darwin --release
cargo build --target=aarch64-apple-darwin --release
```

--------------------------------

### Run unit tests via check.sh

Source: https://godot-rust.github.io/book/contribute/dev-tools.html

Run unit tests (including doctests) using `./check.sh test`. This is the preferred way because additional flags may be needed.

```bash
./check.sh test
```

--------------------------------

### SimpleVar implementation after (0.5)

Source: https://godot-rust.github.io/book/migrate/v0.5.html

Using the new SimpleVar marker trait to get automatic Var implementation for types that support ToGodot + FromGodot + Clone.

```rust
#![allow(unused)]
fn main() {
// MyType: ToGodot + FromGodot + Clone.
impl SimpleVar for MyType {}
}
```

--------------------------------

### Dictionary set method before v0.5 (pass by value)

Source: https://godot-rust.github.io/book/migrate/v0.5.html

Before v0.5, Dictionary::set accepted values by value. This example shows passing a Godot object directly.

```rust
#![allow(unused)]
fn main() {
dict.set("hello", gd);
}
```

--------------------------------

### Connect Godot signals in ready()

Source: https://godot-rust.github.io/book/register/signals.html

Extend the ready() implementation to connect both user-defined and built-in signals, such as damage_taken and renamed, using the signal collection.

```rust
#![allow(unused)]
fn main() {
#[godot_api]
impl INode3D for Monster {
    fn ready(&mut self) {
        // Previous code.
        self.signals()
            .damage_taken()
            .connect_other(&*self.shield, Shield::on_damage_taken);

        // Connect to the `Node::renamed` signal, which is invoked
        // when a node name changes.
        self.signals()
            .renamed()
            .connect_self(|this| {
                let new_name = this.base().get_name();
                println!("Monster node renamed to {new_name}.");
            });
    }
}
}
```

--------------------------------

### Build the extension with cargo build

Source: https://godot-rust.github.io/book/intro/hello-world.html

Compile the extension using cargo. The output will be placed in {YourCrate}/target/debug/.

```bash
cargo build
```

--------------------------------

### Virtual method with raw pointer parameter (before renaming)

Source: https://godot-rust.github.io/book/migrate/v0.3.html

Example of a virtual method that uses a raw pointer in its parameter, before the addition of the _rawptr suffix in godot-rust 0.3.

```rust
#![allow(unused)]
fn main() {
trait IAudioStreamPlayback {
    unsafe fn mix(&mut self, buffer: *mut AudioFrame, 
                  rate_scale: f32, frames: i32) -> i32;
}
}
```
Tokens:
Raw