feat: video poker machines added to casino

1 files changed, 151 insertions, 0 deletions

diff --git a/building_guide/video_poker.md b/building_guide/video_poker.md
new file mode 100644
index 0000000..ca2ece7
--- /dev/null
+++ b/building_guide/video_poker.md
@@ -0,0 +1,151 @@
+# Video poker cabinets
+
+Room 6192, east of Penny Reels (6118), contains exactly five single-seat
+cabinets: Classic, Ultimate X Single Line, Ultimate X Multi-Hand, Super Times
+Pay, and Hot Roll. Choose a game **inside** a cabinet; schedules are not games.
+The shared table lifecycle adapter provides room routing, wallet settlement,
+disconnect and eviction handling, so author cabinets under `casino_tables`:
+
+```yaml
+casino_tables:
+- id: ultimate_x_multi
+  game: video_poker
+  max_players: 1
+  video_poker:
+    cabinet: ultimate_x_multi
+    payout: full
+```
+
+`cabinet` accepts `classic`, `ultimate_x_single`, `ultimate_x_multi`,
+`super_times_pay`, `hot_roll`. `payout` accepts `low`, `normal`, `full`.
+Defaults are classic/full. Do not author variant/pay_table/feature/single_line;
+strict YAML validation rejects those obsolete fields. Do not use table wager
+limits to set coin denominations. Each cabinet has one occupant, but multiple
+cabinets may share a room and are addressed by ID.
+
+## Games and quality tiers
+
+Each row below lists **low / normal / full** schedules. Tier changes apply to
+all games on that cabinet; selecting a different game preserves the tier.
+These are published schedules, not interpolated payouts. The tier names rank
+the offered schedules within a game/cabinet; they do not imply equal RTP across
+games. Some classic full schedules exceed 100% with optimal play.
+
+| Game | Classic | UX Single | UX Multi | STP | Hot Roll |
+|---|---|---|---|---|---|
+| Jacks or Better | 7/5, 8/5, 9/6 | 8/5, 8/6, 9/6 | 7/5, 8/5, 8/6 | 7/5, 8/5, 9/6 | 8/5, 9/5, 9/6 |
+| Bonus Poker | 6/5, 7/5, 8/5 | 6/5, 7/5, 8/5 | omitted | 6/5, 7/5, 8/5 | omitted |
+| Bonus Poker Deluxe | 8/5, 9/5, 9/6 | 8/5, 8/6, 9/6 | 7/5, 8/5, 8/6 | omitted | omitted |
+| Double Bonus | 9/6/4, 9/7, 10/7 | 9/6/4, 9/6/5, 9/7 | 9/5/4, 9/6/4, 9/6/5 | 9/6/4, 9/6/5, 9/7 | omitted |
+| Double Double Bonus | 8/5, 9/6, 10/6 | 8/5, 9/5, 9/6 | 8/5, 9/5, 9/6 | 8/5, 8/6, 9/6 | 8/5, 9/5, 9/6 |
+| Deuces Wild | C | U | U | C | omitted |
+| Joker Poker (Kings or Better) | J | J | J | omitted | omitted |
+
+- C: 20/12/10/4/4/3, 25/15/9/4/4/3, 25/15/9/5/3/2.
+- U: 25/16/13/4/3/2, 20/12/10/4/4/3, 25/15/9/4/4/3.
+- J: 50/15/7/5/3, 50/16/7/5/3, 50/17/7/5/3.
+- Double Bonus 9/7 and 10/7 pay five for straights; three-part names explicitly
+  identify full-house/flush/straight rates.
+- Bonus Poker has only two sourced UX Multi schedules; it is omitted rather
+  than inventing a third tier. Other omissions are deliberately conservative,
+  not claims that no physical edition exists.
+
+The runtime tier selection persists across occupants of the live cabinet.
+A restart or authored configuration replacement restores the authored tier.
+Multiplier banks for *all* tiers remain durable and separate.
+
+| Edition | Supported hands |
+|---|---|
+| Classic Jacks or Better | 1, 3, 5, 10, 25, 50, 100 |
+| Other classic games | 1 |
+| Ultimate X Single | 1 |
+| Ultimate X Multi | 3, 5, 10 |
+| Super Times Pay | 1, 3, 5, 10 |
+| Hot Roll | 3, 5, 10 |
+
+## Controls and presentation
+
+- `play <id>` seats you; `game` lists games; `game jacks` (or a full game name)
+  selects one. `payout low|normal|full` selects cabinet-wide quality.
+- `denom 1|10|50` / `denomination` sets credits per coin.
+- `hands` lists counts; `hands <count>` selects one.
+- `bet 1-4` **adds** coins, capped at five per hand. `bet max` loads five.
+  Bare `bet` / `rebet` repeats the previous selection, initially five.
+- Loading neither charges nor deals. Explicit bets show the pay table; bare
+  bet does not. `deal` charges the full wager and reveals five cards.
+- `531`, `1 3 5`, or `hold 531` **toggles** holds. Repeating the command releases
+  those cards; duplicate digits within one command toggle only once.
+  `hold none` is not supported. `draw` or seated `d` finishes the hand.
+  Away from video poker, `d` retains down movement.
+- `feature on|off` toggles the cabinet's bonus between rounds.
+- `paytable`, `look`, `table rules` redisplay; `rules` opens the cabinet guide.
+  `list` retains available-wagers semantics and is not a pay-table command.
+- `stop` leaves between rounds. Disconnect completes the current holds.
+
+Pay tables use yellow Unicode borders and dotted hand-name leaders. Blue
+`#000269`, red `#fe0000` (selected coin column), and yellow `#f7e70e` are mapped
+to nearest xterm colors. HELD and wins are bold yellow; no-win text is bold
+white. Results are below cards. Bonus indicators and multipliers sit beside
+cards. Multi-hand art shrinks; hundred-play uses compact Unicode ranks/suits.
+
+Payouts are total coins including stake, not profit. Multiply by denomination
+for credits. Natural royals pay 250 per coin below five coins, 4000 at five.
+Other categories scale linearly. Only the highest-paying category pays.
+All games use fresh 52-card decks except Joker Poker's 53-card deck. Each line
+shares the deal/holds but draws from its own shuffled remaining deck, excluding
+**all five** original cards, including discards.
+
+## Bonuses
+
+Feature ON requires five base coins per hand. UX and Hot Roll add five coins
+(10 total); STP adds one (6 total). Fees never increase the base payout.
+
+- **Ultimate X:** each line's current multiplier applies to its payout. Enabled
+  wins earn next-hand multipliers using the published single/3/5/10-play award
+  schedules. Awards never compound. Feature OFF collects existing multipliers
+  without earning new ones. `NEXT X` shows awards for the selected hand count.
+- **Super Times Pay:** a pre-deal 1/15 trigger awards a shared multiplier.
+  Conditional 2x/3x/4x/5x/8x/10x probabilities are 17/33/16/24/6/4 percent.
+- **Hot Roll:** a pre-deal 1/6 trigger rolls two fair dice; their sum multiplies
+  every line. STP and Hot Roll have no next-hand bank.
+
+## Shared banks and money safety
+
+Ultimate X multipliers belong to the **machine**, not the player. Another
+occupant inherits them. Files live at
+`data/casino/video_poker_banks/<room>_<cabinet>.yaml`. Within each file banks
+are keyed by game/tier/denomination/hand-count, preventing denomination or
+edition switching from amplifying an award. Fully consumed banks are removed.
+Missing files are new machines; corrupt/unreadable files block deals.
+
+`casino.PokerWallet` loads banks and atomically settles character credits,
+pending stake removal, and the cabinet file in a multi-file undo-journal
+transaction. There is no package-global persistence callback. The game owner
+serializes writes. The stake is durable before revealing cards; frozen final
+hands and awards survive payment retries without redraws or rerolls. Failed
+transactions leave the old live bank intact. Commit-point failures are recovered
+and reconciled before any retry; unrecoverable storage faults fail closed.
+Startup journal recovery precedes pending-wager recovery. A process crash before
+commit restores both old records, then refunds the unresolved stake. Committed
+payouts cannot replay an old bank. Shutdown/eviction refunds unresolved stakes
+without consuming previously saved multipliers or retaining uncommitted awards.
+
+Old experimental player-owned `video_poker_multipliers` fields are no longer
+read. They are not merged into shared cabinets (multiple player banks cannot
+unambiguously become one physical bank).
+
+## Sources
+
+Published schedules, award tables and feature rules:
+
+- https://wizardofodds.com/games/video-poker/tables/ultimate-x-single-line/
+- https://wizardofodds.com/games/video-poker/tables/ultimate-x/
+- https://wizardofodds.com/games/video-poker/tables/super-times-pay/
+- https://wizardofodds.com/games/video-poker/tables/hot-roll/
+- https://wizardofodds.com/games/video-poker/tables/jacks-or-better/
+- https://wizardofodds.com/games/video-poker/tables/bonus-poker/
+- https://wizardofodds.com/games/video-poker/tables/bonus-poker-deluxe/
+- https://wizardofodds.com/games/video-poker/tables/deuces-wild/
+- https://wizardofodds.com/games/video-poker/tables/double-bonus/
+- https://wizardofodds.com/games/video-poker/tables/double-double-bonus/
+- https://www.videopoker.com/games/ (single/multi/hundred-play editions)