Migration Guide: v0.12 to v0.13

This guide covers changes when upgrading from godot-bevy 0.12.x to 0.13.0.

Table of Contents

Dependencies: Bevy 0.20 and Rust 1.97.1

Update Bevy to 0.20 and use Rust 1.97.1 or newer. Follow Bevy's 0.19 to 0.20 migration guide for changes in your systems and plugins.

The change most users will hit is the lifecycle observer syntax: On<Add, T> becomes On<Add<T>>. The same applies to Insert, Discard, Remove, and Despawn observers.

Breaking: Math types moved to separate crates

godot_bevy::bevy_math no longer re-exports primitives, bounding volumes, rays, or cubic splines. Use bevy_shape for primitives, bounding volumes, and rays; use bevy_curve for cubic splines. Add the corresponding 0.20 crate to your manifest if you depended on these paths. Vectors, quaternions, and matrices remain in bevy_math.

Behavior: Panic diagnostics and error handling

Bevy 0.20 omits system names from panics; panicking Godot accessors report the caller's file and line. Returned packed-scene errors include the path or handle, entity, and operation; Bevy's default error handler also reports their system name. See Shutdown lifecycle for teardown and custom error handlers.

Behavior: High time scales are capped

Bevy 0.20 applies Time<Virtual>::max_delta after multiplying the raw frame delta by the relative speed. See Timing for the cap and its effect. Raise max_delta if your game needs to fast-forward further:

app.world_mut()
    .resource_mut::<Time<Virtual>>()
    .set_max_delta(std::time::Duration::from_secs(1));

Behavior: Event observers see the current scene tree and time

Godot event-bridge and signal observers, and inspector requests, run after SceneTreeSet::Apply and TimeSystems in First, so they see current-frame nodes and time. Order systems that need mirrored entities after SceneTreeSet::Apply.

New: Live property sync

GodotNode and BevyComponents mappings accept sync = two_way and sync = to_godot. Existing mappings stay creation-only. See live property sync for conversions, supported values, and timing.

New: GodotScene::with_setup

Use GodotScene::with_setup::<T, _>(|root| { ... }) to configure a spawned scene's root after the entity's Transform is applied and before it enters the tree and runs _ready. Chained setups run once in the order added. A root that cannot be cast to T returns a spawn error. GodotScene::from_handle waits for a loading asset before spawning and running setups; failed loads and missing assets still return an error. See Spawning Godot scenes for the builder recipe and the observer fallback for setup that needs ECS data.

New: Resource accessors take shared references

GodotResource::get and try_cast, and GodotResourceHandle::get and try_get, take &self. Systems that only read resources can use Res<Assets<GodotResource>> and Assets::get. Handle-based audio playback and scene spawning no longer emit AssetEvent::Modified just from reading an asset.

Mutating the returned Gd changes the shared Godot resource for all users; &self does not make it immutable.

New: Reproducible schedule shuffling in tests

godot-bevy-test supports reproducible schedule shuffling with --schedule-seed <u64> or ITEST_SCHEDULE_SEED. See the runner configuration.

Dependencies: Two glam versions and Tracy clients

gdext uses glam 0.32 while Bevy uses glam 0.33, so both versions compile until gdext updates. Bevy math no longer gets debug-glam-assert through feature unification with gdext. Enable bevy_math/debug_glam_assert if you rely on those debug checks.

Enabling both bevy/trace_tracy and godot-bevy's trace_tracy builds two Tracy clients because the dependencies use different client versions. Enable only the integration you need.