F045 — Deal Animation

Field	Value
ID	F045
Phase	3 — UI
Jira	HEDGE-173
Status	TS ❌ · JS ⬜ · UMA ✅

Business Rule

When a deal is triggered (HOLE stage), each hole card flies out from the card shuffler sprite in the top-right corner of the game canvas and travels to its assigned position within the relevant hand panel. Cards are launched in sequence with staggered delays so each one is visually distinct. The animation gives the player a clear sense of cards being physically dealt from a shoe. Community cards are not dealt with this animation — they appear via a flip reveal in place.

Technical Design

Card Shuffler (Shoe) Sprite

The card shuffler is a three-layer composite:

Layer	Atlas frame	Position (landscape)
Shoe body	`dealer_shoe_body.png`	`(1181, 49)`
Shoe glass	`dealer_shoe_glass.png`	`(1181, 49)`
Card in shoe	`back.png` (card back)	`(1118, 79)`

The card-in-shoe sprite sits at (1118, 79) with:

angle: -59°
skewY: -0.3
scale: (0.58, 0.6)

Animation Sequence

Each hole card goes through two phases:

Phase 1 — Quick Launch from Shoe (~100 ms)

The card group snaps from the shoe position toward a mid-air launch point near (1090, 150) while the angle sweeps from -59° → -40°. This phase is linear and brief, simulating the card being pushed out.

Phase 2 — Main Flight to Target (~300–500 ms, path-dependent)

Five parallel tweens run simultaneously:

Tween	Property	Easing
Shadow	`shadowX`, `shadowY`, `skewY → 0`	`Sinusoidal.Out`
Card skew	`skewY → 0`	`Sinusoidal.Out`
Position + angle	`x`, `y`, `angle → target`	`Sinusoidal.Out`
Scale	`scaleX`, `scaleY → target`	`Sinusoidal.Out`
Group reset	container `x`, `y`, `angle → 0`	`Sinusoidal.Out`

Flight duration is dynamically calculated from the Euclidean distance between the launch point and the card’s final position:

pathX = 1100 − containerX − targetX
pathY = containerY + targetY − 150
path  = √(pathX² + pathY²)
flyTime = path / (2 / PLAY_SPEED)          // desktop
flyTime = path / (4 / PLAY_SPEED)          // device/mobile

Typical flight time: 300–500 ms at normal speed (PLAY_SPEED = 1).

Stagger Delays

Cards are launched in order with a stagger interval based on their index:

// For hole cards (id < 5):
delay = (id + 2 × HANDS_NUMBER + 1) × CARD_FLY_STEP × PLAY_SPEED

// For community cards (id ≥ 5):
delay = (id − 3) × CARD_FLY_STEP × PLAY_SPEED

CARD_FLY_STEP = 300 ms — interval between successive card launches.

Timing Constants

Constant	Value	Purpose
`CARD_FLY_STEP`	300 ms	Delay between successive card launches
`CARD_FLIP_TIME`	150 ms	Half-duration of flip reveal (community cards)
`CARD_SHOW_WIN_TIME`	350 ms	Win highlight animation duration
`PLAY_SPEED`	0.5 (fast) / 1 (normal)	Global speed multiplier

V6 Implementation Notes

V6 should replicate this using Phaser 3’s this.tweens.add(). Key differences from v5 (Phaser 2):

Use this.tweens.add({ targets, x, y, angle, duration, ease: 'Sine.easeOut' }) instead of game.add.tween
Phaser 3 has no native skewY — omit skew or approximate with scaleX oscillation
Use this.time.addEvent({ delay, callback }) for the stagger scheduling
The shoe sprite should already exist in the v6 atlas (desktop_glass_ui or main_game_desktop) — confirm frame name before implementing
Launch sequence: start from shoe card position (1118, 79) with angle: -59, tween to mid-air waypoint (1090, 150) at -40°, then continue to final hand-panel target

V6 Canvas Coordinates

