Migrating to v0.3

This chapter will guide you through the changes from godot-rust version 0.2 to 0.3. See also our May 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.

cargo update -p godot

cargo upgrade -p godot

Geometric APIs

Several geometric APIs have seen slight updates in terms of naming and semantics.

• Aabb, Rect2, Rect2i (#1001)
  • has_point -> contains_point
  • has_area -> has_surface
  • intersection -> intersect
  • intersect_ray: added in addition to intersects_ray, returning intersection point
• Basis + Quaternion (#1035)
  • to_euler -> get_euler + get_euler_with
  • to_quat -> get_quaternion
  • from_quat -> from_quaternion
  • scale -> get_scale
  • new_looking_at -> looking_at

The main idea behind those changes:

• Use intersect for methods returning the intersection, and intersects for boolean checks.
• Use contains for containment checks, and has for checking the presence of a property.
• Use get_ in situations where only a part is extracted (e.g. get_euler instead of to_euler, because Basis has non-rotation components).
• Be closer to Godot terminology.

Signals

While v0.3 brings large-scale changes to signals, they are almost fully backwards compatible. The main breaking change is that declaring #[signal] now requires the class to have a Base<T> field. If you don't need the new type-safe signal API, you can opt out with #[godot_api(no_typed_signals)] on your impl block.

Relatedly, the ConnectFlags enum has been reclassified as a bitfield rather than regular enum. This enables | operations, among others.

Final classes

Godot prevents certain classes from being inherited outside the engine, for example FileAccess or IP. This used to cause runtime errors whose messages weren't always clear.

godot-rust v0.3 properly declares such classes as "final", which has the following implications:

• Rust classes can no longer inherit from them (doing so results in a descriptive compile error).
• The associated interface trait (e.g. IFileAccess, IIp) no longer exists, since you can neither construct a base nor implement virtual methods. In total, 118 I* traits have been removed.
• API Docs clearly state which classes are final, and elaborates the relation between an interface trait and its base interfaces.

Rename of unsafe virtual methods

Some virtual methods declare raw pointers in their parameters or return types, for example:

#![allow(unused)]
fn main() {
trait IAudioStreamPlayback {
    unsafe fn mix(&mut self, buffer: *mut AudioFrame, 
                  rate_scale: f32, frames: i32) -> i32;
}
}

In the future, we would like to transition these to safe methods. To enable a gradual migration period with coexisting safe and unsafe variants, we renamed all such methods now, by appending the _rawptr suffix:

#![allow(unused)]
fn main() {
trait IAudioStreamPlayback {
    unsafe fn mix_rawptr(&mut self, buffer: *mut AudioFrame, 
                         rate_scale: f32, frames: i32) -> i32;
}
}

Details can be seen in pull request #1174.

Entry point

In case you use #[gdextension(entry_point = ...)], the key has now been renamed to #[gdextension(entry_symbol = ...)]. This is consistent with the key name in the .gdextension file.