Expand description
§Rust bindings for Godot 4
The gdext library implements Rust bindings for the Godot engine, more precisely its version 4. It does so using the GDExtension API, a C interface to integrate third-party language bindings with the engine.
This API doc is accompanied by the book, which provides tutorials that guide you along the way.
An overview of fundamental types and concepts can be found on this page.
§Module organization
The contains generated code, which is derived from the GDExtension API specification. This code spans the official Godot API and is mostly the same as the API you would use in GDScript.
The Godot API is divided into several modules:
builtin
: Built-in types, such asVector2
,Color
, andString
.classes
: Godot classes, such asNode
,RefCounted
orResource
.global
: Global functions and enums, such asgodot_print!
,smoothstep
orJoyAxis
.
In addition to generated code, we provide a framework that allows you to easily interface the Godot engine. Noteworthy modules in this context are:
register
, used to register your own Rust symbols (classes, methods, constants etc.) with Godot.obj
, everything related to handling Godot objects, such as theGd<T>
type.tools
, higher-level utilities that extend the generated code, e.g.load<T>()
.
The prelude
contains often-imported symbols; feel free to use godot::prelude::*
in your code.
§Public API
Some symbols in the API are not intended for users, however Rust’s visibility feature is not strong enough to express that in all cases (for example, proc-macros and separated crates may need access to internals).
The following API symbols are considered private:
- Symbols annotated with
#[doc(hidden)]
. - Any of the dependency crates (crate
godot
is the only public interface). - Modules named
private
and all their contents.
This means there are no guarantees regarding API stability, robustness or correctness. Problems arising from using private APIs are
not considered bugs, and anything relying on them may stop working without announcement. Please refrain from using undocumented and
private features; if you are missing certain functionality, bring it up for discussion instead. This allows us to improve the library!
§Cargo features
The following features can be enabled for this crate. All off them are off by default.
Avoid default-features = false
unless you know exactly what you are doing; it will disable some required internal features.
Godot version and configuration:
-
api-4-{minor}
-
api-4-{minor}-{patch}
-
api-custom
Sets the API level to the specified Godot version, or a custom-built local binary. You can use at most one
api-*
feature. If absent, the current Godot minor version is used, with patch level 0. -
double-precision
Use
f64
instead off32
for the floating-point typereal
. Requires Godot to be compiled with the scons flagprecision=double
. -
experimental-godot-api
Access to
godot::classes
APIs that Godot marks “experimental”. These are under heavy development and may change at any time. If you opt in to this feature, expect breaking changes at compile and runtime.
Rust functionality toggles:
-
lazy-function-tables
Instead of loading all engine function pointers at startup, load them lazily on first use. This reduces startup time and RAM usage, but incurs additional overhead in each FFI call. Also, you lose the guarantee that once the library has booted, all function pointers are truly available. Function calls may thus panic only at runtime, possibly in deeply nested code paths. This feature is not yet thread-safe and can thus not be combined with
experimental-threads
. -
experimental-threads
Experimental threading support. This enables
Send
/Sync
traits forGd<T>
and makes the guard typesGd
/GdMut
aware of multithreaded references. The safety aspects are not ironed out yet; there is a high risk of unsoundness at the moment. As this evolves, it is very likely that the API becomes stricter. -
experimental-wasm
Support for WebAssembly exports is still a work-in-progress and is not yet well tested. This feature is in place for users to explicitly opt in to any instabilities or rough edges that may result. Due to a limitation in Godot, it might currently not work Firefox browser.
-
codegen-rustfmt
Use rustfmt to format generated binding code. Because rustfmt is so slow, this is detrimental to initial compile time. Without it, we use a lightweight and fast custom formatter to enable basic human readability.
-
register-docs
Generates documentation for your structs from your Rust documentation. Documentation is visible in Godot via
F1
-> searching for that class. This feature requires at least Godot 4.3. See also:#[derive(GodotClass)]
Integrations:
-
serde
Implement the serde traits
Serialize
andDeserialize
traits for certain built-in types. The serialized representation underlies no stability guarantees and may change at any time, even without a SemVer-breaking change.
Modules§
- Extended documentation
- Built-in types like
Vector2
,GString
andVariant
. - Maps the Godot class API to Rust.
- Godot global enums, constants and utility functions.
- Entry point and global init/shutdown of the library.
- Meta-information about variant types, properties and class names.
- Types and traits related to objects.
- Often-imported symbols.
- Register/export Rust symbols to Godot: classes, methods, enums…
- Higher-level additions to the Godot engine API.