# 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.