Blacksite/.cursor/plans/project_roadmap_8a452d43.plan.md

name	overview	todos	isProject
Project roadmap	A long-term, milestone-based roadmap ("plan of plans") for evolving the current game/shared/editor workspace into a flagship multiplayer FPS that doubles as a reusable, modular Bevy engine/editor toolkit, architected for server-authoritative networking and eventual web support, with each milestone spawning its own detailed sub-plan.	id content status m0-foundations M0 Foundations: fix window visibility, CI (fmt/clippy/build), test scaffolding, ADRs, documented Bevy version/migration policy. completed id content status m1-editor M1 Editor usability (contained sub-plan, see M1 detail section). Exit: an actually usable level editor. completed id content status m1-infra-tagging M1 - Add EditorOnly marker (crates/editor/src/infra.rs); tag editor + egui cameras and helpers; exclude from hierarchy, picking, and scene save. completed id content status m1-scene-hierarchy M1 - Custom scene Hierarchy panel in ui/mod.rs listing only LevelObject root+children, with select, F2 rename, and right-click context menu. completed id content status m1-selection-fixes M1 - Fix selection.rs: pick only LevelObjects, editor infra non-pickable, click-empty/Esc to deselect, keep gizmo-focus gating. completed id content status m1-delete-duplicate M1 - Delete/Backspace and Ctrl+D duplicate for the current selection. completed id content status m1-menu-toolbar M1 - Add top menu bar (File/Edit/View/Play), revamp toolbar, gizmo hotkeys W/E/R + world/local toggle. completed id content status m1-undo-redo M1 - Add history.rs EditorHistory command stack (Spawn/Despawn/Duplicate/SetTransform/Rename/SetMaterial) wired to ops and gizmo drag-end; Ctrl+Z/Ctrl+Shift+Z/Ctrl+Y. completed id content status m1-shared-authoring-ext M1 - Extend shared components+hydration: ModelRef (GLTF), MaterialDesc texture refs, PrefabRef; register new types. completed id content status m1-asset-browser M1 - Add assets.rs + Asset Browser panel scanning assets/{models,textures,materials,levels} with primitives/lights palette and refresh. completed id content status m1-drag-drop-materials M1 - Drag-and-drop from browser into viewport with ground-raycast placement; material/texture assignment + basic material editor in Inspector. completed id content status m1-import-export M1 - rfd import (copy into assets/ + hot reload) and export selection as prefab .scn.ron. completed id content status m1-play-mode M1 - Snapshot/restore Play mode in state.rs: snapshot LevelObjects, activate player+FX camera on Play, restore authored scene on Stop. completed id content status m1-scene-io-polish M1 - New/Open/Save/Save As via rfd with dirty tracking and window-title update in scene_io.rs. completed id content status m1-deps-verify-docs M1 - Add rfd dep, verify GLTF/texture features, cargo check/clippy workspace, update README controls + checklist. completed id content status m2-sim-determinism M2 Sim/authoring split + determinism: extract crates/sim and crates/protocol, move gameplay to FixedUpdate, input-as-intent, determinism test harness. completed id content status m3-netcode M3 Networking slice: Lightyear spike + integration, headless crates/server, client prediction/reconciliation + remote interpolation for player movement. pending id content status m4-fps-core M4 FPS gameplay core: weapons (hitscan/projectile) with lag compensation, health/damage/respawn, a basic game mode in crates/sim. pending id content status m5-asset-pipeline M5 Asset/content pipeline: robust GLTF/material/prefab pipeline, scene schema versioning + migrations, level streaming, import validation. pending id content status m6-modding-scripting M6 Modding/scripting: stable plugin API, data-driven definitions, scripting layer (Lua/Rhai or WASM components), BRP external tooling. pending id content status m7-web-platform M7 Web/platform: WASM client (WebGPU + WebTransport), build matrix, networked asset loading, perf/input adaptation. pending id content status m8-production-polish M8 Production polish: perf budgets/profiling, metrics, settings/save, accessibility, packaging/distribution and update cadence. pending	false

