Protocol description
Types of server response
This section describes the responses of server. In general each response have a status, which resides in "status" field. Only response with status "ok" means that last query have been processed clearly, any status, that differs from this, stands for error and his "message" field describes exactly what bad thing have happened.
OK
Every successful query will be followed by this response, it have a status field with value "ok" and all necessary data after it. { "status": "ok", ... }
Bad Request
This is an error response, and have a meaning of syntax error in JSON query parsing. { "status": "badRequest", "message": "", }
Bad Command
This error appears when command is incorrect, unknown, don't have enough fields for command or have extra fields, that don't required by command. Also may be used for error reporting when other error statuses can't be used. { "status": "badCommand", "message": "", }
Internal Error
This error returned if something unhandled happened inside your engine. { "status": "internalError", "message": "", }
Bad Password
Used when a bad password supplied to a register command, when username already exists. { "status": "badPassword", "message": "", }
Bad Sid
Thats it, invalid sid supplied to any command, that requires a sid. { "status": "badSid", "message": "", }
Already Exists
Stands for an error, when a name of game already reserved. { "status": "alreadyExists", "message": "" }
Already in Game
This is an error, when some command supplied, that couldn't be executed, when user have status "in game". { "status": "alreadyInGame", "message": "", }
Not in Game
Same as above, but with user status "not in game" { "status": "notInGame", "message": "", }
Basic commands
This section contains a list of commands, with short descriptions ( I hope it'll happen soon).
Note: The commands with a star(*) in a beginning of name should work only in test mode, and return Bad Command in a normal mode.
Registration
Request
{
"cmd": "register",
"username": "<username>",
"password": "<password>"
}
Answer
Good: { "status": "ok", "sid": "" } Errors: Bad Password, Bad Username
Logout
Request
{
"cmd": "unregister",
"sid": "<sid>"
}
Answer
Good: OK
Errors: Bad Sid
Sending message
Request
{
"cmd": "sendMessage",
"sid": "<sid>",
"gameName": "<name of the game>"
"message": "<message>"
}
Answer
Good: OK
Errors: Bad Game, Bad Message, Bad Sid
Getting chat history
Request
{
"cmd": "getChatHistory",
"sid": "<sid>",
"gameName": "<name of the game>"
}
Answer
Good: { "status": "ok", "chat": [ { "username": "", "message": "", "time": "" }, ... ] }
Errors: Bad Sid, Bad Game
*Database cleanup
Request
{
"cmd": "clear"
}
Answer
Good: OK
Errors: None
Getting a list of games
Request
{
"cmd": "getGamesList",
"sid": "<sid>"
}
Answer
Good: { "status": "ok", "games": [ { "gameName": "", "mapName": "", "factionName": "", "gameStatus": "", "playersCount": , "connectedPlayersCount": , "totalCost": }, ... ] }
Errors: Bad Sid
Getting a list of players
Request
{
"cmd": "getPlayersList",
"sid": "<sid>"
}
Answer
Good: { "status": "ok", "players": [ { "username": "" }, ... ] }
Errors: Bad Sid
Getting a list of players for the game##
Request
{
"cmd": "getPlayersListForGame",
"sid": "<sid>",
"gameName": "<name of the game>"
}
Answer
Good: { "status": "ok", "players": [ { "username": "" }, ... ] }
Errors: Bad Sid, Bad Game
Setting player status
Request
{
"cmd": "setPlayerStatus",
"sid": "<sid>",
"status": "<status>"
}
Answer
Good: OK
Creation of a game
Request
{
"cmd": "createGame",
"sid": "<sid>",
"gameName": "<name of the game>",
"maxPlayers": <number>,
"mapName": "<name of map>",
"factionName": "<name of faction>",
"totalCost": <number>
}
Answer
Good: OK
Join a game
Request
{
"cmd": "joinGame",
"sid": "<sid>",
"gameName": "<name of the game>"
}
Answer
Good: OK
Leaving a game
Request
{
"cmd": "leaveGame",
"sid": "<sid>",
"gameName": "<name of the game>"
}
Answer
Good: OK
Tests format specification
Each test is a file with .tst extension. The name of a test must contain only Latin letters, symbol "_", and digits. In other words, it must match following regexp /[a-zA-Z0-9_]+\.tst/
The format of test is a set of JSON requests, separated by newlines and/or white spaces. Only double quotes are allowed. An answer to a test must have exactly the same name, but with .ans extension. The format of an answer is absolutely the same as the format of a test.
Consider the following example:
goodUsername_1.tst { "cmd": "register", "username": "Vasya_Pupkin", "password": "123456" } goodUsername_1.ans { "sid": "Vasya_Pupkin123456", "status": "ok" }
The previous example also shows another important aspect - the sid-generator. While running in testing mode, it must return sid, that is generated by simple rule: sid = username + password
Also there are some tricks to make tests fully determined. First of all server must use random number generator, based on Mersenne Twister algorithm. Tester must provide 0 as a seed to a random number generator before each test. Any time specific test must use "2000-01-01 00:00:00" value.
Rules of the game
Its a turn-based strategy game, the action takes place on a rectangular field, which is represented by a sequence of strings, consist only of a 3 types of characters: "x" - obstacle, "." - free cell, "[1-9]"(digits from 1 to 9) - players deployment spots. For instance the map in JSON query can be drawn like this { ... "map": ["......222", "....x.222", "...xxx...", "111.x....", "111......"] ... } Before the game starts players must put their Units on a deployment spots. Each Unit have a cost, and sum of all Units costs must be equal of lower then totalCost declared for map. Each Unit have a list of characteristics:
- HP - health
- MP - count of squares, unit can cross in one turn
- Defense
- Attack
- Range
- Damage
- Cost
Extensions to protocol
Upload a map
Request
{
"cmd": "uploadMap",
"sid": "<sid>",
"name": "<name>",
"terrain": "[<map strings>,...]",
}
Answer
Good: OK
Error: Bad Map, Bad Sid, Already Exists
Delete a map
Request
{
"cmd": "deleteMap",
"sid": "<sid>",
"name": "<name>"
}
Answer
Good: OK
Upload Faction
Request
{
"cmd": "uploadFaction",
"sid": "<sid>",
"name": "<name of faction",
"units": [
{
"name": "<name of unit>",
"hp": <number>,
"mp": <number>,
"defense": <number>,
"attack": <number>,
"range": <number>,
"damage": <number>,
"cost": <number>
}, ... ]
}
Answer
Good: OK
Delete Faction
Request
{
"cmd": "deleteFaction",
"sid": "<sid>",
"name": "<name of faction>"
}
Answer
Good: OK
Upload Army
Request
{
"cmd": "uploadArmy",
"sid": "<sid>",
"name": "<name of army>",
"factionName": "<name of faction>",
"units": [
{
"name": "<unit name>",
"count": <number>
},...]
}
Answer
Good: OK
Delete Army
Request
{
"cmd": "deleteArmy",
"sid": "<sid>",
"name": "<name of army>"
}
Answer
Good: OK
Choose army
Request
{
"cmd": "chooseArmy",
"sid": "<sid>",
"name": "<name of Army>"
}
Answer
Good: OK
Get Map
Request
{
"cmd": "getMap",
"sid": "<sid>,
"name": "<name of map>"
}
Answer
Good: { "status": "ok", "map": ["",...], }
Get Map List
Request
{
"cmd": "getMapList",
"sid": "<sid>"
}
Answer
Good: { "status": "ok", "maps": [ { "name": "", "players": "", "width": "", "height": "" } ] }
Get Faction
Request
{
"cmd": "getFaction",
"sid": "<sid>",
"name": "<name of faction>"
}
Answer
Good: { "status": "ok", "units": [ { "name": "", "hp": , "mp": , "defense": , "attack": , "range": , "damage": , "cost": }, ... ] }
Get Army
Request
{
"cmd": "getArmy",
"sid": "<sid>",
"name": "<name of army>"
}
Answer
Good: { "status": "ok", "units": [ { "name": "", "count": },... ] }
Get Game State
Request
{
"cmd": "getGameState",
"sid": "<sid>",
"name": "<name of game>"
}
Answer
Good:
{
"status": "ok",
"players": [
{
"username": ""
"units": [
{
"name": "",
"hp": ,
"mp": ,
"defense": ,
"attack": ,
"range": ,
"damage": ,
"cost":
}, ...
]
"isReady":
}, ...
]
"turn":
}
Move
Request
{
"cmd": "move",
"sid": "<sid>",
"turn": <number>
"units": [
{
"name": "<name of unit>",
"posX": <number>,
"posY": <number>,
"destX": <number>,
"destY": <number>,
"attackX": <number>,
"attackY": <number>
}, ...
]
}
Answer
Good: OK