godot - Rust (original) (raw)

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>().
meta, fundamental information about types, properties and conversions.
init, entry point and global library configuration.
task, integration with async code.

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 of 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 adds synchronization to access the user instance in Gd<T> and disables several single-thread checks. 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.
Please read Export to Web in the book.
By default, Wasm threads are enabled and require the flag "-C", "link-args=-pthread" in the wasm32-unknown-unknown target. This must be kept in sync with Godot’s Web export settings (threading support enabled). To disable it, use *additionally the featureexperimental-wasm-nothreads.
It is recommended to use this feature in combination with lazy-function-tables to reduce the size of the generated Wasm binary.
experimental-wasm-nothreads
Requires the experimental-wasm feature. Disables threading support for WebAssembly exports. This needs to be kept in sync with Godot’s Web export setting (threading support disabled), and must not use the "-C", "link-args=-pthread" flag in thewasm32-unknown-unknown target.
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 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.

__docs

Extended documentation

builtin

Built-in types like Vector2, GString and Variant.

classes

Maps the Godot class API to Rust.

global

Godot global enums, constants and utility functions.

init

Entry point and global init/shutdown of the library.