Upgrade to Bevy 0.19 and harden editor workflows
CI / Format, lint, test, build (push) Has been cancelled
CI / Format, lint, test, build (push) Has been cancelled
This commit is contained in:
1 parent
3f85d25cc7
commit
b5e561904c
204 files changed
+6972
-29907
No files matched your search
@@ -6,7 +6,7 @@ Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Bevy moves quickly, and the project depends on ecosystem crates that track Bevy on their own schedules. The current workspace targets Bevy 0.18 with Avian 0.6, bevy_egui, bevy-inspector-egui, and transform-gizmo-bevy.
|
||||
Bevy moves quickly, and the project depends on ecosystem crates that track Bevy on their own schedules. The current workspace targets Bevy 0.19 with Avian 0.7, bevy_egui, bevy-inspector-egui, and local compatibility patches for transform-gizmo-bevy and bevy_ufbx.
|
||||
|
||||
Unplanned upgrades can break editor work, rendering, scene serialization, physics, and later networking. Delayed upgrades can also make migrations larger and riskier.
|
||||
|
||||
@@ -18,9 +18,11 @@ Before merging a Bevy upgrade:
|
||||
|
||||
- Confirm matching versions exist for editor, physics, and networking-related crates used by the active milestone.
|
||||
- Read Bevy migration guides for every skipped release.
|
||||
- Preserve authored scene compatibility when Bevy renames runtime scene components or serialization types.
|
||||
- Run `cargo fmt --check`, `cargo check --workspace`, `cargo clippy --workspace`, strict clippy on changed/foundation crates with `-D warnings`, focused tests for changed crates, and focused binary builds.
|
||||
- Smoke-test the game and editor manually after CI is green.
|
||||
- Record any project-specific migration notes in docs or ADR follow-ups.
|
||||
- Keep the normal development profile fully debuggable. Use line-table-only debug information and no incremental cache for the test profile so Bevy upgrade matrices do not retain multi-gigabyte test images indefinitely; use the indexed target cleanup workflow in the root README after migration passes.
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ Accepted
|
||||
|
||||
## Context
|
||||
|
||||
All rendering configuration previously lived in `RenderingSettings` (`assets/project.ron`) and was applied globally to the single `ProjectRenderCamera`. Bevy 0.18 adds experimental Solari ray-traced GI and `FullscreenMaterial` for custom post passes, but no spatial post-process volumes. Game teams need local overrides (rooms, biomes) without forking Rust or duplicating levels.
|
||||
All rendering configuration previously lived in `RenderingSettings` (`assets/project.ron`) and was applied globally to the single `ProjectRenderCamera`. Bevy 0.19 provides experimental Solari ray-traced GI and `FullscreenMaterial` for custom post passes, but no spatial post-process volumes. Game teams need local overrides (rooms, biomes) without forking Rust or duplicating levels.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -21,7 +21,7 @@ All rendering configuration previously lived in `RenderingSettings` (`assets/pro
|
||||
Runtime exposes `RenderingCapabilities { rt_supported, active_gi_path }` and a resolved `ActiveCameraRenderProfile` each frame.
|
||||
ADR 0016 supersedes the ambiguous `active_gi_path` wording with explicit requested/effective GI fields and `EffectiveRenderStack` fallback reasons.
|
||||
|
||||
Bevy 0.18 Solari samples directional lights and emissive meshes, while point and spot lights require the normal PBR light pass that Solari cameras skip. The editor surfaces this limitation directly on point/spot `LightDesc` components and runtime-disables them while Solari is active; point/spot light authoring uses Forward PBR. Requested Solari tags project geometry for raytracing and switches camera plus opaque-renderer components to Solari as soon as RT support is available; render-world readiness counters report whether BLAS/TLAS/bind-group setup and compatible lights are actually ready.
|
||||
Bevy 0.19 Solari samples directional lights and emissive meshes, while point and spot lights require the normal PBR light pass that Solari cameras skip. The editor surfaces this limitation directly on point/spot `LightDesc` components and runtime-disables them while Solari is active; point/spot light authoring uses Forward PBR. Requested Solari tags project geometry for raytracing and switches camera plus opaque-renderer components to Solari as soon as RT support is available; render-world readiness counters report whether BLAS/TLAS/bind-group setup and compatible lights are actually ready.
|
||||
|
||||
### WYSIWYG
|
||||
|
||||
@@ -52,4 +52,4 @@ Authoring is saved to disk; BRP mutates authoring only ([ADR 0009](0009-authorin
|
||||
- `camera_fx.rs` consumes `ActiveCameraRenderProfile`, not raw `RenderingSettings`.
|
||||
- Editor Rendering panel explains GI fallback, overlapping volumes, and active contributors.
|
||||
- Game teams keep global look in `project.ron`, local looks in volumes, reusable bundles in `assets/rendering_profiles/`, custom shaders in `assets/post_fx/`.
|
||||
- Solari may break some debug draws and does not support point/spot lights in Bevy 0.18; `GiMode::Auto` remains the default startup path and the Rendering panel reports the limitation and render-scene readiness.
|
||||
- Solari may break some debug draws and does not support point/spot lights in Bevy 0.19; `GiMode::Auto` remains the default startup path and the Rendering panel reports the limitation and render-scene readiness.
|
||||
@@ -21,7 +21,7 @@ used by `ProjectSun`.
|
||||
## Decision
|
||||
|
||||
1. **`game_hot::rendering::viewport_camera`** is the only module that adds/removes the viewport
|
||||
render stack (`ProjectRenderCamera`, exposure, GI, atmosphere, bloom, fog, etc.).
|
||||
render stack (`ProjectRenderCamera`, exposure, GI, camera atmosphere settings, bloom, fog, etc.).
|
||||
2. **Editor** `scene_view` and `play/session` set `RenderTarget`, `Camera::is_active`, and
|
||||
`viewport = None` only. **`render_view::sync_project_render_view`** calls
|
||||
`clear_viewport_camera_stack` on owner handoff and `sync_viewport_camera_stack` on the active
|
||||
@@ -41,3 +41,5 @@ used by `ProjectSun`.
|
||||
- Thumbnail studio and multi-viewport remain out of scope; they do not use the viewport camera sync path.
|
||||
- `setup_project_camera_effects` no longer skips cameras that already have atmosphere; editor defers
|
||||
player FX via `GameRenderBootstrap` and relies on `sync_project_render_view` once HDR RTT exists.
|
||||
- On Bevy 0.19, the project owns one stable world-space `Atmosphere` entity and cameras receive
|
||||
`AtmosphereSettings`; render-stack sync strips stale camera-side `Atmosphere` components.
|
||||
@@ -10,7 +10,7 @@ Rendering state crossed settings, hydration, game runtime, Solari readiness, edi
|
||||
ownership, and diagnostics. The project already had `ActiveCameraRenderProfile` for project and
|
||||
volume intent, but GI fallback decisions were repeated across camera sync, Solari systems, and UI.
|
||||
|
||||
Bevy 0.18 Solari is still experimental. It needs raytracing-capable hardware, eligible
|
||||
Bevy 0.19 Solari is still experimental. It needs raytracing-capable hardware, eligible
|
||||
`Mesh3d + MeshMaterial3d<StandardMaterial>` scene geometry, Solari-compatible mesh assets
|
||||
(TriangleList, POSITION/NORMAL/UV_0/TANGENT, U32 indices), a render-scene bind group, and a
|
||||
compatible directional or emissive light source. It also does not replace Forward PBR local
|
||||
@@ -52,5 +52,5 @@ point/spot lighting.
|
||||
required Solari mesh attributes or U32 indices.
|
||||
- Existing scenes and material assets remain compatible through serde defaults for new emissive
|
||||
fields.
|
||||
- Bevy 0.19+ rendering upgrades remain a separate migration track under ADR 0002, not part of this
|
||||
- Future Bevy rendering upgrades remain a separate migration track under ADR 0002, not part of this
|
||||
contract change.
|
||||
@@ -6,7 +6,7 @@ Accepted
|
||||
|
||||
## Context
|
||||
|
||||
glTF/GLB and FBX previously entered the editor as imported scenes through `ModelRef`, with runtime hydration loading a format-specific `SceneRoot`. That path is still useful for full scene playback, but it makes ordinary static mesh placement depend on source format behavior and prevents the inspector from exposing a stable renderer component.
|
||||
glTF/GLB and FBX previously entered the editor as imported scenes through `ModelRef`, with runtime hydration loading a format-specific `WorldAssetRoot`. That path is still useful for full scene playback, but it makes ordinary static mesh placement depend on source format behavior and prevents the inspector from exposing a stable renderer component.
|
||||
|
||||
The editor needs model drag/drop to create editable static mesh actors by default, while retaining an explicit scene-instance path for animation, skinning, cameras, and other full-scene data.
|
||||
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
Status: Accepted
|
||||
Status: Superseded by [ADR 0022](0022-bevy-0-19-upgrade.md)
|
||||
|
||||
Context
|
||||
=======
|
||||
|
||||
The editor targets Linux desktop sessions where transient swapchain acquire
|
||||
timeouts can occur during heavy GPU work, compositor stalls, or driver hiccups.
|
||||
In upstream `bevy_render` 0.18.1, `prepare_windows` treats
|
||||
In upstream `bevy_render` 0.18.1, `prepare_windows` treated
|
||||
`wgpu::SurfaceError::Timeout` as a fatal path. That can crash the editor even
|
||||
though the next frame can often recover.
|
||||
|
||||
Decision
|
||||
========
|
||||
|
||||
Patch `bevy_render` locally through `[patch.crates-io]` and vendor the scoped
|
||||
For the Bevy 0.18 line, patch `bevy_render` locally through `[patch.crates-io]` and vendor the scoped
|
||||
crate copy under `third_party/bevy_render`. The patch is limited to transient
|
||||
surface acquire timeouts in `prepare_windows`: log the timeout and skip the
|
||||
frame instead of panicking. Other surface errors remain on their existing paths.
|
||||
@@ -23,6 +23,7 @@ Consequences
|
||||
The editor is more tolerant of transient Linux swapchain stalls while preserving
|
||||
the current Bevy API surface for the rest of the workspace.
|
||||
|
||||
The vendor patch must be reviewed during every Bevy upgrade and removed once
|
||||
upstream behavior is sufficient. Keep the diff narrow; do not use the vendored
|
||||
crate for unrelated render changes.
|
||||
The Bevy 0.19 upgrade removed the active `[patch.crates-io]` entry for `bevy_render`.
|
||||
The historical `third_party/bevy_render` copy was removed with the upgrade. Future
|
||||
swapchain timeout work should start from Bevy 0.19/wgpu behavior rather than carrying
|
||||
this patch forward by default.
|
||||
@@ -0,0 +1,33 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user