F005 — Hand Evaluation

Business Rule

At the RIVER stage, every hand is evaluated against the 5 community cards to produce a standard Texas Hold’em hand ranking. The hand with the highest ranking wins. The 10 valid hand rankings (highest to lowest):

Rank	Name
1	Royal Flush
2	Straight Flush
3	Four of a Kind
4	Full House
5	Flush
6	Straight
7	Three of a Kind
8	Two Pair
9	Pair
10	High Card

Evaluation is performed server-side by the poker hand evaluator (node-poker-odds-calculator / pokersolver). The client receives pre-computed handName and handStatus per hand in the API response at STATUS_RIVER.

Technical Design

API response (STATUS_RIVER)

Each entry in handOdds[] contains:

{
  "handName":   "Full House",
  "handStatus": "IN_PLAY_WINNER"
}

handName — pokersolver hand classification string (one of the 10 rankings above)
handStatus — "IN_PLAY_WINNER" for the winning hand, "IN_PLAY" for losers

UMA client state bridge

platform.js builds a debug array at RIVER and exposes it for Playwright assertions:

window._winnerInfo = [
  {
    handIndex: 0,
    isWinner:  true,
    handName:  'Full House',   // from API handOdds[i].handName
    prizeId:   'full_house',   // mapped via HAND_NAME_TO_PRIZE_ID
    winAmount: 300,            // pence
    multiplier: 3.0,
  },
  // ... one entry per hand
];

handName → prizeId mapping

handName	prizeId
Royal Flush	royal_flush
Straight Flush	straight_flush
Four of a Kind	four_of_a_kind
Full House	full_house
Flush	flush
Straight	straight
Three of a Kind	three_of_a_kind
Two Pair	two_pairs
Pair	pair
High Card	high_card

The GDK uses prizeId to trigger the win animation and display the hand name banner.

Acceptance Criteria

AC1 — At RIVER, _winnerInfo is defined and contains exactly one entry per hand (length equals _holeCards.length)
AC2 — Every hand in _winnerInfo has a valid handName (one of the 10 standard poker rankings)
AC3 — Exactly one hand has isWinner === true
AC4 — The winning hand has the highest (or tied-highest) poker hand rank among all hands
AC5 — The winning hand’s prizeId correctly maps to its handName (e.g. 'Full House' → 'full_house')

Version Parity

Version	Status	Notes
JavaScript	⬜ Not yet audited	Evaluation server-side; client reads pre-computed values
TypeScript	⬜ Not yet audited	`GameEngine` reads `handName` from coredata/API
UMA	✅ Verified	`tests/features/F005-hand-evaluation.spec.ts` — AC1–AC5 pass (2026-04-15)

Known Discrepancies

None documented yet.

Test Coverage

Playwright spec: tests/features/F005-hand-evaluation.spec.ts — AC1–AC5. Run with:

VERSION=uma npx playwright test tests/features/F005-hand-evaluation.spec.ts --project=features --workers=1

Overview

Game Engine

Betting

UI

Config

Bonus

V7 Horse Race

Platform

Lobby

F005 — Hand Evaluation

Business Rule

Technical Design

API response (STATUS_RIVER)

UMA client state bridge

handName → prizeId mapping

Acceptance Criteria

Version Parity

Known Discrepancies

Test Coverage

​Business Rule

​Technical Design

​API response (STATUS_RIVER)

​UMA client state bridge

​handName → prizeId mapping

​Acceptance Criteria

​Version Parity

​Known Discrepancies

​Test Coverage

Business Rule

Technical Design

API response (STATUS_RIVER)

UMA client state bridge

handName → prizeId mapping

Acceptance Criteria

Version Parity

Known Discrepancies

Test Coverage