Introduction

The 0.9.0 release consists of a massive redesign of the godot-rust API in order to solve long-standing soundness problems in the old API, that cannot be easily fixed without changing the internals significantly and breaking compatibility. The result is an interface that abstracts Godot behavior much closer, improving users' abilities to build abstractions that push unsafe actions towards the interface, and guarantee safety in internal code.

Beside soundness, there has also been quality-of-life improvements. For example, the trait system is now used to drastically reduce conversion boilerplate when using generated API methods. Procedural macros are also constantly improved, becoming more flexible over time, and able to report errors more accurately.

Due to the redesign, 0.9.0 contains numerous breaking changes from previous versions. To help users update their code, we have created a migration guide from godot-rust 0.8.x in the user guide.

This release is made from tag 0.9.0, commit a370645.

Known issues

There are a few known issues in this version, which we're looking to fix as soon as possible.

• Users on case-insensitive systems may get wrong/missing generated documentation, or git warnings when checking out the source. (#597). Usage is not affected.
• Users may get type mismatch errors when building the bindings for Android, likely due to platform ABI differences. (#571).

Changelog

Added

• All public functions now have the #[inline] attribute, improving cross-crate inlining in builds without LTO.

• A curated prelude module is added in gdnative crate, containing common types and traits.

• Added the SubClass trait, which allows for static up-casts and static validation of downcasts.

• Added the OwnedToVariant trait and derive macro which enabled Variant conversion for more types.

• The NativeScript and #[methods] proc-macros now report errors more accurately.

• Added the godot_init convenience macro that declares all three endpoints for common use cases.

• Added more extension methods for Vector2, Vector3 and Color.

• Added wrappers for GodotString::get_basename and get_extensions.

• Added a high-level interface to the Godot script profiler in the gdnative::nativescript::profiling module, and in the #[gdnative::profiled] attribute.

• Added before/after hooks for the #[property] attribute.

• API methods now have generated documentation according to Godot documentation XMLs. The Godot docs contain custom markup which isn't currently parsed. We expect to improve the generated docs in the following releases.

• Added custom resource example.

Changed

• The default API version is now Godot 3.2.3-stable.

• The object reference system is revamped using the typestate pattern, with semantics that model Godot behavior more accurately, allowing for clearer boundaries between safe and unsafe code.

• API methods are now generic over types that can be converted to Variant, GodotString, or generated API types, removing the need for boilerplate code like &thing.into().

• Enums in the API are now represented more accurately as newtypes around i64. They are available in the same modules where their associated objects are defined.

• Dictionary and VariantArray now use the typestate pattern as well.

• The typed arrays are unified into a generic TypedArray type. The old names remain as type aliases.

• Moved generated bindings into the gdnative::api module, making the top-level namespace easier to navigate.

• It's now possible to crate custom binding crates without forking the repository using the generator, since gdnative_bindings_generator::Api::new now takes JSON input as an argument.

• Separated core wrappers and NativeScript support into the core_types and nativescript modules.

• Cleaned up the public interface with regards to intended usage. The public API no longer uses gdnative-sys types.

• The new_ref method is now in a NewRef trait.

• High-level wrappers are added for godot_gdnative_init and godot_gdnative_terminate callback arguments.

• Improved source links on docs.rs.

• bindgen is updated to 0.55.1.

• euclid is updated to 0.22.1.

• Improved build time performance.

Removed

• Removed deprecated items from the public interface in 0.8.1.

• Removed gdnative-sys types from the public interface. gdnative-sys is considered an internal dependency starting from 0.9.

• Removed the Object and Reference wrappers from gdnative-core. The same types are available in gdnative-bindings.

• Removed generated bindings for virtual methods, since they cannot actually be called.

• Removed From implementations for Variant since ToVariant is much more comprehensive.

Fixed

• Fixed typos in variant names of VariantOperator and GodotError.

• StringName::from_str now returns Self correctly.

• Fixed a case of undefined behavior that may manifest as crashes when some specific methods that return VariantArray are called.

• Fixed an issue with platform headers when building on Windows with the gnu toolchain that prevented compilation.

• Macros can now be used with qualified imports, removing the need for #[macro_use].

• Fixed an issue where Rid arguments passed to API methods are incorrect due to use-after-free.