Project Roadmap (Plan of Plans)

This is the top-level strategy. Each milestone (M0-M8) becomes its own detailed sub-plan when started. Milestone M1 (Editor Build-Out) is fully contained inline in the "M1 detail" section below; later milestones get their detailed plans spun out as they begin.

Vision

A flagship, server-authoritative multiplayer FPS built on Bevy, whose engine/editor systems are factored as a reusable, modular toolkit. Desktop-first (Linux/Windows), architected so a WASM/WebGPU client is a later additive step, not a rewrite.

Guiding principles (apply from now, retrofit is expensive)

• Deterministic, fixed-timestep simulation. Gameplay logic lives in FixedUpdate/FixedMain, decoupled from render framerate.
• Input as intent. All world mutation flows through input/command/message events (never ad-hoc mutation from raw input). This is the single highest-leverage thing for cheap multiplayer retrofit and replays.
• Reflection-first, data-driven content. Authoring components + scenes (already in crates/shared), with a versioned, migratable schema.
• Strict crate boundaries: reusable engine/toolkit code separate from game-specific content; deterministic sim separate from rendering.
• WASM-friendly core. Native-only deps (rfd, mold, OS dialogs, BRP HTTP) are quarantined behind features or in tooling/editor crates only.
• BRP-aligned tooling so the custom editor can interoperate with the future official Bevy editor.
• Continuous quality: CI, lints, determinism tests, benchmarks, and a per-release Bevy migration discipline.

Target architecture (north star)

Evolve the current crates/{game,shared,editor} into:

flowchart TD
  subgraph core [Shared deterministic core - wasm-safe]
    protocol[protocol: net types, inputs, messages, replication]
    sim[sim: deterministic gameplay in FixedUpdate]
    scene[scene: authoring data + hydration]
  end
  server[server: headless authoritative bin] --> sim
  server --> protocol
  client[game: render, input, audio, ui, glue] --> sim
  client --> protocol
  client --> scene
  editor[editor: egui tooling + BRP] --> scene
  editor --> client
  netcode[Lightyear] --- server
  netcode --- client
  xtask[xtask: build, codegen, CI] -.-> core

• crates/protocol (new): networked types, input commands, messages, replication registration. Shared by client + server.
• crates/sim (extracted from crates/game): deterministic gameplay (movement, combat, rules), no rendering/audio.
• crates/game -> client app: rendering/FX (current rendering/), input, audio, UI, presentation glue.
• crates/server (new): headless authoritative binary.
• crates/shared -> crates/scene: authoring components + hydration (current files), now also used to seed networked world.
• crates/editor: stays the egui toolkit; native-only deps isolated here.
• xtask (new): build/codegen/CI helper.

Milestone roadmap

flowchart LR
  M0[M0 Foundations] --> M1[M1 Editor usability]
  M1 --> M2[M2 Sim split + determinism]
  M2 --> M3[M3 Netcode slice]
  M3 --> M4[M4 FPS gameplay]
  M4 --> M5[M5 Asset pipeline]
  M5 --> M6[M6 Modding + scripting]
  M6 --> M7[M7 Web + platform]
  M7 --> M8[M8 Production polish]

