# 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
    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.
`bet 20` places the main wager; `bet 5 fortune` adds the optional side bet.
`deal` marks a bettor ready; when all bettors are ready, or the betting
window expires, the cards are dealt. Place side bets before marking ready.
A Fortune wager requires a main wager. Both 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.

## Player hand setting

`24` or `set 24` selects positions 2 and 4 for the two-card low hand.
`13456` selects those five positions for the high hand. Spaces and order
are immaterial; duplicates, out-of-range positions and other counts are
rejected. Setting locks the hand. Fouls are rejected with a clear warning
and leave the hand unset. `house` (`house way`, `set house`) sets
automatically. Timeout or disconnect sets an unfinished hand the house
way; a committed round cannot be abandoned.

## 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).