This commit is contained in:
commit
f29712d158
259 files changed
+52069
No files matched your search
@@ -0,0 +1,34 @@
|
||||
# ADR 0001: Roadmap Architecture
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The project is a Bevy FPS foundation with a runtime game, shared authoring data, and an in-process editor. The long-term goal is a server-authoritative multiplayer FPS that can also serve as a reusable Bevy engine/editor toolkit.
|
||||
|
||||
The architecture needs to keep early editor work productive while avoiding choices that would make later deterministic simulation, networking, and web support expensive.
|
||||
|
||||
## Decision
|
||||
|
||||
Keep the current `game`, `shared`, and `editor` crates for M0/M1, but treat them as stepping stones toward a stricter split:
|
||||
|
||||
- `shared` owns reflectable authoring types and scene hydration until it can be renamed or split into a scene-focused crate.
|
||||
- `game` owns native client presentation, player input, rendering, audio, UI, and glue.
|
||||
- `editor` owns native editor tooling and editor-only dependencies.
|
||||
- Future deterministic gameplay moves out of `game` into a simulation crate that can be reused by the native client, a headless server, and tests.
|
||||
- Future network protocol types move into a protocol crate shared by client and server.
|
||||
- Runtime app startup/windowing stays narrow and reusable so both the game and editor launch consistently.
|
||||
|
||||
## Consequences
|
||||
|
||||
This preserves the current M1 editor velocity while setting boundaries for later milestones. Gameplay code should avoid depending on editor systems, and reusable authoring/simulation code should avoid native-only editor dependencies.
|
||||
|
||||
The project will add CI and focused local verification now, then expand tests around determinism, scene migration, and networking as those crates appear.
|
||||
|
||||
## Follow-Ups
|
||||
|
||||
- M2 extracts deterministic simulation and input-as-intent systems.
|
||||
- M3 adds the server-authoritative networking spike and chooses the production netcode stack.
|
||||
- M5 formalizes scene schema versioning and migrations.
|
||||
@@ -0,0 +1,29 @@
|
||||
# ADR 0002: Bevy Version And Migration Policy
|
||||
|
||||
## Status
|
||||
|
||||
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.
|
||||
|
||||
Unplanned upgrades can break editor work, rendering, scene serialization, physics, and later networking. Delayed upgrades can also make migrations larger and riskier.
|
||||
|
||||
## Decision
|
||||
|
||||
Use the latest stable Bevy release that is supported by the required ecosystem crates for the active milestone. Review Bevy upgrades on a scheduled release cadence instead of opportunistically changing versions during feature work.
|
||||
|
||||
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.
|
||||
- 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.
|
||||
|
||||
## Consequences
|
||||
|
||||
Feature branches should not upgrade Bevy unless the upgrade is their explicit scope. This reduces churn for parallel editor/gameplay work and keeps CI failures easier to attribute.
|
||||
|
||||
The project can still adopt new Bevy releases quickly, but the upgrade is treated as a focused compatibility task with verification and manual runtime checks.
|
||||
@@ -0,0 +1,43 @@
|
||||
# ADR 0003: Editor Framework Mission
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The in-process editor (`crates/editor`) started as a level-editing shell for the FPS foundation. It now includes docked panels, scene I/O, undo/redo, asset browser, real play-in-editor (PIE), and BRP. As milestones M3–M8 add networking, weapons, asset maturity, and modding, the editor must evolve from a game-specific tool into a **reusable Bevy editor framework** without forking gameplay code or duplicating rendering/sim logic.
|
||||
|
||||
Competing approaches:
|
||||
|
||||
1. **Game-only tool** — fastest short-term; blocks reuse and BRP/automation alignment.
|
||||
2. **Separate preview runtime** — simpler isolation; breaks WYSIWYG and doubles maintenance.
|
||||
3. **In-process framework** — same `GamePlugin` + `sim` + shared authoring; editor adds UI, PIE, settings, and BRP only.
|
||||
|
||||
## Decision
|
||||
|
||||
Treat the editor as a **reusable in-process framework** with these commitments:
|
||||
|
||||
- **One world, one sim** — PIE runs the real `GamePlugin`; no preview stub.
|
||||
- **Authoring over runtime** — `shared` components + hydration are the scene source of truth.
|
||||
- **WYSIWYG rendering** — the active viewport camera uses the project rendering profile (`assets/project.ron` via `settings` crate).
|
||||
- **Edit-safe infrastructure** — `EditorOnly` marks editor cameras/helpers; excluded from hierarchy, picking, and save.
|
||||
- **Command-based undo** — structural edits use `EditorHistory`; PIE uses player/sim snapshots, not full-scene rollback when editing during play.
|
||||
- **Native-first, wasm-safe core** — `rfd`, BRP HTTP, and OS dialogs stay in `editor`; `shared`, `sim`, `protocol`, and `settings` remain usable from a future WASM client.
|
||||
- **BRP-aligned, not BRP-dependent** — custom egui UX is primary; scene schema follows Bevy ecosystem conventions for future interop.
|
||||
|
||||
Mission statement and phased roadmap: [`docs/mission.md`](../mission.md), [`docs/editor/roadmap.md`](../editor/roadmap.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
- New editor features should be game-agnostic where possible (viewport, PIE, settings, history).
|
||||
- Game-specific panels register through an extensibility API (`EditorPlugin`) rather than hard-coding in `ui/mod.rs`.
|
||||
- Project settings live in a dedicated `settings` crate, not scattered consts in `sim` and `game`.
|
||||
- Documentation updates are required when changing editor behavior (see `.cursor/rules/documentation.mdc`).
|
||||
- Shipping the editor binary to players remains out of scope; BRP stays editor-only.
|
||||
|
||||
## Follow-Ups
|
||||
|
||||
- M1.5: project settings, shared camera FX, PIE possess/eject.
|
||||
- M5: asset database and prefab workflow in editor.
|
||||
- M6: `EditorPlugin` trait, command registry, BRP automation surface.
|
||||
@@ -0,0 +1,48 @@
|
||||
# ADR 0004: Editor Gameplay Hot Reload
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Iterating on FPS controller feel (sim movement, player input, camera presentation) required restarting the entire editor after every Rust change. Full restarts are slow (GPU init, egui layout, scene reload) and break flow.
|
||||
|
||||
Competing approaches:
|
||||
|
||||
1. **Full editor restart** — simple; too slow for gameplay iteration.
|
||||
2. **Subprocess game binary** — preserves editor shell; breaks in-process viewport render-to-texture (cross-process GPU sharing).
|
||||
3. **In-process dylib hot reload** — keeps one world and PIE model; swaps gameplay function bodies via [`hot-lib-reloader`](https://github.com/rksm/hot-lib-reloader-rs).
|
||||
|
||||
## Decision
|
||||
|
||||
Add dev-only **in-process hot reload** for the full `GamePlugin` surface:
|
||||
|
||||
| Layer | Crate | Hot reload? |
|
||||
|-------|-------|-------------|
|
||||
| Components, resources, TypeIds | `protocol`, `shared`, `settings`, `sim` | Static (never swapped) |
|
||||
| Gameplay system bodies | `game_hot` (cdylib + rlib) | Yes |
|
||||
| Plugin registration shell | `game`, `editor` | Static |
|
||||
| Editor UI | `editor` | Static |
|
||||
|
||||
Implementation:
|
||||
|
||||
- [`crates/game_hot`](../../crates/game_hot) holds `#[unsafe(no_mangle)]` systems (sim, player, world, rendering bootstrap).
|
||||
- [`game`](../../crates/game) registers systems once; with `hot-reload` feature, [`hot_module`](../../crates/game/src/lib.rs) wraps dylib functions.
|
||||
- [`editor`](../../crates/editor) `HotReloadPlugin` (enabled via `dev` feature) polls `LibReloadObserver`, watches the dylib with `notify`, shows status in the bottom bar, and supports **Ctrl+Shift+R** manual refresh.
|
||||
- `on_hot_reload` re-applies idempotent bootstrap (camera FX tags, ambient light); spawns guard against duplicate player/world entities.
|
||||
|
||||
Release builds omit `hot-reload`; shipped game binary links `game_hot` statically.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Gameplay iteration no longer requires editor restart for logic-only changes.
|
||||
- Component layout or schedule graph changes still require a full restart (documented in README).
|
||||
- Linux uses a single `target/` directory; Windows may need separate bin/dylib target dirs to avoid DLL locking (follow-up).
|
||||
- `dev` feature on editor implies `hot-reload` (not optional in daily dev workflow).
|
||||
|
||||
## Related
|
||||
|
||||
- [Editor architecture](../editor/architecture.md)
|
||||
- [Editor roadmap — Phase 3](../editor/roadmap.md)
|
||||
- [ADR 0003: Editor Framework Mission](0003-editor-framework-mission.md)
|
||||
@@ -0,0 +1,21 @@
|
||||
# ADR 0005: Prefab Instance and Asset Registry
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Editor prefab placement and content pipeline work (H1/H2) require stable asset identity across sessions. The asset browser previously regenerated UUIDs on every sync, breaking references.
|
||||
|
||||
## Decision
|
||||
|
||||
- Persist stable `AssetId` (UUID) per `assets/` path in `assets/.index/registry.ron`.
|
||||
- Introduce `PrefabInstance { asset_id, source_path, overrides_ron }` on placed prefab roots alongside hydration via `PrefabRef`.
|
||||
- Scene save includes `PrefabInstance` and gameplay marker components from `shared`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Prefab paths can be resolved through the registry for dependency tracking.
|
||||
- Override apply/revert (H2) builds on `overrides_ron` without changing the instance component shape.
|
||||
- Registry must be version-controlled with the project.
|
||||
@@ -0,0 +1,20 @@
|
||||
# ADR 0006: Scene Schema Versioning
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Levels under `assets/levels/` need forward-compatible migrations as authoring components evolve (M5).
|
||||
|
||||
## Decision
|
||||
|
||||
- Track `schema_version` in scene files (wrapper or sidecar during transition).
|
||||
- Provide `scene_schema` module with `migrate_scene_text` and `validate_level_file`.
|
||||
- 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.
|
||||
@@ -0,0 +1,20 @@
|
||||
# ADR 0007: EditorPlugin Extensibility
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Game-specific UI (weapons panel, net HUD) must not grow `crates/editor/src/ui/mod.rs` indefinitely (M6 / H5).
|
||||
|
||||
## Decision
|
||||
|
||||
- Formalize `EditorPlugin` and `EditorCommand` traits in `extensibility.rs`.
|
||||
- Game crates register plugins at startup via `register_editor_plugin`.
|
||||
- Command palette and BRP dispatch through named command ids (`play.toggle`, etc.).
|
||||
|
||||
## Consequences
|
||||
|
||||
- Third-party panels register without forking core editor UI.
|
||||
- Command registry remains the single invocation surface for palette + automation.
|
||||
@@ -0,0 +1,41 @@
|
||||
# ADR 0008: Editor Module Boundaries and lib/bin Split
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The in-process editor grew to ~15k LOC in a flat `src/` root with manual plugin tuples in `main.rs`. Stubs, domain logic, and UI cross-cuts lived side by side, making navigation, review, and repeat render-target bugs harder to prevent (see Outstanding Issues Audit Phase A).
|
||||
|
||||
## Decision
|
||||
|
||||
1. **lib + bin split:** `crates/editor` exposes `editor` as a library (`src/lib.rs`) with a thin binary (`src/bin/main.rs`) that calls `configure_editor_app` and `register_game_editor_plugins`.
|
||||
|
||||
2. **Domain modules** under `src/` with flat re-exports at the crate root for stable `crate::scene_io` paths:
|
||||
- `scene/` — I/O, schema plugin, viewport render-target setup
|
||||
- `viewport/` — camera, selection, gizmos, render views, panel settings
|
||||
- `play/` — PIE session, editor mode state, net editor profiles
|
||||
- `assets/` — catalog, asset DB, prefab overrides
|
||||
- `project/` — workspace, project I/O, settings UI
|
||||
- `ext/` — extensibility, BRP, command queue, game panel adapters, hot reload
|
||||
- `history/` — undo commands + plugin (commands in submodule)
|
||||
- `ui/` — egui shell (asset browser split into submodules)
|
||||
|
||||
3. **`EditorPluginGroup`** in `lib.rs` is the single ordered plugin registration surface. Order is documented in `docs/editor/architecture.md`.
|
||||
|
||||
4. **Shared `scene` crate** owns schema stamp/migrate/validate; editor save/load and `xtask validate-levels` both use it.
|
||||
|
||||
5. **Dependency rules:**
|
||||
- `sim`, `protocol`, `settings`, `shared`, `scene` must not depend on `editor` or `bevy_egui`.
|
||||
- `editor` may depend on `game`; `game` must not depend on `editor`.
|
||||
- Game-specific editor panels register via `game::editor_ext::editor_panel_setups()`; editor wraps them as `EditorPlugin` (ADR 0007).
|
||||
|
||||
6. **Stub policy:** unwired modules live in domain folders (`net_editor`, `prefab_overrides` v2 fields), not at an ambiguous crate root.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Third-party and game panels can embed or extend the editor library without forking the binary.
|
||||
- Domain moves are incremental; flat re-exports avoid wide import churn.
|
||||
- New workspace crates require an ADR update when they cross the dependency rules above.
|
||||
- `cargo test -p editor` becomes viable as logic tests are added to the library.
|
||||
@@ -0,0 +1,22 @@
|
||||
# ADR 0009: Authoring vs hydrated components
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Level data must round-trip through save/load without leaking runtime ECS components (meshes, Bevy lights, physics, scene instances). Editors that expose raw ECS in the main inspector cause users to edit hydrated state that is overwritten on the next hydration pass.
|
||||
|
||||
## Decision
|
||||
|
||||
- **Authoring components** (`Primitive`, `StaticMeshRenderer`, `MaterialDesc`, `MaterialOverride`, `LightDesc`, `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, `ActorKind`, etc.) are the only components written to `.scn.ron`.
|
||||
- **Hydration** in `crates/shared/src/hydration/` generates runtime components in a fixed `Update` chain.
|
||||
- **Save path** uses an explicit `DynamicSceneBuilder` allowlist and `strip_hydrated_entity` on each entity before serialize.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Hydration modules must strip conflicting runtime components before re-insert (especially lights).
|
||||
- Static mesh renderer hydration spawns generated child mesh parts; those children are runtime state, not durable scene entities. Static mesh collision is authored through `ColliderDesc::StaticMesh` and hydrated onto generated mesh children.
|
||||
- Inspector and BRP mutate authoring components only.
|
||||
- CI and unit tests cover strip/hydrate invariants in `shared`.
|
||||
@@ -0,0 +1,22 @@
|
||||
# ADR 0010: ActorKind and inspector architecture
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Inspector panels were routed by `if world.get::<LightDesc>` and mixed with `bevy_inspector_egui` entity dumps, which exposed runtime components and diverged from saved scenes.
|
||||
|
||||
## Decision
|
||||
|
||||
- Every savable `LevelObject` carries a required **`ActorKind`** component (schema v2).
|
||||
- One-shot **`ActorKind` backfill** runs in `crates/scene` migration v1→v2; load-time backfill is a fallback only for unsaved in-memory entities.
|
||||
- **`validate_actor`** runs on save and rejects invalid component sets per kind.
|
||||
- The default **Inspector** tab uses **`actor_inspector`** only (transform first, then authoring panels). No `ui_for_entity_with_children` in production builds.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Spawn/history snapshots always include `actor_kind`.
|
||||
- `DefaultInspectorConfigPlugin` is not registered in the editor app; `bevy-inspector-egui` remains only for `SelectedEntities` until selection is decoupled.
|
||||
- Optional `inspector-debug` feature may add a separate engine ECS tab later—not a second inspector on the same tab.
|
||||
@@ -0,0 +1,21 @@
|
||||
# ADR 0011: Scene lighting policy (project sun vs scene sun)
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
A single scene-authored directional `LightDesc` hides the runtime `ProjectSun`, which can make outdoor levels appear black if lux values are wrong. Project Settings ambient/sun did not always apply live after **Apply**.
|
||||
|
||||
## Decision
|
||||
|
||||
- **`ProjectSun`** is the default outdoor directional; scene-authored directionals override it (existing `sync_project_sun_visibility` behavior).
|
||||
- **Editor commands** (Scene menu + Rendering Diagnostics): *Use project sun* (remove scene directionals) and *Bake scene sun from project* (spawn directional `LightDesc` from current `sun_illuminance`).
|
||||
- On **`ProjectSettingsChanged`**, the editor applies ambient light, `sync_project_sun_illuminance`, and `sync_project_sun_visibility`; render view refreshes via existing `ProjectSettings` change detection.
|
||||
- Legacy directional lux < 1000 is corrected in **schema migration** to `100_000` lux (documented default), not at hydration time.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Status/diagnostics UI should surface sun override state (Rendering Diagnostics panel).
|
||||
- Designers use authoring `LightDesc` units: lumens (point/spot), lux (directional).
|
||||
@@ -0,0 +1,24 @@
|
||||
# ADR 0012: Zero tech debt policy for editor UI
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The production editor program commits to shipping one correct path per feature rather than parallel “temporary” implementations.
|
||||
|
||||
## Decision
|
||||
|
||||
| Anti-pattern | Policy |
|
||||
|--------------|--------|
|
||||
| Dual inspector (ECS dump + authoring) | **Removed** from default Inspector; actor inspector only |
|
||||
| Monolithic hydration | **Replaced** by `shared/hydration/*`; delete old function in same change |
|
||||
| Optional `ActorKind` inference at runtime | **Migration + validation** only; no long-term guesswork |
|
||||
| Deferred sub-phases (“Phase 3b”) | **Not used**; sibling order and related features ship in their named phase |
|
||||
| Dead code after refactor | **Deleted in the same PR** |
|
||||
|
||||
## Consequences
|
||||
|
||||
- Each phase ends with a debt gate (tests green, old path removed, docs updated).
|
||||
- New subsystems get ADR or editor doc entries when behavior is user-visible.
|
||||
@@ -0,0 +1,55 @@
|
||||
# ADR 0013: Rendering tiers and post-process volumes
|
||||
|
||||
## Status
|
||||
|
||||
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.
|
||||
|
||||
## Decision
|
||||
|
||||
### GI tiers
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `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 |
|
||||
|
||||
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.
|
||||
|
||||
### WYSIWYG
|
||||
|
||||
The unified viewport uses the same `ActiveCameraRenderProfile` resolution path for the editor fly camera and the possessed player camera, so authors see the blended stack in both modes.
|
||||
|
||||
### Post-process volumes
|
||||
|
||||
- **Shape:** axis-aligned box in entity local space (`half_extents` on `PostProcessVolumeDesc`).
|
||||
- **Priority:** higher `priority` wins overlaps; equal priority → stable entity-id tie-break.
|
||||
- **Edge blend:** weight fades from 1 at center to 0 at faces over `blend_distance`.
|
||||
- **Override model:** each FX field is `None` = inherit project, `Some(v)` = override (prefab-style).
|
||||
- **Custom FX:** one active fullscreen effect from the highest-priority contributing volume.
|
||||
- **Non-goals v1:** baked GI, multi-shader stacks, per-mesh post FX.
|
||||
|
||||
### Crate boundaries
|
||||
|
||||
| Crate | Owns |
|
||||
|-------|------|
|
||||
| `settings` | `RenderingSettings`, `GiMode`, `ActiveCameraRenderProfile`, capabilities types, save/load |
|
||||
| `shared` | `PostProcessVolumeDesc`, overrides, reflect registration, asset RON types |
|
||||
| `game_hot` | Profile resolver, camera component application, Solari path, fullscreen effects |
|
||||
| `editor` | All egui: Project Settings, Rendering panel, inspector, visualizers, commands |
|
||||
|
||||
Authoring is saved to disk; BRP mutates authoring only ([ADR 0009](0009-authoring-vs-hydrated.md)). No egui in `settings`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- `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.
|
||||
@@ -0,0 +1,38 @@
|
||||
# ADR 0014: Unified Viewport Model
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The editor previously exposed separate Scene View and Game View tabs. They used separate offscreen
|
||||
targets and UI paths even though only one 3D camera could safely own the full project rendering
|
||||
stack at a time. This made Play-in-editor feel inconsistent: entering Play changed tabs, editor
|
||||
overlays were controlled separately from player rendering, and future multi-viewport work had to
|
||||
account for two special-case primary panels.
|
||||
|
||||
## Decision
|
||||
|
||||
The editor has one primary **Viewport** tab backed by one HDR `ViewportRenderTarget`.
|
||||
|
||||
- Edit mode and Play-ejected bind the editor fly camera to the viewport target.
|
||||
- Play-possessed binds the player camera to the same viewport target.
|
||||
- `render_view.rs` continues to move the project render stack to exactly one active 3D camera.
|
||||
- `G` toggles a clean game-view overlay that hides editor chrome, grid, selection outlines,
|
||||
transform gizmos, visualizers, and selectable proxies without changing camera ownership.
|
||||
- `Ctrl+G` toggles the grid.
|
||||
- Saved dock layouts containing the old Game View tab are migrated to one Viewport tab.
|
||||
- Multi-viewport support is represented as future-facing state/API shape only; secondary visible
|
||||
viewports remain future work.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Play starts in place instead of switching to a Game View tab.
|
||||
- Camera ownership is explicit: F8 possession selects player camera vs editor camera; G only hides
|
||||
editor overlays.
|
||||
- The HDR/swapchain invariant remains centralized around one offscreen viewport target.
|
||||
- Future secondary viewports should add viewport-id keyed rects, targets, cameras, and overlay state
|
||||
rather than reintroducing a Scene View/Game View split.
|
||||
- Post-FX and GI on the active viewport camera are owned by `game_hot::rendering::viewport_camera`
|
||||
(see [ADR 0015](0015-viewport-camera-stack-ownership.md)); editor systems must not strip the stack.
|
||||
@@ -0,0 +1,40 @@
|
||||
# ADR 0015: Viewport camera stack ownership
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
ADR 0014 unified the editor viewport render target and camera binding, but post-processing and GI
|
||||
components were still stripped in multiple places (`scene_view`, play session, and full strip/reapply
|
||||
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.
|
||||
|
||||
Scene directionals hydrated with hardcoded cascade bounds that did not match project shadow settings
|
||||
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.).
|
||||
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
|
||||
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).
|
||||
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.
|
||||
|
||||
## 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)”.
|
||||
- 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.
|
||||
@@ -0,0 +1,49 @@
|
||||
# ADR 0016: Unified rendering contract
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Rendering state crossed settings, hydration, game runtime, Solari readiness, editor viewport
|
||||
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
|
||||
`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.
|
||||
|
||||
## Decision
|
||||
|
||||
- `settings` owns the neutral render-stack contract:
|
||||
`ActiveCameraRenderProfile` is requested intent, and `EffectiveRenderStack` records requested GI,
|
||||
effective GI, Solari readiness, local shadow-light state, and fallback reason.
|
||||
- `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.
|
||||
- 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.
|
||||
- Material authoring includes emissive color, intensity, and texture fields so scenes can create
|
||||
Solari-compatible emissive contributors without Rust changes.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Diagnostics must report requested GI, effective GI, and fallback reason from
|
||||
`EffectiveRenderStack` rather than deriving labels independently.
|
||||
- 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
|
||||
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
|
||||
contract change.
|
||||
@@ -0,0 +1,32 @@
|
||||
# ADR 0017: Normalized Static Mesh Assets
|
||||
|
||||
## Status
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Decision
|
||||
|
||||
Model imports now generate deterministic project artifacts under `assets/meshes/generated/*.static_mesh.ron`. The artifact records stable part IDs, source path, format, source fingerprint, import settings, mesh/material subasset labels, source node/material metadata, dependency paths, and warnings for metadata that is not played by the static mesh path.
|
||||
|
||||
The saved scene authoring component is `StaticMeshRenderer`. Its slots reference imported mesh/material assets by `EditorAssetRef` (`asset_id` + `sub_asset_id`) rather than source file paths. Hydration resolves those refs through the generated artifact, spawns runtime child `Mesh3d` parts, and strips/regenerates them like other hydrated ECS. Built-in primitives remain `Primitive`, and explicit full-scene placement remains `ImportedModel + ModelRef`.
|
||||
|
||||
Asset import settings choose the default placement mode:
|
||||
|
||||
- `StaticAsset` creates `ActorKind::StaticMesh + StaticMeshRenderer`; when collider generation is enabled it also creates `RigidBodyDesc + ColliderDesc::StaticMesh`.
|
||||
- `SceneInstance` creates the legacy `ActorKind::ImportedModel + ModelRef`.
|
||||
|
||||
Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts into one renderer. `SourceHierarchy` creates an authored root with child static mesh actors.
|
||||
|
||||
## Consequences
|
||||
|
||||
- glTF/GLB and FBX placement consume the same renderer contract after processing.
|
||||
- Scene files store renderer intent, not runtime Bevy mesh/material handles.
|
||||
- Static mesh actors can expose renderer slots, source labels, shadows, collider policy, and material overrides in the inspector.
|
||||
- Animated/skinned playback remains on the scene-instance path until a future animation authoring component exists.
|
||||
- Generated artifacts are project files but are hidden from the Asset Browser catalog to avoid treating them as levels/prefabs.
|
||||
@@ -0,0 +1,57 @@
|
||||
# ADR 0018: Componentized actor inspector and material overrides
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Context
|
||||
|
||||
The actor inspector had started to expose too many unrelated concerns through a
|
||||
single static mesh renderer entry: source model paths, mesh labels, material
|
||||
overrides, shadow flags, and collider generation. That made imported FBX/glTF
|
||||
actors look format-specific and prevented a Unity-style component list where
|
||||
rendering, collision, rigid body state, and material overrides are separate
|
||||
authoring concepts.
|
||||
|
||||
The editor component system spec also requires stable actor/component IDs,
|
||||
registered editor-visible components, Transform pinned at the top, and an Add
|
||||
Component footer rather than an ad hoc button near Transform.
|
||||
|
||||
## Decision
|
||||
|
||||
- Actors now have stable editor-facing identity components (`ActorId`,
|
||||
`ActorName`) and repeatable authoring items use `ComponentInstanceId`.
|
||||
- Editor-visible actor components are described by an
|
||||
`EditorComponentRegistry`; the Add Component footer reads from this registry.
|
||||
- `InspectorOrder` stores editor component order plus per-component active
|
||||
state. Collapse state is session-only UI state; active state is persisted with
|
||||
the scene and is undoable.
|
||||
- `StaticMeshRenderer` stores `MeshRenderSlot` values that reference imported
|
||||
content-browser assets through `EditorAssetRef { asset_id, sub_asset_id,
|
||||
label }`. Actor renderer data does not store source FBX/glTF paths.
|
||||
- Static mesh hydration resolves `EditorAssetRef` through generated artifacts in
|
||||
`assets/meshes/generated/`.
|
||||
- Collision and rigid body state are separate authoring components:
|
||||
`ColliderDesc` and `RigidBodyDesc`. Mesh collider generation creates
|
||||
`ColliderDesc::StaticMesh` instead of renderer collider flags.
|
||||
- Materials are shader-schema aware. `MaterialDesc` stores a `ShaderRefDesc`,
|
||||
typed shader parameters, and texture bindings. Actor-level material edits are
|
||||
stored in `MaterialOverride`; shared material assets remain content-browser
|
||||
assets.
|
||||
|
||||
## Consequences
|
||||
|
||||
- New model placement creates `StaticMeshRenderer` plus optional
|
||||
`RigidBodyDesc`/`ColliderDesc`; legacy `PhysicsBody` remains loadable for old
|
||||
scenes.
|
||||
- Actor inspectors show imported asset selectors for mesh/material slots instead
|
||||
of source-path text fields.
|
||||
- Disabling a component in the inspector keeps its authoring data but prevents
|
||||
hydration/runtime systems from using it. Mesh, material, light, physics, and
|
||||
post-process hydration strip stale runtime components when active state
|
||||
changes.
|
||||
- Existing static mesh artifacts without part IDs are still resolved by deriving
|
||||
stable sub-asset IDs from loader labels.
|
||||
- Custom shader support is schema-driven; v1 stores and edits typed parameters,
|
||||
while runtime rendering currently maps built-in Lit/Unlit through Bevy
|
||||
`StandardMaterial`.
|
||||
Reference in new issue
Block a user