• M0 - Foundations and hardening: resolve the window-visibility issue, quiet/understand wgpu validation noise, add CI (fmt/clippy/build), test scaffolding, ADRs (architecture decision records), and a documented Bevy version policy. Exit: green CI, reproducible builds, ADR-0001 (architecture) + ADR-0002 (netcode choice spike planned).
• M1 - Editor usability: the existing Editor Build-Out sub-plan (selection/hierarchy fixes, delete/duplicate, undo/redo, asset browser, drag-and-drop, materials/GLTF, save/load, snapshot Play mode). Exit: an actually usable level editor.
• M2 - Simulation/authoring split + determinism: extract crates/sim, move gameplay to FixedUpdate, introduce crates/protocol, convert input to intent/command events, add a determinism test harness (same inputs -> same state hash). Exit: gameplay deterministic in fixed timestep; no ad-hoc world mutation from input.
• M3 - Networking vertical slice: spike then integrate Lightyear (server-authoritative) with client-side prediction + reconciliation for player movement and snapshot interpolation for remotes; stand up crates/server (headless). Exit: server + 2 clients, responsive predicted local movement, smooth remote players.
• M4 - FPS gameplay core: weapons (hitscan + projectiles) with lag compensation, health/damage/respawn, a basic game mode, all in crates/sim. Exit: playable networked skirmish.
• M5 - Asset and content pipeline maturity: robust GLTF/material/prefab pipeline, scene schema versioning + migrations, level streaming/partitioning, import validation tooling. Exit: author a real level end-to-end from assets in the editor.
• M6 - Modding and scripting extensibility: stable plugin API, data-driven definitions, and a scripting/modding layer (Lua/Rhai or WASM components) plus BRP-based external tooling. Exit: a mod adds a new entity/weapon without recompiling core.
• M7 - Web and platform expansion: WASM client (WebGPU + WebTransport via Lightyear), build matrix, networked asset loading, perf/input adaptation. Exit: a browser client connects to the live server.
• M8 - Production polish and release engineering: performance budgets + profiling, metrics/observability, settings/save systems, accessibility, packaging/distribution and update cadence. Exit: a shippable demo build.

M1 detail - Editor Build-Out (contained sub-plan)

Phased; each phase is independently testable and leaves the editor working. Maps directly to the reported issues (cluttered hierarchy, broken selection, no delete, button-spawning, weak save, no undo, no asset browser, no real play mode).

Architectural decisions:

• Add an EditorOnly marker (new crates/editor/src/infra.rs) for editor infrastructure (editor camera, egui camera, gizmo/selection helpers). Hierarchy, picking, and scene save all filter off it.
• Replace bevy-inspector-egui's hierarchy_ui with a custom scene hierarchy that only walks LevelObject roots + children.
• Keep authoring data the source of truth: extend crates/shared/src/components.rs so GLTF models and textured materials are reflectable/serializable and round-trip through .scn.ron via the existing hydration system.
• Undo/redo via an explicit command stack (EditorHistory), except Play mode which uses a scene snapshot for restore.
• Add rfd (editor-only dep) for native Open/Save/Import dialogs.

flowchart LR
  Browser[Asset Browser] -->|drag payload| Viewport
  Viewport -->|ground raycast place| Spawn[Spawn authoring entity]
  Spawn --> History[EditorHistory cmd]
  Hierarchy -->|select| Selection
  Selection --> Gizmo[Transform gizmo]
  Gizmo -->|drag end| History
  History -->|undo or redo| World

M1 Phase 1 - Core usability (the reported bugs):

• New infra.rs: EditorOnly marker; mark editor camera + egui camera (crates/editor/src/camera.rs) and helper entities.
• Custom Hierarchy panel in crates/editor/src/ui/mod.rs: only LevelObject entities (root + children), click to select, F2 rename, right-click context menu (Rename / Duplicate / Delete / Focus).
• Selection fixes in crates/editor/src/selection.rs: only LevelObjects pickable (editor infra opts out via Pickable::IGNORE), click empty to deselect, Esc to clear, keep gizmo-focus gating.
• Delete (Delete/Backspace) and Duplicate (Ctrl+D).
• Gizmo hotkeys in crates/editor/src/gizmos.rs (W/E/R) + world/local toggle.

M1 Phase 2 - Undo / Redo:

• New crates/editor/src/history.rs: EditorHistory with undo/redo stacks and an EditorCommand enum (Spawn, Despawn, Duplicate, SetTransform, Rename, SetMaterial).
• Capture gizmo transform edits on drag-end; structural ops push commands; Ctrl+Z / Ctrl+Shift+Z (+ Ctrl+Y).
• Inspector field-edit undo is out of scope for v1 (README follow-up).

M1 Phase 3 - Asset browser, authoring extensions, drag-and-drop, materials:

