Torusgo Network Protocol v1.0 - lukas-schneider/torusgo GitHub Wiki

This protocol assumes a socket.io implementation, but may be implemented on any TCP/IP like technology. A special requirement is an ack feature similar to socket.io.

A session starts after the connection is established. The server accepts any incoming connections without authentication.

A session ends when either client or server terminate the connection, or when the connection times out. After that, no information concerning the client is persisted on the server. If the same client reconnects, or establishes multiple connections, the server does not identify the two connections as the same client.

Server and client keep track of the session's state. Depending on the state, different actions are or aren't available.

• Idle: The client is not observing or playing in any game. Available actions are watch and create.
• Observing (w.r.t. a game instance): The client is observing, i.e. getting updates about a game, but not currently a player in the game. Available actions are watch, join, leave and create.
• Playing (w.r.t. a game instance and role): The client is currently playing in a game as white or black. Available actions are watch, leave and create, as well as move and resign.

On disconnect, the server removes the client from the game it is currently playing in, if any.

An event consists of a name and a payload. The name is a string, while the payload is a serialized JSON Object. For Events with a return type (=>) specified, the sender expects a response from the receiver. Instead of a return value, the receiver may always respond with an error object (see Error section).

<event_name> <payload_type> => <response_type>

• Create Game (all states)

create {size: {x: number, y: number}, komi: number, handicap: number} => {id: string}

The client requests a game instance to be created with the given parameters. The server returns the id of the created game. The session state remains unchanged, it is up to the client to watch/join the new game.

• Watch Game (all states)

watch {gameId: string} => GameState

The client requests to watch the specified game. If the game exists, the server returns the game state (see Game State section). The session state is set to Observing, and the client will receive moves and updates (see Server Events section). If the client was previously observing or playing in another game, it leaves this game (see Leave Game event).

• Join Game (Observing or Playing)

join {role: 1 | 2} => null

The client requests to join the currently observed game as black (1) or white (2). Joining is only possible if the requested role is not taken. If the client is already playing, he may still switch sides.

• Leave Game (all states)

leave null => null

The client requests to leave the current game. The server removes the client as player from the current game and stops sending moves and updates. The session state is set to Idle (if already in Idle, this event does nothing but is still allowed).

• Set Name (all states)

set_name {name: string} => null

The client requests to change it's chosen name. The name, if present, is how the client appears to other players. Name constraints are: between 1 and 32 characters out of [0-9a-zA-Z\s] (leading and trailing whitespaces are trimmed)

• Make Move (Playing)

move {type: 'Move',  x: number, y: number} | {type: 'Pass'} => null

The client makes a move in the current game. If legal, the server applies the move to the current game and sends the move as a server event to all observing players.

• Resign (Playing)

resign null => null

The client resigns. The game enters a final state and no more moves can be made.