# 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: accepted - Done: finalizer, loader adapters, lifecycle/material verifier and required documentation - Next: continue animated M2 playback/instance materialization extraction - Blocked by: ## Handoff - Commit: `1b450dc` - Results: animated scene finalizer passes 13 invalid/type/lifetime/traversal/ material/transfer/source cases and 10,000 depth-eight queries in 40.126 ms; all 48 autonomous headless verifiers pass, while the proprietary ADT placement probe is unavailable without `data/extracted`; checkpoint dry-run passes 7/7; documentation and coordination gates pass; loader-private inventory remains 30. - Remaining risks: proprietary GLB traversal, material/animation comparison, descriptor pressure, leaks and p95/p99 remain unavailable; no paired original- client visual comparison is claimed. Positional material mapping is unchanged. - Documentation updated: inline API; `m2-animated-scene-finalizer.md` with data-flow, lifecycle, sequence and dependency diagrams; animation pipeline, prototype/world-renderer specs, module registry and `RENDER.md`. ## Integration - Merge commit: `e7a7c67` - Post-merge results: finalizer `cases=13 iterations=10000 elapsed_ms=40.314`; animation pipeline, prototype state, shutdown, materials, facade, internal-access `30`, manifest `7/7`, documentation and coordination passed.