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
+2
-1
@@ -33,9 +33,10 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [0016](adr/0016-unified-rendering-contract.md) | Requested/effective render stack, Solari eligibility, emissive materials |
|
||||
| [0017](adr/0017-normalized-static-mesh-assets.md) | Normalized static mesh assets and renderer placement |
|
||||
| [0018](adr/0018-componentized-actor-inspector-and-materials.md) | Componentized actor inspector, imported asset refs, collider split, material overrides |
|
||||
| [0019](adr/0019-local-bevy-render-timeout-patch.md) | Local `bevy_render` patch for transient Linux swapchain timeouts |
|
||||
| [0019](adr/0019-local-bevy-render-timeout-patch.md) | Superseded local `bevy_render` patch for transient Linux swapchain timeouts |
|
||||
| [0020](adr/0020-jackdaw-inspired-editor-roadmap.md) | Jackdaw-inspired roadmap source policy and attribution requirements |
|
||||
| [0021](adr/0021-brush-authoring-schema.md) | Brush authoring schema and hydration contract |
|
||||
| [0022](adr/0022-bevy-0-19-upgrade.md) | Bevy 0.19 / Avian 0.7 upgrade and compatibility patches |
|
||||
|
||||
## Editor framework
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -45,7 +45,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
- **Static mesh renderer** — model drag/drop defaults to `ActorKind::StaticMesh + StaticMeshRenderer` using normalized artifacts under `assets/meshes/generated/`. Renderer slots store imported `EditorAssetRef` mesh/material references, not source FBX/glTF paths. `SceneInstance` placement keeps the legacy `ImportedModel + ModelRef` path for full scene playback.
|
||||
- **Brush authoring** — `ActorKind::Brush + BrushDesc` stores persisted convex blockout faces, validates authored geometry in the inspector and Window → Brush Diagnostics, and hydrates active valid brushes into generated mesh children. See [brushes.md](brushes.md).
|
||||
- **Draw Brush** — `B`, toolbar pencil, or command `brush.draw` enters a floor-polygon draw mode. LMB places snapped points, Backspace removes the last point, Enter locks the outline for height editing, mouse up/down adjusts height, and Enter/LMB creates additive prism brushes through history. Esc/right-click cancels. Simple concave outlines decompose into convex brush parts; self-intersections remain blocked.
|
||||
- **Brush edit modes** — with a brush selected, `1`/`2`/`3`/`4` enter vertex, edge, face, and clip element modes. Element modes show brush handles in the viewport, own LMB picking, support Shift multi-select, show a mode badge, and Esc returns to object mode. Vertex/edge/face selections can be dragged on the viewport floor plane and commit undoable `SetBrush` edits; clip mode is a preview/selection mode until CSG split support lands.
|
||||
- **Brush edit modes** — with a brush selected, `1`/`2`/`3`/`4` enter vertex, edge, face, and clip element modes. Element modes show brush handles in the viewport, own LMB picking, support Shift multi-select, show a mode badge, and Esc returns to object mode. Vertex/edge/face selections use the standard `W`/`E`/`R` gizmo at the element pivot and commit undoable `SetBrush` edits. Clip previews a bounds-based half-brush and commits with Enter; command-palette intersect, convex merge, and subtract operations use the same preview/commit lifecycle for conservative cuboid/prism blockout.
|
||||
- **Collider split** — imported mesh collision lives in a separate `ColliderDesc::StaticMesh` plus optional `RigidBodyDesc`; renderer slots own only render visibility, shadows, mesh, and material references.
|
||||
- **Material assets** — `MaterialAsset` RON (`label` + `MaterialDesc`) is shader-schema aware. Actor material edits live on the actor `MaterialDesc`; static mesh slot material refs are source/default selectors, and content-browser asset inspectors are the path for editing shared material assets.
|
||||
- **Prefab overrides** — `PrefabInstance.overrides_ron` stores transform/material/child-visibility overrides; inspector collapsible groups with **Apply** / **Revert** (replaces transform-only revert v1).
|
||||
@@ -55,7 +55,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
- **World lighting** has two layers: project default sun/ambient settings, and optional scene-authored directional `LightDesc` overrides. **Scene → Lighting** menu and **Rendering** panel (Window) restore project sun or bake a scene directional from project settings. **Apply** in Project Settings updates ambient and sun illuminance live.
|
||||
- **Rendering** — `GiMode` + post-process volumes; see [rendering.md](rendering.md). **Window → Rendering** shows requested/effective active-camera stack, fallback reason, Solari eligibility, viewport GI badge, and volume HUD.
|
||||
- **Inspector** shows a responsive header, **Transform**, registered authoring component cards, and an Add Component footer (`actor_inspector`) that expands an inline search shelf above the button; only the component body scrolls. Rows wrap or stack inside narrow docks instead of forcing the panel wider, and legacy authoring sections use the same component-card shell. Component card carets collapse/expand for the current editor session, status dots toggle persisted active state, and triple-dot menus provide reset, copy/paste values, move, remove, and documentation slots. Inactive authoring components remain in the scene but are skipped by hydration/runtime queries, stripping their generated meshes, lights, physics, or post-process effects. The Add Component shelf is registry-driven with persistent search, category groups, descriptions, hydration hints, duplicate/conflict disabled states, and recommendation hints. `StaticMeshRenderer` uses concept-style slot cards with model thumbnails, imported mesh/source-material selectors, visibility, and shadow flags. Actor material authoring lives in the `Authoring Material` component, whose texture refs use Asset Browser picker/drop controls. Empty source material refs display the inherited source material from the generated static mesh artifact as **Source default**; selector **Browse** assigns explicit normalized imported sub-assets, **Locate** focuses the owning asset in the Asset Browser, and **Clear** returns optional material slots to the inherited source default. `ColliderDesc` and `RigidBodyDesc` are separate component cards. Game crates add sections via `ActorInspectorSection` + `game::editor_ext::actor_inspector_section_ids()`.
|
||||
- **Command palette** (`Ctrl+P`): focuses the filter on open, selects the first filtered command, supports arrow-key selection and Enter to run. Commands include `scene.reset_lighting`, `brush.draw`, `brush.subtract`, `brush.intersect`, `brush.merge_convex`, `rendering.create_volume`, `rendering.select_volumes_at_camera`, `rendering.focus_active_volumes`, `selection.group`, `selection.focus`, `selection.reset_transform`, and play commands.
|
||||
- **Command palette** (`Ctrl+P`): opens centered, clears and focuses the filter, selects the first result, searches both human-facing labels and stable command IDs, and supports arrow-key selection and Enter to run. Commands include `scene.reset_lighting`, `brush.draw`, `brush.subtract`, `brush.intersect`, `brush.merge_convex`, `rendering.create_volume`, `rendering.select_volumes_at_camera`, `rendering.focus_active_volumes`, `selection.group`, `selection.focus`, `selection.reset_transform`, and play commands.
|
||||
- **Editor input routing** gives egui text fields first claim on keyboard input. Viewport shortcut keys require viewport pointer focus and are suspended while RMB/MMB camera navigation is active.
|
||||
- **ActorKind** is required on saved level objects (schema v2). Save strips hydrated ECS before writing `.scn.ron`.
|
||||
- **Scene visualizers** expose actor root icons, colliders, lights, player spawns, prefab/model anchors, Project Sun, and runtime player/camera markers without changing saved scene data. Viewport options include actor icon size and transform gizmo size sliders.
|
||||
|
||||
@@ -59,6 +59,12 @@ Workflow: run `cargo watch … build -p game_hot` in one terminal, `cargo run -p
|
||||
|
||||
Do not add egui or editor-only state to the `settings` crate.
|
||||
|
||||
The active project root is a startup boundary because `AssetPlugin.file_path`, project settings,
|
||||
the asset catalog, and the initial level must agree before editor systems initialize. The editor
|
||||
currently starts in the repository project root. Cross-project selection and scaffolding belong in
|
||||
the planned BS-JD-001 launcher before the main app is built; do not reintroduce in-process project
|
||||
switching that only changes settings metadata while leaving the AssetServer on the old root.
|
||||
|
||||
## Camera and viewport model
|
||||
|
||||
See [ADR 0014](../adr/0014-unified-viewport-model.md) for the unified viewport decision.
|
||||
@@ -115,7 +121,7 @@ The egui layer lives under `crates/editor/src/ui/`:
|
||||
| `diagnostics.rs` | Detailed stats (Window → Diagnostics, Asset Browser footer) |
|
||||
| `layout.rs` | Dock layout RON persistence in `editor_prefs.ron` |
|
||||
|
||||
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. A blue status bar shows scene path, mode, selection count, and history. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
|
||||
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. A blue status bar prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
|
||||
|
||||
**Follow-up (Phase 4b):** hierarchy expand/collapse persistence, inspector search, and richer per-asset previews.
|
||||
|
||||
@@ -146,7 +152,7 @@ On play enter/exit the editor snapshots **player sim state only** (transform, ve
|
||||
2. `EditorOnly` entities (cameras, helpers) are filtered from hierarchy and save; visualizer proxies can be picked but resolve back to source entities.
|
||||
3. Player placement is stored as `PlayerSpawn`; the runtime `Player` is never serialized.
|
||||
4. `SceneIo` writes native Bevy dynamic scenes under `assets/levels/`, routed through the Bevy-free `scene::document::SceneDocument` seam. The document layer preserves the current RON storage while exposing stable actor/component document concepts and patch vocabulary for tools.
|
||||
5. Hydration systems in `game` spawn meshes, colliders, lights, and static mesh renderer parts at runtime. `ActorId` and `ComponentInstanceId` are the persisted identities; raw Bevy `Entity` IDs are runtime-only and must not become tool-facing document IDs.
|
||||
5. Hydration systems in `game` spawn meshes, colliders, lights, and static mesh renderer parts at runtime. Level-object roots are initialized with Bevy visibility hierarchy components before generated children are attached, so authoring `EditorVisibility` participates in normal visibility propagation. `ActorId` and `ComponentInstanceId` are the persisted identities; raw Bevy `Entity` IDs are runtime-only and must not become tool-facing document IDs.
|
||||
6. Brush actors store authored convex geometry as `BrushDesc`; hydration rebuilds generated mesh children from those faces and strips the children before save.
|
||||
|
||||
## Model import (glTF + FBX)
|
||||
@@ -156,7 +162,7 @@ On play enter/exit the editor snapshots **player sim state only** (transform, ve
|
||||
- **Browser subassets:** model rows can expand into a content shelf backed by the generated manifest. Mesh subassets can be selected or dragged into the viewport as `StaticMeshRenderer` actors, material subassets expose source defaults, and texture dependencies can be applied to selected actors without treating glTF and FBX differently. The thumbnail studio renders each generated model/subasset/material preview into its own render target before registering it in the cache so later thumbnails cannot overwrite earlier cache entries.
|
||||
- **Default placement:** model drag/drop creates `ActorKind::StaticMesh + StaticMeshRenderer`. Renderer slots reference imported `EditorAssetRef` values (`asset_id` + `sub_asset_id`) and hydration resolves those through the generated artifact. `SingleActor` hierarchy mode stores all parts in one renderer; `SourceHierarchy` creates a root with child static mesh actors.
|
||||
- **Collision:** when collider generation is enabled, placement adds `RigidBodyDesc` and `ColliderDesc::StaticMesh` using the same imported mesh refs. Renderer slots no longer own collider state.
|
||||
- **Scene-instance placement:** asset details can switch placement to `SceneInstance`; that keeps `ImportedModel + ModelRef`, which hydrates to `SceneRoot`. glTF uses `GltfAssetLabel::Scene`; FBX uses `bevy_ufbx` (`path#SceneN`). `FbxPlugin` is registered in `GamePlugin`.
|
||||
- **Scene-instance placement:** asset details can switch placement to `SceneInstance`; that keeps `ImportedModel + ModelRef`, which hydrates to `WorldAssetRoot`. glTF uses `GltfAssetLabel::Scene`; FBX uses `bevy_ufbx` (`path#SceneN`). `FbxPlugin` is registered in `GamePlugin`.
|
||||
- **Limitations:** Binary FBX only (not ASCII). Static mesh placement stores animation/skinning/camera/light metadata and warnings but does not play those features; use Scene Instance for full-scene playback.
|
||||
|
||||
## Undo / history
|
||||
@@ -181,7 +187,7 @@ PIE stop restores player simulation state only; authored `LevelObject` edits mad
|
||||
| `viewport/` | Camera, selection, gizmos, render views, panel settings |
|
||||
| `play/` | PIE session, editor mode, net editor profiles |
|
||||
| `assets/` | Catalog, asset DB, static mesh artifacts, prefab overrides |
|
||||
| `project/` | Workspace, project I/O, settings UI |
|
||||
| `project/` | Project I/O and settings UI |
|
||||
| `ext/` | Command palette, BRP, game panel adapters |
|
||||
| `history/` | Undo commands + plugin |
|
||||
| `ui/` | egui dock shell |
|
||||
@@ -192,7 +198,7 @@ Shared scene schema lives in `crates/scene` (stamp/migrate/validate on save, loa
|
||||
|
||||
The unified viewport renders through an HDR offscreen target (`render_target.rs`). When the panel target is missing (egui reflow), cameras must strip atmosphere/post-FX before targeting the swapchain. User-authored HDR may be disabled, but atmosphere and effective Solari still force `Hdr` on the active viewport camera because Bevy sky/Solari pipelines are not safe to carry across SDR targets. `render_view::sync_project_render_view` runs in **PostUpdate** after RTT target assignment and reapplies the project FX stack whenever the active panel target handle changes (startup, resize), not only on settings Apply. Project Settings uses a **draft buffer**; **Apply** commits after render targets resync.
|
||||
|
||||
The workspace patches `bevy_render` under `third_party/bevy_render` so Linux `wgpu::SurfaceError::Timeout` during swapchain texture acquisition logs and skips the frame instead of panicking in `prepare_windows`. Keep this patch scoped to transient surface acquire timeouts and re-evaluate it during Bevy upgrades.
|
||||
Bevy 0.19 removed the workspace's prior local `bevy_render` swapchain-timeout patch. The only active Bevy-adjacent patches are compatibility shims for ecosystem crates: `transform-gizmo-bevy` and `bevy_ufbx` under `third_party/`.
|
||||
|
||||
## Extensibility (phase 6)
|
||||
|
||||
|
||||
+4
-4
@@ -15,17 +15,17 @@ Launch the editor with dev features as usual:
|
||||
cargo run -p editor --features dev
|
||||
```
|
||||
|
||||
Default HTTP endpoint follows Bevy 0.18 remote defaults (port **15702**, routes under `/remote/`).
|
||||
Default HTTP endpoint follows Bevy 0.19 remote defaults (port **15702**, routes under `/remote/`).
|
||||
|
||||
## Authoring-only mutation policy
|
||||
|
||||
**BRP and automation must mutate authoring components only** — the same allowlist used on scene save in `scene_io.rs`. Hydration rebuilds runtime ECS (`Mesh3d`, Bevy lights, physics, `SceneRoot`, etc.) on the next frame.
|
||||
**BRP and automation must mutate authoring components only** — the same allowlist used on scene save in `scene_io.rs`. Hydration rebuilds runtime ECS (`Mesh3d`, Bevy lights, physics, `WorldAssetRoot`, etc.) on the next frame.
|
||||
|
||||
| Allowed (examples) | Forbidden on level objects |
|
||||
|--------------------|----------------------------|
|
||||
| `Transform`, `Name`, `ActorKind` | `PointLight`, `SpotLight`, `DirectionalLight` |
|
||||
| `Primitive`, `StaticMeshRenderer`, `MaterialDesc`, `MaterialOverride`, `LightDesc` | `Mesh3d`, `MeshMaterial3d`, `RigidBody`, `Collider` |
|
||||
| `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, gameplay markers | `SceneRoot`, generated static mesh children, internal visibility types |
|
||||
| `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, gameplay markers | `WorldAssetRoot`, generated static mesh children, internal visibility types |
|
||||
| `PostProcessVolumeDesc` | Runtime post-process components on cameras |
|
||||
|
||||
Prefer:
|
||||
@@ -107,7 +107,7 @@ External automation can enqueue the same names through the editor command queue
|
||||
Validate committed levels without the editor UI:
|
||||
|
||||
```bash
|
||||
cargo run -p xtask --bin validate-levels
|
||||
cargo validate-levels
|
||||
```
|
||||
|
||||
This runs `scene::validate_level_file` (schema migrate + **authoring-only** component check).
|
||||
|
||||
@@ -16,13 +16,13 @@ Brushes are persisted blockout geometry stored as `ActorKind::Brush + BrushDesc`
|
||||
|
||||
## Element Modes
|
||||
|
||||
With a brush actor selected, `1`/`2`/`3`/`4` enter vertex, edge, face, and clip modes. Element modes show viewport overlays for the selected brush, route LMB to element picking, support Shift+LMB multi-select, and display a `Brush: <mode>` badge. `Esc` returns to object mode.
|
||||
With a brush actor selected, `1`/`2`/`3`/`4` enter vertex, edge, face, and clip modes. Element modes show viewport overlays for the selected brush, route LMB to element picking, support Shift+LMB multi-select, and display a brush edit banner with the active mode, selected element count, and available controls. Actor transform gizmos are replaced by a brush element transform gizmo at the selected element pivot while a brush element mode is active. `Esc` returns to object mode.
|
||||
|
||||
Vertex, edge, and face selections can be dragged on the viewport floor plane. The editor moves matching duplicated corner vertices across all brush faces so simple cube/prism brushes stay welded, recomputes face planes, validates the result, and commits one undoable brush edit when the drag releases. Invalid drag results are rejected with operator status text and reverted to the pre-drag brush.
|
||||
Vertex, edge, and face selections are transformed through the standard viewport gizmo. `W`, `E`, and `R` choose translate, rotate, and scale for the selected brush elements. The editor transforms matching duplicated corner vertices across all brush faces so simple cube/prism brushes stay welded, recomputes face planes, validates the result, and commits one undoable brush edit when the gizmo releases. Invalid gizmo results are rejected with operator status text and reverted to the pre-edit brush.
|
||||
|
||||
Clip mode is a bounds-based MVP for cuboid/prism blockout. Select one face in Clip mode to preview the half-brush result along that face's dominant normal axis; the magenta wireframe shows the pending trimmed bounds. **Enter** commits the clip through history and **Esc** returns to Object mode.
|
||||
|
||||
When one or more faces are selected in Face mode, the Brush inspector shows selected-face controls for UV offset, UV scale, UV rotation, material ref, and texture ref. Material and texture rows use Asset Browser-aware picker controls with clear, locate, browse, and compatible drag/drop assignment. These fields edit the persisted `BrushFaceDesc` data through undoable brush updates. Face refs cache loadable source paths when available; hydration groups faces by material/texture path and spawns separate generated mesh children for those batches.
|
||||
When one or more faces are selected in Face mode, the Brush inspector shows selected-face controls for UV offset, UV scale, UV rotation in degrees, material ref, and texture ref. Material and texture rows use Asset Browser-aware picker controls with clear, locate, browse, and compatible drag/drop assignment. These fields edit the persisted `BrushFaceDesc` data through undoable brush updates and update hydrated brush mesh UVs. Face refs cache loadable source paths when available; hydration groups faces by material/texture path and spawns separate generated mesh children for those batches. Non-finite UV offset/scale/rotation values are reported as brush diagnostics and sanitized during hydration so invalid authoring data does not emit NaN mesh UVs.
|
||||
|
||||
## Boolean Operations
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
- PIE step while paused (F7)
|
||||
- Net editor state + determinism HUD stub
|
||||
- `EditorPlugin` / `EditorCommand` extensibility surface
|
||||
- `cargo run -p validate-levels --manifest-path xtask/Cargo.toml`
|
||||
- `cargo validate-levels`
|
||||
|
||||
## Gates
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@ Step-by-step guide for game teams managing look development without Rust changes
|
||||
2. **Post-process volumes** — scene actors with local overrides (rooms, biomes, boss arenas).
|
||||
3. **Requested profile** — the active viewport camera always uses `ActiveCameraRenderProfile` (project + blended volumes), whether it is the editor fly camera or the possessed player camera.
|
||||
4. **Effective stack** — `EffectiveRenderStack` records requested GI, effective GI, and fallback reason for renderer sync and diagnostics.
|
||||
5. **Atmosphere ownership** — Bevy 0.19 uses one stable project `Atmosphere` entity; active cameras only carry `AtmosphereSettings` when the profile enables sky rendering.
|
||||
6. **Antialiasing ownership** — all 3D cameras spawn with MSAA disabled. The project rendering profile owns temporal antialiasing, and Bevy's deferred path does not support MSAA.
|
||||
|
||||
See [ADR 0013](../adr/0013-rendering-tiers-and-post-process-volumes.md) for tier policy and crate boundaries, and [ADR 0016](../adr/0016-unified-rendering-contract.md) for the requested/effective stack contract.
|
||||
|
||||
@@ -60,7 +62,7 @@ Viewport overlays: **GI badge** (Forward / Solari), **volume HUD** when inside a
|
||||
| Forward | Bevy Forward PBR with HDR/TAA/SSAO/atmosphere/shadows |
|
||||
| Solari | Request Solari; the camera attaches Bevy Solari when RT support is available |
|
||||
|
||||
Solari in Bevy 0.18 samples directional lights and emissive meshes. Point and spot lights require the normal PBR light pass, so `LightDesc` point/spot components are runtime-disabled while Solari is active. The component remains in the scene, the inspector shows an unsupported message, and hydration strips/skips the Bevy `PointLight` / `SpotLight` until authors switch the light to Directional or switch GI to Forward. The viewport resolves Hybrid Auto through **`EffectiveRenderStack`**: requested Solari keeps project meshes eligible for raytracing and attaches Bevy Solari when RT support is available. Effective GI falls back to **Forward** only when RT is unavailable. Effective Solari forces an HDR camera target even if project HDR is off, because Bevy Solari writes to the main texture through a storage binding and sRGB textures are invalid for that use. Primitive hydration generates tangents so built-in boxes/spheres can enter Solari BLAS/TLAS; imported/custom meshes still need TriangleList geometry, POSITION/NORMAL/UV_0/TANGENT attributes, and U32 indices. The Rendering panel reports the exact fallback reason, Solari-compatible asset counts, bind-group state, and compatible light counters. Set `BEVY_FPS_FORCE_SOLARI=1` to force RT feature probing in dev (see README troubleshooting).
|
||||
Solari in Bevy 0.19 samples directional lights and emissive meshes. Point and spot lights require the normal PBR light pass, so `LightDesc` point/spot components are runtime-disabled while Solari is active. The component remains in the scene, the inspector shows an unsupported message, and hydration strips/skips the Bevy `PointLight` / `SpotLight` until authors switch the light to Directional or switch GI to Forward. The viewport resolves Hybrid Auto through **`EffectiveRenderStack`**: requested Solari keeps project meshes eligible for raytracing and attaches Bevy Solari when RT support is available. Effective GI falls back to **Forward** only when RT is unavailable. Effective Solari forces an HDR camera target even if project HDR is off, because Bevy Solari writes to the main texture through a storage binding and sRGB textures are invalid for that use. Primitive hydration generates tangents so built-in boxes/spheres can enter Solari BLAS/TLAS; imported/custom meshes still need TriangleList geometry, POSITION/NORMAL/UV_0/TANGENT attributes, and U32 indices. The Rendering panel reports the exact fallback reason, Solari-compatible asset counts, bind-group state, and compatible light counters. Set `BEVY_FPS_FORCE_SOLARI=1` to force RT feature probing in dev (see README troubleshooting).
|
||||
|
||||
## Emissive lighting
|
||||
|
||||
@@ -103,5 +105,6 @@ Open `assets/levels/rendering_showcase.scn.ron` for fog, exposure, and vignette
|
||||
| GI badge shows Forward unexpectedly | Solari RT wgpu features unavailable; Rendering → Active Camera tab |
|
||||
| Volume has no effect | Camera inside AABB? Priority vs other volumes? Overrides enabled? |
|
||||
| Custom FX missing | RON path in volume matches `assets/post_fx/`; shader path in RON |
|
||||
| Atmosphere flickers or artifacts | Confirm only the project `Atmosphere` entity exists and active cameras have `AtmosphereSettings`, not camera-side `Atmosphere` components. |
|
||||
|
||||
Command palette: `rendering.select_volumes_at_camera`, `rendering.focus_active_volumes`.
|
||||
@@ -39,7 +39,7 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
|
||||
| `ProjectWorkspace` resource | Done | Root, settings path, dirty flags |
|
||||
| User prefs (`~/.config/bevy-fps/editor_prefs.ron`) | Done | Recent levels, load on startup |
|
||||
| Window title from project + scene | Done | `project_io::window_title` |
|
||||
| New/Open project menu | Done | File → Project; distinct from level New/Open |
|
||||
| Project launcher and scaffolding | Planned | BS-JD-001; project selection must happen before AssetServer startup, so the former in-process New/Open menu was removed |
|
||||
| Dock layout persistence | Done | RON in `editor_prefs.ron`; View → Reset Layout |
|
||||
|
||||
## Phase 2 — Viewport excellence
|
||||
@@ -101,7 +101,7 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Dark pro theme + Phosphor icons | Done | `ui/theme.rs`, `ui/fonts.rs`, high-contrast selection states, overlay toolbars |
|
||||
| Fixed status bar | Done | Replaces Status dock tab |
|
||||
| Fixed status bar | Done | Replaces Status dock tab; exposes scene I/O and operator feedback alongside scene/mode/selection/history |
|
||||
| Viewport overlay toolbar | Done | Gizmo/grid/focus/options/game-view toggle (play moved to main toolbar) |
|
||||
| Main toolbar transport | Done | Centered Play/Pause/Stop/Eject; taller bar (~52px) |
|
||||
| Pause in PIE | Done | `PlayPaused` freezes sim while staying in Play (`F6`) |
|
||||
|
||||
Reference in new issue
Block a user