121 lines
11 KiB
Markdown
121 lines
11 KiB
Markdown
# 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`](../.cursor/rules/documentation.mdc).
|
||
|
||
## Core
|
||
|
||
| Document | Purpose |
|
||
|----------|---------|
|
||
| [mission.md](mission.md) | Why the editor framework exists, principles, audience, non-goals |
|
||
| [../README.md](../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](adr/0001-roadmap-architecture.md) | Crate split, sim/protocol direction, milestone north star |
|
||
| [0002](adr/0002-bevy-version-and-migration-policy.md) | Bevy upgrade cadence and verification |
|
||
| [0003](adr/0003-editor-framework-mission.md) | Editor as reusable in-process framework |
|
||
| [0004](adr/0004-editor-hot-reload.md) | Dev-only `game_hot` dylib hot reload |
|
||
| [0005](adr/0005-prefab-instance-and-asset-registry.md) | Prefab instances + stable asset registry |
|
||
| [0006](adr/0006-scene-schema-versioning.md) | Scene schema versioning and validation |
|
||
| [0007](adr/0007-editor-plugin-extensibility.md) | EditorPlugin extensibility surface |
|
||
| [0008](adr/0008-editor-module-boundaries.md) | Editor domain modules, lib/bin split, plugin group |
|
||
| [0009](adr/0009-authoring-vs-hydrated.md) | Authoring vs hydrated components; strip-on-save |
|
||
| [0010](adr/0010-actor-kind-and-inspector.md) | ActorKind, validation, actor inspector |
|
||
| [0011](adr/0011-scene-sun-policy.md) | Project sun vs scene directional policy |
|
||
| [0012](adr/0012-zero-tech-debt-editor.md) | Zero tech debt / no dual inspector |
|
||
| [0013](adr/0013-rendering-tiers-and-post-process-volumes.md) | GI tiers, post-process volumes, editor model |
|
||
| [0014](adr/0014-unified-viewport-model.md) | Unified viewport render target and clean game-view overlay |
|
||
| [0015](adr/0015-viewport-camera-stack-ownership.md) | Viewport camera FX ownership and Solari local-light authoring policy |
|
||
| [0016](adr/0016-unified-rendering-contract.md) | Requested/effective render stack, Solari eligibility, emissive materials |
|
||
| [0017](adr/0017-normalized-static-mesh-assets.md) | Normalized static mesh assets and renderer placement |
|
||
| [0018](adr/0018-componentized-actor-inspector-and-materials.md) | Componentized actor inspector, imported asset refs, collider split, material overrides |
|
||
| [0019](adr/0019-local-bevy-render-timeout-patch.md) | Superseded local `bevy_render` patch for transient Linux swapchain timeouts |
|
||
| [0020](adr/0020-jackdaw-inspired-editor-roadmap.md) | Jackdaw-inspired roadmap source policy and attribution requirements |
|
||
| [0021](adr/0021-brush-authoring-schema.md) | Brush authoring schema and hydration contract |
|
||
| [0022](adr/0022-bevy-0-19-upgrade.md) | Bevy 0.19 / Avian 0.7 upgrade and compatibility patches |
|
||
| [0023](adr/0023-transactional-scene-persistence-and-recovery.md) | Atomic scene writes, user-local recovery snapshots, and restore/discard policy |
|
||
| [0024](adr/0024-versioned-editor-session-state.md) | Versioned machine-local session state and safe abnormal-shutdown resume |
|
||
| [0025](adr/0025-project-root-is-a-startup-boundary.md) | Pre-engine project validation, activation, and sandbox contract |
|
||
| [0026](adr/0026-stable-scene-composition-and-active-document.md) | Stable scene IDs, subscene ownership, tabs, and active-world materialization |
|
||
| [0027](adr/0027-stable-prefab-ownership-and-variants.md) | Stable prefab ownership, nested override identity/layering, transactional source writes, variants, and local conversion |
|
||
| [0028](adr/0028-authoritative-project-content-validation.md) | Shared editor/headless dependency manifest and project content findings |
|
||
| [0029](adr/0029-validation-gated-build-profiles-and-packaging.md) | Shared validation-gated build profiles, runtime packaging, and metadata |
|
||
| [0030](adr/0030-audio-authoring-and-bus-schema.md) | Serializable audio sources/listeners, stable clip references, and project bus graph |
|
||
| [0031](adr/0031-animation-authoring-runtime-contract.md) | glTF animation artifacts, stable controller states, runtime hydration, and exact-signature retargeting |
|
||
| [0032](adr/0032-versioned-navigation-bake-and-runtime-query.md) | Rerecast bake artifacts, Polyanya runtime queries, and editor/runtime ownership |
|
||
| [0033](adr/0033-dedicated-skinned-mesh-renderer.md) | Dedicated skinned renderer, static/skinned import boundary, and scene migration |
|
||
| [0034](adr/0034-registry-driven-authoring-components.md) | Stable component IDs, reflected lifecycle/history, composition, and independent active state |
|
||
| [0035](adr/0035-shared-material-assets-and-renderer-slots.md) | Shared Material/Material Instance assets, stable renderer slots, and runtime-only property blocks |
|
||
| [0036](adr/0036-surface-abi-and-solari-parity.md) | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
|
||
| [0037](adr/0037-collaborative-authored-file-safety.md) | Exact authored-file revisions, observational Git status, and optional ownership providers |
|
||
| [0038](adr/0038-non-blocking-native-dialog-broker.md) | Worker-owned native waits with one-shot main-thread workflow completion |
|
||
| [0039](adr/0039-inline-height-grid-terrain-foundation.md) | Inline authored height grids with deterministic runtime-only chunk hydration |
|
||
|
||
## Editor framework
|
||
|
||
| Document | Purpose |
|
||
|----------|---------|
|
||
| [editor/release-notes.md](editor/release-notes.md) | Editor framework 1.0 baseline |
|
||
| [editor/evaluations/](editor/evaluations/) | Horizon gate sign-offs (R1–R6) |
|
||
| [editor/architecture.md](editor/architecture.md) | Viewport / PIE / settings data flow |
|
||
| [editor/visual-language.md](editor/visual-language.md) | Editor chrome, viewport, selection, gizmo, and visualizer language |
|
||
| [editor/roadmap.md](editor/roadmap.md) | Phased editor roadmap and status |
|
||
| [editor/brp.md](editor/brp.md) | BRP automation and authoring-only policy |
|
||
| [editor/debt-audit.md](editor/debt-audit.md) | Zero-debt phase gates |
|
||
| [editor/brushes.md](editor/brushes.md) | Brush authoring schema, hydration behavior, and MVP limits |
|
||
| [editor/operator-regression-testing.md](editor/operator-regression-testing.md) | Reusable modal-tool and operator invariant harness |
|
||
| [editor/session-recovery.md](editor/session-recovery.md) | Clean restart, abnormal shutdown, session schema, and privacy boundary |
|
||
| [editor/project-launcher.md](editor/project-launcher.md) | Project manifests, explicit startup roots, recents, and sandbox scaffolding |
|
||
| [editor/build-and-package.md](editor/build-and-package.md) | Editor/headless package profiles, output, exclusions, and metadata |
|
||
| [editor/multi-scene-composition.md](editor/multi-scene-composition.md) | Independent scene tabs, composition ownership, validation, and recovery |
|
||
| [editor/prefab-authoring.md](editor/prefab-authoring.md) | Linked instances, scoped overrides/source Apply, conflicts, variants, unpacking, and local conversion |
|
||
| [editor/audio-authoring.md](editor/audio-authoring.md) | Audio clips, source/listener authoring, audition, buses, runtime parity, and validation |
|
||
| [editor/animation-authoring.md](editor/animation-authoring.md) | glTF rigs/clips, controller states, preview, runtime requests, stable moves, and validation |
|
||
| [editor/navigation-authoring.md](editor/navigation-authoring.md) | Bounds/obstacles/areas/links, deterministic bake, overlay, path preview, and runtime queries |
|
||
| [editor/extensibility.md](editor/extensibility.md) | Static authoring component registration, lifecycle, composition, and history contract |
|
||
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
|
||
| [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
|
||
| [editor/native-dialogs.md](editor/native-dialogs.md) | Non-blocking native dialog acquisition and main-thread result application |
|
||
| [editor/terrain.md](editor/terrain.md) | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries |
|
||
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
|
||
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
|
||
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
|
||
|
||
## Working plans (not canonical long-term)
|
||
|
||
Detailed milestone and feature plans live in [`.cursor/plans/`](../.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 |
|
||
| `source_control_collaboration_safety_*.plan.md` | Exact authored-file guards, observational Git status, conflict recovery, and provider contract |
|
||
| `production_readiness_acceptance_*.plan.md` | Release-candidate evidence matrix, blocker sequence, clean-checkout checks, soak, budgets, and independent sign-off |
|
||
| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |
|
||
|
||
## 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).
|