feat: additional baca and bj rules variants

1 files changed, 96 insertions, 6 deletions

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index 25c6f5f..af19119 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -282,7 +282,8 @@ Two blackjack knobs are player-favourable and on by default, so set them
 explicitly when authoring a standard-rules table:
 
 - `split_unlike_ten_values: true` lets any two 10-valued cards split
-  (K+Q, 10+J). Standard play splits only identical ranks.
+  (K+Q, 10+J). Casinos vary: some permit any ten-valued pair, others
+  require identical ranks.
 - `double_split_blackjack: true` pays a 3+ card hand that reaches 21 after a
   split and double as a blackjack (3:2). Standard play pays 1:1 for any 21 on
   a split hand, doubled or not. Both raise the table's actual RTP above the
@@ -292,7 +293,45 @@ Baccarat's `banker_payout` (0.95 = a 5% commission) rounds the commission UP:
 a winning banker bet too small to carry a whole credit of commission returns
 only the stake rather than paying a commission-free 1:1. Payout multipliers
 are capped (`blackjack_payout`/`insurance_payout` ≤ 5, `tie_payout` ≤ 10,
-`banker_payout` ≤ 0.99) so a typo cannot silently create an absurd table.
+commission-table `banker_payout` ≤ 0.99) so a typo cannot silently create an
+absurd table. No-commission baccarat variants require `banker_payout: 1`
+(or omit it); their compensating exceptions are enforced by the engine.
+
+### Blackjack rule cards and test tables
+
+`look blackjack`, `look blackjack table`, or `look <table-id>` displays the
+fixture's complete effective rule card (including omitted/default settings,
+fixed engine rules, limits, and timers). Joining with `play blackjack` also
+shows it privately. No scenery object or room-description text is required:
+placing a `casino_tables` entry in any room brings the rule card with it.
+Currently only one table of each game is allowed per room; use separate rooms
+for different blackjack tables.
+
+The casino has these test profiles:
+
+| Room | Table | Decks | Blackjack | Soft 17 | DAS | Maximum hands | Re-split aces | Surrender |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 6110 | Classic | 6 | 3:2 | Stand | Yes | 4 | No | No |
+| 6112 | Mercy | 6 | 3:2 | Stand | Yes | 4 | Yes | Late |
+| 6114 | Single Deck | 1 | 6:5 | Hit | No | 2 | No | No |
+| 6116 | Midnight | 8 | 3:2 | Hit | Yes | 4 | No | No |
+
+All four disable the nonstandard split-and-double blackjack bonus. Use
+`blackjack_payout: 1.5` for 3:2 or `1.2` for 6:5. `max_split_hands: 1`
+disables splitting; 2 allows one split, and larger values allow re-splitting
+within the cap (aces additionally require `resplit_aces`).
+
+Common casino variations not currently configurable are restricted double-down
+totals (e.g. 9–11 or 10–11 only), hitting split aces, disabling insurance,
+and a separate even-money action for a natural against an ace. Doubling is
+always for the full original stake, not “double for less.” Late surrender is
+supported; early surrender is not. Side bets are not implemented.
+
+Casino-fidelity caveats: fractional credits round down. Shoe coverage may
+trigger an early shuffle, and exhaustion rebuilds the shoe mid-round rather
+than guaranteeing a casino-style finite shoe for the whole round. A connected
+solo player's action timer also has special grace behavior. None of these
+mechanics were changed by adding rule cards.
 
 At a blackjack table, `bet` uses the configured minimum wager; `bet min`,
 `bet max`, and `bet <amount>` select the wager explicitly.
@@ -318,22 +357,73 @@ casino_tables:
     min_bet: 1
     max_bet: 1000
     baccarat:
+      variant: commission       # commission (default), super_6, ez_baccarat
       decks: 8
       shuffle_at: 0.25
