diff --git a/.cursor/plans/material_library_and_targeted_drop_2026-07-12.plan.md b/.cursor/plans/material_library_and_targeted_drop_2026-07-12.plan.md new file mode 100644 index 0000000..07a7975 --- /dev/null +++ b/.cursor/plans/material_library_and_targeted_drop_2026-07-12.plan.md @@ -0,0 +1,84 @@ +# Material Library And Targeted Viewport Drop + +Working implementation plan for Gitea issues +[`#16`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/16) and +[`#18`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/18). +The shared Material/Material Instance and stable renderer-slot foundation from `#51` is already +present; this slice completes the production-facing catalog and drag/drop workflow. + +## Status + +Source audit complete. Implementation starts on a clean branch after collaborative-safety `#49` is +published, because both slices touch the Asset Browser and should remain independently reviewable. + +## Current Gaps + +- Material assets are edited inside generic Asset Browser Details; no dedicated Material Library or + scene-usage view exists. +- Viewport material/texture drops act on the existing selection instead of the surface under the + pointer. +- Multi-slot renderers silently assign all slots; the hydrated draw hit already carries + `HydratedRendererMaterialBinding`, but the drop path does not use it. +- Primitive and brush-face targeting is not explicit, and unsupported authored actors can receive a + generic `MaterialDesc` instead of an actionable rejection. +- Drag UI describes an eventual action but does not preview the actual affected surface or restore a + preview on cancel/target change. + +## Material Library + +1. Add a dockable `Material Library` panel, opened from Window and placed in the existing bottom dock + without adding another permanent toolbar. +2. Present project Materials and Material Instances with search, Material/Instance filter, thumbnail + grid/list modes, base/dependency health, and source-control status. +3. Add a scene-usage section that counts renderer-slot, primitive, and brush-face references and can + select/locate users. Do not revive ambiguous hidden scene-local material clones. +4. Reuse the existing guarded Material/Instance drafts for Apply, Revert, Create Instance, and + texture-parameter editing. Shared-file edits remain explicit; scene assignment changes use + history. +5. Material and Instance cells are first-class drag sources and preserve the current pointer-following + visual identity. + +## Targeted Drop Contract + +Introduce a frame-updated `ViewportAssetDropTarget` resolved by the existing mesh-picking path: + +- A hydrated static/skinned draw maps through `HydratedRendererMaterialBinding` to the authored actor + and exact stable slot ID. +- A primitive maps to its authored actor-level `MaterialDesc`. +- A brush performs authored face intersection and identifies the stable face ID. +- An authored but unsupported target remains a visible invalid target with a specific reason. +- Empty space remains placement-only for placeable assets and invalid for Material/Texture payloads. + +Payload matrix: + +| Payload | Renderer slot | Primitive | Brush face | +|---------|---------------|-----------|------------| +| Material / Material Instance | Assign exact hit slot; one-slot actors may assign directly | Replace actor material reference/values | Replace the hit face material reference | +| Texture | Reject with guidance to create/edit a Material Instance | Set base-color texture | Set hit-face base-color texture/material binding | + +An explicit `Apply All Slots` command remains available from the renderer inspector/library usage +menu; a viewport hit never silently broadens from one slot to all slots. + +## Preview, Commit, And Cancel + +1. Start a persistent drop-preview session when a supported Material/Texture payload enters the + viewport. Snapshot only the target's affected authored state. +2. Apply a transient visual preview without pushing history or marking the scene dirty. +3. When the pointer changes target, restore the previous snapshot before previewing the new target. +4. On release, restore the transient state first, then commit exactly one typed history/operator + transaction to the identified slot, primitive, or face. +5. On Escape, drag cancellation, leaving the viewport, invalid target, or missing source, restore the + exact snapshot and remove every preview/helper marker. +6. The drag card and target outline name the payload, actor, slot/face, action, and invalid reason. + +## Verification + +- Unit-test ray-hit to authored target/slot mapping, primitive/face targeting, and invalid reasons. +- Use `OperatorInvariantHarness` for preview target changes, release commit, Escape/outside cancel, + dirty-state preservation, helper cleanup, and one-step undo/redo. +- Cover static one/multi-slot, skinned multi-slot, primitive, brush face, Texture rejection on a + renderer slot, missing material, and linked/locked prefab boundaries. +- Verify Material Library filtering, scene-usage counts, dependency diagnostics, and drag sources in + headless egui tests. +- Run full source/headless checks. Packaged testing remains deferred until the project owner requests + it again; live visual acceptance is still required before closing `#16`/`#18`. diff --git a/.cursor/plans/production_readiness_acceptance_2026-07-12.plan.md b/.cursor/plans/production_readiness_acceptance_2026-07-12.plan.md new file mode 100644 index 0000000..cd6b308 --- /dev/null +++ b/.cursor/plans/production_readiness_acceptance_2026-07-12.plan.md @@ -0,0 +1,37 @@ +# Production-Readiness Acceptance Gate + +Working plan for Gitea issue +[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50). +This gate is broader than the M7 feature list: it proves the complete daily authoring, content, +recovery, performance, and release workflow against one exact release-candidate commit. + +## Status + +Audit in progress. The versioned acceptance matrix exists, but no release candidate is nominated and +the gate is not signed off. Packaged/release testing remains explicitly deferred until the project +owner requests it again. + +## Sequence + +1. Keep one evidence matrix under `docs/editor/evaluations/production-readiness/`; historical H1-H6 + notes remain context only. +2. Close implementation blockers before nominating a candidate: collaborative safety `#49`, the + remaining Material/drag-drop contract in `#16`, `#18`, and `#51`, terrain `#22`-`#24`, physics + placement/diagnostics `#25`-`#26`, and their regression fixtures. +3. Complete the representative regression project, mutation-invariant coverage, performance budgets, + and first-hour workflow tracked by `#32`-`#36`. +4. Nominate one exact commit, validate it from a clean checkout, and record source/headless results. +5. When packaged testing is re-enabled, run the candidate's package/build and packaged-runtime + matrix without substituting older artifacts. +6. Run the eight-hour soak and measured performance protocol, consolidate limitations by severity + and workaround, and obtain independent first-hour/recovery sign-off. +7. Post the signed Gitea milestone comment linking the exact commit and immutable evidence. Close + `#50` only when every required row passes and no P0 blocker remains. + +## Gate Rules + +- Feature presence is not acceptance evidence. +- A local dirty worktree is not a release candidate. +- Results from another commit or an old package do not transfer to the candidate. +- Deferred, missing, partial, and implementer-only evidence are not passes. +- Every failure records an owner ticket or a concrete rerun condition. diff --git a/docs/README.md b/docs/README.md index 20189a4..fa529e2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -79,6 +79,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi | [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers | | [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) @@ -98,6 +99,8 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans | `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) diff --git a/docs/editor/README.md b/docs/editor/README.md index 634d4bd..6ea2a87 100644 --- a/docs/editor/README.md +++ b/docs/editor/README.md @@ -26,6 +26,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a | [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers | | [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation | | [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity | +| [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence | ## Subsystems (code → doc) diff --git a/docs/editor/evaluations/h1-signoff.md b/docs/editor/evaluations/h1-signoff.md index aacb136..3c1c543 100644 --- a/docs/editor/evaluations/h1-signoff.md +++ b/docs/editor/evaluations/h1-signoff.md @@ -1,5 +1,7 @@ # H1 Gate Sign-Off — Game Development Ready +> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/). + **Date:** 2026-05-30 **Evaluator:** implementation pass **Result:** Pass (implementation complete; manual dogfood recommended) diff --git a/docs/editor/evaluations/h2-signoff.md b/docs/editor/evaluations/h2-signoff.md index 8790e4f..0984984 100644 --- a/docs/editor/evaluations/h2-signoff.md +++ b/docs/editor/evaluations/h2-signoff.md @@ -1,5 +1,7 @@ # H2 Gate Sign-Off — Content Pipeline Maturity +> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/). + **Date:** 2026-05-30 **Result:** Pass with waivers diff --git a/docs/editor/evaluations/h3-signoff.md b/docs/editor/evaluations/h3-signoff.md index 2617923..8a49722 100644 --- a/docs/editor/evaluations/h3-signoff.md +++ b/docs/editor/evaluations/h3-signoff.md @@ -1,5 +1,7 @@ # H3 Gate Sign-Off — Gameplay Authoring +> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/). + **Date:** 2026-05-30 **Result:** Pass diff --git a/docs/editor/evaluations/h4-signoff.md b/docs/editor/evaluations/h4-signoff.md index e53c558..9f9cdae 100644 --- a/docs/editor/evaluations/h4-signoff.md +++ b/docs/editor/evaluations/h4-signoff.md @@ -1,5 +1,7 @@ # H4 Gate Sign-Off — Multiplayer Tooling +> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/). + **Date:** 2026-05-30 **Result:** Pass with waivers diff --git a/docs/editor/evaluations/h5-signoff.md b/docs/editor/evaluations/h5-signoff.md index e00f336..ebc027a 100644 --- a/docs/editor/evaluations/h5-signoff.md +++ b/docs/editor/evaluations/h5-signoff.md @@ -1,5 +1,7 @@ # H5 Gate Sign-Off — Extensibility +> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/). + **Date:** 2026-05-30 **Result:** Pass diff --git a/docs/editor/evaluations/h6-signoff.md b/docs/editor/evaluations/h6-signoff.md index c3fd3ce..cb45bf6 100644 --- a/docs/editor/evaluations/h6-signoff.md +++ b/docs/editor/evaluations/h6-signoff.md @@ -1,5 +1,7 @@ # H6 Gate Sign-Off — Production / Framework 1.0 +> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/). + **Date:** 2026-05-30 **Result:** Pass with waivers diff --git a/docs/editor/evaluations/production-readiness/README.md b/docs/editor/evaluations/production-readiness/README.md new file mode 100644 index 0000000..7dead10 --- /dev/null +++ b/docs/editor/evaluations/production-readiness/README.md @@ -0,0 +1,104 @@ +# Production-Readiness Acceptance Matrix + +**Matrix version:** 0.1 + +**Last audit:** 2026-07-12 + +**Release-candidate commit:** Not nominated + +**Overall result:** **Not ready** + +This is the current authority for Gitea +[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50). +The older H1-H6 files are historical implementation snapshots and do not satisfy this gate. + +## Evidence Rules + +| State | Meaning | +|-------|---------| +| Pass | Candidate-specific evidence proves the full row. | +| Partial | Some implementation/evidence exists, but the full row is not proven. | +| Deferred | The project owner has explicitly postponed this check; it is not a pass. | +| Missing | Required implementation or candidate evidence does not exist. | +| Fail | Current authoritative evidence contradicts the gate. | +| External | Requires a person other than the implementer. | + +Acceptance evidence must name the exact candidate commit and commands or protocol used. Results from +another commit, a dirty worktree, or an older package do not transfer to the candidate. + +## Exit Gate + +| ID | Requirement | State | Current evidence and gap | +|----|-------------|-------|--------------------------| +| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Candidate-specific end-to-end reruns and the open asset-integrity work remain. | +| G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Fail | Animation, audio, navigation, and build foundations are implemented. Material/drag-drop tickets `#16`, `#18`, and `#51` remain open; terrain `#22`-`#24` and physics placement `#25` are not complete; brush acceptance `#37` remains open. Packaged testing is owner-deferred. | +| G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | The reusable harness and current tool coverage are documented in [operator regression testing](../../operator-regression-testing.md). Gitea `#33` remains open for terrain-stroke and physics-settle fixtures after those tools exist. | +| G4 | Representative project completes an eight-hour soak without unbounded memory/target growth or unrecoverable failure | Missing | No candidate soak log, resource timeline, failure ledger, or target-growth measurement exists. | +| G5 | Cold start, scene open/save, asset refresh, common manipulation, and package-build budgets are documented and measured | Missing | Gitea `#34` is open; no ratified budgets or candidate measurement record exists. | +| G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) exists and local source/headless checks have passed during feature work, but no clean-checkout candidate run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. | +| G7 | First-hour UX and recovery QA are signed off by someone other than the implementer | External | No independent sign-off exists. Gitea `#36` remains open; historical H1-H6 implementation-pass notes do not count. | +| G8 | Known limitations have severity/workaround and no P0 blocker remains | Fail | Limitations are distributed across feature docs rather than one candidate ledger. Open P0 work includes `#16`, `#18`, `#32`, `#33`, `#35`, and `#51`; `#50` cannot close while a gate-relevant P0 remains. | + +## Deliverables + +| ID | Deliverable | State | Evidence or next action | +|----|-------------|-------|-------------------------| +| D1 | Versioned acceptance matrix under `docs/editor/evaluations/` | Pass | This file, version 0.1. | +| D2 | Release-candidate representative project and reproducible validation commands | Missing | Expand the committed project/regression pack through `#32`, including terrain and physics-placement samples, then nominate an exact commit. | +| D3 | Signed milestone comment linking evidence, limitations, and exact commit | Missing | Post only after G1-G8 pass; no candidate exists yet. | + +## Workflow Coverage + +| Workflow | Implementation status | Candidate acceptance | +|----------|-----------------------|----------------------| +| Project create/open/resume | Implemented | Not rerun | +| Scene save, autosave, recovery | Implemented | Not rerun | +| Hierarchy parenting and prefab structure | Implemented | Not rerun | +| Multi-scene composition | Implemented | Not rerun | +| Brush blockout/edit/CSG | Implemented foundation; `#37` open | Not signed off | +| Material catalog and assignment | Partial; `#16`, `#18`, `#51` open | Blocked | +| Terrain authoring | `#22`-`#24` open | Blocked | +| Physics placement | `#25` open | Blocked | +| Animation | Implemented | Not rerun | +| Audio | Implemented | Not rerun | +| Navigation | Implemented | Not rerun | +| PIE | Implemented | Not rerun | +| Build/package/runtime | Implemented foundation | Deferred by owner | +| Collaborative file safety | Local source/headless acceptance; `#49` open | Awaiting publication and live visual QA | + +## Candidate Validation Commands + +Run these from a fresh clone of the nominated commit with Git LFS content present. Record wall time, +machine profile, exit code, and artifact hashes. Packaged commands stay disabled until the project +owner re-enables them. + +```bash +cargo fmt --all -- --check +cargo check --workspace --all-targets +cargo clippy --workspace --all-targets -- -D warnings +cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings +cargo test --workspace +cargo validate-levels --project . +cargo bake-navigation --project . --check +``` + +When packaged acceptance is re-enabled, append the exact `package-project` profile/target commands, +package hash verification, and packaged-runtime smoke protocol used for the candidate. + +## Soak Protocol + +The final candidate must run for eight continuous hours against the representative project. The +record must sample process RSS, GPU memory, target-directory size, recovery generations, background +job counts, and error/warning totals at least every five minutes. Exercise scene switching, save and +recovery, asset refresh, material editing, brush/terrain/physics tools, animation/audio/navigation, +PIE transitions, and build UI cancellation without replacing the candidate during the run. + +A pass requires no unrecoverable editor failure, no lost authored work, no unbounded upward trend in +steady-state resource use, bounded recovery/cache behavior, and a triaged explanation for every +error. Numeric thresholds remain blocked on the performance-budget work in `#34`. + +## Independent Sign-Off + +The evaluator must not be the implementation agent. They record the candidate commit, machine, +elapsed first-hour workflow, recovery scenario, defects, severity, and go/no-go decision. Waivers +must include a workaround and owner ticket; an open P0 cannot be waived.