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.

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, see tasks module for details.

• serde
  Enable for serde support of several core types. See also Variant.

• inventory
  Enables automatic class registration via inventory.

  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 diagnostic init::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:

  1. If a GODOT_BIN environment variable is defined, it will interpret it as a path to the binary (not directory).
  2. An executable called godot, accessible in your system’s PATH, is used.
  3. 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.

• 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 the ptrcall convention for calling Godot API methods. This increases performance, at the cost of forward binary compatibility with the engine. Binaries built with ptrcall 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 using ptrcall.

  Cargo features are additive, and as such, it’s only necessary to enable this feature for the final cdylib crates, whenever desired.

Modules

• api
  Bindings for the Godot Class API.
• core_types
  Types that represent core types of Godot.
• derive
• export
  Functionality for user-defined types exported to the engine (native scripts).
• globalscope
  Port of selected GDScript built-in functions.
• init
  Global initialization and termination of the library.
• log
  Functions for using the engine’s logging system in the editor.
• object
  Provides types to interact with the Godot Object class hierarchy
• prelude
  Curated re-exports of common items.
• profiler
  Interface to Godot’s built-in profiler.
• tasks
  Runtime async support for godot-rust.

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_print
  Print a message using the engine’s logging system (visible in the editor).
• godot_site
  Creates a Site value from the current position in code, optionally with a function path for identification.