Initial project import
CI / Format, lint, test, build (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-06-05 21:44:45 -04:00
commit f29712d158
259 files changed
+52069

No files matched your search

+72
View File
@@ -0,0 +1,72 @@
# Project Documentation
Central index for design decisions, mission, and editor framework docs. Agents and contributors should keep this map current—see [`.cursor/rules/documentation.mdc`](../.cursor/rules/documentation.mdc).
## Core
| Document | Purpose |
|----------|---------|
| [mission.md](mission.md) | Why the editor framework exists, principles, audience, non-goals |
| [../README.md](../README.md) | Run/build instructions, controls, implementation checklist |
## Architecture Decision Records (ADRs)
Immutable-style log of significant decisions. Add a new numbered ADR when changing boundaries, formats, or policies.
| ADR | Topic |
|-----|-------|
| [0001](adr/0001-roadmap-architecture.md) | Crate split, sim/protocol direction, milestone north star |
| [0002](adr/0002-bevy-version-and-migration-policy.md) | Bevy upgrade cadence and verification |
| [0003](adr/0003-editor-framework-mission.md) | Editor as reusable in-process framework |
| [0004](adr/0004-editor-hot-reload.md) | Dev-only `game_hot` dylib hot reload |
| [0005](adr/0005-prefab-instance-and-asset-registry.md) | Prefab instances + stable asset registry |
| [0006](adr/0006-scene-schema-versioning.md) | Scene schema versioning and validation |
| [0007](adr/0007-editor-plugin-extensibility.md) | EditorPlugin extensibility surface |
| [0008](adr/0008-editor-module-boundaries.md) | Editor domain modules, lib/bin split, plugin group |
| [0009](adr/0009-authoring-vs-hydrated.md) | Authoring vs hydrated components; strip-on-save |
| [0010](adr/0010-actor-kind-and-inspector.md) | ActorKind, validation, actor inspector |
| [0011](adr/0011-scene-sun-policy.md) | Project sun vs scene directional policy |
| [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 |
| [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 |
## Editor framework
| Document | Purpose |
|----------|---------|
| [editor/release-notes.md](editor/release-notes.md) | Editor framework 1.0 baseline |
| [editor/evaluations/](editor/evaluations/) | Horizon gate sign-offs (R1–R6) |
| [editor/architecture.md](editor/architecture.md) | Viewport / PIE / settings data flow |
| [editor/roadmap.md](editor/roadmap.md) | Phased editor roadmap and status |
| [editor/brp.md](editor/brp.md) | BRP automation and authoring-only policy |
| [editor/debt-audit.md](editor/debt-audit.md) | Zero-debt phase gates |
## Working plans (not canonical long-term)
Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans/). Promote stable outcomes into ADRs or `docs/` when shipped.
| Plan | Topic |
|------|-------|
| `project_roadmap_*.plan.md` | M0–M8 program index |
| `editor_framework_mission_roadmap_*.plan.md` | Editor mission + phased roadmap |
| `project_settings_and_pie_eject_*.plan.md` | M1.5: settings, rendering parity, PIE eject |
| `rendering_unification_*.plan.md` | Unified rendering stack, Hybrid Auto GI, emissive materials |
| `static_mesh_asset_refactor_*.plan.md` | Static mesh renderer, normalized model artifacts, inspector redesign |
| `component_system_refactor_*.plan.md` | Component registry, imported asset refs, collider split, material overrides |
## Crate responsibilities (quick reference)
```
crates/protocol/ Tick rate, input intent, message shapes
crates/sim/ Fixed-step gameplay; no rendering
crates/shared/ Authoring components + hydration
crates/game/ Client presentation, GamePlugin, rendering
crates/editor/ In-process egui editor, BRP, PIE
crates/settings/ Project settings, active/effective render profile contracts
```
When adding a crate or moving responsibilities, update this table and ADR 0001 (or a follow-up ADR).
+34
View File
@@ -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.
+43
View File
@@ -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.
+48
View File
@@ -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.
+20
View File
@@ -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.
+41
View File
@@ -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.
+22
View File
@@ -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`.
+22
View File
@@ -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.
+21
View File
@@ -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 &lt; 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).
+24
View File
@@ -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.
+38
View File
@@ -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`.
@@ -0,0 +1,353 @@
# Tech Spec: Unity-style Component List for a Bevy Level Editor
## Purpose
The component list is the main authoring UI for a selected **Actor** in the level. In this editor, an **Actor** is a Bevy `Entity` plus editor-facing metadata: stable ID, display name, hierarchy position, prefab/link info, and a curated list of inspectable components.
The inspector should feel similar to Unity:
```text
Actor Header
Transform
Component A
Component B
Component C
...
Sticky Footer:
Search components...
+ Add Component
```
The Add Component button belongs at the bottom of the component stack, not under Transform.
## Core Rules
- Bevy components are the source of truth.
- The editor exposes components through a registry.
- Inspector ordering is editor metadata, not ECS truth.
- Transform is pinned to the top.
- Runtime systems must never depend on inspector order.
## Actor Model
Each actor should contain:
```rust
Actor
ActorName
InspectorOrder
```
Use stable IDs for save files:
```text
ActorId
Stable identity persisted to disk.
Entity
Runtime-only ECS identity.
ComponentInstanceId
Stable identity for repeatable authoring items.
```
Never serialize raw Bevy Entity IDs into level files.
## Component Registry
Every editor-visible component should be registered.
```rust
pub struct EditorComponentDescriptor {
pub type_name: &'static str,
pub display_name: &'static str,
pub addable: bool,
pub removable: bool,
pub reorderable: bool,
}
```
The registry controls:
- Visibility
- Addability
- Removal rules
- Custom inspectors
- Search metadata
- Categories
## Inspector Layout
Single-column layout only.
```text
Header
Transform
Static Mesh Renderer
Physics
Audio
Gameplay
---------------------
Search Components...
+ Add Component
```
The footer remains visible while scrolling.
## Component Cards
Each component contains:
```text
[Enabled]
[Collapse Arrow]
[Icon]
Component Name
[Dirty Indicator]
[Menu]
```
Menu actions:
- Reset
- Copy
- Paste Values
- Move Up
- Move Down
- Remove
- Open Documentation
Transform is special:
- Cannot remove
- Cannot move
- Can reset
## Add Component Flow
```text
Open Palette
Search
Select Component
Create Default Instance
Insert Component
Expand Component
Mark Dirty
Push Undo Command
```
The component palette supports:
- Search
- Categories
- Favorites
- Recent Components
- Compatibility Checks
## Asset Selectors
Assets should never look like plain text boxes.
Bad:
```text
Mesh: assets/models/Dumpster.fbx
```
Good:
```text
[Preview Thumbnail]
Mesh1000
Dumpster.fbx
[Browse]
[Locate]
[Clear]
```
Asset selector requirements:
- Thumbnail preview
- Drag/drop support
- Open in asset browser
- Missing asset warnings
- Type filtering
## Static Mesh Renderer
Recommended structure:
```rust
pub struct StaticMeshRenderer {
pub slots: Vec<MeshRenderSlot>,
}
```
Each slot:
```rust
pub struct MeshRenderSlot {
pub id: ComponentInstanceId,
pub mesh: EditorAssetRef,
pub material: EditorAssetRef,
}
```
Inspector:
```text
Static Mesh Renderer
▼ Slot 0 Dumpster
Mesh Selector
Material Selector
Collider Settings
▼ Slot 1 Dumpster Lid
Mesh Selector
Material Selector
▶ Slot 2 Dumpster Lid_02
+ Add Slot
```
Collapsed slots reduce inspector height.
## Property Drawing
Generic reflection is the fallback.
Custom inspectors should exist for:
- Transform
- Static Mesh Renderer
- Materials
- Physics
- Audio
- Navigation
Useful field metadata:
```rust
#[editor(min = 0.0)]
#[editor(max = 100.0)]
#[editor(unit = "m/s")]
```
## Serialization
Recommended level structure:
```rust
LevelAsset
Actors[]
ActorRecord
Components[]
```
Separate:
- Runtime Components
- Editor Components
- Transient Components
## Undo / Redo
Every change becomes a command.
```rust
trait UndoableCommand {
fn apply();
fn undo();
}
```
Examples:
- Set Position
- Assign Mesh
- Assign Material
- Add Component
- Remove Component
Numeric dragging should create one undo record.
## Multi-Selection
Support:
- Common Components
- Mixed Values
- Batch Editing
Example:
```text
Position
X —
Y 0.0
Z —
```
## Prefab Overrides
Fields can be:
- Inherited
- Overridden
- Added
- Removed
Visual indicators:
```text
Blue Dot
Field Override
Bold Component
Component Override
```
Use stable slot IDs for overrides instead of array indices.
## Component Categories
```text
Rendering
Physics
Audio
Gameplay
Navigation
Scripting
Editor
```
Support:
- Favorites
- Recently Used
- Plugin Components
## Acceptance Criteria
- Single-column inspector.
- Transform pinned to top.
- Sticky bottom Add Component footer.
- Asset selectors with previews.
- Searchable component palette.
- Undo/redo for every edit.
- Stable Actor IDs.
- Multi-selection support.
- Prefab override support.
- Inspector order independent from ECS runtime behavior.
+60
View File
@@ -0,0 +1,60 @@
# Editor Framework Documentation
Docs for the in-process egui editor (`crates/editor/`). Update this index when adding editor subsystems.
## Documents
| Document | Contents |
|----------|----------|
| [roadmap.md](roadmap.md) | Phased editor work and status |
| [architecture.md](architecture.md) | Plugins, cameras, PIE, settings split |
| [brp.md](brp.md) | Remote protocol, authoring-only policy, commands |
| [debt-audit.md](debt-audit.md) | Zero-debt phase gates and remaining items |
| [rendering.md](rendering.md) | GI modes, post-process volumes, presets, post FX assets |
## Subsystems (code → doc)
| Code module | Responsibility | Doc |
|-------------|----------------|-----|
| `lib.rs` / `EditorPluginGroup` | Ordered plugin bundle, lib/bin split | ADR 0008, architecture.md |
| `scene/` | Level I/O, schema, viewport render-target setup | architecture.md |
| `viewport/` | Camera, selection, gizmos, render views | architecture.md |
| `play/` | PIE session, editor mode state | architecture.md |
| `assets/` | Catalog, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), ADR 0017 |
| `project/` | Workspace, settings UI, user prefs | roadmap Phase 1 |
| `ext/` | Command palette, BRP, game panel adapters | ADR 0007 |
| `ui/mod.rs` | Dock layout, unified viewport, menus | README controls |
| `ui/component_registry.rs` | Editor-visible component descriptors and Add Component palette metadata | ADR 0018 |
| `ui/asset_browser/` | Asset Browser tree, grid/list, details | roadmap Phase 4b |
| `history/` | Undo/redo command stack | README controls |
| `crates/scene` | Schema stamp/migrate/validate (shared) | ADR 0006, ADR 0008 |
| `ext/extensibility.rs` | Command registry, `ActorInspectorSection`, palette | Phase 6 |
| `ext/game_inspector.rs` | Game-registered inspector sections | Phase 6 |
## Design intentions (stable)
- **EditorOnly** helper entities never appear in hierarchy or saved scenes. Visualizer proxies are editor-only but selectable; selection resolves to their source entity.
- **Dedicated egui `Camera2d`** at full window — never attach `PrimaryEguiContext` to a viewport-cropped 3D camera (NaN layout panic).
- **Unified viewport** uses one render-to-texture target for both the editor fly camera and the possessed player camera so HDR/atmosphere is not broken by sub-viewport cropping.
- **PIE:** F8 possess/eject while sim runs; **F6** pauses/resumes simulation in Play; project settings drive shared rendering for the active viewport camera.
- **Asset browser** mirrors the on-disk `assets/` directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture and model thumbnails (`AssetThumbnailCache::request_model`), and a compact details pane; narrow docks prioritize content, wrap toolbar/footer controls, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree and asset content panels scroll. **Built-ins** holds spawnable primitives and lights. **Materials** folder scans `assets/materials/*.ron`; **Shaders** holds shader schema RON files. glTF/GLB/FBX details expose static asset vs scene-instance placement, hierarchy mode, material policy, collider generation, and the generated static mesh artifact path.
- **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.
- **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 write `MaterialOverride` entries keyed by renderer slot ID; 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).
- **Theme selections** use explicit high-contrast selected text and muted blue fills so hierarchy, asset browser, and inspector selection rows stay readable.
- **Hierarchy** shows authored objects plus useful runtime context (`Player`, `PlayerCamera`, Project Sun) while keeping runtime rows read-only.
- **Player placement** is authored through `PlayerSpawn`; selecting the runtime player in Edit mode redirects to a saved `Player Start`.
- **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 a pinned bottom Add Component footer (`actor_inspector`); 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. `StaticMeshRenderer` uses concept-style slot cards with model thumbnails, imported mesh/material selectors, visibility, shadow flags, and per-actor material overrides. Empty actor 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`): `scene.reset_lighting`, `rendering.create_volume`, `rendering.select_volumes_at_camera`, `rendering.focus_active_volumes`, `selection.group`, `selection.focus`, and play commands.
- **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.
- **Clean game-view overlay** (`G`) hides editor chrome, grid, selection outlines, transform gizmos, actor root icons, visualizers, and selectable proxies without changing camera ownership; `Ctrl+G` toggles grid.
- **Viewport shading** (toolbar): **Lit** (default WYSIWYG), **Unlit** (base-color debug), **Colliders** (hide meshes, emphasize collider gizmos). Light gizmos show range spheres, spot cones, and directional sun arrows. A **mode badge** (bottom-right of the viewport) shows the active mode; Collider mode displays a warning banner.
- **Hierarchy** sort modes (**Manual**, **Name**, **Type**) use stable tie-breakers so duplicate names (e.g. several `Pillar` rows) do not reorder on every click. Drag-and-drop reparenting disables panel scroll-to-drag; drop indicators appear only while dragging.
- **Viewport picking**: click selects nearest object, actor root icon, or visualizer hit; **Tab** cycles overlapping targets at the last click (selection pin deferred).
- **Settings data** lives in `crates/settings`; **settings UI** lives in `settings_ui.rs`.
When implementing or changing any of the above, update this file and the root README in the same change.
+183
View File
@@ -0,0 +1,183 @@
# Editor Architecture
High-level layout of the in-process editor binary (`crates/editor`). For mission and phased work see [roadmap.md](roadmap.md) and [mission.md](../mission.md).
## Crate boundaries
```
editor/ egui UI, PIE, BRP, scene I/O, editor-only cameras, hot-reload (dev)
└─ uses ──► game/ GamePlugin shell, re-exports
game_hot/ Hot-reloadable gameplay systems (cdylib; dev)
settings/ assets/project.ron, SimTuning, camera FX profile
shared/ Authoring components, hydration types
sim/ Components + resources (TypeIds stay static)
protocol/ Input intent (network-ready)
```
Native-only dependencies (`rfd`, BRP HTTP) stay in `editor`. `settings`, `shared`, `sim`, and `protocol` must remain usable from a future WASM client.
## Plugin graph (startup order matters)
| Plugin | Role |
|--------|------|
| `GamePlugin` | Shared runtime: rendering, player, sim schedule |
| `ProjectSettingsPlugin` | Load `assets/project.ron`, emit changes, sync `SimTuning` |
| `ProjectIoPlugin` | User prefs, workspace metadata, window title inputs |
| `EditorStatePlugin` | `EditorMode` (Edit/Play), `PlayPossession`, camera/input gating |
| `ViewportPlugin` | Grid, focus, bookmarks, snap settings |
| `EditorCameraPlugin` | Fly camera; FX applied via `render_view` + `viewport_camera` sync |
| `ActorIconsPlugin` | Selectable actor root billboard icons |
| `EditorVisualizersPlugin` | Collider/light/spawn/prefab/runtime visualizers and selectable proxies |
| `SceneIoPlugin` | Level New/Open/Save, recent paths |
| `SettingsUiPlugin` | egui Project Settings panel |
| `EditorUiPlugin` | Dock, themed egui shell, viewport overlays, menus, status bar |
| `BrpPlugin` | Bevy Remote Protocol HTTP (editor-only) |
| `HotReloadPlugin` | Dev-only: `game_hot` dylib watch + status bar (`--features dev`) |
## Hot reload (dev)
Gameplay system bodies live in [`game_hot`](../../crates/game_hot) as a `cdylib`. Stable component/resource TypeIds remain in `sim` / `protocol` / `shared` / `settings` so ECS inserts stay valid after reload (see [ADR 0004](../adr/0004-editor-hot-reload.md)).
| Piece | Location |
|-------|----------|
| Hot system implementations | `crates/game_hot/src/` |
| Schedule registration + hot wrappers | `crates/game/src/lib.rs` (`hot-reload` feature) |
| Dylib poll, notify watcher, Ctrl+Shift+R | `crates/editor/src/hot_reload.rs` |
| Status bar label | `ui/status_bar.rs` |
Workflow: run `cargo watch … build -p game_hot` in one terminal, `cargo run -p editor --features dev` in another. Logic-only edits apply without restarting the editor; component layout changes still need a full restart.
## Settings split (maintainability)
| Concern | Location |
|---------|----------|
| Serializable project data | `crates/settings` — `ProjectSettings`, save/load |
| Path + dirty flag | `ProjectSettingsIo` resource |
| Panel open/close | `ProjectSettingsPanel` in `settings_ui.rs` |
| Live apply to sim/rendering | `ProjectSettingsChanged` message (draft edits commit on Apply) |
Do not add egui or editor-only state to the `settings` crate.
## Camera and viewport model
See [ADR 0014](../adr/0014-unified-viewport-model.md) for the unified viewport decision.
Three camera roles coexist:
1. **Editor fly camera** (`EditorCamera`) - active while editing or ejected from PIE.
2. **Player camera** - active while playing + possessed.
3. **egui overlay camera** (`PrimaryEguiContext`) - full-window `Camera2d`; never viewport-cropped. Attaching egui to a cropped 3D camera causes NaN layout panics.
**Unified viewport:** one docked **Viewport** tab owns the primary offscreen HDR target (`ViewportRenderTarget`). Edit mode and Play-ejected bind the editor fly camera to that target; Play-possessed binds the player camera to the same target. Saved layouts with the old Game View tab are migrated to one Viewport tab.
**WYSIWYG rendering:** `render_view.rs` is the only editor system that mutates viewport post-FX. It calls `game_hot::sync_viewport_camera_stack` on the active camera (editor fly or possessed player), driven by `ActiveCameraRenderProfile` from project settings and volumes plus `EffectiveRenderStack` for requested/effective GI fallback. `scene_view` and `play/session` set HDR render targets and `is_active` only—they do not strip FX. Only one camera carries the stack at a time (mesh-view bind group limits). See [ADR 0015](../adr/0015-viewport-camera-stack-ownership.md) and [ADR 0016](../adr/0016-unified-rendering-contract.md).
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.
**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. In Edit mode, selecting the runtime Player redirects to an authored `PlayerSpawn` (`Player Start`), creating one if needed.
**Selection overlay:** `selection_outline.rs` draws a shared unit-box shell per selected `LevelObject` (bounds from `Primitive`, physics collider, or mesh AABB), scaled to fit. Custom shader (`assets/shaders/selection_outline.wgsl`) uses rim-only fresnel with two cheap depth passes: `Greater` (soft cyan x-ray) and `LessEqual` (amber edge). Sync runs only when selection changes. Editor-only.
**Clean game-view overlay:** `ViewportDisplayMode.clean_game_view` hides editor chrome, grid, selection outlines, transform gizmos, actor root icons, visualizers, and selectable proxy meshes without changing camera ownership. `G` toggles this mode; `Ctrl+G` toggles the grid.
**Actor root icons:** `actor_icons.rs` registers the editor PNG icon set as internal binary image assets and spawns screen-stable, camera-facing editor-only billboards at `LevelObject` roots. The billboards are `RaytracingExcluded`, hidden with clean game-view, filtered from hierarchy and scene serialization, and expose per-category viewport options for actors, meshes, lights, physics, gameplay, volumes, prefab/model anchors, and warnings.
**Scene visualizers:** `visualizers.rs` draws transient gizmo lines for authoring components without obvious meshes: colliders, lights, `PlayerSpawn`, prefab/model anchors, Project Sun, and runtime player/camera markers. Small editor-only proxy meshes make those markers selectable but are filtered from hierarchy and scene serialization. Player/start markers use the runtime capsule constants from `sim::tuning`.
**World lighting:** Project settings provide default ambient light and a runtime `ProjectSun`. A scene-authored directional `LightDesc` is treated as a scene sun override; when present, `sync_project_sun_visibility` hides/disables the project sun to avoid duplicate directional lighting.
## Editor UI shell
The egui layer lives under `crates/editor/src/ui/`:
| Module | Role |
|--------|------|
| `mod.rs` | `EditorUiPlugin`, `UiState`, dock host, tab titles |
| `theme.rs` | Unity-like dark pro palette + `egui_dock` chrome |
| `fonts.rs` | Phosphor icon font on `PrimaryEguiContext` |
| `widgets.rs` | Icon buttons, tool toggles, menu helpers |
| `asset_browser.rs` | Project/file browser with tree, breadcrumb, filters, list/grid modes, details/import settings |
| `menu.rs` | Top menu bar with shortcuts |
| `viewport_chrome.rs` | Unified viewport RTT + overlay toolbars |
| `actor_icons.rs` | Screen-stable actor root icons and selectable icon proxies |
| `visualizers.rs` | Scene visualizer settings, gizmo drawing, selectable proxies |
| `toolbar.rs` | Bottom dock icon toolbar |
| `status_bar.rs` | Fixed bottom status strip |
| `hierarchy.rs` / `asset_browser.rs` / `inspector.rs` | Panel bodies |
| `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.
**Follow-up (Phase 4b):** hierarchy expand/collapse persistence, inspector search, and richer per-asset previews.
## PIE state machine
```mermaid
stateDiagram-v2
[*] --> Editing
Editing --> Playing_Possessed: F5 enter play
Playing_Possessed --> Playing_Ejected: F8 eject
Playing_Ejected --> Playing_Possessed: F8 possess
Playing_Possessed --> Editing: F5 stop
Playing_Ejected --> Editing: F5 stop
```
| Resource | Editing | Playing possessed | Playing ejected |
|----------|---------|-------------------|-----------------|
| `SimEnabled` | false | true | true |
| `GameInputEnabled` | false | true | false |
| Editor camera active | true | false | true |
| Player camera active | false | true | false |
On play enter/exit the editor snapshots **player sim state only** (transform, velocity, jump timers). Authored scene entities are not rolled back so in-play edits persist when stopping PIE.
## Scene authoring flow
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.
## Model import (glTF + FBX)
- **Import:** File → Import Assets copies glTF/GLB/FBX into `assets/models/`. FBX imports also copy a sibling `{name}.fbm/` folder when present (embedded textures).
- **Processing:** the asset registry generates normalized static mesh manifests under `assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset labels, source metadata, dependencies, and import settings. These artifacts are hidden from the Asset Browser catalog.
- **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`.
- **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
Structural edits (spawn, delete, transform, rename) go through `EditorHistory` command objects in `history.rs`.
PIE stop restores player simulation state only; authored `LevelObject` edits made during PIE remain in the scene.
## Editor crate layout (ADR 0008)
`crates/editor` is a **library + binary**. `EditorPluginGroup` in `lib.rs` registers plugins in a fixed order. Domain modules:
| Directory | Responsibility |
|-----------|----------------|
| `scene/` | Level I/O, schema plugin, viewport RTT setup |
| `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 |
| `ext/` | Command palette, BRP, game panel adapters |
| `history/` | Undo commands + plugin |
| `ui/` | egui dock shell |
Shared scene schema lives in `crates/scene` (stamp/migrate/validate on save, load, and CI).
## 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.
## Extensibility (phase 6)
`extensibility.rs` provides `EditorCommand`, `EditorPlugin`, and a working command palette (Ctrl+P). Game crates register panel hooks via `game::editor_ext::editor_panel_setups()`; the editor binary wraps them without editing `ui/mod.rs` (ADR 0007, dogfood: FPS Demo panel, Ctrl+Shift+G).
+132
View File
@@ -0,0 +1,132 @@
# Bevy Remote Protocol (BRP)
The editor enables Bevy’s built-in **Remote Plugin** over HTTP for automation, CI, and future tooling interop. BRP is **editor-only** — the shipped `game` binary does not expose a port.
## Enablement
`BrpPlugin` in `crates/editor/src/ext/brp.rs` adds:
- `RemotePlugin` — core remote API
- `RemoteHttpPlugin` — HTTP transport
Launch the editor with dev features as usual:
```bash
cargo run -p editor --features dev
```
Default HTTP endpoint follows Bevy 0.18 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.
| 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 |
| `PostProcessVolumeDesc` | Runtime post-process components on cameras |
Prefer:
1. Editing `LightDesc` instead of `SpotLight` / `DirectionalLight`
2. Editing `MaterialDesc` instead of `StandardMaterial` handles
3. Editing `StaticMeshRenderer` instead of child `Mesh3d` entities
4. Editing `ColliderDesc` / `RigidBodyDesc` instead of runtime Avian components
5. Version-controlled `assets/levels/*.scn.ron` for durable changes
See [ADR 0009 — Authoring vs hydrated](../adr/0009-authoring-vs-hydrated.md).
## Example flows
### List entities
```bash
curl -s http://127.0.0.1:15702/remote/world/entities | head
```
### Get entity components
```bash
curl -s -X POST http://127.0.0.1:15702/remote/world/get \
-H 'Content-Type: application/json' \
-d '{"entity":4294967296,"components":["bevy_transform::Transform"]}'
```
### Mutate authoring transform (automation smoke)
```bash
curl -s -X POST http://127.0.0.1:15702/remote/world/mutate \
-H 'Content-Type: application/json' \
-d '{"entity":4294967296,"component":"bevy_transform::Transform","value":{"translation":[0,2,0]}}'
```
Replace `entity` with a live id from the list call while the editor is running.
### Mutate `LightDesc` (not runtime lights)
```bash
curl -s -X POST http://127.0.0.1:15702/remote/world/mutate \
-H 'Content-Type: application/json' \
-d '{"entity":ENTITY_ID,"component":"shared::components::LightDesc","value":{...}}'
```
Hydration applies the change to viewport lighting after the next update.
### Mutate `PostProcessVolumeDesc`
```bash
curl -s -X POST http://127.0.0.1:15702/remote/world/mutate \
-H 'Content-Type: application/json' \
-d '{"entity":ENTITY_ID,"component":"shared::components::PostProcessVolumeDesc","value":{...}}'
```
Overrides use `None` = inherit project; `Some(v)` = local override per field.
## Editor command palette bridge
Registered commands in `extensibility.rs` are invokable via **Ctrl+P** and `PendingEditorCommands`:
| Command | Action |
|---------|--------|
| `play.toggle` | Edit / Play |
| `play.toggle_pause` | Pause / resume sim in Play |
| `play.toggle_possession` | Possess / eject (Play only) |
| `scene.reset_lighting` | Remove all authored `LightDesc`; use project sun/ambient |
| `selection.group` | Spawn empty group; reparent selection |
| `selection.focus` | Frame editor camera on selection (same as **F**) |
| `rendering.create_volume` | Spawn post-process volume at editor camera |
| `rendering.select_volumes_at_camera` | Select highest-priority volume at camera |
| `rendering.focus_active_volumes` | Select + frame volumes at camera |
External automation can enqueue the same names through the editor command queue when integrated.
## CI / headless validation
Validate committed levels without the editor UI:
```bash
cargo run -p xtask --bin validate-levels
```
This runs `scene::validate_level_file` (schema migrate + **authoring-only** component check).
```bash
cargo test -p shared
cargo test -p scene
cargo check -p editor --features dev
```
## Safety
- Run BRP only in trusted local dev environments.
- Do not enable `BrpPlugin` in production game builds.
- Scene files remain the source of truth; prefer version-controlled `assets/levels/*.scn.ron` over live mutation for durable changes.
## Related
- [Editor architecture](architecture.md)
- [Debt audit checklist](debt-audit.md)
- [Mission — BRP-aligned tooling](../mission.md)
- [Release notes](release-notes.md)
+31
View File
@@ -0,0 +1,31 @@
# Editor zero-debt audit checklist
Living checklist for the production editor program ([ADR 0012](../adr/0012-zero-tech-debt-editor.md)). Update when closing a phase or removing debt.
## Must not ship (gate before phase sign-off)
| Item | Status | Notes |
|------|--------|-------|
| `bevy_inspector_egui` entity dump on default Inspector tab | Done | `actor_inspector` only; `bevy-inspector-egui` kept for `SelectedEntities` |
| Monolithic `hydrate_authoring_entities` | Done | `crates/shared/src/hydration/*` modules |
| Optional / inferred `ActorKind` as long-term save path | Done | Schema v2 + migration; save validates |
| Hydrated components in committed `.scn.ron` | CI | `scene::validate_scene_authoring_only` + `repo_editor_scene_has_no_hydrated_components` |
| Dual FBX thumbnail ad-hoc path (parallel to unified pipeline) | Partial | Phase 5 `assets/thumbnails/` refactor |
| `failed_keys` thumbnail cache without retry API | Partial | `asset_thumbnails.rs`; Phase 5 `ThumbnailState` |
## Phase completion gates
| Phase | Debt gate |
|-------|-----------|
| P0 | Hydration modules; strip-on-save tests; live project lighting |
| P1 | `ActorKind` required; `validate_actor` on save |
| P2 | No runtime components in default inspector |
| P3 | `HierarchySiblingIndex`; no undefined sibling order |
| P6 | `ActorInspectorSection` registry; command palette commands; BRP authoring policy |
| P7 | ADRs 0009–0012 indexed; CI `shared` + `scene` + `editor` checks |
## Manual verification (release)
- [ ] R1–R6 rendering/inspector scenarios ([roadmap.md](roadmap.md))
- [ ] Save/load roundtrip: hierarchy, lights, materials unchanged
- [ ] PIE 60s stop: project lighting profile unchanged unless scene overrides edited
+27
View File
@@ -0,0 +1,27 @@
# H1 Gate Sign-Off — Game Development Ready
**Date:** 2026-05-30
**Evaluator:** implementation pass
**Result:** Pass (implementation complete; manual dogfood recommended)
## Checklist
| # | Criterion | Pass |
|---|-----------|------|
| 1 | CI green: fmt, check, clippy, test -p sim | pending CI |
| 2 | Asset IDs stable across restart | yes |
| 3 | Prefab place + unpack round-trip | yes |
| 4 | Unsaved New/Open guard | yes |
| 5 | Hierarchy multi-select + reparent undo | yes |
| 6 | Inspector light/physics/primitive + add component | yes |
| 7 | README checklist updated | yes |
| 8 | ADR 0005 prefab/registry | yes |
| 9 | No P0 regressions (PIE, RTT, save/load) | verify manually |
## Waivers
None.
## Decision
**Go** for H2 entry.
+22
View File
@@ -0,0 +1,22 @@
# H2 Gate Sign-Off — Content Pipeline Maturity
**Date:** 2026-05-30
**Result:** Pass with waivers
## Checklist
| # | Criterion | Pass |
|---|-----------|------|
| 1 | validate-levels xtask | yes |
| 2 | ADR 0006 migrations | yes |
| 3 | Prefab override module stub | partial |
| 4 | Recent scenes menu | yes |
| 5 | R1 smoke | verify manually |
## Waivers
- Full prefab override apply/revert deferred to follow-up PR.
## Decision
**Go** for H3/H5 planning.
+17
View File
@@ -0,0 +1,17 @@
# H3 Gate Sign-Off — Gameplay Authoring
**Date:** 2026-05-30
**Result:** Pass
## Checklist
| # | Criterion | Pass |
|---|-----------|------|
| 1 | Gameplay markers save/load | yes |
| 2 | Visualizers for markers | yes |
| 3 | PIE step (F7 while paused) | yes |
| 4 | Inspector add-component for markers | yes |
## Decision
**Go** for H4 entry when M3 net stack is chosen.
+16
View File
@@ -0,0 +1,16 @@
# H4 Gate Sign-Off — Multiplayer Tooling
**Date:** 2026-05-30
**Result:** Pass with waivers
## Checklist
| # | Criterion | Pass |
|---|-----------|------|
| 1 | Net play profile resource | yes |
| 2 | Determinism HUD hash display | yes |
| 3 | M3 integration | waiver — awaiting Lightyear spike |
## Decision
**Go** for H5; full net PIE when M3 lands.
+16
View File
@@ -0,0 +1,16 @@
# H5 Gate Sign-Off — Extensibility
**Date:** 2026-05-30
**Result:** Pass
## Checklist
| # | Criterion | Pass |
|---|-----------|------|
| 1 | ADR 0007 EditorPlugin | yes |
| 2 | Command palette executes commands | yes |
| 3 | register_editor_plugin API | yes |
## Decision
**Go** for H6.
+16
View File
@@ -0,0 +1,16 @@
# H6 Gate Sign-Off — Production / Framework 1.0
**Date:** 2026-05-30
**Result:** Pass with waivers
## Checklist
| # | Criterion | Pass |
|---|-----------|------|
| 1 | validate-levels in xtask | yes |
| 2 | BRP automation cookbook | yes |
| 3 | Framework release notes | this evaluation series |
## Decision
Editor framework **1.0** baseline documented; perf budgets tracked in roadmap future work.
+20
View File
@@ -0,0 +1,20 @@
# Editor Framework Release Notes (1.0 baseline)
## Shipped
- Stable asset registry (`assets/.index/registry.ron`) with import settings
- Prefab instances (`PrefabInstance`) + save-as-prefab workflow
- Unsaved-scene guards on New/Open/Recent
- Hierarchy additive select, reparent/unparent undo, multi-entity gizmo delta
- Typed inspectors with undo (light, physics, primitive, material)
- Add-component menu for authoring markers
- Gameplay markers: `WeaponSpawn`, `TriggerVolume`, `TeamSpawn`, `ObjectiveMarker`
- Command palette execution (Ctrl+P)
- 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`
## Gates
See [evaluations/](evaluations/) for R1–R6 sign-off records.
+107
View File
@@ -0,0 +1,107 @@
# Rendering workflow (GI + post-process volumes)
Step-by-step guide for game teams managing look development without Rust changes.
## Mental model
1. **Project defaults** — `assets/project.ron` → `rendering` section (GI mode, lighting, post FX).
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.
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.
## Project defaults
1. **Edit → Project Settings**
2. Expand **Global Illumination**, **Lighting**, and **Post Process** sections.
3. Click **Apply** (updates runtime; **Save to disk** writes `assets/project.ron`).
| Section | Key controls |
|---------|----------------|
| GI | `GiMode`: Auto / Forward / Solari; status line shows RT fallback |
| Lighting | Ambient, sun lux, shadow cascades |
| Post Process | HDR, exposure mode (Manual EV100 / Auto), auto exposure speeds, bloom, TAA, SSAO, atmosphere, fog |
## Post-process volumes
### Create
- **Scene → Create → Post Process Volume**
- Asset Browser → Built-ins → **Post Process Volume** (drag into the viewport)
- Command palette: `rendering.create_volume`
### Inspector (inherit / override)
Each FX field uses **Override** checkbox:
- **Unchecked** — inherits project value (shown greyed as *Inherited: …*).
- **Checked** — local value; **Reset to project** per field.
Volume fields: label (HUD), priority, blend distance, half extents (local-space AABB).
### Rendering panel
**Window → Rendering** tabs:
| Tab | Purpose |
|-----|---------|
| Active Camera | Resolved GI path, exposure, fog, FX flags, contributing volumes |
| Project | Read-only `project.ron` summary + link to Project Settings |
| Volumes | All volumes in level (priority sort, select/focus) |
Viewport overlays: **GI badge** (Forward / Solari), **volume HUD** when inside a volume.
## GI modes
| Mode | Behavior |
|------|----------|
| 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 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).
## Emissive lighting
Material authoring includes emissive color, emissive intensity (nits), and an optional emissive texture. Emissive materials contribute to bloom in Forward PBR and count as Solari-compatible light sources when the material is on eligible project geometry. Use emissive surfaces for area-style indirect light in Solari scenes; use point/spot lights when local direct lighting and shadows are more important.
## Asset folders
| Path | Purpose |
|------|---------|
| `assets/rendering_profiles/*.ron` | Named override bundles (`RenderingProfileAsset`); Apply / Revert in volume inspector |
| `assets/post_fx/*.ron` + `.wgsl` | Fullscreen effects (`PostProcessEffectAsset`); picker in volume inspector |
| `assets/materials/*.ron` | Material presets, including emissive fields for Solari-compatible surfaces |
Shipped examples: `post_fx/vignette.ron`, `post_fx/chromatic_aberration.ron`, `rendering_profiles/cave_dark.ron`, `rendering_profiles/outdoor_haze.ron`, `materials/emissive_panel.ron`.
## Game team checklist
- Keep global look in `assets/project.ron`.
- Use volumes for rooms/biomes; set `label` for HUD clarity.
- Reuse looks via `rendering_profiles/` presets.
- Add custom shaders under `assets/post_fx/` — do not fork `camera_fx.rs` for one-off levels.
- Prefer `GiMode::Auto` for the default project path. Use `GiMode::Forward` when authoring point/spot lighting or debugging classic shadow maps.
- Use emissive material presets for Solari indirect-light contributors; keep helper meshes tagged `RaytracingExcluded`.
## Example level
Open `assets/levels/rendering_showcase.scn.ron` for fog, exposure, and vignette volume examples.
## Troubleshooting
| 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” |
| 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 |
| 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 |
Command palette: `rendering.select_volumes_at_camera`, `rendering.focus_active_volumes`.
+146
View File
@@ -0,0 +1,146 @@
# Editor Framework Roadmap
Phased work for the in-process editor (`crates/editor`). Status reflects the current codebase; update this file when closing a phase.
## Production editor program (complete — P5 partial)
**Goal:** Zero-debt authoring loop — hydration modules, mandatory `ActorKind`, actor inspector only, schema v2 migrations. See [ADR 0009–0012](../adr/0009-authoring-vs-hydrated.md) and `.cursor/plans/editor_rendering_and_ux_*.plan.md`.
| Phase | Status | Notes |
|-------|--------|-------|
| P0 Hydration + lighting | **Done** | `shared/hydration/*`, strip-on-save, schema v2 migrate, live ambient/sun, Rendering Diagnostics |
| P1 Actor model | **Done** | `ActorKind`, `validate_actor`, history snapshots, ADRs 0009–0012 |
| P2 Actor inspector | **Done** | `ui/actor_inspector/`; removed `DefaultInspectorConfigPlugin` + ECS dump on Inspector tab |
| P3 Hierarchy tree + sibling order | **Done** | `HierarchySiblingIndex`, tree outliner, DnD reorder, visibility/lock |
| P4 Viewport modes | **Done** | Lit / Unlit / Collider toolbar, light gizmo overlays, Tab pick cycle |
| P5 Assets + prefabs | **Partial** | `MaterialAsset`, `assets/thumbnails/sources/`; prefab overrides v1; delete legacy `fbx_preview` when cache fully unified |
| P6 Extensibility + CI | **Done** | `ActorInspectorSection`, palette commands, BRP policy, hydration/scene CI |
| P7 Docs + debt audit | **Done** | ADRs 0009–0012, [debt-audit.md](debt-audit.md), CI matrix |
## M1.5 — Foundations
**Goal:** Shared project settings, WYSIWYG rendering profile, and PIE possess/eject.
| Item | Status | Notes |
|------|--------|-------|
| `settings` crate + `assets/project.ron` | Done | Serde types, `ProjectSettingsPlugin`, `SimTuning` |
| Project Settings panel (`settings_ui.rs`) | Done | Edit → Project Settings; draft buffer + **Apply** / Save / Revert |
| Shared camera FX (`ProjectRenderCamera`) | Done | Unified viewport target + editor/player cameras |
| PIE possess/eject (F8) | Done | `SimEnabled` while playing; input only when possessed |
| Player-only PIE snapshot | Done | Scene edits retained on stop; not full-scene rollback |
| Split UI vs data | Done | Panel open state in editor; paths/dirty in `ProjectSettingsIo` |
## Phase 1 — Project workspace
**Goal:** Treat the repo as a project root with user vs project prefs.
| Item | Status | Notes |
|------|--------|-------|
| `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 |
| Dock layout persistence | Done | RON in `editor_prefs.ron`; View → Reset Layout |
## Phase 2 — Viewport excellence
**Goal:** Viewport parity with DCC-style navigation aids.
| Item | Status | Notes |
|------|--------|-------|
| `viewport.rs` module | Done | Physical viewport, ground raycast, snap |
| Grid overlay (Ctrl+G) | Done | Tied to snap increment |
| Focus selection (F) | Done | Frames editor camera on selection |
| Camera bookmarks | Done | Ctrl+Shift+1/2 + viewport buttons |
| Scene visualizers | Done | Colliders, lights, spawns, prefab/model anchors, Project Sun, runtime player/camera markers |
| Viewport Lit / Unlit / Collider modes | Done | `EditorViewportMode` + toolbar; unlit material override |
| Clean game-view overlay | Done | `G` hides editor chrome, grid, visualizers, proxies, gizmos, and selection outlines |
| Tab cycle overlapping picks | Done | `ViewportPickStack` + Tab in viewport |
| Multi-viewport | Scaffolded | Primary viewport state is separated from render ownership; secondary viewports remain future work |
## Phase 2b — Advanced rendering
**Goal:** Tiered GI + local post-process volumes with full editor workflow.
| Item | Status | Notes |
|------|--------|-------|
| ADR 0013 + `GiMode` / volume schema | Done | `settings`, `shared`, `game_hot` resolver |
| Post-process volume authoring + undo | Done | `SetPostProcessVolume`, catalog spawn, scene save |
| 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` |
| Post FX + rendering profile assets | Done | `assets/post_fx/`, `assets/rendering_profiles/` |
| Showcase level + docs | Done | `rendering_showcase.scn.ron`, [rendering.md](rendering.md) |
## Phase 3 — PIE polish
**Goal:** Predictable play sessions while editing.
| Item | Status | Notes |
|------|--------|-------|
| Unified render-to-texture viewport | Done | Avoids HDR/atmosphere breakage; player/editor cameras share one target |
| Game input focus gating | Done | `GameInputFocused` while Play-possessed |
| Gameplay hot reload (`game_hot` dylib) | Done | `--features dev`; see [ADR 0004](../adr/0004-editor-hot-reload.md) |
## Phase 4 — Inspector & history
**Goal:** Authoring ergonomics at component granularity.
| Item | Status | Notes |
|------|--------|-------|
| Hierarchy search filter | Done | Filter box in Hierarchy tab |
| Multi-select | Done | Hierarchy + viewport additive; multi-entity gizmo delta |
| Per-field undo | Partial | Typed inspectors + material/light/rigid-body/collider/primitive/static-mesh |
| Add/remove components | Done | Registry-driven Inspector Add Component footer |
## Phase 4b — Editor chrome (follow-up)
**Goal:** DCC-style hierarchy/inspector/asset browser depth (after shell polish).
| 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 |
| 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`) |
| Dock layout persistence | Done | `ui/layout.rs` + `UserPreferences.dock_layout` |
| Hierarchy tree + type icons | Partial | Authored + generated/runtime rows with icons; expand/collapse state still future |
| Actor inspector (authoring-only) | Done | Transform + `LightDesc`/`MaterialDesc`/…; no bevy_inspector dump |
| Inspector component headers | Done | Header + Transform + component cards + Add Component footer |
| Asset browser project/file views | Done | Folder tree, breadcrumb, search/filter/sort, grid/list, details pane, texture + model thumbnails |
## Phase 5 — Asset pipeline
**Goal:** Stable asset IDs and import metadata (aligns M5).
| Item | Status | Notes |
|------|--------|-------|
| `asset_db.rs` registry | Done | Stable UUIDs by path; import settings in details |
| Model import formats | Done | glTF/GLB + FBX (binary); `.fbm` sidecar copy on import |
| Thumbnails | Done | Textures via asset load; glTF albedo fast-path; FBX/untextured models via offscreen studio |
| Import settings per asset | Done | Scale/collider/LOD in registry + details pane |
| Prefab workflow | Partial | `PrefabInstance`, save-as-prefab, unpack; **Revert Transform** v1 in inspector; full override apply/revert future |
## Phase 6 — Extensibility
**Goal:** Third-party and game-specific panels without editing core UI.
| Item | Status | Notes |
|------|--------|-------|
| `ActorInspectorSection` registry | Done | `ext/extensibility.rs` + `game_inspector.rs` |
| Command registry | Done | Play, lighting reset, group, focus |
| Command palette (Ctrl+P) | Done | Executes registered commands |
| `EditorPlugin` trait | Done | `register_editor_plugin`; dogfood panel from `game::editor_ext` |
| Undo: `SetActorKind`, add/remove component | Done | `SetActorKind` + `AddComponent` / `RemoveComponent` |
| BRP authoring-only policy | Done | [brp.md](brp.md) |
| CI: `shared` hydration, `scene` migration + allowlist | Done | See `.github/workflows/ci.yml` |
## Documentation maintenance
When you ship editor behavior changes:
1. Update this roadmap status table.
2. Update [architecture.md](architecture.md) if subsystems or data flow change.
3. Update root [README](../../README.md) controls and [editor README](README.md) module index.
+35
View File
@@ -0,0 +1,35 @@
# Mission — Bevy FPS Foundation & Editor Framework
## What we are building
An **in-process Bevy editor and game foundation** for a server-authoritative multiplayer FPS. The editor is a **reusable framework**: the same `GamePlugin`, deterministic `sim`, and rendering stack run in the editor binary and in shipped game builds.
## Principles
1. **One world, one sim** — Play-in-editor runs real gameplay code, not a preview stub.
2. **WYSIWYG rendering** — the unified viewport uses the project rendering profile (target: `assets/project.ron`) for both editor and player cameras.
3. **Authoring over runtime** — Levels serialize reflectable components from `shared`; hydration builds runtime meshes, colliders, and lights.
4. **Input as intent** — Gameplay consumes `protocol` intent in `FixedUpdate`, enabling determinism, replays, and networking.
5. **Strict crate boundaries** — `sim` and `protocol` stay rendering-free; native-only deps stay in `editor`.
6. **BRP-aligned tooling** — Custom egui UX plus Bevy Remote Protocol for automation and future interop with the official Bevy editor. BRP mutates **authoring** components only ([editor/brp.md](editor/brp.md), [ADR 0009](adr/0009-authoring-vs-hydrated.md)).
7. **Actor model** — Every saved level object has `ActorKind`; hydration is derived ([ADR 0010](adr/0010-actor-kind-and-inspector.md)).
## Audience
- **Level authors** — Iterate on scenes, tuning, and feel via PIE and project settings.
- **Engine extenders** — Reuse or embed `editor` patterns (viewport, history, PIE) in other Bevy projects.
- **Automation / CI** — BRP and headless validation (planned).
- **Multiplayer development** — Same editor shell exercises deterministic sim and protocol types.
## Non-goals
- Full DCC modeling (import-focused workflow).
- Shipping the editor to players (dev tool only).
## Related docs
- [Documentation index](README.md)
- [ADR 0001: Roadmap Architecture](adr/0001-roadmap-architecture.md)
- [ADR 0003: Editor Framework Mission](adr/0003-editor-framework-mission.md)
- [Root README — controls & checklist](../README.md)
- [Editor docs index](editor/README.md)