@idealic/poker-engine/HAND.md

Professional poker game engine and hand evaluator with built-in iterator utilities

# Poker.Hand Notation

This section explains the fields of the `Poker.Hand` notation. For a more detailed explanation of the notation, please refer to the [PHH notation white paper](https://arxiv.org/html/2312.11753v2).

**Note:** This section is primarily for game engine developers. Front-end engineers and other integrators will not need to work with the notation directly, as the game engine parses it and provides handy accessors for everything.

TODO: Document our extensions to phh

### Meta Information

- `venue`: Name of the venue where the hand was played.
- `table`: Table number or identifier.
- `clubId`: Club ID for PokerStars Home Game.
- `hand`: Hand number.
- `id`: Unique identifier for the game.
- `seed`: Random seed for deterministic card dealing.
- `author`: Name of person who recorded the hand.

### Event Information

- `event`: Name of the poker event/tournament.
- `level`: Tournament blind/ante level number.
- `url`: URL relevant to the event or venue.
- `currency`: Currency code in ISO 4127 format (e.g. 'USD', 'EUR').

### Seat Setup

- `seatCount`: Total number of seats at the table.
- `seats`: Array of actual seat numbers for each player. `seats` aligns 1:1 with `players` by index. Index 0 in `players` corresponds to index 0 in `seats`. Engine logic uses player indices (0-based positions) for button/SB/BB resolution and turn order. Venue seat numbers in `seats` are for presentation/export. 
- Button/SB/BB are derived from `blindsOrStraddles` while skipping players marked in `_inactive` (see Custom fields). Heads‑up: the button is also the small blind.
- When `seats` is absent or invalid, exporters synthesize seat numbers from `seatCount` to render headers/seat lines.
- Seat numbers are venue-provided and may be 0‑ or 1‑based depending on source; they are not normalized by the engine.

### Financials

- `rake`: Absolute amount taken by the house from the pot.
- `totalPot`: Total pot size including rake.

### Rules/Settings

- `rakePercentage`: Rake percentage used to calculate rake when absolute amount is not provided (0.05 = 5%).
- `anteTrimming`: Whether short stacks can only win what they contributed to antes.
- `timeLimit`: Time limit per action in seconds. Used for timeout handling.

### Players Information

- `antes`: Array of ante amounts for each player position.
- `blindsOrStraddles`: Array of blind or straddle amounts for each player position.
- `startingStacks`: Array of starting stack amounts for each player position.
- `players`: Array of player names in clockwise order from first to act.
- `finishingStacks`: Final stack amounts for each player after the hand.
- `timeBanks`: Time bank amounts in seconds for each player. Used for timeout handling.
- `winnings`: Array of player winnings in the hand.

### Actions

- `actions`: Array of actions in the hand.

### Date and Time

- `timestamp`: Timestamp of the game start.
- `year`: Year the hand was played.
- `month`: Month the hand was played (1-12).
- `day`: Day of month the hand was played (1-31).
- `time`: Time in ISO format YYYY-MM-DDTHH:mm:ss.
- `timeZone`: IANA timezone name (e.g. 'America/Toronto').

### Location

- `country`: Country where the hand was played.
- `region`: Region/state/province where the hand was played.
- `city`: City where the hand was played.
- `postalCode`: Postal/zip code of the venue.
- `address`: Physical address of the venue.

### Variant-Specific Fields

- `variant`: The poker variant being played.
- `minBet`: The minimum bet amount for no-limit games.
- `smallBet`: The small bet amount for fixed-limit games.
- `bigBet`: The big bet amount for fixed-limit games.
- `bringIn`: The bring-in amount for stud games.

### Custom fields

- `_venueIds`: Array of per-seat player identifiers local to the source venue. Order aligns with `players`.
- `_heroIds`: Array of per-seat hero identifiers local to the venue; entries may be `null` for non-hero seats. Order aligns with `players`.
- `_managerUid`: Identifier of the upstream manager/controller responsible for the game/session.
- `_croupierId`: Identifier of the upstream croupier/dealer captured from the source system.
- `_inactive`: Per-seat flags (0 or 1) indicating a player is sitting out for this hand. Truthy values mark the seat as inactive for blind assignment, button placement, and hole-card dealing; length equals `players.length`.
- `_deadBlinds`: Per-seat amounts posted as dead blinds (e.g. missed-blind penalties or extra blinds). Added to antes during preflop initialization and do not count as live bets.
- `_timestamp`: Millisecond-precision source timestamp where available. `timestamp` remains the canonical field; `_timestamp` preserves source granularity/provenance.