Matchmaking¶
Search Rooms¶
Returns a list of rooms.
← Request¶
GET /rooms/<application_name>/<application_version>/<game_server_name>
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
settings |
Optional. A JSON Database Query, filtering room’s settings. |
show_full |
Optional, default is true . To return rooms with maximum players capacity reached, or not. |
my_region_only |
Optional, default is false . Return only rooms from my Region. See Concepts |
region |
Optional. Return only rooms from a specific region. Contradicts with my_region_only |
Access scope game
is required for this request.
→ Response¶
In case of success, a JSON object with rooms is returned:
{
"rooms": [<room>, <room>, <room>, ...]
}
A room object would be:
{
"id": <room id>,
"settings": <room settings>,
"players": <number of players>,
"max_players": <maximum number of players>,
"game_name": <application_name for the room>,
"game_version": <application_version for the room>,
"location": <location>
}
Response | Description |
---|---|
200 OK |
Everything went OK, rooms follow. |
400 Bad Arguments |
Some arguments are missing or wrong. |
404 Not Found |
No such application_name / application_version / game_server_name combination found |
Join to a Room¶
“Joins” a player to specific Room by its ID.
← Request¶
POST /rooms/<application_name>/<room_id>/join
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
room_id |
A Room ID to join into |
Access scope game
is required for this request.
→ Response¶
In case of success, a JSON object with room is returned:
{
"id": <room id>,
"settings": <room settings>,
"players": <number of players>,
"max_players": <maximum number of players>,
"game_name": <application_name for the room>,
"game_version": <application_version for the room>,
"key": <key>,
"location": <location>
}
At that point, the player has very little time window to actually to connect to the Game Server. The last two arguments in the example above should be used to proceed with connecting to the Game Server. See Join Room Flow for more information.
Response | Description |
---|---|
200 OK |
Everything went OK, join info follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
404 Not Found |
No such room |
423 Banned |
The player has been banned from participating in the Matchmaking.
See X-Ban-Until , X-Ban-Id and X-Ban-Reason HTTP return headers for additional information. |
Find a Room and Join into it¶
Performs a search for appropriate Room and does automatic join into it. Useful for “quick play” type of joins, where you don’t see any rooms before joining.
← Request¶
POST /join/<application_name>/<application_version>/<game_server_name>
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
settings |
Optional. A JSON Database Query, filtering room’s settings. |
auto_create |
Optional, default is true . Create a new Room, if there is no suitable one. This will instantiate a new
Game Server instance. If false , and there is no suitable room, a 404 Not Found will be returned. |
create_settings |
Optional. If auto_create is true , and new room is being created, these settings will be used for a new
room. |
my_region_only |
Optional, default is false . Join only in rooms from my Region. See Concepts |
region |
Optional. Join only rooms from a specific region. Contradicts with my_region_only |
Access scope game
is required for this request.
→ Response¶
In case of success, a JSON object with room is returned:
{
"id": <room id>,
"settings": <room settings>,
"players": <number of players>,
"max_players": <maximum number of players>,
"game_name": <application_name for the room>,
"game_version": <application_version for the room>,
"key": <key>,
"location": <location>
}
At that point, the player has very little time window to actually to connect to the Game Server. The last two arguments in the example above should be used to proceed with connecting to the Game Server. See Join Room Flow for more information.
Response | Description |
---|---|
200 OK |
Everything went OK, join info follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
404 Not Found |
No suitable rooms has been found |
423 Banned |
The player has been banned from participating in the Matchmaking.
See HTTP headers X-Ban-Until , X-Ban-Id and X-Ban-Reason returned for additional information. |
Find a Room and Join into it for several players¶
Performs a search for appropriate Room and does automatic join into it, in behalf of several players. Usually done by
authoritative party since game_multi
scope is required. May be useful to perform “quick play” with friends, but
somehow difficult due to the fact that you need authoritative party for it (for example, a Game Server instance itself).
← Request¶
POST /join/multi/<application_name>/<application_version>/<game_server_name>
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
accounts |
A JSON list of accounts [1, 20, 444, 888] the search fill be performed for. The more accounts the
more room in the destination room is required. |
settings |
Optional. A JSON Database Query, filtering room’s settings. |
auto_create |
Optional, default is true . Create a new Room, if there is no suitable one. This will instantiate a new
Game Server instance. If false , and there is no suitable room, a 404 Not Found will be returned. |
create_settings |
Optional. If auto_create is true , and new room is being created, these settings will be used for a new
room. |
my_region_only |
Optional, default is false . Join only in rooms from my Region. See Concepts.
Please note, that “my” context is determined from the caller’s IP. |
region |
Optional. Join only rooms from a specific region. Contradicts with my_region_only |
Access scopes game
and game_multi
are required for this request.
→ Response¶
In case of success, a JSON object with room information is returned, along with keys for individual accounts:
{
"id": <room id>,
"settings": <room settings>,
"slots": <slots>,
"location": <location>
}
The slots object is made from keys as account ID’s being requested:
{
<account-id>: {
"slot": <slot-id>,
"key": <key for account>
},
1: { "slot": <slot-id>, "key": <a key for account 1> },
20: { ... },
444: { ... },
888: { ... }
}
The entity that has requested the join needs to pass the information to the appropriate members for them to to proceed with connecting to the Game Server. See Join Room Flow for more information.
Response | Description |
---|---|
200 OK |
Everything went OK, join info follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
404 Not Found |
No suitable rooms has been found |
Create Room¶
Spawns a new Room (and new Game Server instance) and does automatic join into it. Useful for cases when existing rooms should be ignored and there should be always a new one.
← Request¶
POST /create/<application_name>/<application_version>/<game_server_name>
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
settings |
These settings will be used for a new room. |
Warning
Creating new Room does not allow to pick a region, as it always automatically chosen by caller’s geo location.
Note
The caller gets automatically “joined” into the Room, meaning there is no way to create an empty room.
Access scope game
is required for this request.
→ Response¶
In case of success, a JSON object with a new room info is returned:
{
"id": <room id>,
"settings": <room settings>,
"players": <number of players>,
"max_players": <maximum number of players>,
"game_name": <application_name for the room>,
"game_version": <application_version for the room>,
"key": <key>,
"location": <location>
}
At that point, the player has very little time window to actually to connect to the Game Server. The last two arguments in the example above should be used to proceed with connecting to the Game Server. See Join Room Flow for more information.
Response | Description |
---|---|
200 OK |
Everything went OK, join info follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
404 Not Found |
No suitable rooms has been found |
423 Banned |
The player has been banned from participating in the Matchmaking.
See HTTP headers X-Ban-Until , X-Ban-Id and X-Ban-Reason returned for additional information. |
Create Room for several players¶
Spawns a new Room (and new Game Server instance) and does automatic join for several players into it.
Useful for cases when a player’s list is known beforehand. Usually done by authoritative party since
game_multi
scope is required.
← Request¶
POST /create/multi/<application_name>/<application_version>/<game_server_name>
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
accounts |
A JSON list of accounts [1, 20, 444, 888] the creation fill be performed for. |
settings |
These settings will be used for a new room. |
Warning
Creating new Room does not allow to pick a region, as it always automatically chosen by caller’s geo location.
Note
The caller gets automatically “joined” into the Room, meaning there is no way to create an empty room.
Access scopes game
and game_multi
are required for this request.
→ Response¶
In case of success, a JSON object with room information is returned, along with keys for individual accounts:
{
"id": <room id>,
"settings": <room settings>,
"slots": <slots>,
"location": <location>
}
The slots object is made from keys as account ID’s being requested:
{
<account-id>: {
"slot": <slot-id>,
"key": <key for account>
},
1: { "slot": <slot-id>, "key": <a key for account 1> },
20: { ... },
444: { ... },
888: { ... }
}
The entity that has requested the creation of the Room needs to pass the information to the appropriate members for them to to proceed with connecting to the Game Server. See Join Room Flow for more information.
Response | Description |
---|---|
200 OK |
Everything went OK, join info follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
404 Not Found |
No such Game Server Configuration found |
Get Region List¶
Returns a current list of regions. Useful as way for the Player to pick the region to look into.
→ Response¶
In case of success, a JSON object with regions is returned:
{
"regions": {
"<region-id>": <region>,
"<region-id>": <region>,
"<region-id>": <region>,
"<region-id>": <region>
},
"my_region": "<region-id>"
}
my_region
is an automatically detected region of the caller.
A region object would be:
{
"settings": <custom settings>,
"location": {
"x": <Longitude location>,
"y": <Latitude geo location>
}
}
settings
are custom JSON object defined in admin-tool and can be used to display additional
information (like title, icon, etc). location
can be used to display that region on a map.
Get Player Game Status¶
Returns Player’s “playing” information. If a Player is playing, a record with information would be returned. Useful to display Player’s status, like “playing”, “offline”, etc.
← Request¶
GET /player/<account_id>
Argument | Description |
---|---|
account_id |
Account ID of the Player in question |
Access scope game
is required for this request.
→ Response¶
In case of success, a JSON object with associated records is returned:
{
"records": [<record>, <record>]
}
It is possible for a fraction of a time, for a Player, to have multiple records (for example, player is joining into some game while being in “lobby” server).
Each of the records would be:
{
"id": <room id>,
"settings": <room settings>,
"players": <number of players>,
"max_players": <maximum number of players>,
"game_name": <application_name for the room>,
"game_version": <application_version for the room>
}
Empty records
yield means the Player in question is not playing anywhere.
Get Game Status for several players¶
Returns “playing” information for several players. If Players are playing, a record with information would be returned. Useful to display Player’s status in batch, when you know ID’s of each of them, for example, from a leaderboard.
← Request¶
GET /players
Argument | Description |
---|---|
accounts |
a JSON list of Account ID’s [1, 2, 444, 888] of the Player’s in question |
Access scope game
is required for this request.
→ Response¶
In case of success, a JSON object with associated records for each player is returned:
{
"records": {
"1": [<record>, <record>],
"2": [<record>],
"444": [],
"888": [<record>]
}
}
It is possible for a fraction of a time, for a Player, to have multiple records (for example, player is joining into some game while being in “lobby” server).
Each of the records would be:
{
"id": <room id>,
"settings": <room settings>,
"players": <number of players>,
"max_players": <maximum number of players>,
"game_name": <application_name for the room>,
"game_version": <application_version for the room>
}
Empty records
yield means the Player in question is not playing anywhere.
Banning System¶
Issue a ban¶
Bans a certain account from participating in Matchmaking (joining servers, etc).
Note
Once issued, the player would not be able to join a server with certain account. Upon first attempt of player’s join, player’s IP address would be also associated with that ban, so joining servers would not be possible from that IP from now on, regardless of the account in question.
← Request¶
POST /ban/issue
Argument | Description |
---|---|
account |
Player’s account in question |
reason |
Human-readable description of the ban |
expires |
When the ban expires, a date in %Y-%m-%d %H:%M:%S format. |
Access scope game_ban
is required for this request.
→ Response¶
In case of success, a JSON object with ban id is returned:
{
"id": <ban id>
}
Response | Description |
---|---|
200 OK |
Everything went OK, ban information follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
406 Not Acceptable |
This user have already been banned |
Get ban information¶
Returns existing ban’s information by its ID.
← Request¶
GET /ban/<ban-id>
Argument | Description |
---|---|
ban-id |
Ban ID in question |
Access scope game_ban
is required for this request.
→ Response¶
In case of success, a JSON object with ban information is returned:
{
"id": "<ban-id>",
"reason": "<ban-reason>",
"expires": "<ban-expire-date>",
"account": "<account-id>",
"ip": "<account's-ip>"
}
Response | Description |
---|---|
200 OK |
Everything went OK, ban information follows. |
404 Not Found |
Not such ban. |
400 Bad Arguments |
Some arguments are missing or wrong. |
Updated ban information¶
Updates existing ban by its ID.
← Request¶
POST /ban/<ban-id>
Argument | Description |
---|---|
ban-id |
Ban ID in question |
reason |
Human-readable description of the ban |
expires |
When the ban expires, a date in %Y-%m-%d %H:%M:%S format. |
Access scope game_ban
is required for this request.
→ Response¶
In case of success, nothing is returned.
Response | Description |
---|---|
200 OK |
Everything went OK, ban has been updated. |
400 Bad Arguments |
Some arguments are missing or wrong. |
Invalidate a ban¶
Invalidates existing ban by its ID.
← Request¶
DELETE /ban/<ban-id>
Argument | Description |
---|---|
ban-id |
Ban ID in question |
Access scope game_ban
is required for this request.
→ Response¶
In case of success, nothing is returned.
Response | Description |
---|---|
200 OK |
Everything went OK, ban has been invalidated. |
400 Bad Arguments |
Some arguments are missing or wrong. |
Parties¶
Create Party¶
Creates a fresh new Party and returns its information. Please note this request does not open Party Session.
← Request¶
POST /party/create/<application_name>/<application_version>/<game_server_name>
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
party_settings |
See Party Properties |
room_settings |
See Party Properties |
max_members |
See Party Properties |
region |
See Party Properties |
auto_start |
See Party Properties |
auto_close |
See Party Properties |
close_callback |
See Party Properties |
Access scope party_create
is required for this request.
→ Response¶
In case of success, a JSON object with party information is returned:
{
"party": {
"id": "<party-id>",
"num_members": <number-of-members>,
"max_memvers": <meximum-numver-of-members>,
"settings": { ... }
}
}
Response | Description |
---|---|
200 OK |
Everything went OK, room information follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
Get Party Information¶
Returns Party information.
← Request¶
GET /party/<party-id>
Argument | Description |
---|---|
party-id |
Id of the party in question |
Access scope party
is required for this request.
→ Response¶
In case of success, a JSON object with party information is returned:
{
"party": {
"id": "<party-id>",
"num_members": <number-of-members>,
"max_memvers": <meximum-numver-of-members>,
"settings": { ... }
}
}
Response | Description |
---|---|
200 OK |
Everything went OK, room information follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
Close Party¶
Closes an existing Party.
The called does not have to be the creator of the party, but scope party_close
is required.
← Request¶
DELETE /party/<party-id>
Argument | Description |
---|---|
party-id |
Id of the party in question |
Access scope party_close
is required for this request.
→ Response¶
If the party had close_callback
defined, a result of execution of such callback will be returned. Otherwise, and empty {}
is returned.
Response | Description |
---|---|
200 OK |
Everything went OK, room information follows. |
400 Bad Arguments |
Some arguments are missing or wrong. |
Create Party And Open Session¶
Creates a fresh new party and opens a Party Session on it.
Web Socket Request¶
Note
This request is a Web Socket request, meaning that HTTP
session will be upgraded to a Web Socket session.
WEB SOCKET /party/create/<application_name>/<application_version>/<game_server_name>/session
Additional query artuments:
Query Argument | Description |
---|---|
party_settings |
See Party Properties |
room_settings |
See Party Properties |
room_filters |
Optional, A JSON Database Query in Party Properties |
max_members |
See Party Properties |
region |
See Party Properties |
auto_start |
See Party Properties |
auto_close |
See Party Properties |
close_callback |
See Party Properties |
auto_join |
If true (default), the current memmber will be joined to a new session automatically. |
member_profile |
If auto_join is true , this would be used to define member’s profile. See Member Properties |
Access scope party_create
is required for this request.
Connect To Existing Party¶
Connects to existing Party and opens a Party Session on it.
Web Socket Request¶
Note
This request is a Web Socket request, meaning that HTTP
session will be upgraded to a Web Socket session.
WEB SOCKET /party/<party_id>/session
Argument | Description |
---|---|
party_id |
Id of the party in question |
Additional query artuments:
Query Argument | Description |
---|---|
auto_join |
If true (default), the current memmber will be joined to a new session automatically. |
member_profile |
If auto_join is true , this would be used to define member’s profile. See Member Properties |
check_members |
If auto_join is true , this Profile Object may be used to theck ALL of the members for certain condition, or the automatic join will fail. |
Access scope party
is required for this request.
Find A Party And Open Session¶
Find a Party (possibly creates a new one) and opens a Party Session on it.
Web Socket Request¶
Note
This request is a Web Socket request, meaning that HTTP
session will be upgraded to a Web Socket session.
WEB SOCKET /parties/<application_name>/<application_version>/<game_server_name>/session
Argument | Description |
---|---|
application_name |
Name of the game, see Application Name |
application_version |
Version of the game, see Application Version |
game_server_name |
Game Server Configuration name, see Concepts |
Additional query arguments:
Query Argument | Description |
---|---|
party_filters |
A JSON Object filter to search the parties for. This argument is required. Simple {} means no filters. |
auto_create |
To automatically create a new party if there’s no party that satisfies party_filters . Please note that if auto_create is true , access scope party_create is required. |
member_profile |
Member’s profile. See Member Properties |
If auto_create
is true
, these arguments are expected:
Query Argument | Description |
---|---|
create_party_settings |
party_settings in Party Properties |
create_room_settings |
room_settings in Party Properties |
create_room_filters |
room_filters A JSON Database Query, in Party Properties |
max_members |
See Party Properties |
region |
See Party Properties |
create_auto_start |
auto_start in Party Properties |
create_auto_close |
auto_close in Party Properties |
create_close_callback |
close_callback in Party Properties |
The auto_join
cannot be defined in this argumend as it will always do automatically join.
Access scope party
is required for this request.