API SPECIFICATION

GST - CODEFEST
version 2021-0122

ID HTTP METHOD SOCKET-EVENT SOCKET-METHOD

API-1a POST join game METHOD
socketClient.emit('join game

INPUT PARAMETERS
- game_id:

- player_id:

Data Format:

Data Structure:
{
"game_id": "xxxx"
"player_id": "xxxx"
}

API-1b POST join game METHOD

socketClient.on('join game',

RESPONSE PARAMETERS
Response parameters of

Data Format:

Data Structure:
- game_id:
- player_id:

API-2 POST ticktack player METHOD

socketClient.on('ticktack pla

RESPONSE PARAMETERS
Response parameters of

Data Format:

Data Structure:
- id
- timestamp
- map_info
 - tag:

- player_id:
- gameStatus:
- gameRemainTime:

API-3a POST drive player METHOD

socketClient.emit('drive play

INPUT PARAMETERS
- direction:

Data Format:
 Data Structure:
{
"direction": "xxxxx
}

API-3b POST drive player METHOD

socketClient.on('drive player

RESPONSE PARAMETERS
Response parameters of

Data Format:

Data Structure:
- direction:
- player_id:
KET-METHOD

etClient.emit('join game', Parameters)

T PARAMETERS
The verification key of a match. Data type is String.
Admin will share to you before every fighting time.

player_id: The verification key of team. Data type is String.

Admin will share to you before every fighting time

JSON

Structure:

"game_id": "xxxx"
"player_id": "xxxx"

etClient.on('join game', callbackFunction)

ONSE PARAMETERS
Response parameters of callbackFuntion(Response)

Data Format: JSON

Data Structure:
- game_id: The key of game.
- player_id: The key of player

etClient.on('ticktack player', callbackFunction)

ONSE PARAMETERS
Response parameters of callbackFuntion(Response)

Data Format: JSON

Data Structure:
ID of request
- timestamp Time of request
- map_info Map information
Properties of Map Info
- size: The information of map.
Include size of map by horizotal and vertical squares.
Properties of Size:
- rows: The max number of cell of map by vertical.
- cols: The max number of cell of map by horizontal.
- players: The array list of player on map.
Properties of Player:
- id : The Id of competitor or player
- skin: The name of competitor or player
- spawnBegin: The player or conpetitor's position is born at the start
of the game on map (row,col) by horizotal and vertical
squares.
- currentPosition: The current position of player or competitor on
map(row,col) by horizotal and vertical squares.
- power: The power of the player's bomb (not of the competitor).
- speed: The speed of the player (not of the competitor)
- delay: Time interval between 2 times of placing a bomb of the
player(not of the competitor).
- score: Current score of player.
- lives: Player’s lives left.
- box: Number of destroyed box.
- pill: Amount of your pills.
- pillUsed: Amount of pill have used.
- humanCured: Amount of man have cured.
- humanSaved: Amount of man have rescued.
- virus: Amount of virus have destroyed.
- virusInfected: Amount of times infected sickness by virus.
- humanInfected: Amount of times infected sickness by man.
- quarantine: Amount of times you are quarantined.
- map: 2D array describing infomation of map.
Values of item in array:
0 - A Road
1 - A Wall (None destructible cell)
 2 - A Balk (Destructible cell)
6 - A Teleport Gate
7 - A Quarantine Place

- bombs: The array list of bombs on map.

Properties of Bomb:
- row: The position of item in horizontal.
- col: The position of item in vertical.
- remainTime: The time of bomb will exploded.
- spoils: The array list of spoils on map.
Properties of Spoil:
- row: The position of item in horizontal.
- col: The position of item in vertical.
- spoil_type : Spoil type specification
Values of spoil types:
5 - A Pill
3 - A BOMB POWER The length of bomb's blast
4 - A BOMB DELAY TIME Delay time interval between 2 times
of placing a bomb of player
- viruses: The array list of virus.
Properties of Virus:
- position: The current position of the virus in squares.
Properties of position
- row: The position of item in horizontal.
- col: The position of item in vertical.
- direction: The virus's movement direction.
Value of directions:
0 - No direction.
1 - Move LEFT
2 - Move RIGHT.
3 - Move UP
4 - Move DOWN
- human: The array list of human.
Properties of Human:
- position: The current position of the human in squares
Properties of position
- row: The position of item in horizontal.
- col: The position of item in vertical.
- direction: The human's movement direction.
Value of directions:
1 - Move LEFT
2 - Move RIGHT.
 3 - Move UP
4 - Move DOWN
- infected: The infected virus status of human.
- curedRemainTime: Remain time before man could moving again.
- humanSpeed: The speed of human on map.
- virusSpeed: The speed of virus on map.
The reason for this ticktac update
Player's tag values:
player:moving-banned Player's moving is blocking, two player moves to same cell.
player:start-moving Player is started moving.
player:stop-moving Player is stopped moving.
player:be-isolated Player is blocking in quarantine area.
player:back-to-playground Player was moved out quarantine area, and stand on floor.
player:pick-spoil Player just pick a spoil.
player:cure people Human is in curing process.
player:destroy-virus Virus was killed.
player:cure-completed Human was rescused.
Bomb's tag values:
bomb:explosed Bomb have explosed.
bomb:setup Bomb have setup on map.
Game's tag values
start-game Game is started.
update-data Auto looping in interval time. (Ex: every 500ms)
- player_id: The player’s id whose action made the update
- gameStatus: Only have in fighting stage.
- gameRemainTime: Remain time in seconds of game before time over.

etClient.emit('drive player', Parameters)

T PARAMETERS
The player's series of movement direction. Data type is String.
Value of direction:
1 - Move LEFT
2 - Move RIGHT.
3 - Move UP
4 - Move DOWN
b - Drop BOMB
x - Stop Moving

JSON
 Structure:

"direction": "xxxxx"

etClient.on('drive player', callbackFunction)

ONSE PARAMETERS
Response parameters of callbackFuntion(Response)

Data Format: JSON

Data Structure:
- direction: The player's movement direction.
- player_id: The moved player
DESCRIPTION
Emmited request to sign your bot to game.
It is required.

Example in JavaScript:
socketClient.emit('join game', { game_id: 'xxxx-xxxx-xxxx-xxxx',
player_id: 'xxxx-xxxx-xxxx-xxxx'});

Response of request on API-1a.

The heart beat(tick tack) of game. The event is triggered every

changes of game.

It is required implementation to tracking game states.

 The event provide information of game like: size of map,
player's states, current map states, spoils, bombs, …

ompetitor).

omb of the
val between 2 times
b of player
Send request to move your bot, set your bomb.

Example-1: Move player with many steps

{
"direction": "1111333332222224444",
}

Example-2: Move bomber with only one step

{
"direction": "3",
}

Example-3: Move player and drop the bomb

{
"direction": "111b2222",
}

Response of request on API-3a.

 API SERVER
GST - CODEFEST

A/ Client & Server Comminication

SocketIO
Client Server
SocketIO

B/ Server Information
- SocketIO Software, version 3.0.4
- NodeJS, version 10.16.3

C/ Examples
JavaScript Example
https://fpt.workplace.com/groups/398715607126625/permalink/1031631217168391/

Java Example
https://fpt.workplace.com/groups/398715607126625/permalink/1021696008161912/?comment_id=10992
https://fpt.workplace.com/groups/398715607126625/permalink/768569630141219/
12/?comment_id=1099262990405213
API WORKFLOW
GST - CODEFEST

(5) Update Playground

GAME SERVER
(API Server)
(2) Join Game (API-1b)
(1) Join Game (API-1a)

(4) Drive bot (API-3a)

(3) Ticktack (API-2)

CLIENT APP
(Bot Controlling Env)

(1)(2) Join Game Controlling

(3) Ticktack Listener

(4) Driving Bot Engine

Playground
GAME PLAYGROUND
(Web Browser)
View

People