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

```mermaid
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

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

```mermaid
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 `LevelObject`s 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 `LevelObject`s 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.