Blacksite/docs/adr/0003-editor-framework-mission.md

ADR 0003: Editor Framework Mission

Status

Accepted

Context

The in-process editor (crates/editor) started as a level-editing shell for the FPS foundation. It now includes docked panels, scene I/O, undo/redo, asset browser, real play-in-editor (PIE), and BRP. As milestones M3–M8 add networking, weapons, asset maturity, and modding, the editor must evolve from a game-specific tool into a reusable Bevy editor framework without forking gameplay code or duplicating rendering/sim logic.

Competing approaches:

1. Game-only tool — fastest short-term; blocks reuse and BRP/automation alignment.
2. Separate preview runtime — simpler isolation; breaks WYSIWYG and doubles maintenance.
3. In-process framework — same GamePlugin + sim + shared authoring; editor adds UI, PIE, settings, and BRP only.

Decision

Treat the editor as a reusable in-process framework with these commitments:

• One world, one sim — PIE runs the real GamePlugin; no preview stub.
• Authoring over runtime — shared components + hydration are the scene source of truth.
• WYSIWYG rendering — the active viewport camera uses the project rendering profile (assets/project.ron via settings crate).
• Edit-safe infrastructure — EditorOnly marks editor cameras/helpers; excluded from hierarchy, picking, and save.
• Command-based undo — structural edits use EditorHistory; PIE uses player/sim snapshots, not full-scene rollback when editing during play.
• Native-first, wasm-safe core — rfd, BRP HTTP, and OS dialogs stay in editor; shared, sim, protocol, and settings remain usable from a future WASM client.
• BRP-aligned, not BRP-dependent — custom egui UX is primary; scene schema follows Bevy ecosystem conventions for future interop.

Mission statement and phased roadmap: docs/mission.md, docs/editor/roadmap.md.

Consequences

• New editor features should be game-agnostic where possible (viewport, PIE, settings, history).
• Game-specific panels register through an extensibility API (EditorPlugin) rather than hard-coding in ui/mod.rs.
• Project settings live in a dedicated settings crate, not scattered consts in sim and game.
• Documentation updates are required when changing editor behavior (see .cursor/rules/documentation.mdc).
• Shipping the editor binary to players remains out of scope; BRP stays editor-only.

Follow-Ups

• M1.5: project settings, shared camera FX, PIE possess/eject.
• M5: asset database and prefab workflow in editor.
• M6: EditorPlugin trait, command registry, BRP automation surface.