> ## Documentation Index
> Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# F048 — Coin Spill Animation (Win Payout)

> On a winning round, gold coins burst from the centre of the win panel and cascade across the screen while YOU WON and the amount are displayed

# F048 — Coin Spill Animation

| Field  | Value               |
| ------ | ------------------- |
| ID     | F048                |
| Phase  | 3 — UI              |
| Jira   | HEDGE-176           |
| Status | TS ✅ · JS ⬜ · UMA ✅ |

## Business Rule

When the player wins (any hand returns a positive payout), a burst of animated gold coins erupts from the win panel and cascades downward across the screen. The coins are displayed **in front of** the win panel and "YOU WON" overlay. The animation runs for \~2 s of active emission; coins then coast and fade out over their lifespan. The win panel auto-hides after 5 s total.

## V5 Implementation

V5 uses an animated sprite sheet (`coin_anim` atlas) rendered in a tight loop. Coins launch from roughly the centre of the win panel and arc downward under gravity, landing across the lower portion of the screen.

The JS client (`ShowWinner()`) starts the coin animation alongside `ramp_loop` SFX, and `StopWinner()` halts both after the display timer expires.

## V6 Implementation

The coin spill is a **Phaser 3 `ParticleEmitter`** (`this.coinEmitter`), constructed in `create()` and attached to the 'coins' texture atlas.

### Emitter Configuration

| Parameter   | Value                            | Effect                              |
| ----------- | -------------------------------- | ----------------------------------- |
| `frame`     | `[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]` | Random coin face each particle      |
| `lifespan`  | 4000 ms                          | Coins visible for 4 s from spawn    |
| `speedY`    | min −350 / max −100 px/s         | Coins launch upward                 |
| `speedX`    | min −200 / max 200 px/s          | Lateral spread                      |
| `gravityY`  | 300 px/s²                        | Arc back down naturally             |
| `rotate`    | −40° to +40°                     | Tumbling effect                     |
| `quantity`  | 3                                | Coins per emission tick             |
| `frequency` | 25 ms                            | Tick interval (≈ 120 coins/s burst) |

### Emitter Position

```typescript theme={null}
const emitterY = this.isPortrait ? panelY + 120 : panelY + 80;
this.coinEmitter = this.add.particles(panelX, emitterY, 'coins', { ... })
  .setDepth(22)   // above winnerPanel (depth 20) and YOU WON text (depth 21)
  .setVisible(false);
```

Landscape: emitter at canvas centre-x, `panelY + 80` (slightly below panel midpoint).

### Timing

| Time    | Event                                                             |
| ------- | ----------------------------------------------------------------- |
| 0 ms    | `coinEmitter.start()` — coins emit                                |
| 2000 ms | `coinEmitter.stop()` — no new coins; existing particles coast out |
| 5000 ms | `_hideWinnerScreen()` — panel, text and emitter hidden            |

### Z-Order (depth)

| Object                                     | Depth                      |
| ------------------------------------------ | -------------------------- |
| Win panel background (`you_won_plate.png`) | 20                         |
| YOU WON text / amount BitmapText           | 21                         |
| Coin particle emitter                      | **22** — in front of panel |

### Sound

`ramp_loop` SFX starts with the coin spill. `ramp_loop_end` fires after 2 000 ms, overlapping with the coasting-coin phase.

## Acceptance Criteria

| ID         | Criterion                                                                        |
| ---------- | -------------------------------------------------------------------------------- |
| AC-F048-01 | On any winning round, coins burst from the win panel on payout display           |
| AC-F048-02 | Coins appear **in front of** (above) the win panel background                    |
| AC-F048-03 | Active emission lasts \~2 s; coins then coast until lifespan ends                |
| AC-F048-04 | Win panel + coins auto-hide after 5 s                                            |
| AC-F048-05 | No coins appear on non-winning rounds                                            |
| AC-F048-06 | Coins do NOT appear when SFX/animations are suppressed (future fast-mode toggle) |

## Version Parity

| Version         | Status            | Notes                                              |
| --------------- | ----------------- | -------------------------------------------------- |
| JS (v4)         | ⬜ Not yet audited | `ShowWinner()` / `StopWinner()` pattern expected   |
| TypeScript (v6) | ✅ Implemented     | Phaser ParticleEmitter, depth 22, commit `545db03` |
| UMA (v5)        | ✅ Implemented     | Sprite-sheet coin anim in `ShowWinner()`           |

## V5 Source References

| File                                                          | Lines        | Purpose                           |
| ------------------------------------------------------------- | ------------ | --------------------------------- |
| `source/client_source/src/js/Game/gameTypes/baseGameScene.js` | \~ShowWinner | Coin anim start + `ramp_loop` SFX |
| `source/client_source/src/js/Game/gameTypes/baseGameScene.js` | \~StopWinner | Hide coins + stop SFX             |