feat: pai gow poker added to the casino

1 files changed, 65 insertions, 0 deletions

diff --git a/dev_guide/pai_gow.md b/dev_guide/pai_gow.md
new file mode 100644
index 0000000..9d26871
--- /dev/null
+++ b/dev_guide/pai_gow.md
@@ -0,0 +1,65 @@
+# Pai Gow Poker internals
+
+Builder-facing table configuration and the published Fortune pay table
+live in [../building_guide/pai_gow.md](../building_guide/pai_gow.md).
+This page covers the engine side: hand evaluation, the house way,
+settlement and the Joker art.
+
+## Hand evaluation
+
+The Joker is partially wild: an ace, or any missing card completing a
+straight, flush or straight flush. Five aces beats a royal flush. A2345
+is the second-highest straight (and straight flush), below TJQKA but above
+9TJQK. Low hands recognize only pairs and high cards. Suits do not break
+ties. Copies lose to the dealer. The high hand must strictly outrank the
+low hand.
+
+## House way
+
+This is a **local, deterministic house way**, not a claim to reproduce a
+particular casino's proprietary chart or optimal player strategy:
+
+1. Enumerate the 21 possible splits and discard fouls.
+2. Preserve the strongest available high-hand category.
+3. With two pair or a full house available, also allow splits leaving at
+   least a pair high and a pair low.
+4. Maximize the low hand among these options, then the high hand.
+
+The dealer and automatic player setting use precisely the same algorithm.
+Published main-game house-edge estimates using other house ways do not
+necessarily apply to this implementation.
+
+## Fortune / Envy mathematics
+
+Of the eight published fixed tables compared on the Wizard of Odds page,
+table 8 (the one configured here) has the lowest house edge: 4.4292%
+before Envy, about 0.08% with six players each betting five. With Envy
+disabled, quads improve from 25:1 to 30:1, a custom local schedule
+lowering the published no-Envy edge by about 0.9974 percentage points to
+3.4318%. These are published theoretical side-bet figures, not a
+simulation of this server; Envy value depends on occupancy and wager size.
+
+## Face Up mechanics
+
+The dealer sets and reveals before players act; the automatic ace-high
+push is checked against the dealer's best five-card hand (`pgDealerPush`),
+so ace pairs and ace-headed flushes do not trigger it. Push Ace High
+classes are resolved by `pgPushAceClass`: a Joker in the dealer's seven
+cards pays the Joker rate (a natural ace plus the Joker makes a pair of
+aces, which is NOT ace-high); otherwise 40:1 when the player is also
+ace-high, else the plain rate.
+
+## Settlement
+
+Main, Fortune, Envy and Push Ace High settle in a single wallet
+transaction per player. Failed settlements freeze the result and block
+the next deal; `settle` or the table tick retries payment, never redraws.
+Successful recipients are not paid twice. Shutdown uses the existing
+durable stake-refund mechanism.
+
+## Joker art
+
+The shared Joker is rank `JK`, suit `joker`. `data/cards.yaml` supplies
+`JK` artwork at sizes 1/5/7/9; `internal/game/render_joker.go` also has
+ASCII and no-store fallbacks, including dark/light styles. Existing Joker
+Poker video poker uses the same art.