docs: open character animation repair

2026-08-12 21:42:11 +08:00
parent db75a17ce8
commit 9f26320d51
5 changed files with 190 additions and 12 deletions
@@ -0,0 +1,75 @@
+# Phase 9.0R2 Character Animation Runtime Contract
+
+## Definition
+
+Character animation means the visible character image progresses through
+authored frames whose body or limb poses differ. Position translation, bobbing,
+rotation, scaling, opacity, particles and camera motion may support a frame
+sequence but cannot replace it.
+
+## Runtime States
+
+| Tutorial phase | Hearthguard | Wayrunner | Farstring | Kindhand | Riftblade | Commit |
+|---|---|---|---|---|---|---|
+| Advance | `advance`, loop | `advance`, loop | `advance`, loop | `advance`, loop | `advance`, loop | none |
+| Threat | `idle`, loop | `idle`, loop | `idle`, loop | `idle`, loop | `telegraph`, once/hold | none |
+| Enemy attack | `guard`, once/hold | `evade_counter`, once/hold | `idle`, loop | `idle`, loop | `attack`, once/hold | front HP at Riftblade impact frame |
+| Rear action | `idle`, loop | `idle`, loop | `draw_release`, once/hold | `lantern_heal`, once/hold | `hit` for Farstring, otherwise `idle` | enemy HP or front heal at rear impact frame |
+| Final action | `basic_attack`, once/hold | `evade_counter`, once/hold | `draw_release`, once/hold | `lantern_heal`, once/hold | `hit`, once/hold | enemy HP at final impact frame |
+| Defeat | `idle`, loop | `idle`, loop | `idle`, loop | `idle`, loop | `death`, once/hold | enemy HP reaches zero once |
+| Victory | `victory`, once/hold | `idle`, loop | `idle`, loop | `idle`, loop | final death frame | one victory transition |
+
+For non-Hearthguard Recruits, the first accepted generated action row may also
+supply a restrained two-or-more-frame ready/idle sequence when no separate
+idle row exists. Reusing different action poses as an erratic loop is not
+allowed.
+
+## Timing
+
+- Each animation state declares frames, FPS, loop/non-loop and impact frame.
+- Looping states wrap. Non-looping states clamp to the final frame.
+- The runtime records a per-phase impact-committed flag. Crossing the impact
+  frame commits the value once even when one rendered delta skips multiple
+  frames.
+- Phase duration must allow the primary non-looping action to reach its final
+  frame and remain readable before the next phase.
+- Pausing for Restart confirmation freezes frame time and event commits.
+
+## Reduced Motion
+
+Reduced motion removes the advance translation and nonessential looping idle
+cycles. It does not replace action states with the old static anchors. Required
+actions step through their authored anticipation, impact and terminal frames at
+a lower bounded FPS so their meaning remains visible.
+
+## Art And Provenance
+
+- Hearthguard and Riftblade runtime frames are byte-identical copies of the
+  accepted Phase 6 frame authority named in the asset manifest.
+- Wayrunner, Farstring and Kindhand generation uses their Phase 7 canonical
+  anchors as image references and the `sprite-gen` component-row contract.
+- The generated strips use a flat chroma background, are deterministically
+  extracted to transparent PNG frames, and retain request, prompt, provider
+  report, source image, curation and hashes.
+- Runtime actor frames keep identity, handedness, equipment, facing, baseline
+  and play-size silhouette stable. VFX remain separate layers.
+
+## Runtime Evidence
+
+The fixed recording must include:
+
+1. authored advance cycles and collision stop;
+2. Riftblade telegraph and attack;
+3. one visible front guard or evade/counter response;
+4. one visible Farstring draw/release or Kindhand lantern/heal action;
+5. final attack, enemy recoil and non-looping death;
+6. victory without a reset seam.
+
+Static captures support layout only. The animation claim requires a continuous
+normal-render recording and sampled-frame proof that actor textures changed.
+
+## Evidence Markers
+
+- `ABG_P9_0R2_ANIMATION_ASSETS_OK`
+- `ABG_P9_0R2_CHARACTER_ANIMATION_OK`
+- `ABG_P9_0R2_DYNAMIC_SLICE_OK`