9.5 KiB
9.5 KiB
Project Documentation
Central index for design decisions, mission, and editor framework docs. Agents and contributors should keep this map current—see .cursor/rules/documentation.mdc.
Core
| Document | Purpose |
|---|---|
| mission.md | Why the editor framework exists, principles, audience, non-goals |
| ../README.md | Run/build instructions, controls, implementation checklist |
Architecture Decision Records (ADRs)
Immutable-style log of significant decisions. Add a new numbered ADR when changing boundaries, formats, or policies.
| ADR | Topic |
|---|---|
| 0001 | Crate split, sim/protocol direction, milestone north star |
| 0002 | Bevy upgrade cadence and verification |
| 0003 | Editor as reusable in-process framework |
| 0004 | Dev-only game_hot dylib hot reload |
| 0005 | Prefab instances + stable asset registry |
| 0006 | Scene schema versioning and validation |
| 0007 | EditorPlugin extensibility surface |
| 0008 | Editor domain modules, lib/bin split, plugin group |
| 0009 | Authoring vs hydrated components; strip-on-save |
| 0010 | ActorKind, validation, actor inspector |
| 0011 | Project sun vs scene directional policy |
| 0012 | Zero tech debt / no dual inspector |
| 0013 | GI tiers, post-process volumes, editor model |
| 0014 | Unified viewport render target and clean game-view overlay |
| 0015 | Viewport camera FX ownership and Solari local-light authoring policy |
| 0016 | Requested/effective render stack, Solari eligibility, emissive materials |
| 0017 | Normalized static mesh assets and renderer placement |
| 0018 | Componentized actor inspector, imported asset refs, collider split, material overrides |
| 0019 | Superseded local bevy_render patch for transient Linux swapchain timeouts |
| 0020 | Jackdaw-inspired roadmap source policy and attribution requirements |
| 0021 | Brush authoring schema and hydration contract |
| 0022 | Bevy 0.19 / Avian 0.7 upgrade and compatibility patches |
| 0023 | Atomic scene writes, user-local recovery snapshots, and restore/discard policy |
| 0024 | Versioned machine-local session state and safe abnormal-shutdown resume |
| 0025 | Pre-engine project validation, activation, and sandbox contract |
| 0026 | Stable scene IDs, subscene ownership, tabs, and active-world materialization |
| 0027 | Stable prefab ownership, nested override identity/layering, transactional source writes, variants, and local conversion |
| 0028 | Shared editor/headless dependency manifest and project content findings |
| 0029 | Shared validation-gated build profiles, runtime packaging, and metadata |
| 0030 | Serializable audio sources/listeners, stable clip references, and project bus graph |
| 0031 | glTF animation artifacts, stable controller states, runtime hydration, and exact-signature retargeting |
| 0032 | Rerecast bake artifacts, Polyanya runtime queries, and editor/runtime ownership |
| 0033 | Dedicated skinned renderer, static/skinned import boundary, and scene migration |
| 0034 | Stable component IDs, reflected lifecycle/history, composition, and independent active state |
| 0035 | Shared Material/Material Instance assets, stable renderer slots, and runtime-only property blocks |
| 0036 | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
Editor framework
| Document | Purpose |
|---|---|
| editor/release-notes.md | Editor framework 1.0 baseline |
| editor/evaluations/ | Horizon gate sign-offs (R1–R6) |
| editor/architecture.md | Viewport / PIE / settings data flow |
| editor/visual-language.md | Editor chrome, viewport, selection, gizmo, and visualizer language |
| editor/roadmap.md | Phased editor roadmap and status |
| editor/brp.md | BRP automation and authoring-only policy |
| editor/debt-audit.md | Zero-debt phase gates |
| editor/brushes.md | Brush authoring schema, hydration behavior, and MVP limits |
| editor/operator-regression-testing.md | Reusable modal-tool and operator invariant harness |
| editor/session-recovery.md | Clean restart, abnormal shutdown, session schema, and privacy boundary |
| editor/project-launcher.md | Project manifests, explicit startup roots, recents, and sandbox scaffolding |
| editor/build-and-package.md | Editor/headless package profiles, output, exclusions, and metadata |
| editor/multi-scene-composition.md | Independent scene tabs, composition ownership, validation, and recovery |
| editor/prefab-authoring.md | Linked instances, scoped overrides/source Apply, conflicts, variants, unpacking, and local conversion |
| editor/audio-authoring.md | Audio clips, source/listener authoring, audition, buses, runtime parity, and validation |
| editor/animation-authoring.md | glTF rigs/clips, controller states, preview, runtime requests, stable moves, and validation |
| editor/navigation-authoring.md | Bounds/obstacles/areas/links, deterministic bake, overlay, path preview, and runtime queries |
| editor/extensibility.md | Static authoring component registration, lifecycle, composition, and history contract |
| editor/material-system.md | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
| editor/evaluations/material-renderer-foundation/ | Live screenshots and acceptance results for the renderer/material/component foundation |
| editor/evaluations/navigation-authoring/ | Live screenshots and acceptance results for navigation authoring and runtime parity |
Working plans (not canonical long-term)
Detailed milestone and feature plans live in .cursor/plans/. Promote stable outcomes into ADRs or docs/ when shipped.
| Plan | Topic |
|---|---|
project_roadmap_*.plan.md |
M0–M8 program index |
editor_framework_mission_roadmap_*.plan.md |
Editor mission + phased roadmap |
project_settings_and_pie_eject_*.plan.md |
M1.5: settings, rendering parity, PIE eject |
rendering_unification_*.plan.md |
Unified rendering stack, Hybrid Auto GI, emissive materials |
static_mesh_asset_refactor_*.plan.md |
Static mesh renderer, normalized model artifacts, inspector redesign |
component_system_refactor_*.plan.md |
Component registry, imported asset refs, collider split, material overrides |
jackdaw_feature_roadmap_*.plan.md |
Jackdaw-inspired production roadmap; tracked in Gitea as BS-JD-* issues |
blacksite_production_readiness_*.plan.md |
M6-M7 reliability, content production, shipping, and acceptance gates |
animation_authoring_*.plan.md |
M7 glTF skeletal animation import, preview, controller, and runtime acceptance |
navigation_authoring_*.plan.md |
M7 navigation bounds, deterministic bake, diagnostics, preview, and runtime query API |
renderer_material_component_foundation_*.plan.md |
Renderer/material slots, skinned pose lifecycle, Surface ABI, and component foundation |
Crate responsibilities (quick reference)
crates/protocol/ Tick rate, input intent, message shapes
crates/sim/ Fixed-step gameplay; no rendering
crates/shared/ Authoring components + hydration
crates/game/ Client presentation, GamePlugin, rendering
crates/editor/ In-process egui editor, BRP, PIE
crates/settings/ Project settings, active/effective render profile contracts
When adding a crate or moving responsibilities, update this table and ADR 0001 (or a follow-up ADR).