API reference

Module game_server_api provides an API for communicating with the server. It allows you to

• start or join a game session
• submit moves
• retrieve the game state
• passively observe another player
• restart a game within the current session
• enable TLS

__init__

GameServerAPI.__init__(server, port, game, session='auto', players=None, name='')

Information needed in order to connect to the server and to start or join a game session is passed to this constructor. Parameter game specifies the game to be started. It corresponds to the name of the game class on the server. To be able to join a specific game session, all participants need to agree on a session token and pass it to the constructor. The token is used to identify the game session. Alternatively, you can have the server automatically assign you to a session by passing 'auto' as the token (this is the default). Refer to function join for more information.

The optional parameter players is required by function join in order to start a new game session with the specified number of players. If the argument is omitted, the join function will only try to join an existing session but never start a new one. The argument is ignored when an existing session can be joined.

The optional parameter name makes it possible for other clients to passively observe your playing by joining a game using the observe function. They will receive the same data calling the state function as you do.

Parameters
server (str): IP or hostname
port (int): port number
game (str): name of the game
session (str): name of the game session (optional), 'auto' for auto-join (default)
players (int): total number of players (optional)
name (str): player name (optional)

Raises
AssertionError for invalid arguments

join

GameServerAPI.join()

Start or join a game session.

This function lets a client join a game session. A new session is started, if necessary. In order to start a new session, the number of players must be passed to the constructor. If the argument is omitted, this function will only try to join an existing session but never start a new one. The argument is ignored when an existing session can be joined.

There are two ways to start or join a game session:

• By providing a shared session token to the constructor. All clients using the same token will join this specific game session. If such a session exists but is already fully occupied by players, it is terminated and a new session is started.
• By passing the string 'auto' as the session token. This causes the server to automatically assign you to an open session. If no session exists that can be joined, a new one is started. Existing sessions are never terminated. This method of starting and joining sessions does not interfere with the above method. To achieve this, the server creates a unique token internally.

The game starts as soon as the required number of clients has joined the game. The function then returns the player ID. The server assigns IDs in the range 0...n-1 to all players that join the game.

Returns
player ID (int)

Raises
GameServerError in case no session could be started or joined

move

GameServerAPI.move(**move)

Submit a move.

This function is used to submit a move to the game server. The move must be passed as keyword arguments. Refer to the documentation of a specific game to find out about the required or available arguments. If it is not your turn to submit a move or if the move is illegal, the server replies with an error message, and an exception containing the message is raised. The message can be any object compatible with JSON. Refer to the documentation of a specific game for more information about error handling.

Parameters
move (keyword arguments): the player's move

Raises
IllegalMove in case of an illegal move
GameServerError in case any other error occurred

state

GameServerAPI.state()

Retrieve the game state.

This function retrieves the game state from the server. The state is returned as a dictionary. Refer to the documentation of a specific game to find out about the structure and content of the dictionary.

Independent of the game, the dictionary always contains these two keys:

• 'current': a list of player IDs, indicating whose player's turn it is
• 'gameover': a boolean value indicating whether the game has ended or is still active

This function will block until the game state changes. Only then will the server respond with the updated state. This is more efficient than polling. To avoid deadlocks, the function never blocks in these situations:

• when the game has just started to allow clients to get the initial state
• after a move was performed to allow clients to get the new state
• when the game was restarted and a client still has to get the previous game's state

Returns
game state (dict)

Raises
GameServerError in case the state could not be retrieved

observe

GameServerAPI.observe()

Observe another player.

This function lets one client observe another client. The name of the player to be observed must be passed to the constructor. You will then receive the same data calling the state function as that player does. This function will return the player ID of the observed player.

This function can only be called, after the specified game session has already been started. The observer mode is not available for auto-join sessions.

Returns
ID of the observed player (int)

Raises
GameServerError in case the session could not be joined as observer

restart

GameServerAPI.restart()

Restart a game.

This function restarts the current game. There is no need to rejoin the session, and all players will keep their IDs. The server ensures that all clients will receive the state of the previous game a last time before receiving the new game's state. This way they will not miss the end/outcome of the previous game.

Raises
GameServerError in case the game could not be restarted

enable_tls

GameServerAPI.enable_tls(cert='')

Enable TLS.

Calling this function enables TLS encryption. By providing a certificate, identity verification of the server is performed in addition to encryption.

The server must have TLS enabled.

Parameters
cert (str): certificate file (optional)

Raises
GameServerError if loading the certificate failed