feat: new casino game: cash hunt, fixed verb issue with pai gow

3 files changed, 59 insertions, 12 deletions

diff --git a/data/help/cash_hunt.yaml b/data/help/cash_hunt.yaml
new file mode 100644
index 0000000..734a156
--- /dev/null
+++ b/data/help/cash_hunt.yaml
@@ -0,0 +1,41 @@
+name: cash hunt
+aliases: [cashhunt, cash_hunt, cash-hunt]
+category: Interaction
+related: [casino, plinko]
+description: |
+  CASH HUNT — 100 squares. One choice.
+
+  play cash hunt             Take the single seat.
+  difficulty easy            Choose easy, medium or hard (default easy).
+  paytable                   Show exact per-square prize probabilities.
+  bet 10                     Commit 10 credits and reveal the prize board.
+  73 / pick 73               Unlock square 73 after the positions are mixed.
+  bet / rebet                Repeat your last wager.
+  table                      Check the current phase or last revealed result.
+  stop                       Leave after the hunt has settled.
+
+  Each wager generates 100 prizes and shows the ENTIRE numbered board.
+  The prizes are then hidden and their positions uniformly shuffled.
+  The final positions are fixed BEFORE you enter your choice: choosing a
+  square reveals its stored prize, not a fresh random roll. The final
+  board shows every prize and highlights your selected square with >73<.
+  Preview numbers do not identify the prizes' final positions.
+  Tiles use a dark rainbow gradient, one hue per column.
+
+  All three difficulties have exactly 98% theoretical RTP and a 2% house
+  edge. Harder games move more return into rare large prizes, with more
+  zero-return squares. Each board's mixture and average return vary.
+  You must wager before seeing the preview and cannot cancel afterward.
+
+  Prizes: 0x, 1x, 2x, 5x, 10x, 20x, 100x, 200x, 500x, 1000x,
+  10000x and 50000x. Large prizes are possible, not guaranteed; there may
+  be none, one, or several. RTP includes the very rare jackpots.
+  The paytable lists exact probabilities for your chosen difficulty.
+  Multipliers INCLUDE your stake: 0x loses it, 1x returns it, 2x doubles it.
+
+  Settings and your stake are locked during a hunt. A failed payout keeps
+  your selection locked; settle retries that SAME prize without rerolling.
+  Disconnecting automatically settles square 1 if you have not picked;
+  if you already picked, it retries that selection instead. Shutdown
+  refunds unpicked boards and attempts to settle already chosen prizes.
+  Failed bank saves leave stakes pending for recovery, never a paid receipt.
diff --git a/data/help/casino.yaml b/data/help/casino.yaml
index e1ce06d..478a742 100644
--- a/data/help/casino.yaml
+++ b/data/help/casino.yaml
@@ -1,7 +1,7 @@
 name: casino
 aliases: [play, bet, rebet, table, watch, rules]
 category: Interaction
-related: [big6, roulette, racetrack, blackjack, baccarat, craps, slots, video poker, pai gow poker, plinko]
+related: [big6, roulette, racetrack, blackjack, baccarat, craps, slots, video poker, pai gow poker, plinko, cash hunt]
 description: |
   Casino quick guide
 
@@ -18,7 +18,7 @@ description: |
 
   Profit odds exclude your returned stake: a 10-credit win at 2:1
   returns 30 total (20 profit + 10 stake). A push returns the stake;
-  a loss returns nothing. Slots, Plinko and video poker paytables use total-return
+  a loss returns nothing. Slots, Plinko, Cash Hunt and video poker paytables use total-return
   multipliers; the shared payout receipt uses profit odds instead.
   Fractional table-game returns round down to whole credits, except
   craps, which rounds stakes up to exact payout units (commission rounds down),
@@ -45,6 +45,7 @@ description: |
   help craps         Multiplayer dice, free odds, Fire and ATS bets.
   help slots         Matching symbols, ways and free spins.
   help plinko        Animated pyramid, four risk levels, up to ten balls.
+  help cash hunt     Reveal 100 prizes, mix their positions, pick one square.
   help video poker   Five cabinet types, selectable games, toggle holds and bonuses.
   help pai gow poker Seven cards, two hands; Classic, EZ, No Push and Fortune/Envy.
 
diff --git a/data/help/plinko.yaml b/data/help/plinko.yaml
index 4691cd6..486a87b 100644
--- a/data/help/plinko.yaml
+++ b/data/help/plinko.yaml
@@ -20,24 +20,29 @@ description: |
   per tick, without clearing your screen. Balls fall between pegs.
   Equal payouts share a letter: normally A B C D E F G H I H G F E D C B A.
   Rounded ties also share letters, so some risks use fewer than nine labels.
-  A single dim-white ruler of pocket letters prints once, at the board's
-  midpoint, marking the fixed pocket columns; the base repeats it in
-  brackets. Hints mark positions, not a prediction of the result.
+  Dim-gray pocket letters appear below the midpoint, without hiding balls
+  or pegs. The base repeats the letters in brackets; landing pockets light
+  up as >A< instead of [A]. Hints mark positions, not predicted results.
   The outside A pockets pay 16x on easy, 100x on medium, 1000x on hard
   and 10000x on expert.
   Multipliers INCLUDE your stake. Each outer pocket has a 1/65536 chance.
-  Higher difficulty has much higher variance. Upward payout rounding also
-  makes the actual expected return differ slightly between difficulties.
+  Higher difficulty has much higher variance, including zero-return pockets.
+  The one-line paytable shows the actual RTP for your selected difficulty.
+  Actual RTP never decreases as difficulty increases.
 
   A single ball is white. Overlapping balls become pink, then pure red
   when all released balls meet. Basic ANSI approximates these shades.
   Without color, overlaps show 2-9 or * for ten balls.
 
-  The room's configured BASE return defaults to 98% at every difficulty.
-  Interior multipliers adjust to that base, then round UP to the next 0.1x;
-  the outside prizes stay fixed. The displayed multipliers are what pays.
-  Rounding increases actual RTP (possibly above 100%); the menu shows the
-  actual return for your selected difficulty as well as the configured base.
+  The receipt after each drop itemizes the result by landed payout: one
+  row per distinct multiplier, with its staked amount and net (mirrored
+  pockets share a row). The board has no fixed background, so your
+  terminal theme shows through.
+
+  The room's configured target return defaults to 98% at every difficulty.
+  Interior multipliers are balanced in 0.1x steps to stay close to that
+  target; the outside prizes stay fixed. The displayed multipliers are
+  exactly what pays. Returns include your stake.
   Fractional batch winnings round randomly to adjacent whole credits,
   preserving the expected return even for one-credit bets.