-      tie_payout: 8
-      banker_payout: 0.95
+      tie_payout: 8              # 8:1 or 9:1 are common
+      banker_payout: 0.95        # omit or use 1 for no-commission variants
+      pair_bets: false          # player_pair and banker_pair, 11:1
+      dragon_7: false           # winning three-card Banker 7, 40:1
+      panda_8: false            # winning three-card Player 8, 25:1
+      super_6_bet: false        # winning Banker 6, 12:1
 ```
 
 At a baccarat table, `bet <amount> on player`, `bet <amount> on banker`, and
 `bet <amount> on tie` place wagers (the words and amounts may come in any
 order, and `min`/`max` work as usual). A bare `bet` repeats the previous
-amount and target. Winning player bets pay 1:1; winning banker bets pay
-`banker_payout`:1 (0.95 is the classic 5% commission); winning tie bets pay
+amount and target. Winning player bets pay 1:1; on commission tables winning
+banker bets pay `banker_payout`:1 (0.95 is the classic 5% commission); winning tie bets pay
 `tie_payout`:1. On a tie, player and banker bets push. When the betting
 window closes, both hands are dealt by the standard tableau: naturals (8 or
 9) stand immediately, the player hand draws on 0-5, and the banker hand
 follows the usual third-card rules.
 
+#### Baccarat variants, rule cards, and test tables
+
+- **Commission punto banco:** default 5% commission on Banker winnings;
+  reduced commission can be configured with `banker_payout` (e.g. 0.98).
+- **Super 6 (`super_6`):** no commission; Banker wins pay 1:1 except a
+  winning Banker 6, with either two or three cards, pays 1:2.
+- **EZ Baccarat (`ez_baccarat`):** no commission; Banker wins pay 1:1 except
+  a winning **three-card** Banker 7 pushes the Banker wager. Player and Tie
+  wagers still lose on that outcome. A two-card Banker 7 pays normally.
+
+All variants use the same automatic punto banco drawing tableau. Standard,
+mini-, and midi-baccarat mainly differ in seating, limits, dealing pace, and
+card handling, not this tableau; they do not need separate settlement engines.
+Deck count, cut threshold, limits, seats, and Tie payout remain table-specific.
+
+Optional wagers default off and may be enabled independently on any variant.
+Use `bet 10 on player_pair`, `banker_pair`, `dragon_7`, `panda_8`, or `super_6`
+where offered. Pairs mean matching **ranks** of the first two cards (not merely
+matching baccarat values); they settle independently of which hand wins and
+can win on a tie. Dragon 7, Panda 8, and Super 6 require an outright hand win,
+not a tie. Their fixed profit odds are listed in the configuration example.
+The separate Super 6 optional bet is not the main Banker's half-pay rule.
+
+**Current wagering limitation:** one wager per player per round. Optional
+bets are selectable wagers, not additions to a simultaneous Player/Banker bet.
+All use the table's bet limits. Fractional winnings round down; for exact
+5% commissions use multiples of 20 credits, and for half-pay wins use even
+stakes. Commission is deducted immediately, not collected later on a ledger.
+
+`look baccarat`, `look baccarat table`, and `look <table-id>` display the full
+rule card, as does joining with `play baccarat`. It lists every supported
+setting, including disabled optional bets, automatic drawing rules, rounding,
+and operational limits. It belongs to the table and works in any room without
+a plaque or special room text. One baccarat table is allowed per room.
+
+| Room | Table | Variant | Decks | Tie pays | Optional wagers |
+| --- | --- | --- | --- | --- | --- |
+| 6127 | Harbor | 5% commission | 8 | 8:1 | Player/Banker pair |
+| 6128 | Charter | Super 6 | 6 | 9:1 | Pairs, Super 6 |
+| 6129 | Crown | EZ Baccarat | 8 | 8:1 | Dragon 7, Panda 8 |
+
+Not modeled: player squeeze/shoe-passing ceremonies, burn-card rituals,
+deferred commission, simultaneous wagers, and other casino-specific side-bet
+paytables (such as Dragon Bonus or progressive jackpots). These are not
+implied by selecting an implemented variant.
+
 Single-player machines use `casino_machines` and are separate from multiplayer
 tables: