215 lines
16 KiB
Markdown
215 lines
16 KiB
Markdown
---
|
|
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. |