sindoring/open-wc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor(M03): extract M2 animation playback

Browse Source
This commit is contained in:
sindoring
2026-07-18 01:25:54 +04:00
parent 5be36376c2
commit 9b73571dcb
12 changed files with 615 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/README.md
+1
View File
@@ -23,6 +23,7 @@
| M2 build batch planner | Implemented extraction | [`m2-build-batch-planner.md`](m2-build-batch-planner.md) |
| M2 runtime mesh rebuild classifier | Implemented extraction | [`m2-runtime-mesh-rebuild-classifier.md`](m2-runtime-mesh-rebuild-classifier.md) |
| M2 animated scene finalizer | Implemented extraction | [`m2-animated-scene-finalizer.md`](m2-animated-scene-finalizer.md) |
| M2 animation playback controller | Implemented extraction | [`m2-animation-playback-controller.md`](m2-animation-playback-controller.md) |
| M2 animation load pipeline state | Implemented extraction | [`m2-animation-load-pipeline-state.md`](m2-animation-load-pipeline-state.md) |
| M2 mesh load pipeline state | Implemented extraction | [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md) |
| M2 mesh resource cache state | Implemented extraction | [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md) |
docs/modules/m2-animated-scene-finalizer.md
+4 -1
View File
@@ -172,7 +172,8 @@ versions and prototype lifetimes are unchanged; no rebake is required.
## Extension points
Animation playback policy and native animator cloning remain separate services.
Animation playback policy and native animator field copying now belong to
`M2AnimationPlaybackController`; instance/batch materialization remains loader-owned.
## Capability status
@@ -193,6 +194,7 @@ Animation playback policy and native animator cloning remain separate services.
| Path | Responsibility |
|---|---|
| `src/render/m2/m2_animated_scene_finalizer.gd` | Candidate ownership, traversal, material repair and validation |
| `src/render/m2/m2_animation_playback_controller.gd` | Accepted-instance playback and native animator startup |
| `src/render/m2/m2_animation_load_pipeline_state.gd` | Pending/terminal records before finalization |
| `src/render/m2/m2_prototype_cache_state.gd` | Accepted prototype/static-only outcomes |
| `src/scenes/streaming/streaming_world_loader.gd` | I/O, permits, material source, adoption and logs |
@@ -200,6 +202,7 @@ Animation playback policy and native animator cloning remain separate services.
## Related decisions and references
- [`m2-animation-playback-controller.md`](m2-animation-playback-controller.md)
- [`m2-animation-load-pipeline-state.md`](m2-animation-load-pipeline-state.md)
- [`m2-prototype-cache-state.md`](m2-prototype-cache-state.md)
- [`world-renderer.md`](world-renderer.md)
docs/modules/m2-animation-playback-controller.md
+212
View File
@@ -0,0 +1,212 @@
# M2 Animation Playback Controller
## Metadata
| Field | Value |
|---|---|
| Status | Implemented extraction |
| Target/work package | M03 / `M03-RND-M2-ANIMATION-PLAYBACK-001` |
| Owners | Per-instance AnimationPlayer/native animator playback mutation |
| Last verified | Worktree `work/sindo-main-codex/m03-m2-animation-playback`, 2026-07-18 |
| Profiles/capabilities | Imported GLB and native experimental animated M2 instances |
## Purpose
Apply deterministic playback to one already duplicated M2 instance: copy native
animator runtime fields, derive a stable phase, prepare/phase native animators,
select an imported animation and configure linear looping/playback/seek.
## Non-goals
- Duplicate, name, transform or attach instances/batch roots.
- Apply visibility, shadows or Editor ownership.
- Load/finalize/cache animated scenes or decide eligibility.
- Change animation priorities, phase formula or native animator implementation.
## Context and boundaries
```mermaid
flowchart LR
Prototype[Animated prototype] --> Loader[StreamingWorldLoader materializer]
Loader -->|source and duplicate| Playback[M2AnimationPlaybackController]
Finalizer[M2AnimatedSceneFinalizer player inventory] --> Playback
Playback --> Native[M2NativeAnimator mutation]
Playback --> Imported[AnimationPlayer mutation]
```
Allowed dependencies are supplied Nodes, Script identity, AnimationPlayer and
Animation resources. ResourceLoader, files, workers, caches, scheduler,
MultiMesh, SceneTree attachment and application layers are forbidden.
## Public API
| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|---|---|---|---|---|
| `copy_native_animator_data(source_root, target_root, script)` | Command | Copy five runtime fields in depth-first pair order | Main thread; borrowed nodes | Null/script mismatch yields no pairs |
| `start_instance_playback(root, path, index, script, players, collect_diagnostics)` | Command/query | Start native/imported playback and optionally return native state | Main thread; one instance | Null/empty inventories no-op |
| `native_animators_in_subtree(root, script)` | Query | Exact-script depth-first inventory | Main thread; borrowed nodes | Null root/script returns empty |
| `phase_for_instance(path, index)` | Pure query | Stable phase in `[0, 1)` | Any thread; scalar | Historical hash behavior retained |
| `choose_default_animation(player, path)` | Pure engine query | Apply exact ordinary/fish/bird/fallback priority | Main thread; borrowed player | Null/no animations returns empty |
## Inputs and outputs
| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|---|---|---|---|---|---|
| Input | Prototype and duplicate subtrees | Loader materializer | Native field copy | Borrowed Nodes | One duplicate |
| Input | Exact native animator Script | Loader composition | Native inventory | Borrowed Script | Call-local |
| Input | Relative path and instance index | Build batch adapter | Phase/selection | Copied values | One start |
| Input | AnimationPlayer inventory | Animated scene finalizer traversal | Imported playback | Borrowed players | One start |
| Output | Mutated native/imported playback | Controller | Rendered instance | Nodes retain state/resources | Instance lifetime |
| Output | Detached native diagnostic records | Controller | Loader log adapter | Caller-owned Dictionaries | Debug call |
Side effects are native field assignment, prepare/phase calls, animation loop
mutation, play and seek. The service retains no inputs.
## Data flow
```mermaid
flowchart TD
Identity[Path and index] --> Phase[Stable hash phase]
NativeInventory[Exact-script native inventory] --> Prepare[prepare runtime if available]
Phase --> NativePhase[set native phase]
Players[AnimationPlayers] --> Select[Choose path-specific default]
Select --> Loop[Set every animation LOOP_LINEAR]
Loop --> Play[Play selected name]
Phase --> Seek[Seek positive-length selection]
NativePhase --> Diagnostics{Debug requested?}
Diagnostics -->|yes| Snapshot[Detached runtime state]
```
## Lifecycle/state
```mermaid
stateDiagram-v2
[*] --> Unstarted
Unstarted --> Prepared: copy native data and start
Prepared --> Playing: native phase and/or AnimationPlayer play
Playing --> Playing: repeated deterministic start
Playing --> [*]: instance owner releases subtree
```
The controller itself is stateless; lifecycle labels describe borrowed instance state.
## Main sequence
```mermaid
sequenceDiagram
participant L as StreamingWorldLoader
participant F as M2AnimatedSceneFinalizer
participant P as M2AnimationPlaybackController
participant N as M2NativeAnimator
participant A as AnimationPlayer
L->>P: copy_native_animator_data(prototype, duplicate, script)
L->>F: animation_players_in_subtree(duplicate)
F-->>L: ordered players
L->>P: start_instance_playback(path, index, players, debug)
P->>N: prepare_runtime and set_phase
P->>A: choose, loop, play and seek
P-->>L: optional detached native diagnostics
L->>L: preserve existing log format
```
## Dependency diagram
```mermaid
flowchart TB
Loader[StreamingWorldLoader] --> Playback[M2AnimationPlaybackController]
Finalizer[M2AnimatedSceneFinalizer] --> Loader
Playback --> Engine[Node / Script / AnimationPlayer / Animation]
Loader --> Batch[SceneTree batch materialization]
Loader --> NativeScript[M2NativeAnimator script]
Playback -. no dependency .-> ResourceLoader
Playback -. no dependency .-> Cache[M2PrototypeCacheState]
Playback -. no dependency .-> Scheduler[RenderBudgetScheduler]
```
## Ownership, threading and resources
- Loader owns prototype duplication, instance/batch roots and SceneTree attachment.
- Finalizer traversal supplies borrowed AnimationPlayer references.
- Controller borrows Nodes/Script/players only for the synchronous call.
- Native arrays are assigned by reference exactly as before extraction.
- Diagnostic Dictionaries are deep-duplicated before return.
- Main thread performs all engine-object mutation; pure phase math is thread-safe.
## Errors, cancellation and recovery
| Failure | Detection | Behavior | Diagnostic | Recovery |
|---|---|---|---|---|
| Missing roots/script | Inventory guard | No native copy/start | Contract fixture | Correct composition |
| Fewer target animators | Pair-count minimum | Copy available pairs only | Native copy fixture | Rebuild import/prototype |
| No matching name | Ordered fallback | Substring, first name, then empty | Selection fixtures | Add compatible animation |
| Empty animation selection | Empty result | Skip loop/play/seek for that player | Selection fixture | Static/native path continues |
| Zero-length selected animation | Length guard | Play without seek | Playback contract | Imported timing remains engine-owned |
| Cancellation/shutdown | Outside service | No retained state | N/A | Loader owns subtree release |
## Configuration and capabilities
| Setting/capability | Default | Profile | Runtime mutable | Effect |
|---|---|---|---|---|
| Phase buckets | 1000 | All | No | Stable per path/index desynchronization |
| Loop mode | `LOOP_LINEAR` | All | No | Every available imported animation loops |
| Native diagnostics | `debug_streaming` | Debug | Yes | Samples state only when requested |
## Persistence, cache and migration
No state or format is serialized. GLB/native cache formats, prototype lifetime
and material versions are unchanged; no rebake is required.
## Diagnostics and observability
- Optional native states remain detached and contain existing prepared,
processing, mesh, bone, surface and length fields.
- Loader retains `M2_NATIVE_ANIMATOR` log formatting and path normalization.
- Controller emits no logs or metrics.
## Verification
- `verify_m2_animation_playback_controller.gd` covers exact phase, ordinary/
fish/bird priorities, substring/first fallback, loop/play/seek, native exact-
script order, five-field copy, phase, detached diagnostics and boundaries.
- Finalizer/build/prototype/material/shutdown regressions protect adjacent behavior.
- Fidelity evidence is exact policy/mutation extraction; no private asset or
original-client animation comparison is claimed.
- Performance budget: 20,000 phase-and-selection pairs under one second.
## Extension points
Server-driven animation state may later replace default selection through a
separate presentation contract; this fallback controller must remain available
for world doodads and compatibility fixtures.
## Capability status
| Capability | Status | Evidence | Gap/next step |
|---|---|---|---|
| Imported default selection/playback | Implemented extraction | Synthetic priority/play/seek verifier | Asset-backed animation-name corpus pending |
| Native data/phase startup | Implemented extraction | Exact-reference/native state verifier | Native visual fidelity remains experimental |
| Instance/batch materialization | Existing loader-owned | Adjacent build tests | Safe extraction next |
## Known gaps and risks
- Hash phase intentionally depends on existing Godot String hashing behavior.
- Default-name heuristics are not a complete WoW animation-state mapping.
- No proprietary traversal, animation timing comparison, p95/p99 or paired-client run exists.
## Source map
| Path | Responsibility |
|---|---|
| `src/render/m2/m2_animation_playback_controller.gd` | Phase, selection, native copy/start and imported playback |
| `src/render/m2/m2_animated_scene_finalizer.gd` | Accepted prototype/player inventory |
| `src/scenes/streaming/m2_native_animator.gd` | Experimental native deformation runtime |
| `src/scenes/streaming/streaming_world_loader.gd` | Instance duplication/attachment and diagnostic formatting |
| `src/tools/verify_m2_animation_playback_controller.gd` | Policy/mutation/boundary/timing regression |
## Related decisions and references
- [`m2-animated-scene-finalizer.md`](m2-animated-scene-finalizer.md)
- [`m2-build-batch-planner.md`](m2-build-batch-planner.md)
- [`world-renderer.md`](world-renderer.md)
- [`../../RENDER.md`](../../RENDER.md)
- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)
docs/modules/m2-build-batch-planner.md
+2 -1
View File
@@ -174,7 +174,8 @@ queue depth, build activity and hitch observability.
| Path | Responsibility |
|---|---|
| `src/render/m2/m2_build_batch_planner.gd` | Pure limit/count/cursor planning |
| `src/scenes/streaming/streaming_world_loader.gd` | Build job, queue, resources, materialization and budgets |
| `src/scenes/streaming/streaming_world_loader.gd` | Build job, queue, resources, instance materialization and budgets |
| `src/render/m2/m2_animation_playback_controller.gd` | Animated-instance phase/selection/native/imported playback |
| `src/render/m2/m2_placement_grouper.gd` | Produces grouped transform arrays |
| `src/tools/verify_m2_build_batch_planner.gd` | Formula, source and timing regression |
docs/modules/world-renderer.md
+6 -1
View File
@@ -7,7 +7,7 @@
| Status | Partial |
| Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; M03 facade/planner/scheduler/internal-access/ground/environment/entity packages; M03 terrain packages; M03 M2 packages; M03 WMO placement package |
| Owners | Renderer workstream / milestone integrator |
| Last verified | Worktree `work/sindo-main-codex/m03-m2-animated-scene-finalizer`, 2026-07-18 |
| Last verified | Worktree `work/sindo-main-codex/m03-m2-animation-playback`, 2026-07-18 |
| Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |
## Purpose
@@ -135,6 +135,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
| `M2RuntimeMeshRebuildClassifier` | Internal memoized M2 service | Detects billboard/UV-rotation metadata requiring stale cached-mesh rebuild | Renderer main thread; cached until reset | Invalid variants/indices skipped; first path decision wins |
| `M2AnimationLoadPipelineState` | Internal M2 async-state service | Owns animated scene pending request records and terminal finalize FIFO | Renderer main thread; map/session | Empty/duplicate/unknown transitions rejected |
| `M2AnimatedSceneFinalizer` | Internal M2 scene-finalization service | Instantiates candidates, repairs materials and requires AnimationPlayer descendants | Renderer main thread; stateless after each call | Invalid/rejected detached roots are freed |
| `M2AnimationPlaybackController` | Internal M2 playback service | Applies stable phase, default imported animation and native animator startup | Renderer main thread; stateless after each call | Missing inventories/names no-op through historical fallbacks |
| `M2MeshLoadPipelineState` | Internal M2 async-state service | Owns static Mesh pending request records and terminal finalize FIFO | Renderer main thread; map/session | Empty/duplicate/unknown transitions rejected |
| `M2MeshResourceCacheState` | Internal M2 Resource cache | Owns prepared static Mesh references by normalized path | Renderer main thread; final shutdown | Empty path/null Mesh rejected; same path replaces |
| `M2MeshResourceExtractor` | Internal M2 scene/resource service | Selects first Mesh from direct Resource, PackedScene or Node subtree | Renderer main thread; stateless except temporary instance | Invalid/no Mesh returns null; temporary PackedScene root freed |
@@ -187,6 +188,7 @@ loader configuration remains transitional composition data, not a caller API.
| Internal raw M2 read | Extracted directory and normalized relative path | Loader / `M2RawModelRepository` | Finalizer, static or animated builder adapters | Fresh Dictionary; repository retains nothing | One synchronous native call |
| Internal animated M2 load | Normalized path, cached GLB path and opaque terminal status | Loader / `M2AnimationLoadPipelineState` | Loader poll/finalize adapters | State-owned String/status records; detached pending snapshots | Request through terminal finalize/reset |
| Internal animated M2 candidate | Loaded PackedScene, static material root and detached candidate | Loader / `M2AnimatedSceneFinalizer` | Loader prototype adoption/static fallback | Finalizer owns until rejection or exact-root transfer | One main-thread finalize permit |
| Internal animated M2 playback | Prototype/instance native animators, path/index and player inventory | Loader/finalizer / `M2AnimationPlaybackController` | Native and imported animation state | Borrowed Nodes; detached optional diagnostics | One duplicated instance startup |
| Internal M2 prototype state | Normalized path, adopted static/animated Node or negative outcome | Loader / `M2PrototypeCacheState` | Loader reuse/fallback adapters | State-owned strong Node refs and Strings; detached diagnostics | Until final shutdown |
| Output | Desired tile/detail operations | Streamer plan application | Finalize queues | Loader-owned | Cross-frame |
| Output | Terrain/M2/WMO/liquid instances | Loader/builders | Godot world/renderer | Loader/world owner | Main-thread attach |
@@ -544,6 +546,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
| M2 build batch planner | Implemented extraction | Scene-free limit/count/cursor/source/timing contract | Queue/resource state, spatial cells and asset-backed p95/p99 remain pending |
| M2 animation load pipeline state | Implemented extraction | Synthetic lifecycle/FIFO/source/timing contract | Asset-backed traversal/leak/animation-fidelity/p95/p99 pending |
| M2 animated scene finalizer | Implemented extraction | Synthetic type/lifetime/material/player/source/timing contract | Asset-backed GLB traversal/material/animation comparison pending |
| M2 animation playback controller | Implemented extraction | Synthetic phase/selection/loop/native-copy/source/timing contract | Asset-backed animation timing/name/native comparison pending |
| M2 prototype cache state | Implemented extraction | Synthetic identity/negative/lifecycle/source/timing plus shutdown contract | Asset-backed traversal/leak/p95/p99 pending |
| WMO placement resolver | Implemented extraction | Scene-free path/identity/transform/source/timing contract | Asset-backed comparison pending |
| WMO placement registry | Implemented extraction | Scene-free ownership/lifecycle/source/timing contract | Build/resource state and asset-backed cross-tile corpus pending |
@@ -607,6 +610,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
| `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Billboard/UV-rotation stale cached-mesh rebuild decision and memoization |
| `src/render/m2/m2_animation_load_pipeline_state.gd` | Animated M2 pending Resource paths, terminal statuses and finalize FIFO |
| `src/render/m2/m2_animated_scene_finalizer.gd` | Animated scene candidate ownership, material repair and player validation |
| `src/render/m2/m2_animation_playback_controller.gd` | Per-instance phase, selection, native copy/start and imported playback |
| `src/render/m2/m2_mesh_load_pipeline_state.gd` | Static M2 pending Resource paths, terminal statuses and finalize FIFO |
| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static M2 Mesh references and final-shutdown release |
| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene instance lifetime |
@@ -630,6 +634,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
| `src/tools/verify_m2_runtime_mesh_rebuild_classifier.gd` | M2 rebuild predicate/cache/boundary/timing regression |
| `src/tools/verify_m2_animation_load_pipeline_state.gd` | Animated M2 request/terminal/FIFO/boundary/timing regression |
| `src/tools/verify_m2_animated_scene_finalizer.gd` | Animated M2 candidate/material/player/lifetime/boundary/timing regression |
| `src/tools/verify_m2_animation_playback_controller.gd` | Animated M2 phase/selection/playback/native/boundary/timing regression |
| `src/tools/verify_m2_mesh_load_pipeline_state.gd` | Static M2 request/terminal/FIFO/boundary/timing regression |
| `src/tools/verify_m2_mesh_resource_cache_state.gd` | Static M2 Mesh cache ownership/lifetime/boundary/timing regression |
| `src/tools/verify_m2_mesh_resource_extractor.gd` | M2 direct/PackedScene/subtree order/lifetime/boundary/timing regression |