connect-four/README.md

# Connect Four

A simple version of the popular game "connect four" written in Java.

## API docs
### SOCKET API
#### Basic structure
The structure of the API is really simple. Commands consist of words separated by spaces. 
The first word is always the command, the following ones are the parameters. 
The commands are delivered via plain tcp sockets.

#### Data Types:
- boolean: 
    - 'true'
    - 'false'
- int: Number
- PlateType: 
    - 'X' (red)
    - 'O' (black)
- GameOverReason: 
    - 'Winner' -> somebody won
    - 'Draw'   -> the board is full
    - 'OpponentDisconnected' -> the opponent disconnected
    - 'Error'  -> some error with the scket connection
#### Commands
- setUsingPlateType
    - direction:
        - Server -> Client
    - usage:
        - This is the first command the server sends to the client after a connection is established.
        - The client shall use this plate type for his player.
    - parameters:
        1: (PlateType) for the client to use
- setIsMyTurn
    - direction:
        - Server -> Client
    - usage:
        - Sent to indicate which player's turn it currently is.
        - It is sent for every player after every move.
    - parameters:
        - 1: (PlateType) of the targeted player
        - 2: (boolean) If it is this player's turn
- doMove:
    - direction:
        - Client -> Server
    - usage:
        - Sent in order to perform a move.
        - The server will respond with the command movePerformed or invalidMove
    - parameters:
        - 1: (int) Number of the column to insert the plate into
- movePerformed
    - direction:
        - Server -> Client
    - usage:
        - Sent when a player (client- or serverside) has performed a move.
        - If the move was performed by the client, the command will be sent nevertheless.
    - parameters:
        - 1: (PlateType) of the player who performed the move.
        - 2: (int) Number of the column the plate was inserted into.
- invalidMove
    - direction:
        - Server -> Client
    - usage:
        - Sent the client has tried to perform an invalid move (eg. when it was not his turn)
    - parameters:
        - 1: (int) the column the client tried to insert into
- gameOver
    - direcion:
        - Server -> Client
    - usage:
        - Sent when the game is over
    - parameters:
        - 1: (GameOverReason) Reason for the end of the game.
        - 2: (PlateType) if parameter 1 is 'Winner' otherwise nothing
- gameReset
    - direction:
        - Server <-> Client
    - usage:
        - Sent to indicate that the socket connection will be closed.
        - Just closing shall have the same effect.
        - If the game is not over yet, it shall be ended with the reason 'OpponentDisconnected'
    - parameters:
        - none

#### Example
The communiction between a server and a client could look like this:  

| Direction         | Command             | Meaning |
|-------------------|---------------------|---------|
| Server -> Client  | setUsingPlateType X | The client has to use the PlateTye X |
| Server -> Client  | setIsMyTurn O true  | It is the server's turn |
| Server -> Client  | setIsMyTurn X false | |
| Server -> Client  | movePerformed O 6   | The server inserted a Plate into column 6 |
| Server -> Client  | setIsMyTurn O false | |
| Server -> Client  | setIsMyTurn X true  | It is the client's turn |
| Client -> Server  | doMove 0            | The client wants to insert a Plate into colum 0 |
| Server -> Client  | movePerformed X 0   | The move of the client was accepted and the move was performed |
| Server -> Client  | setIsMyTurn X false | |
| Server -> Client  | setIsMyTurn O true  | It is the server's turn |
| Server -> Client  | movePerformed O 6   | The server inserted a Plate into column 6 |
| Server -> Client  | setIsMyTurn O false | |
| Server -> Client  | setIsMyTurn X true  | |
| Client -> Server  | doMove 0            | |
| Server -> Client  | movePerformed X 0   | |
| Server -> Client  | setIsMyTurn X false | |
| Server -> Client  | setIsMyTurn O true  | |
| Server -> Client  | movePerformed O 6   | |
| Server -> Client  | setIsMyTurn O false | |
| Server -> Client  | setIsMyTurn X true  | |
| Client -> Server  | doMove 0            | |
| Server -> Client  | movePerformed X 0   | |
| Server -> Client  | setIsMyTurn X false | |
| Server -> Client  | setIsMyTurn O true  | |
| Server -> Client  | movePerformed O 6   | |
| Server -> Client  | gameOver Winner O   | The game is over, the server won |
| Server -> Client  | gameReset           | The server performed a reset |

This example ends with a board that looks like this:  
```
---------
|       |
|       |
|      O|
|X     O|
|X     O|
|X     O|
---------
```