[−][src]Crate gdnative

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.

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 `Option`. You may create `Null`s with `Null::null` or `GodotObject::null`.
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. `TRef` can be coerced into bare references with `Deref`.

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
OwnedToVariant
ToVariant