diff --git a/coordination/claims/M03-RND-M2-ANIMATED-SCENE-FINALIZER-001.md b/coordination/claims/M03-RND-M2-ANIMATED-SCENE-FINALIZER-001.md new file mode 100644 index 0000000..bbf63c6 --- /dev/null +++ b/coordination/claims/M03-RND-M2-ANIMATED-SCENE-FINALIZER-001.md @@ -0,0 +1,91 @@ +# M03-RND-M2-ANIMATED-SCENE-FINALIZER-001 + + + +## Owner + +- Agent ID: `sindo-main-codex` +- Target: M03 Renderer Facade and Safe Extraction +- Branch: `work/sindo-main-codex/m03-m2-animated-scene-finalizer` +- Worktree: `C:\Users\sindo\open-wc-worktrees\m03-m2-animated-scene-finalizer` + +## Outcome + +Extract animated M2 PackedScene candidate instantiation, material override repair +and AnimationPlayer validation from `StreamingWorldLoader` into an explicit +main-thread finalizer. + +## Non-goals + +- Call ResourceLoader or interpret threaded-load statuses. +- Choose animation eligibility, cache paths, material prototypes or permits. +- Adopt/cache prototype Nodes or change static/native animation paths. +- Change visible materials, animation selection, cache formats or profiles. + +## Paths + +- Exclusive: `src/render/m2/m2_animated_scene_finalizer.gd`, + `src/tools/verify_m2_animated_scene_finalizer.gd`, + `docs/modules/m2-animated-scene-finalizer.md`, this claim +- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`, M2 + animation pipeline/prototype/material/build/shutdown/facade/internal-access/ + manifest verifiers and module specs, `docs/modules/world-renderer.md`, + `docs/modules/README.md`, `RENDER.md`, `targets/03-renderer-facade.md` +- Generated/ignored: `.godot`, native DLL, generated M2 resources, caches and + proprietary renderer corpus + +## Contracts and data + +- Only a PackedScene whose instantiated root is Node3D becomes a candidate; + unsupported or invalid roots return null and any created invalid root is freed. +- Material repair preserves depth-first MeshInstance3D order, source-index + clamping, per-surface override priority and first-material fallback. +- Finalization accepts a candidate only when at least one descendant + AnimationPlayer exists; rejected detached candidates are freed synchronously. +- Accepted result transfers the exact Node3D and player count to the loader. +- Loader retains ResourceLoader, material-prototype acquisition, permit, + prototype adoption/static fallback and diagnostic-log decisions. + +## Dependencies + +- Requires: accepted animation load pipeline package on master `c20bc62` +- Blocks: further animated M2 build/materialization decomposition +- External state: imported GLB/PackedScene shape remains engine-owned input + +## Verification + +- Commands: dedicated invalid/ownership/traversal/material/finalization/source/ + timing verifier; animation pipeline/prototype/shutdown/material/M2 build/facade/ + internal-access/manifest and adjacent M2 regressions; docs/coordination/dry-run gates +- Fixtures: synthetic PackedScenes, nested AnimationPlayers and ArrayMesh materials +- Fidelity evidence: exact material mapping and accepted/rejected Node transitions +- Performance budget: 10,000 depth-first candidate queries under 1 second + +## Documentation deliverables + +- Inline public API docs +- Module specification with inputs/outputs, ownership and source map +- Data-flow, lifecycle/state, sequence and dependency diagrams +- Adjacent animation/prototype/world-renderer/module-registry/RENDER updates + +## Simplicity and naming + +- Important name introduced: `M2AnimatedSceneFinalizer` +- Simplest solution: one stateless main-thread RefCounted over engine scene types +- Rejected complexity: callbacks, generic scene pipeline, signals or cache ownership +- Unavoidable complexity: material repair occurs between candidate creation and acceptance +- Measured optimization evidence: bounded synthetic subtree traversal + +## Status + +- State: claimed +- Done: candidate/material/player ownership boundary audited on current master +- Next: implement finalizer, migrate adapters, verify and document +- Blocked by: + +## Handoff + +- Commit: +- Results: +- Remaining risks: +- Documentation updated: