# 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; standalone default-level bootstrap |
| `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 |
| `PhysicsPlacementPlugin` | Paused Edit physics plus isolated transactional gravity placement |
| `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 |
| `CollaborationPlugin` | Exact authored-file guards, asynchronous Git status, optional ownership providers |
| `OperatorPlugin` | Active operator lifecycle/status for commands and modal tools |
| `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.

## Scene Persistence And Recovery

`scene/scene_io.rs` owns authored scene extraction and user-facing save/load requests;
`scene/recovery.rs` owns transactional byte persistence and machine-local recovery generations.
The editor sets `GameSceneBootstrap::defer_default_level`, so `SceneIoPlugin` alone materializes
the startup document. A standalone `GamePlugin` instead attaches a schema-aware `DynamicWorldRoot`
for `ProjectSettings.default_level`; it never runs this automatic load inside the editor.
Serialization always rebuilds stripped hydration state before returning, including error paths.
Manual writes use same-directory temporary files plus sync/rename, while recovery snapshots live
under the user state directory and never clear scene dirty state. Newer recovery is discovered on
load and exposed through File menu restore/keep-copy/discard actions; it is never restored
automatically. Keeping a copy writes a separate transactional scene without changing the active
scene or retiring recovery.
The bounded in-session scene I/O event log feeds the Diagnostics window so a later status update
does not erase a save or recovery failure.
See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).

`project/collaboration.rs` wraps user-authored publication with BLAKE3 baselines and a second
revision/read-only check immediately before the same-directory rename. Scene tabs, prefab source
Apply/history, staged Material documents, and Project Settings use this shared boundary. Its worker
observes path-scoped Git porcelain and optional ownership providers without blocking the frame loop
or changing repository state; conflict recovery is explicit Reload, metadata comparison, Save As,
or Cancel. Generated artifacts remain under their subsystem-owned regeneration policy. See
[collaborative-file-safety.md](collaborative-file-safety.md) and
[ADR 0037](../adr/0037-collaborative-authored-file-safety.md).

`project/shutdown.rs` owns native close, **File > Quit**, project switching, and programmatic editor
exit. The editor launch configuration leaves native close requests open; the coordinator coalesces
them, retries the shared native-dialog broker when busy, and authorizes `AppExit` only after clean
state, successful Save All, or explicit Discard. Scene I/O owns the asynchronous per-tab save
transaction and reports completion back to the coordinator. Final authorization and clean-session
persistence run in an editor schedule inserted after Bevy's `Last`, so material drops, brush/gizmo
finalizers, and every other authoring system finish before the last dirty-state check. See
[ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).

`project/session.rs` owns the independent versioned restart document under the user state
directory. It snapshots allowlisted paths, panel visibility, dock/hierarchy metadata, and camera
bookmarks, writes a running marker at startup, and records clean state only for a coordinator-
authorized `AppExit`. Abnormal sessions do not auto-open the prior scene; the explicit safe-resume
prompt is the only path back. See [ADR 0024](../adr/0024-versioned-editor-session-state.md).

`project/diagnostics_bundle.rs` exports a separate, transactional support report from an explicit
metadata allowlist. It summarizes build/renderer identity, project paths, dirty state, aggregate
validation, the prior crash boundary, and the bounded Scene I/O log without serializing ECS data,
asset contents, environment values, host identity, credentials, or operator state.

The active project root is a startup boundary because `AssetPlugin.file_path`, project settings,
the asset catalog, and the initial level must agree before editor systems initialize.
`project/launcher.rs` validates and activates explicit roots before the app exists, filters
user-local recents, and scaffolds only missing/empty sandbox destinations. The graphical BS-JD-001
chooser builds on this contract. Do not reintroduce in-process project switching that changes only
settings metadata while leaving `AssetServer` on the old root; see
[ADR 0025](../adr/0025-project-root-is-a-startup-boundary.md).

## 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:** Atmosphere, authored HDR, and effective Solari all require an `Hdr`
camera target; they must never render to the primary window swapchain
(`Rgba8UnormSrgb`). When the HDR offscreen target is missing, `scene_view` / `play`
deactivate cameras; `render_view` skips stack sync until a target exists.
Render-target changes and Solari/Forward fallback changes force a full camera-stack rebuild so
stale sky or post-FX pipelines cannot survive across texture-format transitions.

**Viewport picking:** LMB selection maps the egui panel UV through `scene_view_ray` and raycasts with `MeshRayCast`. Object pick runs in `Last` after `transform_gizmo_bevy` so gizmo drags take priority. `GizmoOptions.viewport_rect` is synced from the viewport panel rect so gizmo hit-testing matches render-to-texture layout. Actor root icon and visualizer proxy hits resolve to their source entity, so clicking an icon or light/spawn/collider marker selects the authored or runtime object, not the helper. Actor icon hits are ordered ahead of ordinary mesh hits when both are under the cursor. In Edit mode, selecting the runtime Player redirects to an authored `PlayerSpawn` (`Player Start`), creating one if needed.

**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. A custom overlay material draws them unlit with always-pass depth so opaque meshes do not obstruct them. 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, warnings, and icon size.

**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, embedded model shelves, 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 near-black semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. The fixed dark status strip prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, compact active-file collaboration status, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.

**Follow-up (Phase 4b):** 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 |
| `Time<Physics>` | paused | running | running |
| 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.

Paused Play also pauses `Time<Physics>`; **F7** advances that clock by exactly one 64 Hz sim tick.
Edit mode keeps the clock paused. `viewport/physics_placement.rs` may advance bounded 120 Hz
preview steps while selected bodies are temporarily dynamic and every other movable body is
temporarily static. Commit records only final local transforms through grouped history; cancel and
the Edit-to-Play boundary restore the complete runtime snapshot. See
[physics-placement.md](physics-placement.md) and [ADR 0041](../adr/0041-transactional-editor-physics-placement.md).

## 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/`, routed through `scene::document::SceneDocument`. The active tab is materialized in the ECS world; inactive tabs retain normalized authored snapshots, canonical clean checkpoints, and independent dirty/recovery state. Undo/redo reconciles stable authored content rather than transient ECS entity IDs. `SceneComposition` resources reference validated project-relative subscenes by stable IDs, and runtime-only `ComposedSceneMember` ownership prevents child actors from being flattened into the owner save. See [multi-scene-composition.md](multi-scene-composition.md), ADR 0026, and [ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).
5. Hydration systems in `game` spawn meshes, colliders, lights, static mesh renderer parts, and
   dedicated skinned-model hierarchies at runtime. Level-object roots are initialized with Bevy
   visibility hierarchy components before generated children are attached, so authoring
   `EditorVisibility` participates in normal visibility propagation. `ActorId` and
   `ComponentInstanceId` are the persisted identities; raw Bevy `Entity` IDs are runtime-only and
   must not become tool-facing document IDs.
