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
|
||||
### 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 |
|
||||
|
||||
|
|
|
|||
Reference in a new issue