This commit is contained in:
commit
f29712d158
259 files changed
+52069
No files matched your search
@@ -0,0 +1,23 @@
|
||||
# Component System Refactor Plan - 2026-06-05
|
||||
|
||||
## Goal
|
||||
|
||||
Align the actor inspector and static mesh authoring model with
|
||||
`docs/editor/Bevy_Editor_Component_System_Spec.md`.
|
||||
|
||||
## Implemented Scope
|
||||
|
||||
- Stable actor and component item IDs: `ActorId`, `ActorName`, `ComponentInstanceId`.
|
||||
- Editor-visible component registry powering Add Component metadata.
|
||||
- `StaticMeshRenderer` slots using imported `EditorAssetRef` mesh/material refs instead of source model paths.
|
||||
- Static mesh artifact part IDs and resolver fallback for older generated artifacts.
|
||||
- Separate `RigidBodyDesc` and `ColliderDesc`, including static mesh collider sources.
|
||||
- Shader-aware `MaterialDesc`, shader schema assets, and per-actor `MaterialOverride`.
|
||||
- Actor inspector footer and component cards updated for static mesh slots, collider, rigid body, and shader controls.
|
||||
- Docs/ADR updates for the architecture and workflow changes.
|
||||
|
||||
## Follow-Up
|
||||
|
||||
- Content-browser material asset inspector should become the shared-material editing surface.
|
||||
- Custom WGSL material rendering should be promoted from schema/data support to a dedicated runtime material pipeline.
|
||||
- Multi-selection mixed-value editing and prefab override indicators should use the new stable component/slot IDs.
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Rendering Unification Plan
|
||||
|
||||
## Summary
|
||||
|
||||
Unify the Bevy 0.18 rendering framework around a single effective render-stack contract. Preserve
|
||||
Hybrid Auto GI: requested Solari provides realtime indirect lighting when ready, while Forward PBR
|
||||
remains the correctness fallback for unsupported RT hardware, Solari warmup, and local point/spot
|
||||
shadow lights.
|
||||
|
||||
## Implementation
|
||||
|
||||
- Add `settings::EffectiveRenderStack` and `RenderFallbackReason` as the authoritative GI fallback
|
||||
decision.
|
||||
- Route editor camera stack sync and diagnostics through the shared resolver.
|
||||
- Track requested and effective GI separately in `RenderingCapabilities`.
|
||||
- Keep requested Solari raytracing mesh tagging alive while the camera temporarily renders Forward.
|
||||
- Extend material authoring with emissive color, intensity, and texture fields for Solari-compatible
|
||||
emissive scene lighting.
|
||||
- Add diagnostics for requested/effective GI, fallback reason, and Solari mesh eligibility counts.
|
||||
|
||||
## Verification
|
||||
|
||||
- `cargo fmt --check`
|
||||
- `cargo check --workspace`
|
||||
- `cargo clippy --workspace`
|
||||
- Focused tests for settings, shared hydration, game rendering, and editor camera stack behavior.
|
||||
- `cargo run -p xtask -- validate-levels`
|
||||
@@ -0,0 +1,26 @@
|
||||
# Static Mesh Asset Refactor Plan
|
||||
|
||||
Date: 2026-06-05
|
||||
|
||||
## Scope
|
||||
|
||||
- Normalize glTF/GLB and FBX model placement through one static mesh renderer authoring component.
|
||||
- Generate project static mesh manifests under `assets/meshes/generated/`.
|
||||
- Preserve explicit scene-instance placement for full `SceneRoot` behavior.
|
||||
- Redesign the actor inspector around component cards and add renderer slot controls.
|
||||
|
||||
## Implementation Slices
|
||||
|
||||
1. Add `StaticMeshRenderer` shared authoring data, validation, scene save allowlist, history snapshots, and hydration.
|
||||
2. Extend the asset registry import settings with placement mode, hierarchy mode, material policy, collider generation, and generated manifest path.
|
||||
3. Add glTF/FBX static mesh manifest generation and route model drag/drop through renderer placement by default.
|
||||
4. Expose asset import settings and static mesh renderer controls in editor UI.
|
||||
5. Update ADR/docs/README and verify with focused checks.
|
||||
|
||||
## Shipped Behavior
|
||||
|
||||
- `StaticAsset` placement creates `ActorKind::StaticMesh + StaticMeshRenderer`.
|
||||
- `SceneInstance` placement keeps `ActorKind::ImportedModel + ModelRef`.
|
||||
- `SingleActor` hierarchy mode stores all mesh parts on one renderer.
|
||||
- `SourceHierarchy` mode creates a root with child static mesh actors.
|
||||
- Static mesh hydration spawns generated child `Mesh3d` parts with source materials, shadow flags, and optional Avian mesh collider constructors.
|
||||
Reference in new issue
Block a user