This commit is contained in:
1 parent
2fa64106c8
commit
2054fa2558
21 files changed
+711
-159
No files matched your search
+1
-1
@@ -29,7 +29,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [0012](adr/0012-zero-tech-debt-editor.md) | Zero tech debt / no dual inspector |
|
||||
| [0013](adr/0013-rendering-tiers-and-post-process-volumes.md) | GI tiers, post-process volumes, editor model |
|
||||
| [0014](adr/0014-unified-viewport-model.md) | Unified viewport render target and clean game-view overlay |
|
||||
| [0015](adr/0015-viewport-camera-stack-ownership.md) | Viewport camera FX ownership, GI auto-forward for local shadows |
|
||||
| [0015](adr/0015-viewport-camera-stack-ownership.md) | Viewport camera FX ownership and Solari local-light authoring policy |
|
||||
| [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 |
|
||||
|
||||
@@ -12,9 +12,11 @@ Levels under `assets/levels/` need forward-compatible migrations as authoring co
|
||||
|
||||
- Track `schema_version` in scene files (wrapper or sidecar during transition).
|
||||
- Provide `scene_schema` module with `migrate_scene_text` and `validate_level_file`.
|
||||
- Route editor save/load through `scene::document::SceneDocument`, an internal Bevy-free seam that preserves DynamicScene RON while exposing stable actor/component document identities and patch operations for tools.
|
||||
- CI / `xtask validate-levels` loads all committed levels and fails on unknown versions.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Breaking component changes require a migration step and version bump.
|
||||
- Editor save may wrap scenes with schema header in a follow-up change.
|
||||
- The current storage format remains DynamicScene RON; `SceneDocument` is not a BSN/JSN migration.
|
||||
@@ -16,12 +16,12 @@ All rendering configuration previously lived in `RenderingSettings` (`assets/pro
|
||||
|------|----------|
|
||||
| `GiMode::Auto` | Startup default: Solari deferred when RT GPU support is available; Forward PBR otherwise |
|
||||
| `GiMode::Forward` | Bevy Forward PBR with HDR/TAA/SSAO/atmosphere/shadows |
|
||||
| `GiMode::Solari` | Request Solari deferred; camera attaches Bevy Solari when RT support is available and no local shadow-light fallback is required |
|
||||
| `GiMode::Solari` | Request Solari deferred; camera attaches Bevy Solari when RT support is available |
|
||||
|
||||
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 in Rendering diagnostics; 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.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.
|
||||
|
||||
### WYSIWYG
|
||||
|
||||
|
||||
@@ -11,8 +11,9 @@ components were still stripped in multiple places (`scene_view`, play session, a
|
||||
in `render_view`). That caused WYSIWYG gaps between edit and play, lost FX after resize, and
|
||||
interacted badly with `setup_project_camera_effects` filtering on `Without<Atmosphere>`.
|
||||
|
||||
Separately, `GiMode::Auto` could select Solari while shadow-casting point/spot lights were present.
|
||||
Solari deferred skips the forward PBR light pass (ADR 0013), so local light shadows disappeared.
|
||||
Separately, `GiMode::Auto` could select Solari while point/spot lights were present.
|
||||
Solari deferred skips the forward PBR light pass (ADR 0013), so local lights appeared editable
|
||||
while producing no lighting.
|
||||
|
||||
Scene directionals hydrated with hardcoded cascade bounds that did not match project shadow settings
|
||||
used by `ProjectSun`.
|
||||
@@ -25,8 +26,9 @@ used by `ProjectSun`.
|
||||
`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
|
||||
camera (full apply on owner change; incremental when the stack already exists).
|
||||
3. **`effective_viewport_gi_path`** forces `GiPath::Forward` when any `PointLight` or `SpotLight`
|
||||
with `shadows_enabled` exists in the world (auto-forward for local shadows).
|
||||
3. **`effective_viewport_gi_path`** does not switch paths for local lights. When Solari is active,
|
||||
point/spot `LightDesc` authoring remains in the scene but hydrates no runtime light component,
|
||||
and the inspector marks the component unsupported until authors switch to Directional or Forward.
|
||||
4. **Scene directionals** use `cascade_config_from_rendering` from project settings at hydration;
|
||||
`sync_scene_directional_shadow_cascades` updates cascades when settings change.
|
||||
5. **Hydrated lights** always insert `Visibility::Visible` with runtime light components.
|
||||
@@ -34,7 +36,8 @@ used by `ProjectSun`.
|
||||
## Consequences
|
||||
|
||||
- Edit/play possession (F5/F8) and settings Apply no longer flash unlit frames from scattered FX strips.
|
||||
- Rendering diagnostics can report “Solari requested, Forward (local shadow lights)”.
|
||||
- Rendering diagnostics can report unsupported Solari-local light authoring without changing the
|
||||
selected GI path.
|
||||
- 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.
|
||||
@@ -14,7 +14,7 @@ Bevy 0.18 Solari is still experimental. It needs raytracing-capable hardware, el
|
||||
`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
|
||||
point/spot shadow lighting.
|
||||
point/spot lighting.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -24,14 +24,19 @@ point/spot shadow lighting.
|
||||
- `game_hot` owns runtime application of the stack. Camera systems call the shared resolver and
|
||||
mirror the result into `RenderingCapabilities` for renderer method selection and diagnostics.
|
||||
- Requested Solari and effective Solari are distinct. Requested Solari keeps eligible project
|
||||
geometry tagged for raytracing and attaches Bevy Solari as soon as RT support is available, unless
|
||||
local-shadow fallback is required.
|
||||
- Effective Solari forces an HDR camera target regardless of authored HDR settings, because Bevy
|
||||
Solari requires `STORAGE_BINDING` on the camera main texture and wgpu rejects storage usage on
|
||||
sRGB target formats.
|
||||
geometry tagged for raytracing and attaches Bevy Solari as soon as RT support is available.
|
||||
- Point/spot `LightDesc` components are runtime-disabled while Solari is active. They stay authored
|
||||
and editable enough to switch kind, but hydration strips/skips their Bevy `PointLight`/`SpotLight`
|
||||
components and the inspector explains the limitation on the component.
|
||||
- Effective Solari and atmosphere force an HDR camera target regardless of authored HDR settings.
|
||||
Bevy Solari requires `STORAGE_BINDING` on the camera main texture, and Bevy sky/atmosphere
|
||||
pipelines must not be carried onto an SDR swapchain render pass.
|
||||
- Runtime changes that alter the active render target or effective Solari/Forward path rebuild the
|
||||
active camera stack instead of incrementally patching it. This
|
||||
prevents stale pipelines from surviving texture-format transitions.
|
||||
- Hybrid Auto remains the default policy: use Solari for directional/emissive scenes, surface
|
||||
readiness diagnostics while it warms up, and fall back to Forward PBR when local point/spot shadow
|
||||
correctness or unavailable RT features require it.
|
||||
readiness diagnostics while it warms up, and fall back to Forward PBR only when RT features are
|
||||
unavailable.
|
||||
- Material authoring includes emissive color, intensity, and texture fields so scenes can create
|
||||
Solari-compatible emissive contributors without Rust changes.
|
||||
|
||||
@@ -39,6 +44,8 @@ point/spot shadow lighting.
|
||||
|
||||
- Diagnostics must report requested GI, effective GI, and fallback reason from
|
||||
`EffectiveRenderStack` rather than deriving labels independently.
|
||||
- Project settings can disable user-authored HDR, but the active camera still receives `Hdr` when
|
||||
atmosphere or effective Solari requires an HDR target.
|
||||
- Solari mesh eligibility is based on hydrated project geometry under `LevelObject` ancestry with
|
||||
`RaytracingExcluded` helpers filtered out. Built-in primitive hydration generates tangents for
|
||||
Solari compatibility; imported/custom meshes remain visible in diagnostics when they lack
|
||||
|
||||
@@ -74,7 +74,12 @@ Three camera roles coexist:
|
||||
|
||||
The viewport uses **render-to-texture**: the active camera renders to an offscreen HDR target sized to the dock panel (`panel_physical_size()`), then egui displays that texture. Cameras use `viewport = None` on image targets so the scissor always matches the texture; panel size only drives texture allocation, not a sub-viewport on the image.
|
||||
|
||||
**HDR invariant:** The atmosphere/HDR stack (`Atmosphere`, `Hdr`, etc.) must never render to the primary window swapchain (`Rgba8UnormSrgb`). When the HDR offscreen target is missing, `scene_view` / `play` deactivate cameras; `render_view` skips stack sync until a target exists.
|
||||
**HDR invariant:** Atmosphere, authored HDR, and effective Solari all require an `Hdr`
|
||||
camera target; they must never render to the primary window swapchain
|
||||
(`Rgba8UnormSrgb`). When the HDR offscreen target is missing, `scene_view` / `play`
|
||||
deactivate cameras; `render_view` skips stack sync until a target exists.
|
||||
Render-target changes and Solari/Forward fallback changes force a full camera-stack rebuild so
|
||||
stale sky or post-FX pipelines cannot survive across texture-format transitions.
|
||||
|
||||
**Viewport picking:** LMB selection maps the egui panel UV through `scene_view_ray` and raycasts with `MeshRayCast`. Object pick runs in `Last` after `transform_gizmo_bevy` so gizmo drags take priority. `GizmoOptions.viewport_rect` is synced from the viewport panel rect so gizmo hit-testing matches render-to-texture layout. Actor root icon and visualizer proxy hits resolve to their source entity, so clicking an icon or light/spawn/collider marker selects the authored or runtime object, not the helper. Actor icon hits are ordered ahead of ordinary mesh hits when both are under the cursor. In Edit mode, selecting the runtime Player redirects to an authored `PlayerSpawn` (`Player Start`), creating one if needed.
|
||||
|
||||
@@ -139,8 +144,8 @@ On play enter/exit the editor snapshots **player sim state only** (transform, ve
|
||||
1. User edits entities with `LevelObject` + reflectable components from `shared`.
|
||||
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/`.
|
||||
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.
|
||||
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.
|
||||
|
||||
## Model import (glTF + FBX)
|
||||
|
||||
@@ -177,7 +182,7 @@ Shared scene schema lives in `crates/scene` (stamp/migrate/validate on save, loa
|
||||
|
||||
## HDR / swapchain invariant
|
||||
|
||||
The unified viewport renders through an HDR offscreen target (`render_target.rs`). When the panel target is missing (egui reflow) or settings disable HDR, cameras must strip atmosphere/post-FX before targeting the swapchain. `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 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.
|
||||
|
||||
|
||||
@@ -58,9 +58,9 @@ Viewport overlays: **GI badge** (Forward / Solari), **volume HUD** when inside a
|
||||
|------|----------|
|
||||
| Auto | Startup default: Solari when RT GPU support is available; Forward otherwise |
|
||||
| Forward | Bevy Forward PBR with HDR/TAA/SSAO/atmosphere/shadows |
|
||||
| Solari | Request Solari; the camera attaches Bevy Solari when RT support is available and no local shadow-light fallback is required |
|
||||
| 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. 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 or local shadow lights are present. 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.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).
|
||||
|
||||
## Emissive lighting
|
||||
|
||||
@@ -94,12 +94,12 @@ Open `assets/levels/rendering_showcase.scn.ron` for fog, exposure, and vignette
|
||||
| Symptom | Check |
|
||||
|---------|-------|
|
||||
| Point/spot weak at max lumens | Outdoor exposure (~12–15 EV100 in Project Settings) needs much higher lumens than indoor (~7 EV100). Bevy’s reference scale is ~1M lumens (`VERY_LARGE_CINEMA_LIGHT`); inspector allows up to 2M. Narrow spot cones for brighter hotspots. For local lights, GI path must be **Forward** (Solari uses directional + emissive only). |
|
||||
| Point/spot shadows missing under GiMode Auto | Viewport auto-forwards to Forward when shadow-casting point/spot lights exist; check Rendering → Active Camera for “local shadow lights” |
|
||||
| Point/spot controls disabled under GiMode Auto | Auto selected Solari on this GPU. Point/spot `LightDesc` is disabled while Solari is active; switch the light to Directional, use emissive materials, or set GI to Forward. |
|
||||
| Scene sun shadow range wrong vs Project Settings | Scene directionals use `cascade_config_from_rendering`; Apply shadow cascade settings and confirm `sync_scene_directional_shadow_cascades` |
|
||||
| Auto exposure not active | **Rendering → Active Camera**: needs **Exposure: Auto**, HDR on, and GPU compute. Volume **Exposure EV100** override forces manual for that view. |
|
||||
| Viewport black in Lit | Rendering panel → **Runtime lights**, **Stack**, and **Solari raytracing scene**; Collider mode hides meshes |
|
||||
| Solari warming up | Solari raytracing scene readiness: tagged meshes, Solari-compatible mesh assets, render instances, bind group, compatible lights |
|
||||
| Lighting changes do nothing in Solari | Solari samples directional lights and emissive meshes; point/spot lights are Forward-only |
|
||||
| Lighting changes do nothing in Solari | Solari samples directional lights and emissive meshes; point/spot `LightDesc` is disabled while Solari is active |
|
||||
| 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 |
|
||||
|
||||
@@ -69,7 +69,7 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
|
||||
| Rendering panel (Active / Project / Volumes) | Done | Replaces Diagnostics-only view |
|
||||
| Volume inspector inherit/override | Done | `post_process_volume_ui.rs` |
|
||||
| Viewport GI badge + volume HUD + gizmos | Done | `viewport_chrome`, `visualizers` |
|
||||
| Solari + forward fallback | Done | `bevy_solari`, `RenderingCapabilities` |
|
||||
| Solari + Forward fallback | Done | `bevy_solari`, RT fallback, point/spot LightDesc disabled while Solari is active |
|
||||
| Post FX + rendering profile assets | Done | `assets/post_fx/`, `assets/rendering_profiles/` |
|
||||
| Showcase level + docs | Done | `rendering_showcase.scn.ron`, [rendering.md](rendering.md) |
|
||||
|
||||
|
||||
Reference in new issue
Block a user