• Extend crates/shared/src/components.rs + hydration.rs: ModelRef { path, scene_index } -> SceneRoot/Mesh3d from GLTF; MaterialDesc optional texture paths (base color / normal / metallic-roughness); PrefabRef for dragging in saved .scn.ron.
• New crates/editor/src/assets.rs + Asset Browser panel: scan assets/{models,textures,materials,levels}, grid/tree with labels (thumbnails best-effort), refresh, primitives+lights palette.
• Drag-and-drop: egui drag payload from browser -> drop in Viewport -> place via ground raycast -> spawn matching authoring entity (push to history). Keep click-to-spawn fallback.
• Material assignment from the browser to the selection; basic material editor fields in the Inspector.
• Import via rfd: copy external GLTF/GLB/texture into assets/ and hot-reload; export selection as a prefab .scn.ron.

M1 Phase 4 - Working Play mode + scene IO polish:

• crates/editor/src/state.rs: on Edit->Play, snapshot LevelObjects to an in-memory DynamicScene; activate player + high-fidelity camera, enable game input/physics; on Play->Edit, despawn runtime entities and restore the snapshot. Optional pause/step.
• crates/editor/src/scene_io.rs: New/Open/Save/Save As with rfd, dirty tracking, recent path, window-title update; keep filtering to LevelObject + new authoring components.

M1 Phase 5 - Dependencies, verification, docs:

• Add rfd to crates/editor/Cargo.toml; confirm bevy GLTF/texture features (default).
• cargo check/cargo clippy across the workspace; fix 0.18 API drift.
• Update README.md controls + Implementation Checklist.

M1 out of scope (later): per-field inspector undo, multi-scene tabs, full PBR material graph, terrain, lightmap baking. (These align with M5/M6 of this roadmap.)

Cross-cutting tracks (run continuously, not milestones)

• Rendering fidelity (build on current crates/game/src/rendering), UX/UI polish, Tooling/CI, Docs + ADRs, Performance budgets, Security (server authority + anti-cheat posture).

Key technology decisions (validated May 2026)

• Bevy: stay on the latest stable (0.18.1 now; adopt 0.19 when it ships, imminent). Migrate every ~3-month release on a scheduled cadence; gate upgrades on ecosystem (esp. netcode) support. Capture as ADR.
• Netcode: Lightyear (server-authoritative; prediction/rollback, interpolation, lag compensation; WASM/WebTransport). Lightyear tracks Bevy by roughly one version, which constrains upgrade timing. Fallback: bevy_replicon if Lightyear complexity outweighs benefit. Decide via M3 spike.
• Physics: keep Avian for static world + spatial queries; keep the player controller custom and deterministic; movement is server-authoritative. Avoid full physics rollback initially (predict player movement only); revisit if needed. Determinism across machines is the top technical risk.
• Editor: continue the custom egui editor; align scene IO and inspection with BRP so we can interoperate with the official Bevy editor later. Quarantine native-only editor deps.
• WASM readiness: keep protocol/sim/scene/game wasm-compatible; isolate native-only code behind features/editor.

Risks and mitigations

• Cross-platform determinism (floats/physics): fixed timestep + deterministic controller + server authority + state-hash tests; constrain prediction scope.
• Bevy churn (every ~3 months): migration checklist, pinned versions, upgrades gated on Lightyear/ecosystem readiness.
• Scope (game + toolkit + MP): enforce milestone gating and vertical slices; resist premature generality until M5/M6.
• Toolkit/game coupling: keep game content out of reusable crates; reusable code must not depend on crates/game.

How the plan-of-plans operates

This roadmap is the index, and M1's full detail is contained inline above. Starting a later milestone expands its detailed scope/files/todos the same way (either inline or as a spun-out plan). M0 and M2 are the immediate next planning targets; M3 begins with a time-boxed Lightyear spike before committing.

Out of scope for now

• Concrete release dates/staffing (cadence assumptions only), console ports, peer-to-peer topology, and full anti-cheat beyond server authority.