Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
codex/guarded-shutdown-savepoints
Blacksite/docs/adr/0022-bevy-0-19-upgrade.md
Rbanh b5e561904c
Some checks failed
CI / Format, lint, test, build (push) Has been cancelled
Details
Upgrade to Bevy 0.19 and harden editor workflows
2026-07-09 23:43:47 -04:00

2.4 KiB
Raw Permalink Blame History

ADR 0022: Bevy 0.19 Upgrade

Status

Accepted

Context

Avian 0.7 supports Bevy 0.19, which lets the workspace move off Bevy 0.18 while keeping the physics stack current. Bevy 0.19 also renamed the old dynamic scene/world serialization surface: runtime scene roots are WorldAssetRoot, saved dynamic scenes are DynamicWorld, and .scn.ron loading uses WorldDeserializer.

Two ecosystem crates used by the editor still need local compatibility shims during the upgrade:

  • transform-gizmo-bevy 0.9 needs Bevy 0.19 render API updates.
  • bevy_ufbx 0.18.1-rc.1 still targets Bevy 0.18 but is required for FBX import and scene-instance playback.

The old local bevy_render timeout patch was specific to Bevy 0.18 window preparation behavior. Bevy 0.19 also changed the atmosphere model: Atmosphere is a world-space planet entity selected by nearby cameras, while cameras opt in with AtmosphereSettings.

Decision

Upgrade the workspace to Bevy 0.19 and Avian 0.7. Keep FBX support by vendoring bevy_ufbx under third_party/bevy_ufbx and patching it to emit Bevy 0.19 WorldAsset scene labels. Keep the existing local transform-gizmo-bevy patch and update it for Bevy 0.19 render pipeline and phase APIs.

Remove the active [patch.crates-io] override for bevy_render. Runtime scene hydration now uses WorldAssetRoot for glTF/FBX model scenes and DynamicWorldRoot for saved .scn.ron prefabs. Scene save/load continues to write the project’s schema-wrapped .scn.ron format through DynamicWorld.

Keep one stable project-owned Atmosphere entity for the active render profile. Editor and game cameras only receive AtmosphereSettings; camera-side Atmosphere components are stripped during render-stack sync to avoid unstable planet transforms and extraction jitter.

Consequences

The dependency graph has one Bevy 0.19 line and one egui 0.34 line. FBX support remains available, but third_party/bevy_ufbx should be removed when upstream publishes a Bevy 0.19-compatible release.

Docs and tooling should use WorldAssetRoot / DynamicWorldRoot for runtime hydrated scene components. Existing authoring components (ModelRef, PrefabRef, StaticMeshRenderer) remain the stable scene-file surface.

Swapchain timeout behavior now follows upstream Bevy 0.19 and wgpu behavior. If Linux timeout crashes return, investigate current upstream code before reintroducing a local bevy_render patch.