15 KiB
15 KiB
Project Documentation
Central index for design decisions, mission, editor framework docs, and repository workflow.
Before treating any document as current guidance, read authority.toml.
Core
| Document | Purpose |
|---|---|
| authority.toml | Machine-readable current/plan/evidence/historical/superseded classification |
| mission.md | Why the editor framework exists, principles, audience, non-goals |
| ../README.md | Run/build instructions, controls, implementation checklist |
Repository workflow
| Document | Purpose |
|---|---|
| workflow/codex-workflow.md | Task lifecycle, scope deltas, and completion states |
| workflow/documentation-policy.md | Authority hierarchy, lifecycle classes, and integrity audit |
| workflow/verification-policy.md | Fast, slice, and candidate verification tiers |
| workflow/build-storage-policy.md | Managed Cargo lanes, budgets, and safe pruning |
| workflow/gitea-tracking-policy.md | Tracker state and mutation boundaries |
| archive/ | Preserved non-current documentation records |
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 |
| 0037 | Exact authored-file revisions, observational Git status, and optional ownership providers |
| 0038 | Worker-owned native waits with one-shot main-thread workflow completion |
| 0039 | Inline authored height grids with deterministic runtime-only chunk hydration |
| 0040 | Four-channel terrain material layers, compact normalized weights, and raster transport |
| 0041 | Paused editor physics ownership and transactional gravity placement |
| 0042 | Guarded native editor exit and canonical per-document clean checkpoints |
| 0043 | Content-addressed imported-source identity and byte-preserving artifact publication |
| 0044 | Sandboxed FBX texture bundles, validation policy, and deduplicated loading |
| 0045 | Path-agnostic content workspace, registry v3, model material defaults, and DefaultGrid fallback |
| 0046 | Schema-driven Material inputs, registry v3 Texture settings, ARM packing, and deterministic runtime textures |
| 0047 | Editor-dirty asset documents, explicit saves, recovery, and background derived publication |
| 0048 | Thin editor composition, registry-only Inspector dispatch, and automated architecture debt ratchet |
| 0049 | Penpot-led visual tokens, responsive editor components, Source Sans Pro typography, and picker interaction |
Editor framework
| Document | Purpose |
|---|---|
| editor/release-notes.md | Historical editor framework 1.0 snapshot |
| editor/evaluations/ | Dated acceptance evidence and Gitea evidence-publishing policy; not product specification |
| editor/architecture.md | Viewport / PIE / settings data flow |
| editor/visual-language.md | Editor chrome, viewport, selection, gizmo, and visualizer language |
| editor/design-system.md | Penpot-led visual tokens, reusable controls, responsive geometry, and material-inspector presentation |
| 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/content-workspace.md | File-manager content organization, destination-first import, stable IDs, and model material authoring |
| editor/collaborative-file-safety.md | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
| editor/native-dialogs.md | Non-blocking native dialog acquisition and main-thread result application |
| editor/terrain.md | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries |
| editor/physics-placement.md | Transactional gravity placement, diagnostics, isolation, and undo workflow |
| editor/collider-authoring.md | Collider shape authoring, hydration diagnostics, semantic overlays, and placement prerequisites |
| editor/sample-regression-pack.md | Five-area sample catalog, editor workflow, validation gates, and visual QA contract |
| editor/evaluations/material-renderer-foundation/ | Live screenshots and acceptance results for the renderer/material/component foundation |
| editor/evaluations/terrain-sculpt-tools/ | Live screenshot and acceptance results for modal terrain sculpt tools |
| editor/evaluations/terrain-material-layers/ | Live screenshot and acceptance results for terrain material assignment, blending, painting, and history |
| editor/evaluations/physics-placement/ | Live screenshot and acceptance results for physics settling, cancel, commit, undo, and redo |
| editor/evaluations/collider-diagnostics/ | Live screenshot and acceptance results for collider overlays, diagnostics, shape history, and placement preflight |
| editor/evaluations/navigation-authoring/ | Live screenshots and acceptance results for navigation authoring and runtime parity |
| editor/evaluations/operator-invariants/ | Source acceptance results for production operator lifecycle, rollback, cleanup, and undo/redo invariants |
| editor/evaluations/sample-regression-pack/ | Exact-implementation source and native acceptance evidence for the editor sample regression pack |
| editor/evaluations/guarded-shutdown-savepoints/ | Source and native acceptance evidence for guarded editor exit and per-document clean checkpoints |
| editor/evaluations/scoped-ui-actions/ | Exact-implementation source and native acceptance evidence for actions invoked during scoped egui rendering |
| editor/evaluations/deterministic-asset-fingerprints/ | Source, fresh-checkout, hash-stability, and native acceptance evidence for imported-source fingerprints |
| editor/evaluations/fbx-external-texture-dependencies/ | Source, validation, and native acceptance evidence for sandboxed FBX texture dependencies and override states |
| editor/evaluations/content-workspace-m2/ | Native M2 evidence for Content Browser file-manager selection, context menus, managed-folder visibility, and Details resizing |
| editor/evaluations/production-readiness/ | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
Plans
Plans describe desired scope and acceptance, never current implementation truth. Their authoritative
classification is in authority.toml; completed plans are frozen as historical
records instead of being rewritten as status diaries.
Current active plans:
- Content workspace and import authoring
- Production-readiness program
- Production-readiness acceptance gate
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/content_pipeline/ UI-independent content catalog, transaction, import, and processing engine
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).