v2.2.0: add blackjack with reserved bets and hit/stand/double

1 files changed, 33 insertions, 9 deletions

diff --git a/docs/GAMES.md b/docs/GAMES.md
index 12b0e7c..4c42369 100644
--- a/docs/GAMES.md
+++ b/docs/GAMES.md
@@ -6,17 +6,36 @@
 | --- | --- | --- |
 | Slots | Done | 5 reels x 3 rows, 5 paylines, 98.6% RTP |
 | Roulette | Done | European wheel, split bets, 97.3% RTP |
+| Blackjack | Done | Six-deck shoe per hand, S17, 3:2, hit/stand/double |
 
 ## Planned
 
 | Game | Shape | Main open decisions |
 | --- | --- | --- |
-| Blackjack | Multi-step hand | Dealer hits/stands soft 17; double/split/insurance; blackjack payout; shoe persistence |
 | Crash | Real-time round | Crash-point distribution; cashout latency; provable fairness |
 
-Blackjack needs server-side hand state and player actions. Crash needs a timed
-round loop and a cashout action, so it should come after blackjack unless we
-redesign the loop first.
+Crash needs a timed round loop and a cashout action, so it should be its own
+protocol/loop change.
+
+## Blackjack
+
+- Six-deck shoe, shuffled fresh for every hand and discarded afterwards.
+- Dealer stands on all 17s (including soft 17).
+- Blackjack pays 3:2, rounded down to whole PLN.
+- Hit, stand, and double; no split, insurance, or surrender.
+- The bet is reserved when the hand starts. Cancel or disconnect refunds it.
+- A natural or dealer blackjack settles immediately.
+
+Client controls:
+
+```
+H       hit
+S       stand
+D       double (on the first two cards)
+SPACE   deal the next hand
++ or = / -  change the next hand's bet
+Q       leave the table (active hand is cancelled and refunded)
+```
 
 ## Roulette
 
@@ -68,6 +87,9 @@ plays (
 
 // roulette
 {"number":"17","color":"black","bets":"{\"red\":10,\"black\":10,\"even\":10,\"odd\":10,\"numbers\":[{\"number\":17,\"amount\":5}]}"}
+
+// blackjack
+{"player":["10S","6H","5D"],"dealer":["9D","8C"],"player_total":21,"dealer_total":17,"bet":10,"result":"win","winnings":20}
 ```
 
 The balance update and the `plays` insert happen in one transaction
@@ -89,12 +111,14 @@ PLAY_START roulette <total> <bets-json>
 ROULETTE_RESULT <session> <winnings> <bet> <balance> <number> <color> <bets-json>
 ```
 
-Blackjack and crash still need a generic state/action exchange, for example:
+Blackjack is a multi-step session:
 
 ```
-GAME_START <game> <bet>
-GAME_ACTION <action> [json]
-GAME_STATE <json>          # cards, bets, multiplier, legal actions, result
+PLAY_START blackjack <bet>
+BLACKJACK_STATE <json>
+BLACKJACK_ACTION <session> hit|stand|double|cancel
+BLACKJACK_STATE <json>
 ```
 
-That will be its own protocol change.
+`BLACKJACK_STATE` carries the player/dealer cards, totals, actions, balance,
+result and winnings. The dealer's hole card is `?` until the hand is done.