91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# 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: 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:
|