Controller Service JSON-RPC API¶
This section describes API calls that Game Server instance can make to the Controller Service.
Initialized Request¶
Called when the Game Server instance is completely initialized and ready to accept new players.
← Request¶
Method Name: inited
. Arguments:
Argument | Description |
---|---|
settings |
(Optional) Update room settings along with initialization |
If the argument settings
passed along the request, the rooms settings is updated with that argument. For example, if player requested to create a room with {"map": "badone"}
and the Game Server instance realized there is no such map, in can choose the other map instead, and pass {"map": "goodone"}
as the settings
argument to the inited
call. That would lead to the room have correct map setting no matter what setting the Player have passed.
→ Response¶
The Controller will respond {"status": "OK"}
to that request if everything went fine. If the error is returned instead, the Game Server instance should exit the process (and will be forced to at some point).
Player Joined Request¶
Called once a Player connected to the Game Server instance. That call with exchange a Player’s registration Key for Player’s Access Token
, at the same time making Player registration inside of the Room permanent.
← Request¶
Method Name: joined
. Arguments:
Argument | Description |
---|---|
key |
The registration Key |
extend_token , extend_scopes |
(Optional) See step 2a for more information. |
If both extend_token
and extend_scopes
are passed diring the joined
request, the Access Token
of the player will be extended using extend_token
as master token and extend_scopes
as a list of scopes the Player’s Access Token
should be extended with.
Token extention is used to do strict actions server side in behalf of the Player while the Player itself cannot. For example,
- User Authenticates asking for
profile
scope. This scope allows only to read user profile, but not to write; - The Game Server instance Authenticates itself with
profile_write
scope access (allows to modify the profile); - The Game Server extends this token to the more powerful one, so server can write the profile in behalf of the Player;
- At the same time, user still have perfectly working access token, without such possibility;
- So player can only read Player’s profile, but the Game Server can also write it.
→ Response¶
If the request is successful, the Controller will respond:
{ "access_token": <Player's access token>, "scopes": [<A list of Player's access token scopes>], "account": <Player's account>, "credential": <Player's credential>, "info": { ... additional info ... } }
Player Left Request¶
Called once a Player disconnected from the Game Server instance. That call will remove Player’s registration from the Room allowing other Players to connect to the Room.
→ Response¶
If the request is successful, the Controller will respond with empty object {}
Update Room Settings Request¶
Called once Game Server instance decided to update room settings (for example, a map or mode have just changed)
← Request¶
Method Name: update_settings
. Arguments:
Argument | Description |
---|---|
settings |
New settings for the Room |
→ Response¶
If the request is successful, the Controller will respond with empty object {}
Check Game Server Deployment Request¶
Called to check if the Game Server instance is still up to date (the game version may be disabled from spawning, or a new Game Server Deployment is available). Once the deployment is not valid anymore, the Game Server instance may decide to gracefully shut down at the end of
← Request¶
Method Name: check_deployment
. No arguments.
→ Response¶
If the deployment is still up to date, the Controller will respond with empty object {}
. Otherwise, an error will be returned, with the explanation.
Error Code | Description |
---|---|
404 | The game version is turned off or there is no such game version |
410 | Current deployment is outdated |
d like to have a few keys with same name, put a new one under different gamespace.