6. Brush actors store authored convex geometry as `BrushDesc`; hydration rebuilds generated mesh children from those faces and strips the children before save.

## Model import (glTF + FBX)

- **Import:** File -> Import Assets copies glTF/GLB/FBX into `assets/models/`. An FBX import
  parses every safe external texture reference, including sibling `textures/` and `.fbm/` layouts,
  then stages and publishes the complete referenced bundle transactionally. Absolute non-sidecar
  paths, parent traversal, and dependencies that canonically escape the source folder are rejected
  before project files change; unreferenced sidecar contents are not copied.
- **Processing:** the asset registry generates normalized model manifests under
  `assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset
  labels, whether each part is skin-bound, source metadata, dependencies, and import settings.
  Model, texture, and audio registry records use byte length plus BLAKE3 source identity; model
  manifests use the same policy. Semantic RON comparison preserves exact existing bytes for an
  equivalent refresh, so checkout mtimes and formatting do not dirty project content. See
  [ADR 0043](../adr/0043-content-addressed-import-fingerprints.md). These artifacts are hidden from
  the Asset Browser catalog.
- **FBX dependencies:** the local `bevy_ufbx` resolver owns separator normalization, safe `.fbm/`
  rebasing, deduplication, and sandbox rejection. Static-mesh manifests record every declared
  external texture even when it is absent. Project validation reports one blocking finding for
  missing Source Materials textures, or one informational finding when Authoring Override
  deliberately leaves the model untextured. The runtime loader reads unique dependencies through
  `LoadContext` and creates labeled images directly, so missing paths cannot fan out into repeated
  asset-server errors. See [ADR 0044](../adr/0044-sandboxed-fbx-external-texture-dependencies.md).
- **Browser subassets:** model rows can expand into a content shelf backed by the generated
  manifest. Unrigged mesh subassets place as independent `StaticMeshRenderer` actors. A skinned
  subasset places its owning source through `SkinnedMeshRenderer`, retaining joints and inverse bind
  poses. Material subassets expose source defaults, and texture dependencies can be applied to
  selected actors. The thumbnail studio renders each generated model/subasset/material preview into
  its own render target before registering it in the cache so later thumbnails cannot overwrite
  earlier cache entries. FBX model and mesh previews use neutral direct geometry; source-material
  previews preflight external textures and retain one stable hover-visible failure reason instead
  of enqueueing a known-missing path.
- **Default placement:** **Renderable Asset (Auto)** creates
  `ActorKind::StaticMesh + StaticMeshRenderer` for unrigged, non-animated models and
  `ActorKind::SkinnedMesh + SkinnedMeshRenderer` when any part is skin-bound or the source contains
  animation. Static renderer slots
  reference imported `EditorAssetRef` values and exclude skinned parts. Static `SingleActor` mode
  stores all parts in one renderer; `SourceHierarchy` creates a root with child static mesh actors.
  Skinned placement always preserves the imported source hierarchy.
- **Collision:** when collider generation is enabled, static placement adds `RigidBodyDesc` and
  `ColliderDesc::StaticMesh` using the same imported mesh refs. Skinned render surfaces do not
  receive automatic triangle colliders; author stable gameplay collision explicitly.
- **Scene-instance placement:** asset details can switch placement to `SceneInstance`; that keeps
  `ImportedModel + ModelRef` for a generic source scene and hydrates to `WorldAssetRoot`. It is not
  the animation renderer. glTF uses `GltfAssetLabel::Scene`; FBX uses `bevy_ufbx` (`path#SceneN`).
  `FbxPlugin` is registered in `GamePlugin`.
