Add docs

README.md

@@ -1,4 +1,14 @@
 # poker-workshop
+This is a playground for poker.
+The goal is to create a poker game that can be played by multiple computer players.
+
+There are multiple objectives for this project:
+- simulate a poker game
+- create a poker file format to save games and states
+- create poker AIs with different strategies and play them against each other
+- create an environment to train poker AIs
+- create an API to allow anybody to create their own poker AIs
+
 ## Development environment
 In order to ensure that all developers use the same environment, we use docker. This will avoid many problems with different versions of libraries and compilers. We will carry out the development using VSCode's Remote Development extension. This will allow us to do all our coding, compiling and testing inside a docker container.
 
@@ -23,3 +33,7 @@ If you are not using VSCode, you need to skip step 2 and instead of steps 5-8, y
 1. Right click on the `poker-workshop` container and click `Attach to container`
 1. Install the required extensions in the container (C/C++, CMake)
 
+## Docs
+We are using a [Game class](docs/game.md) to simulate one set of poker games. The game class is responsible for the game loop and the game logic. Every time a [Player](docs/player.md) has to make a turn, it calls the player´s `turn` method with the [Data](docs/data.md) struct, which holds all information about the game. The game class simulates a [Deck](docs/deck.md) of cards. Who wins the showdown is determined by the [Handstrength](docs/handstrengths.md) of the players.
+
+There are several implemented [Players](docs/players.md) with different strategies.

docs/data.md

@@ -0,0 +1,37 @@
+# Game Data
+There are two types of data that is used in the game:
+- player data
+- simulation data
+
+## Player Data
+The player data is only available to the player and contains the player´s hand cards only. It is stored directly in the players object. All other information is available for all players and is stored in the simulation data.
+
+## Simulation Data
+The simulation data is available to all players and contains all information about the simulation. It is stored in the game object as `Data` and is passed to the player in the `turn` function. The player can use this information to make a decision.
+`Data` is a struct of the following form:
+- number of players (int)
+- game data (struct)
+- round data (struct)
+- bet round data (struct)
+
+### Game Data
+The game data contains information about one poker game (until only one player is not out yet). It is stored in the `GameData` struct and has the following form:
+- number of chips per player (int[])
+- bool array of players who are out (bool[])
+
+### Round Data
+The round data contains information about one round (until the pot is won). It is stored in the `RoundData` struct and has the following form:
+- small blind (int)
+- big blind (int)
+- add blind (int, which is added to the small blind after the button has moved one time around the table)
+- dealer position (int)
+- pot (int)
+- bool array of players who folded (bool[])
+- community cards (Card[])
+- OutEnum which represents the state of the round (OutEnum)
+
+### Bet Round Data
+The bet round data contains information about one bet round (until all players have bet the same amount). It is stored in the `BetRoundData` struct and has the following form:
+- position of the player who has to act (int)
+- current bet (int)
+- player bets (int[])

docs/deck.md

@@ -0,0 +1,10 @@
+# Deck and Card
+Card class hold the information of a card
+- unsigned char suit: the suit of the card
+- unsigned char rank: the rank of the card
+
+Deck class hold the information of a deck of cards
+- Card cards[52]: the cards in the deck
+- unsigned char len: the number of cards currently in the deck 
+- you can shuffle the deck or draw a card from the deck
+- for a new deck, you can use the constructor to initialize it

docs/game.md

@@ -0,0 +1,2 @@
+# Game class
+The `Game` class is the main class of the game. It contains the game loop and the game logic. It is responsible for the communication between the players and the game logic. It also contains the [`Data`](data.md) struct which is passed to the players in the `turn` function.

docs/handstrengths.md

@@ -0,0 +1,40 @@
+# Handstrengths
+
+There are two parameter that determine the strength of a hand: 
+- `hand kind` 
+- `rank strength`
+
+## Hand kind
+In poker, there are 10 different hands. In order of strength, they are:
+1. Royal flush
+1. Straight flush
+1. Four of a kind
+1. Full house
+1. Flush
+1. Straight
+1. Three of a kind
+1. Two pair
+1. One pair
+1. High card
+
+## Rank strength
+The `rank strength` is a way to determine a winner when two players have the same `hand kind`. The `rank strength` is determined by the ranks of the variable cards (not included to the `hand kind`) in the hand. The higher the `rank strength`, the stronger the hand.
+
+`hc` = hand card; A card that is included in the `hand kind` \
+`nhc` = non-hand card; A card that is not included in the `hand kind`
+
+| Hand kind | Rank strength computation |
+| --- | --- |
+| Royal flush | 0 |
+| Straight flush | highest hc |
+| Four of a kind | hc * 16 + highest nhc |
+| Full house | triple hc * 16 + double hc |
+| Flush | highest hc * 16^4 + second highest hc * 16^3 + third highest hc * 16^2 + fourth highest hc * 16 + lowest hc |
+| Straight | highest hc |
+| Three of a kind | hc * 16^2 + highest nhc * 16 + second highest nhc |
+| Two pair | highest hc * 16^2 + second highest hc * 16 + highest nhc |
+| One pair | hc * 16^3 + highest nhc * 16^2 + second highest nhc * 16 + third highest nhc |
+| High card | highest hc * 16^4 + second highest hc * 16^3 + third highest hc * 16^2 + fourth highest hc * 16 + lowest hc |
+
+## Hand comparison
+In order to compare two hands, we first compare the `hand kinds`. If the `hand kinds` are different, the hand with the higher `hand kind` is the winner. If the `hand kinds` are the same, we compare the `rank strengths`. If the `rank strengths` are the same, the hands are equal.

docs/player.md

@@ -0,0 +1,8 @@
+# Player
+for all available player implementations see [players](players.md) 
+
+A player has only access to its hand cards and is initialized with a number which represents the player's position on the table.
+
+Action `turn`(const Data& data) is called when it is the player's turn. The player has to return a valid action. The action is represented by a struct of the form (`action_type`, `bet`). The `action_type` is an enum which represents the type of the action. If the `action_type` requires a bet, the `bet` is the second element of the struct. If the `action_type` does not require a bet, the bet is ignored.
+
+The player has access to all information from the [data](data.md) struct.

docs/players.md

@@ -0,0 +1,9 @@
+# Player types
+
+A player is a class that extends the `Player` class.
+Here is a list of all currently available player types:
+
+|Name|Strength|Description|
+|----|--------|-----------|
+|RandomPlayer|?|Randomly chooses a legal action|
+|CheckPlayer|?|Always checks/calls|