v1.0.0: replace slots with 5x3 reels and five paylines

1 files changed, 74 insertions, 0 deletions

diff --git a/docs/SLOTS.md b/docs/SLOTS.md
new file mode 100644
index 0000000..ccc3b60
--- /dev/null
+++ b/docs/SLOTS.md
@@ -0,0 +1,74 @@
+# Slots: 5 reels x 3 rows
+
+## Grid
+
+- 5 reels (columns) x 3 rows = 15 visible symbols.
+- Six symbols, uniform: `C` cherry, `L` lemon, `O` orange, `G` grapes,
+  `D` diamond, `S` seven.
+- The bet is the **total** bet, not a per-line bet.
+- Five paylines: top, middle, bottom, V, inverted V.
+- A line pays for 3, 4 or 5 matching symbols starting on reel 1 and reading
+  left to right.
+
+```
+line 1:  top row across all five reels
+line 2:  middle row across all five reels
+line 3:  bottom row across all five reels
+line 4:  top, middle, bottom, middle, top
+line 5:  bottom, middle, top, middle, bottom
+```
+
+## Paytable
+
+Multipliers are applied to the total bet.
+
+| Symbol | 3 of a kind | 4 of a kind | 5 of a kind |
+| --- | ---: | ---: | ---: |
+| C | 2x | 5x | 15x |
+| L | 3x | 7x | 20x |
+| O | 3x | 8x | 25x |
+| G | 4x | 12x | 40x |
+| D | 6x | 18x | 70x |
+| S | 9x | 30x | 150x |
+
+- Exact RTP: **425/432 = 0.983796...** (1.62% house edge).
+- Maximum win: 5 lines x 150x = **750x total bet**.
+- Chance of any win on a spin: about **13%**.
+- The RTP is checked by `SlotsGame::theoretical_rtp()` and `tests/slots.rs`.
+
+## Wire format
+
+`GAME_RESULT` keeps its existing fields and appends the winning lines:
+
+```
+GAME_RESULT <session> <winnings> <bet> <balance> <reels> <win_type> <win_lines>
+```
+
+- `reels`: 15 characters, **column-major**: reel 0 top/middle/bottom, then
+  reel 1, and so on.
+- `win_type`: `none`, `win`, `big` (>= 10x total bet) or `mega` (>= 50x).
+- `win_lines`: 1-based comma-separated line numbers, or `-` for no win.
+- Older servers may still send a 3-character `reels` string; the client
+  degrades it to the first row.
+
+The extra `win_lines` field is additive, but the 5x3 `reels` payload is a
+breaking change for pre-5x3 clients. That is why the release is `1.0.0`.
+
+## Client board
+
+The board is nine lines:
+
+```
+=== SLOTS ===
+Bet: 10 PLN   Lines: 5   Balance: 1000 PLN
+[ C ] [ L ] [ O ] [ G ] [ D ]
+[ S ] [ C ] [ L ] [ O ] [ G ]
+[ D ] [ S ] [ C ] [ L ] [ O ]
+
+Won 20 PLN
+Winning lines: 1, 3
+[+/-] Bet   [SPACE] Spin   [Q] Quit
+```
+
+`win_lines` is already carried through the client state so the next animation
+pass can highlight the winning rows without recomputing the payout.