# Pai Gow Poker tables

Configure a `casino_tables` entry:

```yaml
- id: fortune
  game: paigow
  max_players: 6
  min_bet: 5
  max_bet: 1000
  betting_ticks: 30
  pai_gow:
    variant: classic # classic, ez, no_push, face_up
    envy: true
    autoset: false # default; true locks every legal arrangement without "set"
    a2345_second_highest: true # default; false makes A2345 the lowest straight
    action_ticks: 60
```

There are six player seats and one dealer. Each round deals seven packets
from a fresh 53-card deck, including unused seats. No player banking.
Side bets come first: `bet 5 fortune` (and, on a Face Up table,
`bet <amount> pushace`) is placed before the main wager. `bet 20` is the
main wager that commits the round; when every active player has one, the
cards are dealt immediately. A lone bettor is dealt as soon as the main
wager lands, with no timed window. Otherwise the betting window opens and
expires on `betting_ticks`; anyone who has not bet sits out. `unbet main`,
`unbet fortune`, `unbet pushace` or `unbet all` returns an undealt wager,
and `stop` before the deal returns every wager and frees the seat. Both
wagers use the table's limits; each is also bounded to 500,000,000 credits
to keep combined payouts below the economy's credit cap even on unlimited
tables.

`a2345_second_highest` defaults to true and controls whether A-2-3-4-5 is
the second-highest straight (below TJQKA) or the lowest. When enabled the
rule is printed on the felt.

## Player hand setting

The seven dealt cards are shown with their position numbers underneath.
`24` or `set 24` arranges positions 2 and 4 into the two-card low hand;
`13456` arranges those five positions into the high hand. Spaces and order
are immaterial; duplicates, out-of-range positions and other counts are
rejected. Fouls are rejected with a clear warning and leave the hand
unarranged.

An arrangement is only a preview: the board redraws the five-card high
hand, a gap, then the two-card low hand (with `HIGH` and `LOW` labels and
position numbers) and waits. `set` locks the hand and reveals the dealer.
`house` (`house way`, `set house`) arranges the house way and still needs
`set`. `autoset on` locks any legal arrangement the moment it is made, so
the preview and `set` steps are skipped; `autoset off` restores them, and
`autoset` alone toggles. The table's `autoset` setting only seeds a new
seat. Timeout or disconnect sets an unfinished hand the house way; a
committed round cannot be abandoned.

When every seat has set, the dealer reveals and the showdown compares the
high hands first (your high, then the dealer's high) and then the low hands
(your low, then the dealer's low). Each hand prints its strength in
parentheses, bold yellow when it wins its comparison and bold white when it
loses. The summary names the winner of each hand and then the round.

## Variants

* Classic: win both hands for 0.95:1 profit; lose both to lose; otherwise push.
  Whole-credit profit rounds down, with a minimum of one credit on a win,
  consistent with the existing casino economy. This affects small-bet odds.
* EZ: the **partially-wild Joker edition**. No commission. Dealer's best
  five-card hand exactly queen-high pushes the main bets, regardless of split.
* No Push: no commission. When one player hand beats the dealer and the other
  does not, compare the two extra cards dealt after the seven packets. The
  first is the shared player tiebreaker, the second the dealer's. Joker is an
  ace; equal ranks lose to the dealer. Both-win/both-loss results are unchanged.
* Face Up: no commission; the dealer's seven cards are revealed before
  players set theirs. If the dealer's best five-card hand is exactly
  ace-high the round is an automatic push for every main bet. Requires
  `push_ace_high: 5_15_40` or `5_12_40`, which enables the optional Push
  Ace High side bet (`bet <amount> pushace`, capped at half the main
  wager): dealer ace-high without a Joker 5:1, with a Joker 15:1, both
  sides ace-high 40:1, else lost.

Fortune and Envy are independent of all main-game results, including
variant pushes. `push_ace_high` on a non-Face-Up table (or a Face Up table
without it) is rejected by validation.

## Fortune / Envy

Source: [Wizard of Odds Fortune tables](https://wizardofodds.com/games/pai-gow-poker/side-bets/fortune/).
Of the eight published fixed tables compared there, **table 8** has the
lowest house edge: 4.4292% before Envy, about 0.08% with six players each
betting five. These are published theoretical side-bet figures, not a
simulation of this server. Envy value depends on occupancy and wager size.

| Seven-card holding | Profit odds | Fixed Envy credits |
|---|---:|---:|
| Natural seven-card straight flush | 1000:1 | 500 |
| Royal flush + royal match | 750:1 | 250 |
| Wild seven-card straight flush | 500:1 | 150 |
| Five aces | 250:1 | 100 |
| Royal flush | 150:1 | 50 |
| Straight flush | 50:1 | 20 |
| Four of a kind | 25:1 | 5 |
| Full house | 5:1 | 0 |
| Flush | 4:1 | 0 |
| Three of a kind | 3:1 | 0 |
| Straight | 2:1 | 0 |
| Three pair | 1:1 | 0 |

Only the highest listed category pays, using all seven cards regardless
of the actual split. Royal match means suited KQ in the two remaining
cards. Fortune winning wagers also return their stake. A Fortune wager
of at least five qualifies for fixed Envy prizes on **other active players**,
not the bettor, dealer, unused packets or spectators. Multiple qualifying
hands add. The other player need not have a Fortune bet. A losing Fortune
stake is still lost when Envy pays.

With `envy: false` (default), quads improve to **30:1**, a custom local
schedule. The felt displays the effective table.

Variant sources:
* https://wizardofodds.com/games/ez-pai-gow-poker/partially-wild-joker/
* https://wizardofodds.com/games/pai-gow-poker/appendix/4/
* https://wizardofodds.com/games/face-up-pai-gow-poker/

House-way algorithm, settlement internals and Joker art notes are in
[../dev_guide/pai_gow.md](../dev_guide/pai_gow.md).