- **Limitations:** Binary FBX only (not ASCII). Animated or skinned FBX remains blocked until its
  loader can construct the same hierarchy and clips as the glTF skinned path. See ADRs 0031 and
  0033.

## Undo / history

Structural edits (spawn, delete, transform, rename) go through `EditorHistory` command objects in `history.rs`.
User-facing actions route through the operator lifecycle in `operators.rs`: begin, preview,
commit, cancel, disabled reason, stable ID, and status text. Registered commands return typed
`OperatorAction::Commit` or `OperatorAction::ContinuePreview`, so immediate commands finish while
Draw Brush and CSG retain modal Preview ownership; validation failures terminate instead of leaving
stale status. Existing `EditorHistory` commands remain the undo payload. Group Selection is one
atomic command that remaps its transient group identity on every redo without reparenting unrelated
siblings. Lighting reset and Project Sun changes use one grouped light command. Asset placement,
assignment, exact material drops, brush tools, terrain strokes, physics placement, and the real
transform tracker all publish terminal lifecycle state. `operators/test_harness.rs` verifies semantic
projections, dirty-state preservation, stable IDs, helper cleanup, undo grouping, repeated undo/redo,
and automatic interruption rollback; see
[operator-regression-testing.md](operator-regression-testing.md).

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/` | Project I/O, settings UI, authored-file safety, and observational collaboration status |
| `ext/` | Command palette, BRP, game panel adapters |
| `history/` | Undo commands + plugin |
| `ui/` | egui dock shell |

Shared scene schema lives in the Bevy-free `crates/scene` crate (stamp/migrate/validate on save,
load, and CI). `game::schema_world_loader` is the runtime adapter that validates and unwraps the
schema envelope before Bevy deserializes versioned prefab assets; both game and editor install it
through `GamePlugin`.

## HDR / swapchain invariant

The unified viewport renders through an HDR offscreen target (`render_target.rs`). When the panel target is missing (egui reflow), cameras must strip atmosphere/post-FX before targeting the swapchain. User-authored HDR may be disabled, but atmosphere and effective Solari still force `Hdr` on the active viewport camera because Bevy sky/Solari pipelines are not safe to carry across SDR targets. `render_view::sync_project_render_view` runs in **PostUpdate** after RTT target assignment and reapplies the project FX stack whenever the active panel target handle changes (startup, resize), not only on settings Apply. Project Settings uses a **draft buffer**; **Apply** commits after render targets resync.

Bevy 0.19 removed the workspace's prior local `bevy_render` swapchain-timeout patch. The only active Bevy-adjacent patches are compatibility shims for ecosystem crates: `transform-gizmo-bevy` and `bevy_ufbx` under `third_party/`.

## Extensibility (phase 6)

`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).