feat: new casino game: plinko

1 files changed, 47 insertions, 0 deletions

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.