Initial project import
CI / Format, lint, test, build (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-06-05 21:44:45 -04:00
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.