Crate gdnative[−][src]
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.
Memory management for 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, which
is currently 3.2.3-stable
for the crates.io version. If you want to use the bindings
with another version of the engine, see the instructions here on
generating custom bindings.
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 type-level documentation
on Ref
.
Feature flags
bindings
Enabled by default. Includes the crates.io version of the bindings in the api
module.
Modules
api | Bindings for the Godot Class API. |
core_types | Types that represent core-datatypes of Godot. |
nativescript | Types and functions related to the NativeScript extension of GDNative. |
object | |
prelude | Curated re-exports of common items. |
ref_kind | Marker types to express the memory management method of Godot types. |
thread_access | Typestates to express thread safety of Godot types. |
Macros
godot_dbg | Prints and returns the value of a given expression for quick and dirty debugging, using the engine's logging system (visible in the editor). |
godot_error | Print an error using the engine's logging system (visible in the editor). |
godot_gdnative_init | Declare the API endpoint to initialize the gdnative API on startup. |
godot_gdnative_terminate | Declare the API endpoint invoked during shutdown. |
godot_init | Declare all the API endpoints necessary to initialize a NativeScript library. |
godot_nativescript_init | Declare the API endpoint to initialize nativescript classes on startup. |
godot_print | Print a message using the engine's logging system (visible in the editor). |
godot_warn | Print a warning using the engine's logging system (visible in the editor). |
godot_wrap_method | Convenience macro to wrap an object's method into a function pointer that can be passed to the engine when registering a class. |
Structs
Null | Represents an explicit null reference in method arguments. This works around type inference
issues with |
Ref | A polymorphic smart pointer for Godot objects whose behavior changes depending on the memory management method of the underlying type and the thread access status. |
TRef | A temporary safe pointer to Godot objects that tracks thread access status. |
Traits
GodotObject | Trait for Godot API objects. This trait is sealed, and implemented for generated wrapper types. |
NewRef | A trait for incrementing the reference count to a Godot object. |
Type Definitions
GodotResult |
Attribute Macros
methods | |
profiled | Makes a function profiled in Godot's built-in profiler. This macro automatically creates a tag using the name of the current module and the function by default. |
Derive Macros
FromVariant | |
NativeClass | Makes it possible to use a type as a NativeScript. |
OwnedToVariant | |
ToVariant |