feat: pai gow poker added to the casino

1 files changed, 100 insertions, 0 deletions

diff --git a/building_guide/pai_gow.md b/building_guide/pai_gow.md
new file mode 100644
index 0000000..40e6029
--- /dev/null
+++ b/building_guide/pai_gow.md
@@ -0,0 +1,100 @@
+# Pai Gow Poker tables
+
+Configure a `casino_tables` entry:
+
+```yaml
+- id: fortune
+  game: pai_gow
+  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).