Crate godot

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.

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 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.

  By default, Wasm threads are enabled and require the flag "-C", "link-args=-sUSE_PTHREADS=1" 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 feature experimental-wasm-nothreads.
  
  

• 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=-sUSE_PTHREADS=1" flag in the wasm32-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.

Modules

• __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.
• meta
  Meta-information about Godot types, their properties and conversions between them.
• obj
  Types and traits related to objects.
• prelude
  Often-imported symbols.
• register
  Register/export Rust symbols to Godot: classes, methods, enums…
• tools
  Higher-level additions to the Godot engine API.