dorian/connect-four
Archived
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

added API docs

Browse source
This commit is contained in:
Dorian Zedler 2020-02-25 15:34:16 +01:00
parent 0c972d335c
commit a525075e61
1 changed files with 106 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

149
README.md
View file

@ -5,49 +5,112 @@ A simple version of the popular game "connect four" written in Java.
## API docs
### SOCKET API
#### Basic structure
A command consists of a json encoded string of type object which starts with ```<message>``` and ends with ```</message>```.
It contains:
- id (int): some number, the response will contain the same number
- header (int): the actual command to execute
- data (mixed): data that has to be passed with the command
A response consists of a json encoded string of type object which starts with ```<message>``` and ends with ```</message>```.
It contains:
- id (int): id of the command
- header (int): return code of the command (see later)
- data (midex): returned data of the command
#### Return codes
The return codes are mostly identical with the HTTP standard codes.
However there are some additional ones as well:
#### Enums
Some enumeration types
- PlateType
- 0: X
- 1: O
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
- Confirm game start
- command: 1
- requestdata:
- type: null
- responsedata:
- type: object
- def:
- 'player'
- type: PlateType
- desc: the plate type the client will use
- Insert a plate
- command: 100
- requestdata:
- type: int
- decs: index of column to insert plate
- replydata:
- type: string
- def:
- 'ok': plate was inserted
- 'err': plate was not inserted (either index out of range or clumn full)
- 'X': insertion resulted in the winning of PlateType X
- 'O': insertion resulted in the winning of PlateType O
- 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 lient 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 |