diff --git a/documents/docs/game-engine/README.md b/documents/docs/game-engine/README.md index c556a83..ee1a0b6 100644 --- a/documents/docs/game-engine/README.md +++ b/documents/docs/game-engine/README.md @@ -3,4 +3,4 @@ - [Casono TDA Rules, Version 1.0 (2024)](casono-tda-rules-version-1-2024.md) - [Game Engine Architecture](game-engine-architecture.md) - [Casono Rules Easy Description](casono-rules-easy-description.md) - +- [Game engine implementation](game-engine-implementation.md) diff --git a/documents/docs/game-engine/game-engine-control.md b/documents/docs/game-engine/game-engine-control.md new file mode 100644 index 0000000..c91c862 --- /dev/null +++ b/documents/docs/game-engine/game-engine-control.md @@ -0,0 +1,200 @@ +# Game Engine Control + + +* [GameController](#gamecontroller) +* [How the Server interacts with the GameController](#how-the-server-interacts-with-the-gamecontroller) + * [Starting a Game](#starting-a-game) + * [Preflop Actions](#preflop-actions) + * [Flop](#flop) + * [Turn](#turn) + * [River](#river) + * [Showdown](#showdown) +* [Server Outputs](#server-outputs) + * [Get full game state](#get-full-game-state) + * [Get community cards](#get-community-cards) + * [Get player hole cards](#get-player-hole-cards) + + + +# GameController + +The GameController acts as the main entry point for controlling the poker game logic from the server. + +The server does not manipulate the game state directly. +Instead, it interacts exclusively with the `GameController`, which internally coordinates: + +- the GameEngine +- the GameState +- the RuleEngine +- the RoundManager +- the TurnManager + +# How the Server interacts with the GameController + +The server calls methods on the GameController to control the game. + +## Starting a Game + +```java +GameController game = new GameController(engine); + +game.addPlayer("Julian", 20000); +game.addPlayer("Mathis", 20000); +game.addPlayer("Jona", 20000); +game.addPlayer("Lars", 20000); + +game.startGame(); +``` + +Steps performed: + +1. Create a GameController instance. +2. Add players with their starting chip stacks. +3. Start the game. + +When `startGame()` is called: + +- the deck is prepared +- hole cards are dealt +- the game phase switches to PREFLOP + +## Preflop Actions + +During the preflop phase, players perform actions. + +```java +game.playerCall("Julian"); +game.playerFold("Mathis"); +game.playerCall("Jona"); +game.playerRaise("Lars", 1200); +``` + +Supported actions include: + +* `playerCall(playerId)` +* `playerFold(playerId)` +* `playerRaise(playerId, amount)` + +The GameController passes these actions on to the GameEngine, which validates them using the RuleEngine. + +## Flop + +Once the preflop betting round is completed, the server can deal the flop. + +```java +game.dealFlop(); +``` + +This will: + +- draw 3 community cards +- add them to the board +- update the game phase + +## Turn + +```java +game.dealTurn(); +``` + +This deals the fourth community card. + +## River + +```java +game.dealRiver(); +``` + +This deals the fifth and final community card and starts the final betting round. + +## Showdown + +After the final betting round, the server can determine the winner. + +```java +String winner = game.showdown(); +```` + +This will: + +- evaluate the hands of all remaining players +- determine the best poker hand +- award the pot to the winner +- end the current hand + +Example: + +```text +Winner: Julian +Pot: 3200 +``` + +During the showdown, each remaining player's hand is evaluated using their: + +- two hole cards +- five community cards + +The best possible 5-card poker hand wins the pot. + +# Server Outputs + +The server can query the current game state at any time. + +## Get full game state + +```java +GameState state = game.getState(); +```` + +Returns the complete game state. + +The state includes information such as: + +- players +- chip stacks +- pot +- current game phase +- deck state + +## Get community cards + +```java +List board = game.getCommunityCards(); +``` + +Returns the community cards currently on the board. + +The number of cards depends on the game phase: + +- Flop -> 3 cards +- Turn -> 4 cards +- River -> 5 cards + +Example: + +```text +[NINE of DIAMONDS, TEN of SPADES, JACK of CLUBS] +``` + +## Get player hole cards + +```java +Map> cards = game.getPlayerCards(); +``` + +Returns a mapping of player IDs to their hole cards. + +Each player receives two private cards at the start of the hand. + +```text +playerId -> [Card, Card] +``` + +Example: + +```text +Mathis -> [NINE of DIAMONDS, TEN of SPADES] +Lars -> [JACK of SPADES, TWO of HEARTS] +Jona -> [SEVEN of DIAMONDS, TWO of DIAMONDS] +Julian -> [NINE of HEARTS, FIVE of DIAMONDS] +```