++ + +Source: +https://www.youtube.com/watch?v=h-1WyU5Wqsw&pp=ygUZbGVybmVuIHBva2VyIHRleGFzIGhvbGRlbQ%3D%3D +
+
Der Pokertisch ist ein unglaublich faszinierender Erlebnisraum, in +dem man sehr viel lernen kann: über sich selbst, über andere Menschen +und über Fragen wie: wie treffe ich eigentlich Entscheidungen, wie gehe +ich mit Stress und Unsicherheit um und wie gut ich darin bin, mich in +andere hineinzuversetzen und Situationen richtig einzuschätzen.
+Damit Du in diesem Erlebnisraum starten kannst, ist es – wie bei +jedem Spiel – notwendig, zuerst die Grundregeln und den Spielablauf zu +verstehen.
+Also los geht es:
+Wir haben am Tisch 4 Spieler: Julian, Mathis, Jona +und Lars. Jeder Spieler startet mit 20.000 Chips. Jeder +bekommt 2 Karten auf die Hand und es gibt zusätzlich +5 Gemeinschaftskarten, die später in der Mitte +aufgedeckt werden.
+
+
+Die Spieler sitzen in folgender Reihenfolge: Julian, Mathis, Jona und +Lars. Einer davon hat den Dealer-Button, der bestimmt, wer die Karten +austeilt und von wo die Runde beginnt. Dieser Button wandert nach jeder +Runde im Uhrzeigersinn weiter und verändert damit die Position +ständig.
+Regel: 34 Button Placement and Movement 🟢
+Bevor die Karten verteilt werden, gibt es zwei Pflicht-Einsätze:
+Der Small Blind und der Big Blind. Der Big Blind ist immer doppelt so +hoch wie der Small Blind.
+
+
+Regel: 32 Dead Button 🟡
+Diese Einsätze sorgen dafür, dass sofort ein Pot entsteht und das +Spiel überhaupt beginnt, weil jeder schon “im Spiel” ist.
+Danach werden die Karten verteilt: zuerst Small Blind, dann Big Blind +und dann im Uhrzeigersinn alle anderen Spieler.
+Die erste Setzrunde beginnt immer bei dem Spieler links vom Big +Blind.
+Jetzt muss jeder Spieler entscheiden:
+Regel: 40 Methods of Betting 🟢 Regel: 41 Methods of +Calling 🟢 Regel: 42 Methods of Raising 🟢 Regel: 50 +Acting in Turn 🟢
+Julian schaut seine Karten an und entscheidet sich direkt für einen +Call von 600 Chips.
+
+
+Mathis sieht seine Karten an und merkt, dass sie nicht gut sind, also +foldet er und steigt aus.
+
+
+Jona ist nun dran und entscheidet sich ebenfalls für einen Call, weil +seine Hand spielbar ist.
+
+
+Lars schaut seine Karten an, erkennt eine starke Hand und erhöht auf +1200 Chips.
+
+
+Damit verändert sich sofort die Situation: Julian und Jona müssen +entscheiden, ob sie diesen Raise bezahlen, selbst erhöhen oder +aussteigen.
+Jetzt werden 3 Gemeinschaftskarten in die Mitte +gelegt. Ab hier verändert sich das Spiel komplett, weil alle Spieler +zusätzliche Informationen bekommen.
+
+
+Es beginnt eine neue Setzrunde.
+Regel: 49 Accepted Action 🟢
+Lars setzt 1000 Chips als Erstes. Julian entscheidet +sich mitzugehen (Call), weil seine Karten durch die Gemeinschaftskarten +stärker geworden sind.
+
+
+Jona steigt aus, weil er keine gute Verbindung mehr sieht. Mathis ist +bereits raus.
+Jetzt kommt die 4. Gemeinschaftskarte.
+Wieder beginnt eine neue Setzrunde.
+Lars setzt diesmal 3000 Chips. Julian bezahlt erneut +(Call), weil seine Hand weiterhin gut spielbar ist.
+
+
+Regel: 53 Action Out of Turn 🟡
+Jetzt wird die letzte Gemeinschaftskarte aufgedeckt.
+Dies ist die letzte Entscheidung im Spiel.
+Lars setzt 5000 Chips.
+
+
+Julian muss jetzt entscheiden: Fold, Call oder Raise auf +10000 Chips.
+Regel: 54 Pot Size Bets 🟡
+Wenn nach der letzten Setzrunde noch zwei Spieler übrig sind, kommt +es zum Showdown.
+Beide Spieler zeigen ihre Karten offen. Gewonnen hat die +beste 5-Karten-Kombination aus Handkarten und +Gemeinschaftskarten.
+
+
+Regel: 12 Cards Speak at Showdown 🟢 Regel: 16 Face Up +for All-Ins 🟢 Regel: 17 Non All-In Showdowns 🟢
+Wenn Julian den letzten Einsatz bezahlt, werden die Hände verglichen. +Wenn er foldet, gewinnt Lars automatisch den gesamten Pot.
+Die Kartenkombinationen sind klar geordnet – von schwach bis extrem +stark:
+
+
+Je höher die Kombination, desto stärker die Hand und desto +wahrscheinlicher der Gewinn.
+Julian: 2. Paar:
+
+
+Lars: 1. Paar:
+
+
+Da zwei Paare in der Rangfolge über einem einzelnen Paar stehen, +gewinnt Julian diese Runde.
+Poker ist kein Glücksspiel im klassischen Sinn, sondern ein Spiel aus +Strategie, Psychologie und Mathematik. Jede Entscheidung von Julian, +Mathis, Jona oder Lars verändert die komplette Dynamik am Tisch. Wer die +Regeln versteht, versteht nicht nur Karten, sondern auch Menschen und +Entscheidungen unter Druck.
+Regel: 67 One Player One Hand 🟢 Regel: 52 Incorrect +Bets 🟡 Regel: 57 Non-Standard Betting 🟡
+The poker table is an incredibly fascinating experiential space where +you can learn a great deal: about yourself, about other people, and +about questions such as: How do I actually make decisions? How do I +handle stress and uncertainty? And how good am I at empathizing with +others and correctly assessing situations?
+To enter this experiential space, it’s necessary—like with any +game—to first understand the basic rules and game flow.
+So let’s begin:
+We have 4 players at the table: Julian, Mathis, +Jona, and Lars. Each player starts with 20,000 chips. +Each receives 2 hole cards, and there are 5 +community cards that will later be revealed in the center.
+
+
+The players are seated as follows: Julian, Mathis, Jona, and Lars. +One of them holds the dealer button, which determines who deals the +cards and where the round begins. This button moves clockwise after each +hand, constantly changing the positions.
+Rule: 34 Button Placement and Movement 🟢
+Before cards are dealt, there are two mandatory bets:
+The Small Blind and the Big Blind. The Big Blind is always double the +amount of the Small Blind.
+
+
+Rule: 32 Dead Button 🟡
+These forced bets ensure that a pot exists from the start, making the +game begin with everyone already involved.
+After this, the cards are dealt: first to the Small Blind, then the +Big Blind, and then clockwise to all other players.
+The first betting round always begins with the player to the left of +the Big Blind.
+Now each player must decide:
+Rule: 40 Methods of Betting 🟢
+Rule: 41 Methods of Calling 🟢
+Rule: 42 Methods of Raising 🟢
+Rule: 50 Acting in Turn 🟢
Julian looks at his cards and decides to Call for 600 +chips.
+
+
+Mathis sees his cards and realizes they aren’t strong, so he Folds +and exits the hand.
+
+
+Jona is next and decides to Call as well, because his hand is +playable.
+
+
+Lars looks at his cards, recognizes a strong hand, and Raises to +1200 chips.
+
+
+This immediately changes the situation: Julian and Jona must now +decide whether to call this raise, re-raise, or fold.
+Now 3 community cards are placed face-up in the +center. From this point, the game changes completely, as all players +gain additional information.
+
+
+A new betting round begins.
+Rule: 49 Accepted Action 🟢
+Lars bets 1,000 chips first. Julian decides to Call +because his hand has improved with the community cards.
+
+
+Jona folds, as he no longer sees a strong connection. Mathis is +already out.
+Now the 4th community card is revealed.
+Another betting round begins.
+Lars bets 3,000 chips this time. Julian calls again, +as his hand remains strong.
+
+
+Rule: 53 Action Out of Turn 🟡
+Now the final community card is revealed.
+This is the last decision point in the hand.
+Lars bets 5,000 chips.
+
+
+Julian must now decide: Fold, Call, or even Raise to 10,000 +chips.
+Rule: 54 Pot Size Bets 🟡
+If two or more players remain after the final betting round, a +showdown occurs.
+All active players reveal their cards. The winner is the one with the +best 5-card combination using any combination of their hole +cards and the community cards.
+
+
+Rule: 12 Cards Speak at Showdown 🟢
+Rule: 16 Face Up for All-Ins 🟢
+Rule: 17 Non All-In Showdowns 🟢
If Julian calls the final bet, the hands are compared. If he folds, +Lars wins the entire pot automatically.
+The card combinations are clearly ranked—from weakest to +strongest:
+
+
+The higher the combination, the stronger the hand, and the greater +the chance of winning.
+Julian: Two Pair:
+
+
+Lars: One Pair:
+
+
+Since two pair ranks higher than one pair, Julian wins this +round.
+Poker is not gambling in the traditional sense, but rather a game of +strategy, psychology, and mathematics. Every decision made by Julian, +Mathis, Jona, or Lars changes the entire dynamic at the table. +Understanding the rules means not only understanding cards, but also +people and decision-making under pressure.
+ + diff --git a/documents/docs/networking/commands/protocol-document.md b/documents/docs/networking/commands/protocol-document.md index 3f61212..f4177c3 100644 --- a/documents/docs/networking/commands/protocol-document.md +++ b/documents/docs/networking/commands/protocol-document.md @@ -50,6 +50,42 @@ This document describes the protocol for client-server communication in our appl - [Error Response](#error-response-6) - [Example Request](#example-request-4) - [Example Response](#example-response-4) + - [GET_LOBBY_LIST command](#get_lobby_list-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) + - [Example Request](#example-request) + - [Example Response](#example-response) + - [GET_GAME_STATE command](#get_game_state-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) + - [Example Request](#example-request) + - [Example Response](#example-response) + - [RAISE command](#raise-command) + - [CALL command](#call-command) + - [FOLD command](#fold-command) + - [BET command](#bet-command) + - [SEND_MESSAGE command](#send_message-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) + - [GET_MESSAGE_COUNT command](#get_message_count-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) + - [GET_NEXT_MESSAGE command](#get_next_message-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) + - [JOIN_LOBBY command](#join_lobby-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) + - [GET_LOBBY_STATUS command](#get_lobby_status-command) + - [Required pre-execution checks](#required-pre-execution-checks) + - [Request Parameters](#request-parameters) + - [Success Response](#success-response) @@ -455,6 +491,628 @@ TYPE=GLOBAL GAME=-1 USER=player1 TARGET=null TIME=9:30 TEXT="Guten Tag" END ``` +### Example Response (success) + +``` ++OK +END +``` + +## JOIN_LOBBY command + +The `JOIN_LOBBY` command requests the server to add the currently logged-in user to the lobby with the given identifier. The server resolves the username from the session; clients must only provide the `ID` parameter. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `ID` | `int` | no | Numeric id of the target lobby | + +### Implementation notes + +- Parser: `JoinLobbyParser` — reads the `ID` parameter and builds `JoinLobbyRequest`. +- Handler: `JoinLobbyHandler` — resolves the username from `UserRegistry` using the session id, attempts to add the user to the lobby via `LobbyManager.addPlayerToLobby(...)` and returns appropriate responses. + +### Success Response + +No additional response fields. The server replies with a simple `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `USER_NOT_LOGGED_IN` | No user associated with the session (pre-execution check failed) | +| `LOBBY_NOT_FOUND` | The specified lobby id does not exist | +| `LOBBY_FULL_OR_ALREADY_IN` | Lobby is full or the user is already in the lobby | + +### Example Request + +``` +JOIN_LOBBY ID=1 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=LOBBY_NOT_FOUND + MESSAGE=Lobby not found +END +``` + +## GET_LOBBY_LIST command + +The `GET_LOBBY_LIST` command requests the server to return a list of currently available lobbies with basic metadata. + +### Required pre-execution checks +None. + +### Request Parameters +No parameters. + +### Implementation notes + +- Parser: `GetLobbyListParser` — creates `GetLobbyListRequest` (no parameters). +- Handler: `GetLobbyListHandler` — queries `LobbyManager#getAllLobbies()` and returns `GetLobbyListResponse`. +- Response: `GetLobbyListResponse` — builds a `LOBBIES` collection with repeated `LOBBY` blocks containing `ID`, `NAME`, `PLAYER_COUNT`. + +### Success Response + +The response contains a `LOBBIES` collection with nested `LOBBY` entries. + +Example response structure: + +``` ++OK + LOBBIES + LOBBY + ID=1 + NAME=Room 1 + PLAYER_COUNT=2 + END + LOBBY + ID=2 + NAME=Room 2 + PLAYER_COUNT=3 + END + END +END +``` + +### Example Request + +``` +GET_LOBBY_LIST +``` + +### Example Response (error) + +``` +-ERR + CODE=NO_LOBBIES_AVAILABLE + MESSAGE=No lobbies available +END +``` + +## GET_GAME_STATE command + +The `GET_GAME_STATE` command returns a snapshot of the current game for a lobby. It includes global fields (`PHASE`, `POT`, `CURRENT_BET`, `DEALER`, `ACTIVE_PLAYER`), repeated `CARD` blocks for community cards and repeated `PLAYER` blocks for per-player information. If the requester is a player in the game, their hole cards are included inside their `PLAYER` block as nested `CARD` blocks. + +### Required pre-execution checks +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters +| Parameter Name | Type | Optional | Description | +| :------------- | :----- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to query. If omitted the server will resolve the lobby by the requesting session's associated user. +| `USERNAME` | `String` | yes | Optional username to query the game state for (server will also accept session resolution). + +### Implementation notes + +- Parser: `GetGameStateParser` — accepts optional `GAME_ID` and `USERNAME` and builds `GetGameStateRequest`. +- Handler: `GetGameStateHandler` — resolves the target lobby by `GAME_ID` when provided, otherwise by `USERNAME` or session user; if a game is running a `GetGameStateResponse` is returned. +- Response: `GetGameStateResponse` — uses repeated `CARD` and `PLAYER` blocks to match the client parser expectations. + +### Success Response + +Top-level fields and collections (example): + +``` ++OK + PHASE=PRE_FLOP + POT=150 + CURRENT_BET=50 + DEALER=2 + ACTIVE_PLAYER=1 + CARD + VALUE=K + SUIT=H + END + PLAYER + NAME=player1 + CHIPS=1000 + BET=50 + STATE=ACTIVE + CARD + VALUE=A + SUIT=S + END + END +END +``` + +### Example Request + +``` +GET_GAME_STATE GAME_ID=1 +``` + +### Example Response (error) + +``` +-ERR + CODE=GAME_NOT_STARTED + MESSAGE=Game not started +END +``` + +## BET command + +The `BET` command lets the currently logged-in player place a bet in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | +| `AMOUNT` | `int` | no | Amount the player wants to bet | + +### Implementation notes + +- Parser: `PlayerBetParser` — reads `AMOUNT` and optionally `GAME_ID`. +- Handler: `PlayerBetHandler` — validates the session, lobby (by id when provided or else by session), player's turn and balance and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to bet when not their turn | +| `INSUFFICIENT_FUNDS` | Player does not have enough chips | +| `INVALID_AMOUNT` | Amount parameter is invalid | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +BET GAME_ID=1 AMOUNT=50 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=INSUFFICIENT_FUNDS + MSG=Not enough chips +END +``` + +## RAISE command + +The `RAISE` command lets the currently logged-in player increase the current bet in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | +| `AMOUNT` | `int` | no | Amount the player wants to raise | + +### Implementation notes + +- Parser: `PlayerRaiseParser` — reads `AMOUNT` and optionally `GAME_ID`. +- Handler: `PlayerRaiseHandler` — validates the session, lobby (by id when provided or else by session), player's turn and balance and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to raise when not their turn | +| `INSUFFICIENT_FUNDS` | Player does not have enough chips | +| `INVALID_AMOUNT` | Amount parameter is invalid | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +RAISE GAME_ID=1 AMOUNT=100 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=INSUFFICIENT_FUNDS + MSG=Not enough chips +END +``` + +## CALL command + +The `CALL` command lets the currently logged-in player match the current bet (call) in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | + +### Implementation notes + +- Parser: `PlayerCallParser` — accepts optional `GAME_ID`. +- Handler: `PlayerCallHandler` — validates the session, resolves the lobby by id when provided or by session otherwise and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to call when not their turn | +| `INSUFFICIENT_FUNDS` | Player does not have enough chips | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +CALL GAME_ID=1 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=NOT_YOUR_TURN + MSG=It is not your turn +END +``` + +## FOLD command + +The `FOLD` command lets the currently logged-in player leave the current hand (fold) in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | + +### Implementation notes + +- Parser: `PlayerFoldParser` — accepts optional `GAME_ID`. +- Handler: `PlayerFoldHandler` — validates the session, resolves the lobby by id when provided or by session otherwise and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to fold when not their turn | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +FOLD GAME_ID=1 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=NOT_YOUR_TURN + MSG=It is not your turn +END +``` + +## FOLD command + +The `FOLD` command lets the currently logged-in player leave the current hand (fold) in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | + +### Implementation notes + +- Parser: `PlayerFoldParser` — accepts optional `GAME_ID`. +- Handler: `PlayerFoldHandler` — validates the session, resolves the lobby by id when provided or by session otherwise and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to fold when not their turn | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +FOLD GAME_ID=1 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=NOT_YOUR_TURN + MSG=It is not your turn +END +``` + +## FOLD command + +The `FOLD` command lets the currently logged-in player leave the current hand (fold) in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | + +### Implementation notes + +- Parser: `PlayerFoldParser` — accepts optional `GAME_ID`. +- Handler: `PlayerFoldHandler` — validates the session, resolves the lobby by id when provided or by session otherwise and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to fold when not their turn | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +FOLD GAME_ID=1 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=NOT_YOUR_TURN + MSG=It is not your turn +END +``` + +## FOLD command + +The `FOLD` command lets the currently logged-in player leave the current hand (fold) in the ongoing game for their lobby. + +### Required pre-execution checks + +- [`UserLoggedInCheck`](#userloggedincheck) + +### Request Parameters + +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `GAME_ID` | `int` | yes | Numeric id of the lobby/game to target. If omitted the server resolves the lobby by the requesting session's user. | + +### Implementation notes + +- Parser: `PlayerFoldParser` — accepts optional `GAME_ID`. +- Handler: `PlayerFoldHandler` — validates the session, resolves the lobby by id when provided or by session otherwise and forwards to `GameController`. + +### Success Response + +No additional response fields. Server replies with `+OK` on success. + +### Error Response + +| Code | Description | +| :--- | :---------- | +| `NOT_YOUR_TURN` | The player attempted to fold when not their turn | +| `GAME_NOT_STARTED` | No game is running in the lobby | +| `NOT_IN_LOBBY` | Requesting user is not a member of the lobby | +| `LOBBY_NOT_FOUND` | The specified `GAME_ID` does not exist | + +### Example Request + +``` +FOLD GAME_ID=1 +``` + +### Example Response (success) + +``` ++OK +END +``` + +### Example Response (error) + +``` +-ERR + CODE=NOT_YOUR_TURN + MSG=It is not your turn +END +``` + +## GET_LOBBY_STATUS command + +The `GET_LOBBY_STATUS` command requests the server to return the current state of a lobby, including the list of players and their ready state. + +### Required pre-execution checks +None. + +### Request Parameters +| Parameter Name | Type | Optional | Description | +| :------------- | :--- | :------: | :---------- | +| `ID` | `int` | no | Numeric id of the target lobby | + +### Implementation notes + +- Parser: `GetLobbyStatusParser` — reads the `ID` parameter and builds `GetLobbyStatusRequest`. +- Handler: `GetLobbyStatusHandler` — queries `LobbyManager` for the lobby and builds a `GetLobbyStatusResponse` containing player entries. + +### Success Response + +The response contains a `LOBBY` collection with nested `PLAYERS` and one or more `PLAYER` entries. Each `PLAYER` entry contains `USERNAME` and `READY` fields. + +Example response structure: + +``` ++OK + LOBBY + ID=1 + PLAYERS + PLAYER + USERNAME=Lars_001 + READY=false + END + PLAYER + USERNAME=Anna + READY=true + END + END + END +END +``` + +### Error Response +| Code | Description | +| :--- | :---------- | +| `LOBBY_NOT_FOUND` | The specified lobby id does not exist | + +### Example Request + +``` +GET_LOBBY_STATUS ID=1 +``` + +### Example Response (error) + +``` +-ERR + CODE=LOBBY_NOT_FOUND + MESSAGE=Lobby not found +END +``` + ## CREATE_LOBBY command The `CREATE_LOBBY` command requests the server to create a new lobby and return its identifier. diff --git a/documents/milestones/ms-4/casono-rules-easy-description.md b/documents/milestones/ms-4/casono-rules-easy-description.md new file mode 100644 index 0000000..f6ac3e8 --- /dev/null +++ b/documents/milestones/ms-4/casono-rules-easy-description.md @@ -0,0 +1,323 @@ +# Casono Rules Easy Description + +> Source: