This commit is contained in:
commit
f29712d158
259 files changed
+52069
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user