# M03-RND-M2-ANIMATION-PLAYBACK-001

<!-- OPENWC_CLAIM:M03-RND-M2-ANIMATION-PLAYBACK-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-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: accepted
- Done: playback controller, loader adapters, verifier and required documentation
- Next: extract animated M2 instance/batch materialization
- Blocked by:

## Handoff

- Commit: `9b73571`
- Results: playback controller passes 15 phase/selection/loop/play/seek/native-
  copy/start/diagnostic/source cases and 20,000 phase-selection pairs in
  23.415 ms; all 49 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: private animation-name/timing/native visual comparison,
  descriptor pressure, leaks and p95/p99 remain unavailable; default selection
  is still heuristic and no paired original-client comparison is claimed.
- Documentation updated: inline API; `m2-animation-playback-controller.md` with
  data-flow, lifecycle, sequence and dependency diagrams; finalizer/build/world-
  renderer specs, module registry and `RENDER.md`.

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-ANIMATION-PLAYBACK-001:9b73571 -->

## Integration

- Merge commit: `c0fc191`
- Post-merge results: playback `cases=15 iterations=20000 elapsed_ms=23.008`;
  animated finalizer/pipeline, prototype, build, shutdown, materials, facade,
  internal-access `30`, manifest `7/7`, documentation and coordination passed.

<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-ANIMATION-PLAYBACK-001:c0fc191 -->