Implementing clients

This page demonstrates the usage of the API functions. See the API reference for more detailed information.

Starting and joining a game

To connect to the server and join a game session, you have to provide at least the following information to the constructor of the API class:

from game_server_api import GameServerAPI, GameServerError, IllegalMove

game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe')

You can then try to join a game session:

my_id = game.join()

The function blocks until enough players have joined the session. On success, the player ID is returned.

If no game session exists that can be joined, a GameServerError exception will be raised. This happens when all sessions are fully occupied or when no session exists at all. A new and empty session will not be created.

To start a new session, the number of players must be passed to the constructor.

game = GameServerAPI(server='127.0.0.1', port=4711, game='TicTacToe', players=2)

Now, calling join() will first try to join an existing session. If no session can be joined, a new one will be started.

If you want to play against your peers, you can agree on a session token:

game = GameServerAPI(server='127.0.0.1', port=4711,
                     game='TicTacToe', session='mygame',
                     players=2)

Every client using this token, will join this specific session. The number of players is still optional for joining a session, but required to start a new one.

If a session token is used and join() is called during a session, the current session will be terminated and a new one created. When no token is used (auto-join), sessions are never terminated calling join(). Instead, a new session is started.

Submitting moves

Function move() expects keyword arguments (**kwargs). Any number of keyword arguments can be passed. Refer to the documentation of a specific game to learn about the required arguments.

In the below example, an integer is passed as the value to the key position. This is expected by the tic-tac-toe implementation.

try:
    game.move(position=7)
except IllegalMove as e:
    print(e)

If the move is illegal, an IllegalMove exception is raised. This will happen if it is not the player's turn to perform a move or if the move itself is not valid.

Retrieving the state

The state is retrieved with function state(). It returns a dictionary:

state = game.state()

This function will block until the game state actually changes. Only then will the server respond with the updated state. To avoid deadlocks, the function never blocks in certain situations. This way, the game state is always available when needed.

The dictionary will always at least contain these two keys:

game_status = state['gameover']
current_player = state['current']

• '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

Other key-value-pairs depend on the specific game.

Example

This is a simplified example using the API functions described above. The example shows a typical game loop.

from game_server_api import GameServerAPI, IllegalMove

game = GameServerAPI(server='127.0.0.1', port=4711,
                     game='TicTacToe', session='mygame', players=2)

my_id = game.join()
state = game.state()

while not state['gameover']: # game loop
    # print game board here

    if my_id in state['current']: # my turn
        pos = None # read user input here

        try:
            game.move(position=pos)
        except IllegalMove as e:
            # something went wrong
    else:
        # opponent's turn

    state = game.state()

# end of game

Observing a player

To observe another player, both the observing and the observed players must pass the same name to the constructor:

game = GameServerAPI(..., name='alice')

The observed player calls the join function as usual, whereas the observer has to call observe():

observed_id = game.observe()

The observed player's ID is returned. This function can only be called, after the specified game session has already been started. An observer cannot perform moves, and the observer mode is not available for auto-join sessions.

Restarting games

Games can be restarted by calling function restart(). 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.

Enabling TLS

TLS can be enforced by the server. If this is the case, all clients must enable TLS as well by calling function enable_tls(). Refer to the API reference for more information.