102 lines
4.6 KiB
Markdown
102 lines
4.6 KiB
Markdown
# M03-RND-M2-ANIMATED-SCENE-FINALIZER-001
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-M2-ANIMATED-SCENE-FINALIZER-001:sindo-main-codex:2026-07-20 -->
|
|
|
|
## 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: ready for integration
|
|
- Done: finalizer, loader adapters, lifecycle/material verifier and required documentation
|
|
- Next: integrate on master and run post-merge acceptance gates
|
|
- 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`.
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-M2-ANIMATED-SCENE-FINALIZER-001:1b450dc -->
|