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 ingdnative
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 enabledVariant
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
andColor
. -
Added wrappers for
GodotString::get_basename
andget_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
andVariantArray
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
andnativescript
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 aNewRef
trait. -
High-level wrappers are added for
godot_gdnative_init
andgodot_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
andReference
wrappers fromgdnative-core
. The same types are available ingdnative-bindings
. -
Removed generated bindings for virtual methods, since they cannot actually be called.
-
Removed
From
implementations forVariant
sinceToVariant
is much more comprehensive.
Fixed
-
Fixed typos in variant names of
VariantOperator
andGodotError
. -
StringName::from_str
now returnsSelf
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.