Migrating to v0.2

This chapter will guide you through the changes from godot-rust version 0.1 to 0.2. See also our November dev update for a feature overview, and our changelog for a detailed list of modifications. Breaking changes are marked as such in the changelog, and you can navigate to the respective PRs to get in-depth information.

Godot version support

With godot-rust 0.2, Godot 4.3 is supported out of the box.

Godot 4.0 is no longer supported. We're the last binding to abandon it, after 1.5 years. 4.0 offers no compatibility with today's GDExtension API, not even among patch versions, so using it at this point is not recommended.

Argument passing

The biggest breaking change in 0.2 is the way arguments are passed to Godot APIs. What used to be pass-by-value everywhere, has now more nuance, while making calling code more concise.

The following table goes into different kinds of arguments and corresponding call expressions.

Argument typeParameter type (v0.1 ⇾ v0.2)v0.1 callv0.2 call
i32 (Copy)i32func(i)func(i)
GStringGString ⇾ impl AsArg<GString>func(s)
func(s.clone())		func(&s)
&str"func("str".into())func("str")
String"func(s.into())func(&s)
StringName
NodePath		"func(s.into())func(s.arg())
Gd<Node>Gd<Node> ⇾ impl AsObjectArg<Node>func(g.clone())func(&g)
Gd<Node2D>"func(g.clone().upcast())func(&g)

Most of them are straightforward, noteworthy is maybe arg() as a way to convert between the 3 Godot string types. This conversion is done explicitly, because it's much less obvious than conversion from String/&str but can have significant performance implications due to allocations, re-encoding and synchronization overhead. It also makes you more aware of the string type in use.

Removed APIs

See also #808. Noteworthy changes:

  • Renamed crate feature custom-godot ⇾ api-custom.
  • Godot enums now use SHOUT_CASE enumerators. PascalCase aliases have been around for some time, but not anymore.
  • GString::chars_checked() and GString::chars_unchecked() have been removed. There's no more need for unsafety; use GString::chars() instead.
  • Several collection methods have been migrated, e.g. Dictionary::try_get() ⇾ get(), Packed*Array::set() ⇾ [].
  • Removed ancient pre-0.1 modules godot::engine, godot::log.
  • The #[base] attribute is no longer allowed.

Miscellaneous

  • Some use cases now require a Base<T> field that wasn't previously needed, e.g. OnReady<T>.
  • Virtual functions that are semantically required by Godot are now also required in the I* interface trait in Rust. That is, you must override them in your impl block.
  • There are new validations around Export and #[class(tool)], which no longer accept previously compiling (but broken) code.