Crate godot

Crate godot 

Source
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

  • api-custom-json

    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.

    api-custom feature requires specifying GODOT4_BIN environment variable with a path to your Godot4 binary.

    The api-custom-json feature requires specifying GODOT4_GDEXTENSION_JSON environment variable with a path to your custom-defined extension_api.json.

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

  • experimental-required-objs

    Enables required objects in Godot function signatures. When GDExtension advertises parameters or return value as required (non-null), the generated code will use Gd<T> instead of Option<Gd<T>> for type safety. This will undergo many breaking changes as the API evolves; we are explicitly excluding this from any SemVer guarantees. Needs Godot 4.6-dev. See https://github.com/godot-rust/gdext/pull/1383.

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 feature experimental-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 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…
task
Integrates async rust code with the engine.
tools
Higher-level additions to the Godot engine API.