Trim two-stage animation doc to just the implementation pattern (#6445)

All two-stage actions now have distinct success/failure animations.
Remove the completed status tracking table and animation descriptions,
keeping only the 7-step wiring guide for adding new two-stage actions.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-08 21:39:27 -07:00
committed by GitHub
co-authored by Claude Opus 4.6
parent f2ff4cc912
commit e850ba7546
+3 -92
View File
@@ -1,101 +1,12 @@
# Two-Stage Animation Status
# Two-Stage Animation Implementation Pattern
Actions with server-determined success/failure outcomes use a two-stage system:
1. **Attempt phase**: Animation + sound plays immediately when the command is issued
2. **Result phase**: A distinct success or failure animation + sound plays when the server responds
## Status Key
## Adding a New Two-Stage Action
- **Distinct**: Separate animations for attempt, success, and failure
- **Shared**: Same animation for attempt and result (only sound differs)
- **None**: No failure animation exists (failure has no visual feedback)
## Two-Stage Actions
| Action | Command | Success ActionType | Failure ActionType | Animation Status | Animator |
|--------|---------|-------------------|-------------------|-----------------|----------|
| Fear | FearCommand | FearAttack | FearAttackFailed | **Distinct** | FearAnimator |
| Flee | FleeCommand | Fled | CapturedWhileFleeing | **Distinct** | FleeAnimator |
| Duel | ChallengeDuelCommand | DuelAccepted | DuelDeclined | **Distinct** | GauntletThrowAnimator / DuelAnimator |
| ExtinguishFire | ExtinguishFireCommand | ExtinguishFire | ExtinguishFireFailed | **Distinct** | ExtinguishAnimator |
| StartFire | StartFireCommand | StartFire | StartFireFailed | **Distinct** | FireEffectAnimator |
| FreezeWater | FreezeWaterCommand | FreezeWater | FreezeWaterFailed | **Distinct** | FreezeAnimator |
| Scout | ScoutCommand | Scouted | ScoutFailed | **Distinct** | ScoutAnimator |
| RaiseDead | RaiseDeadCommand | RaisedUndead | FailedRaiseUndead | **Distinct** | RaiseDeadAnimator |
| DismissUnit | DismissUnitCommand | DismissUnit | FailedDismissUnit | **Distinct** | DismissAnimator |
| Repair | RepairCommand | Repair | RepairFailed | **Distinct** | ToolAnimator |
| BraveWater | BraveWaterCommand | CrossedWater | CrossWaterFailed | **Distinct** | WaterEffectAnimator |
| Control | ControlCommand | Controlled | *(none)* | None | ControlAnimator |
## Distinct Animation Details
### Fear (FearAnimator)
- **Attempt** (`AnimateFear`): Dark wave from source toward target
- **Success** (`AnimateFearSuccess`): Skull impact at target, target flees
- **Failure** (`AnimateFearResisted`): Shield flash at target, wave dissipates
### Flee (FleeAnimator)
- **Attempt** (`AnimateFleeAttempt`): Quick dust kick-up and short blur dash
- **Success** (`AnimateFleeSuccess`): Full motion blur dash away from threat + dust trail
- **Failure** (`AnimateFleeCaptured`): Partial flee, abrupt stop, snap back, capture marker
### StartFire (FireEffectAnimator)
- **Attempt** (`AnimateFireAttempt`): Initial ignition — standard flames flicker and rise with drifting embers
- **Success** (`AnimateFireSuccess`): Fire blazes up — taller/brighter flames, colors shift hotter (orange to yellow/white), more embers rise faster, brief outward burst when fire catches (~1.0s)
- **Failure** (`AnimateFireFailed`): Fire sputters out — flames shrink and dim, colors shift cooler (orange to dark red/grey), embers slow and fall, ends with grey smoke puff (~0.8s)
### Repair (ToolAnimator)
- **Attempt** (`AnimateRepair`): Hammer strikes with sparks — tool swings down, impacts hex, sparks fly
- **Success** (`AnimateRepairSuccess`): Golden shimmer beam — warm golden column of light rises from hex center, motes drift upward transitioning gold to white, beam expands slightly then fades (~0.8s)
- **Failure** (`AnimateRepairFailed`): Debris collapse — small rectangular debris pieces (brown/grey) appear above hex, tumble and fall with rotation and horizontal drift, dust puff on landing (~0.8s)
### ExtinguishFire (ExtinguishAnimator)
- **Attempt** (`AnimateExtinguish`): Water droplets fall from above onto hex, splash on impact
- **Success** (`AnimateExtinguishSuccess`): Heavy water deluge with larger droplets, big splash, thick rising steam cloud
- **Failure** (`AnimateExtinguishFailed`): Droplets evaporate mid-fall (shrink, shift blue to grey), fire flares back with orange/red burst expanding outward
### FreezeWater (FreezeAnimator)
- **Attempt** (`AnimateFreeze`): Ice crystals form and expand outward from center with frost particles
- **Success** (`AnimateFreezeSuccess`): More crystals solidify with a bright white flash, intense shimmer
- **Failure** (`AnimateFreezeFailed`): Crystals form then crack — flicker, shatter outward as spinning shards, color fades from icy blue to dull grey
### Scout (ScoutAnimator)
- **Attempt** (`AnimateScout`): Eye appears at source, vision cone extends toward target with traveling glow
- **Success** (`AnimateScoutSuccess`): Cone fully extended, glow pulses bright and expands wide at target, eye flashes golden
- **Failure** (`AnimateScoutFailed`): Glow disk at target turns dark, then cone and glow retract back toward source (reverse of attempt), eye darkens and shrinks to nothing
### RaiseDead (RaiseDeadAnimator)
- **Attempt** (`AnimateRaiseDead`): Ground glow appears, figures begin rising from below
- **Success** (`AnimateRaiseDeadSuccess`): More figures rise quickly with bright green glow and pulse
- **Failure** (`AnimateRaiseDeadFailed`): Figures rise partway then collapse back down, glow flickers green to grey and extinguishes
### DismissUnit (DismissAnimator)
- **Attempt** (`AnimateDismiss`): Dissolve particles drift outward and upward from hex, glow pulses and fades
- **Success** (`AnimateDismissSuccess`): Golden particles rise upward with warm golden glow pulse expanding outward (~0.7s)
- **Failure** (`AnimateDismissFailed`): Particles expand briefly then snap back inward toward center, turning red; red rejection flash at center (~0.8s)
### BraveWater (WaterEffectAnimator)
- **Attempt** (`AnimateWaterSplash`): Splash droplets arc outward in parabolic arcs, ripple rings expand from center
- **Success** (`AnimateBraveWaterSuccess`): Strong upward splash with larger bright droplets, expanding ripples, and brief blue-white flash as unit crosses (~0.9s)
- **Failure** (`AnimateBraveWaterFailed`): Droplets rise high (promising crossing), stall and shudder at peak with color flickering, then violently crash back down with cubic acceleration past center, foam erupts and churns aggressively with large oscillations, everything darkens and fades (~1.15s)
### Duel (GauntletThrowAnimator + DuelAnimator)
- **Attempt** (`AnimateGauntletThrow`): Gauntlet arcs from challenger to target
- **Accepted** (`AnimateDuel`): Weapons clash between combatants
- **Declined** (`AnimateDuelDeclined`): Dismissive visual at target
## Actions Needing Distinct Failure Animations
The following actions use the same animation for both success and failure.
Adding distinct failure animations would improve player feedback.
| Action | Suggested Failure Animation |
|--------|---------------------------|
| Control | Mind control beam broken / resisted |
## Implementation Pattern
To add a distinct failure animation for an action (e.g., `ExtinguishFire`):
To add distinct success/failure animations for an action (using `ExtinguishFire` as an example):
1. **AnimationType enum** (`ShardokGameController.cs`): Add `ExtinguishFireFailed`
2. **AnimationTypeForAction()**: Map `ActionType.ExtinguishFireFailed` to new type