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