Blacksite/docs/README.md

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
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

Editor framework

Document	Purpose
editor/release-notes.md	Editor framework 1.0 baseline
editor/evaluations/	Acceptance records, screenshots, and Gitea evidence-publishing policy
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/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/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/. 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
terrain_material_layers_*.plan.md	Terrain shared-material layers, normalized weights, blended hydration, and modal painting
operator_invariants_completion_*.plan.md	Production operator dispatch, interruption, rollback, cleanup, and undo/redo acceptance
editor_sample_regression_pack_*.plan.md	Five-area sample manifest, editor catalog, deterministic validation, and native regression acceptance
guarded_shutdown_savepoints_*.plan.md	Native close coordination, asynchronous Save All, and canonical history clean points

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).