The v6 canvas is 1280 × 720 (landscape). The v5 canvas was the same resolution for desktop. Shoe position (1181, 49) transfers directly.

Mathematics

Dynamic flight duration:

d = √((1100 − cx − tx)² + (cy + ty − 150)²)
t = d / 2   [ms at PLAY_SPEED=1, desktop]

Where (cx, cy) is the hand container origin and (tx, ty) is the card’s local position within the container. For a card in hand 1 at approximately (200, 400):

d = √((1100 − 0 − 200)² + (0 + 400 − 150)²) = √(900² + 250²) ≈ 933 px
t ≈ 933 / 2 ≈ 467 ms

Acceptance Criteria

ID	Criterion	Playwright assertion
AC-F045-01	On HOLE stage, each hole card starts at the shoe position `(~1118, 79)` before animating	`expect(cardSprite.x).toBeCloseTo(1118, 0)` at frame 0
AC-F045-02	Each hole card reaches its final target position within 800 ms of its launch	Assert card position equals target within timeout
AC-F045-03	Cards are launched sequentially with ≥ 250 ms stagger between each	Measure launch timestamps per card
AC-F045-04	Card angle transitions from −59° at shoe to ≈ 0° (or hand target angle) at destination	`expect(cardSprite.angle).toBeCloseTo(0, 5)` after animation
AC-F045-05	Community cards do not use the fly animation — they flip in place	Assert community card x/y does not change during reveal
AC-F045-06	Animation completes correctly at both `PLAY_SPEED = 1` (normal) and `PLAY_SPEED = 0.5` (fast)	Run game in both speed modes and assert final positions

Version Parity

Version	Status	Notes
JS (v4)	⬜ Not yet audited	Likely implemented — same Phaser 2 codebase as v5
TypeScript (v6)	❌ Not implemented	Cards placed statically; no fly animation
UMA (v5)	✅ Implemented	Full two-phase fly with 5 parallel tweens, stagger delays

V5 Source References

File	Lines	Purpose
`source/client_source/src/js/Game/gameTypes/cardDesktop.js`	42–127	`throwCard()` + `_launchCard()` — desktop deal animation
`source/client_source/src/js/Game/gameTypes/cardDevice.js`	72–135	Mobile variant (faster fly speed: `path/4`)
`source/client_source/src/js/Game/gameView.js`	349–365	Shoe/shuffler sprite setup and coordinates
`source/client_source/src/js/Game/gameView.js`	51–54	Animation timing constants

Overview

Game Engine

Betting

UI

Config

Bonus

V7 Horse Race

Platform

Lobby

F045 — Deal Animation (Hole Cards Fly from Shuffler)

F045 — Deal Animation

Business Rule

Technical Design

Card Shuffler (Shoe) Sprite

Animation Sequence

Phase 1 — Quick Launch from Shoe (~100 ms)

Phase 2 — Main Flight to Target (~300–500 ms, path-dependent)

Stagger Delays

Timing Constants

V6 Implementation Notes

V6 Canvas Coordinates

Mathematics

Acceptance Criteria

Version Parity

V5 Source References

​F045 — Deal Animation

​Business Rule

​Technical Design

​Card Shuffler (Shoe) Sprite

​Animation Sequence

​Phase 1 — Quick Launch from Shoe (~100 ms)

​Phase 2 — Main Flight to Target (~300–500 ms, path-dependent)

​Stagger Delays

​Timing Constants

​V6 Implementation Notes

​V6 Canvas Coordinates

​Mathematics

​Acceptance Criteria

​Version Parity

​V5 Source References

F045 — Deal Animation

Business Rule

Technical Design

Card Shuffler (Shoe) Sprite

Animation Sequence

Phase 1 — Quick Launch from Shoe (~100 ms)

Phase 2 — Main Flight to Target (~300–500 ms, path-dependent)

Stagger Delays

Timing Constants

V6 Implementation Notes

V6 Canvas Coordinates

Mathematics

Acceptance Criteria

Version Parity

V5 Source References