open-wc/coordination/claims/M03-RND-M2-ANIMATION-PLAYBACK-001.md

M03-RND-M2-ANIMATION-PLAYBACK-001

Owner

• Agent ID: sindo-main-codex
• Target: M03 Renderer Facade and Safe Extraction
• Branch: work/sindo-main-codex/m03-m2-animation-playback
• Worktree: C:\Users\sindo\open-wc-worktrees\m03-m2-animation-playback

Outcome

Extract deterministic animated M2 playback selection/phase, AnimationPlayer mutation and native animator data/start behavior from StreamingWorldLoader.

Non-goals

• Duplicate or attach animated instances/batch roots.
• Own visibility, shadow, Editor owner or build-job cursor rules.
• Load/finalize/cache scenes or change animation eligibility.
• Change candidate priority, phase formula, logging text or visible playback.

Paths

• Exclusive: src/render/m2/m2_animation_playback_controller.gd, src/tools/verify_m2_animation_playback_controller.gd, docs/modules/m2-animation-playback-controller.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, M2 animated finalizer/build/prototype/material/facade/internal-access/manifest verifiers and specs, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated resources/caches and proprietary corpus

Contracts and data

• Phase remains abs(hash("path:index")) % 1000 / 1000.0.
• Exact animation-name priority remains ordinary Stand/Idle/Run/Walk, fish Run/Walk/Swim/Stand/Idle/Death, birds Run/Walk/Swim/Stand/Idle, then case-insensitive substring fallback and first-name fallback.
• Every AnimationPlayer animation becomes linear-looping before selected play; positive-length selection seeks to deterministic phase.
• Native animators match exact script identity in depth-first order, copy the same five fields, call prepare_runtime when available and set phase.
• Runtime debug state is sampled only when existing debug mode requests it; loader retains final log formatting/path normalization.

Dependencies

• Requires: accepted animated scene finalizer package on master c0a7bfb
• Blocks: animated M2 instance materializer extraction
• External state: AnimationPlayer and M2NativeAnimator APIs remain engine/scene contracts

Verification

• Commands: dedicated phase/selection/loop/play/seek/native-copy/start/diagnostic/ source/timing verifier; animated finalizer/pipeline/prototype/build/shutdown/ material/facade/internal-access/manifest regressions; docs/coordination/dry-run gates
• Fixtures: synthetic AnimationPlayers and real M2NativeAnimator nodes
• Fidelity evidence: exact priority, phase and mutation/reference contracts
• Performance budget: 20,000 selection/phase operations under 1 second

Documentation deliverables

• Inline API docs
• Module spec with inputs/outputs, ownership and source map
• Data-flow, lifecycle/state, sequence and dependency diagrams
• Adjacent finalizer/build/world-renderer/module-registry/RENDER updates

Simplicity and naming

• Important name introduced: M2AnimationPlaybackController
• Simplest solution: stateless main-thread RefCounted over supplied Nodes/players
• Rejected complexity: signals, playback state machine, generic animation framework
• Unavoidable complexity: native and imported AnimationPlayer paths coexist
• Measured optimization evidence: bounded selection/phase loop

Status

• State: claimed
• Done: playback/native ownership boundary audited on current master
• Next: implement controller, migrate adapters, verify and document
• Blocked by:

Handoff

• Commit:
• Results:
• Remaining risks:
• Documentation updated: