Expand description
Rust bindings for the Godot game engine
This crate contains high-level wrappers around the Godot game engine’s GDNative API. Some of the types were automatically generated from the engine’s JSON API description, and some other types are hand made wrappers around the core C types.
Core types
Wrappers for most core types expose safe Rust interfaces, and it’s unnecessary
to mind memory management most of the times. The exceptions are
VariantArray
and Dictionary
,
internally reference-counted collections with interior mutability in Rust parlance.
These types are modelled using the typestate pattern to enforce that the official
thread-safety guidelines. For more information, read the type-level
documentation for these types.
Since it is easy to expect containers and other types to allocate a copy of their
content when using the Clone
trait, some types do not implement Clone
and instead
implement NewRef
which provides a new_ref(&self) -> Self
method
to create references to the same collection or object.
Generated API types
The api
module contains high-level wrappers for all the API types generated from a
JSON description of the API. The generated types are tied to a specific version, typically
the latest Godot 3.x release (at the time of the godot-rust release).
If you want to use the bindings with another version of the engine, read the notes on
the custom-godot
feature flag below.
Memory management
API types may be reference-counted or manually-managed. This is indicated by the
RefCounted
and ManuallyManaged
marker traits.
The API types can exist in three reference forms: bare, TRef
and Ref
.
Bare references to API types, like &'a Node
, represent valid and safe references to Godot objects.
As such, API methods may be called safely on them. TRef
adds typestate tracking, which
enable additional abilities like being able to be passed to the engine. Ref
, or
persistent references, have 'static
lifetime, but are not always safe to use. For more
information on how to use persistent references safely, see the object
module documentation
or the corresponding book chapter.
Feature flags
All features are disabled by default.
Functionality toggles:
-
async
Activates async functionality, seetasks
module for details. -
serde
Enable forserde
support of several core types. See alsoVariant
. -
inventory
Enables automatic class registration viainventory
.Attention: Automatic registration is unsupported on some platforms, notably WASM.
inventory
can still be used for iterative development if such platforms are targeted, in which case the run-time diagnosticinit::diagnostics::missing_manual_registration
may be helpful.Please refer to the
rust-ctor
README for an up-to-date listing of platforms that do support automatic registration.
Bindings generation:
-
custom-godot
When active, tries to locate a Godot executable on your system, in this order:- If a
GODOT_BIN
environment variable is defined, it will interpret it as a path to the binary (not directory). - An executable called
godot
, accessible in your system’s PATH, is used. - If neither of the above is found, an error is generated.
The symbols in
api
will be generated in a way compatible with that engine version. This allows to use Godot versions older than the currently supported ones.See Custom Godot builds for detailed instructions.
- If a
-
formatted
Enable if the generated binding source code should be human-readable and split into multiple files. This can also help IDEs that struggle with a single huge file. -
ptrcall
Enables theptrcall
convention for calling Godot API methods. This increases performance, at the cost of forward binary compatibility with the engine. Binaries built withptrcall
enabled may exhibit undefined behavior when loaded by a different version of Godot, even when there are no breaking API changes as far as GDScript is concerned. Notably, the addition of new default parameters breaks any code usingptrcall
.Cargo features are additive, and as such, it’s only necessary to enable this feature for the final
cdylib
crates, whenever desired.
Modules
- Bindings for the Godot Class API.
- Types that represent core types of Godot.
- Functionality for user-defined types exported to the engine (native scripts).
- Port of selected GDScript built-in functions.
- Global initialization and termination of the library.
- Functions for using the engine’s logging system in the editor.
- Provides types to interact with the Godot
Object
class hierarchy - Curated re-exports of common items.
- Interface to Godot’s built-in profiler.
- Runtime async support for godot-rust.
Macros
- Prints and returns the value of a given expression for quick and dirty debugging, using the engine’s logging system (visible in the editor).
- Print an error using the engine’s logging system (visible in the editor).
- Print a message using the engine’s logging system (visible in the editor).
- Creates a
Site
value from the current position in code, optionally with a function path for identification.