feat: new casino game: plinko

2 files changed, 52 insertions, 3 deletions

diff --git a/data/help/casino.yaml b/data/help/casino.yaml
index 4634579..e1ce06d 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]
+related: [big6, roulette, racetrack, blackjack, baccarat, craps, slots, video poker, pai gow poker, plinko]
 description: |
   Casino quick guide
 
@@ -18,10 +18,11 @@ 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 and video poker paytables use total-return
+  a loss returns nothing. Slots, Plinko 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).
+  craps, which rounds stakes up to exact payout units (commission rounds down),
+  and Plinko, which randomly rounds fractional batch returns without bias.
 
   Every game uses the same payout receipt: Wager, Staked, Odds, Result, Net.
   All amounts are credits. Returned includes any returned stake; Net is
@@ -43,6 +44,7 @@ description: |
   help baccarat      Bet which hand finishes closest to 9.
   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 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
new file mode 100644
index 0000000..4691cd6
--- /dev/null
+++ b/data/help/plinko.yaml
@@ -0,0 +1,47 @@
+name: plinko
+aliases: [difficulty, balls]
+category: Interaction
+related: [casino]
+description: |
+  PLINKO — let it rain!
+
+  play plinko                 Take the single seat at a pyramid.
+  difficulty easy             Choose easy, medium, hard or expert.
+  balls 5                     Drop 1-10 balls together (default 1).
+  paytable                    Check the current pocket multipliers.
+  bet 10                      Wager 10 PER BALL and release them.
+  bet / rebet                 Repeat with your current risk and ball count.
+  stop                        Leave after the balls have landed.
+
+  Every ball makes 16 independent, equally likely left/right bounces.
+  The payout legend runs down the left, outside the pyramid, one entry per
+  row, so every value is known well before the ball reaches the pockets.
+  Each entry takes the pocket's board color. The board then unfolds one row
+  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.
+  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.
+
+  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.
+  Fractional batch winnings round randomly to adjacent whole credits,
+  preserving the expected return even for one-credit bets.
+
+  Your full batch is charged up front and paid once when all balls land.
+  You cannot change settings or leave mid-drop. Disconnect forfeits an
+  unfinished drop; shutdown refunds pending stakes. Failed payments keep
+  their stake pending for recovery rather than claiming a paid win.