Crate godot

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 as Vector2, Color, and String.
classes: Godot classes, such as Node, RefCounted or Resource.
global: Global functions and enums, such as godot_print!, smoothstep or JoyAxis.

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 the Gd<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 of f32 for the floating-point type real. Requires Godot to be compiled with the scons flag precision=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 for Gd<T> and makes the guard types Gd/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.

Integrations:

serde

Implement the serde traits Serialize and Deserialize 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§