diff --git a/coordination/claims/M03-RND-M2-ANIMATION-PLAYBACK-001.md b/coordination/claims/M03-RND-M2-ANIMATION-PLAYBACK-001.md new file mode 100644 index 0000000..463733c --- /dev/null +++ b/coordination/claims/M03-RND-M2-ANIMATION-PLAYBACK-001.md @@ -0,0 +1,90 @@ +# 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: