Blacksite/docs/editor/roadmap.md

# 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 (P5 cleanup remaining)

**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, full-row DnD attach/reorder/root, world-transform preservation, cycle guards, visibility/lock |
| P4 Viewport modes | **Done** | Lit / Unlit / Collider toolbar, light gizmo overlays, Tab pick cycle |
| P5 Assets + prefabs | **Partial** | Prefab v2 is production-accepted with stable nested identity, scoped/runtime overrides, committed base/nested/variant fixtures, source Apply/conflict recovery, and local conversion; legacy `fbx_preview` cleanup remains |
| 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` |
| Project launcher and scaffolding | Done | Project Browser validates/scaffolds before AssetServer startup; `--project`, recent projects, and clean process handoff preserve the startup boundary |
| 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 |
| Physics placement | Done | Existing horizontal toolbar action; real Avian settling, prerequisite diagnostics, exact cancel, grouped undo, and isolated non-selected bodies |
| Collider authoring diagnostics | Done | World-scale shape overlays, semantic health colors, stale/missing/invalid/oversized findings, undoable shape switching, and shared placement preflight |

## 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`, RT fallback, point/spot LightDesc disabled while Solari is active |
| Post FX + rendering profile assets | Done | `assets/post_fx/`, `assets/rendering_profiles/` |
| Showcase level + docs | Done | `rendering_showcase.scn.ron`, [rendering.md](rendering.md) |

## 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 |
|------|--------|-------|
| Blacksite dark visual system + Phosphor icons | Done | Near-black shell, Blacksite toolbar mark, semantic amber/cyan states, `ui/theme.rs`, `ui/fonts.rs`, overlay toolbars |
| Fixed status bar | Done | Replaces Status dock tab; exposes scene I/O and operator feedback alongside scene/mode/selection/history |
| 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 | Done | Authored + generated/runtime rows, persistent expansion, full-row attach targets, subtree-safe multi-drag, transform-preserving undo |
| 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 | Done | Shared stable nested property/component/structural overrides, recursive validation, committed variant fixtures, transactional source Apply, conflict recovery, and undoable outer unpack/recursive local conversion passed headless, packaged-runtime, and live editor acceptance in Gitea #43 |
| Curated editor regression samples | Done | Versioned five-area manifest, dedicated brush/material labs, strengthened terrain/physics/rendering fixtures, **File > Open Sample**, typed scene coverage, and `validate-samples` release gate in Gitea #32 |

## 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 |
| Typed operator dispatch and mutation invariants | Done | Immediate commands commit, modal commands retain Preview ownership, and production asset/brush/terrain/physics/history paths pass the shared lifecycle and undo contract ([testing guide](operator-regression-testing.md), [Gitea #33](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/33)) |
| `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` |

## Production Readiness Program

The live program is tracked by Gitea
[`#1`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/1),
with implementation sequencing in
`.cursor/plans/blacksite_production_readiness_2026-07-10.plan.md`.

| Milestone | Exit condition | Status |
|-----------|----------------|--------|
| M6 Reliability, recovery, and project workflow | Transactional save/recovery, stable sessions, project launcher, hardened hierarchy/prefabs, multi-scene composition | Implementation complete; all six scoped issues are closed after prefab #43 passed workspace, headless, packaged-runtime, and live editor acceptance |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#49 are complete after source, headless, and native acceptance. P0 #55 is complete at source implementation `4b33f32`, and follow-on P0 #57 scoped UI action safety is complete at `9e23ae7` after workspace, focused, independent-review, and native acceptance. No known P0 implementation blocker remains, but #50 is still the final candidate gate and production readiness is not established. Deterministic imported-asset fingerprints #56 are P1 follow-up work. Packaged acceptance is deferred until requested by the project owner. |

Production readiness is not inferred from feature count. Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
requires representative-project workflows, soak and performance evidence, headless validation,
packaging, recovery QA, first-hour signoff, and no open P0 blocker.

## 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.