added API docs
This commit is contained in:
parent
0c972d335c
commit
a525075e61
1 changed files with 106 additions and 43 deletions
149
README.md
149
README.md
|
|
@ -5,49 +5,112 @@ A simple version of the popular game "connect four" written in Java.
|
||||||
## API docs
|
## API docs
|
||||||
### SOCKET API
|
### SOCKET API
|
||||||
#### Basic structure
|
#### Basic structure
|
||||||
A command consists of a json encoded string of type object which starts with ```<message>``` and ends with ```</message>```.
|
The structure of the API is really simple. Commands consist of words separated by spaces.
|
||||||
It contains:
|
The first word is always the command, the following ones are the parameters.
|
||||||
- id (int): some number, the response will contain the same number
|
The commands are delivered via plain tcp sockets.
|
||||||
- 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
|
|
||||||
|
|
||||||
|
#### 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
|
#### Commands
|
||||||
- Confirm game start
|
- setUsingPlateType
|
||||||
- command: 1
|
- direction:
|
||||||
- requestdata:
|
- Server -> Client
|
||||||
- type: null
|
- usage:
|
||||||
- responsedata:
|
- This is the first command the server sends to the client after a connection is established.
|
||||||
- type: object
|
- The client shall use this plate type for his player.
|
||||||
- def:
|
- parameters:
|
||||||
- 'player'
|
1: (PlateType) for the client to use
|
||||||
- type: PlateType
|
- setIsMyTurn
|
||||||
- desc: the plate type the client will use
|
- direction:
|
||||||
- Insert a plate
|
- Server -> Client
|
||||||
- command: 100
|
- usage:
|
||||||
- requestdata:
|
- Sent to indicate which player's turn it currently is.
|
||||||
- type: int
|
- It is sent for every player after every move.
|
||||||
- decs: index of column to insert plate
|
- parameters:
|
||||||
- replydata:
|
- 1: (PlateType) of the targeted player
|
||||||
- type: string
|
- 2: (boolean) If it is this player's turn
|
||||||
- def:
|
- doMove:
|
||||||
- 'ok': plate was inserted
|
- direction:
|
||||||
- 'err': plate was not inserted (either index out of range or clumn full)
|
- Client -> Server
|
||||||
- 'X': insertion resulted in the winning of PlateType X
|
- usage:
|
||||||
- 'O': insertion resulted in the winning of PlateType O
|
- 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 |
|
||||||
|
|
||||||
|
|
|
||||||
Reference in a new issue