v1.3.0: simplify payouts to bet x symbol x shape

2 files changed, 70 insertions, 29 deletions

diff --git a/docs/SLOTS.md b/docs/SLOTS.md
index b8c670b..1dbaba5 100644
--- a/docs/SLOTS.md
+++ b/docs/SLOTS.md
@@ -20,19 +20,33 @@ 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**.
+```
+payout = total bet x symbol multiplier x shape multiplier
+```
+
+Symbol multipliers:
+
+| Symbol | Multiplier |
+| --- | ---: |
+| C | 1 |
+| L | 2 |
+| O | 3 |
+| G | 4 |
+| D | 6 |
+| S | 10 |
+
+Shape multipliers (how many matching symbols on the line):
+
+| Shape | Multiplier |
+| --- | ---: |
+| 3 of a kind | 1 |
+| 4 of a kind | 3 |
+| 5 of a kind | 14 |
+
+Every winning payline is added together.
+
+- Exact RTP: **3835/3888 = 0.986368...** (1.36% house edge).
+- Maximum win: 5 lines x S(10) x 5-shape(14) = **700x total bet**.
 - Chance of any win on a spin: about **13%**.
 - The RTP is checked by `SlotsGame::theoretical_rtp()` and `tests/slots.rs`.
 
@@ -67,19 +81,45 @@ The board is ten lines:
 ```
 === SLOTS ===
 Bet: 10 PLN   Balance: 1000 PLN
-[ C ] [ L ] [ O ] [ G ] [ D ]
-[ S ] { C } { C } [ O ] [ G ]
-[ D ] [ S ] { C } [ L ] [ O ]
-Pays 3/4/5 x bet: C 2/5/15 L 3/7/20 O 3/8/25
-G 4/12/40 D 6/18/70 S 9/30/150
-Won 20 PLN
-Winning lines: 2
+{ G } [ L ] [ S ] [ O ] [ G ]
+[ D ] { G } [ L ] [ S ] [ C ]
+[ O ] [ O ] { G } [ L ] [ O ]
+Pays bet x symbol x shape
+Symbol C1 L2 O3 G4 D6 S10   Shape 3:1 4:3 5:14
+Won 40 PLN
+Winning lines: 4 (V)
 [+/-] Bet   [SPACE] Spin   [Q] Quit
 ```
 
-The two lines above the status are the compact paytable: for each symbol, the
-multipliers of the total bet for 3, 4 and 5 of a kind. It is split so it does
-not wrap on a narrow terminal. Winning cells use braces and are rendered
-yellow/bold in the terminal. The line list below the status names the paylines
-that won. Both come from the server's `win_lines` and `win_cells`, which are
-already carried through the client state for the animation pass.
+The two lines above the status show the payout formula and the two multiplier
+tables. Winning cells use braces and are rendered yellow/bold in the terminal.
+The line list below the status names the paylines that won. Both come from the
+server's `win_lines` and `win_cells`, which are already carried through the
+client state for the animation pass. Multiple winning lines are summed; the
+board lists all of them and highlights the union of their matched cells.
+
+## Reading a win
+
+A payline is one of five fixed paths across the five reels:
+
+| Line | Name | Rows on reels 1-5 |
+| ---: | --- | --- |
+| 1 | top | top, top, top, top, top |
+| 2 | middle | middle, middle, middle, middle, middle |
+| 3 | bottom | bottom, bottom, bottom, bottom, bottom |
+| 4 | V | top, middle, bottom, middle, top |
+| 5 | inverted V | bottom, middle, top, middle, bottom |
+
+A line pays only when the first **3, 4 or 5** symbols on that line match,
+reading from the leftmost reel.
+
+In the example above, line 4 (V) contains `G G G S G`:
+
+- reels 1-3 are `G`, so three `G` symbols pay;
+- reel 4 is `S`, which breaks the run, so the `G` on reel 5 does not count;
+- `G` has symbol multiplier 4 and 3-of-a-kind has shape multiplier 1, so the
+  win is `10 x 4 x 1 = 40 PLN`.
+
+A diagonal of `L` symbols that is not one of the five paylines does not win,
+and a run must start on reel 1. That is why only the three `G` cells are
+marked in the example.
diff --git a/docs/TESTING.md b/docs/TESTING.md
index 84d98e7..acdcdd4 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -36,12 +36,13 @@ Use an 80-column terminal because several output lines are width-sensitive.
    prompt, Ctrl+C exits and restores the terminal.
 4. `help` fits 80 columns. Tab completion wraps within 76 columns and the
    cursor stays visible.
-5. `play slots 50` shows a 5x3 grid, the `Pays 3/4/5 x bet:` paytable line, and
+5. `play slots 50` shows a 5x3 grid, the `Pays bet x symbol x shape` lines, and
    the fetched balance.
 6. Space shows `Spinning...`, then the 3 rows, win text, winning-line list, and
    new balance inside the same 10-line board. Winning symbols appear as
-   yellow/bold `{ X }` cells; the `Winning lines:` list matches. The controls
-   line is never overwritten. Slots rules and RTP: `docs/SLOTS.md`.
+   yellow/bold `{ X }` cells; the `Winning lines:` list names the payline
+   (e.g. `4 (V)`). The controls line is never overwritten. Slots rules and RTP:
+   `docs/SLOTS.md`.
 7. `+` / `-` after a spin changes only the bet; no stale grid or result lines
    appear.
 8. `q` clears the board. Ctrl+C in a game clears the board and exits.