git.haldean.org grandmaster / master PROTOCOL
master

Tree @master (Download .tar.gz)

PROTOCOL @masterraw · history · blame

------------------------------------------------------------------
The gm client-server protocol
------------------------------------------------------------------

The gm protocol is used to update and query the state of a
grandmaster server by a grandmaster client. It is a stateless,
unencrypted protocol, where each session is comprised of a single
length-denoted JSON message sent from the client to the server,
with a single length-denoted JSON message sent from the server to
the client in reply. Servers and clients may choose what port to
operate on, but the default is port 7100.


------------------------------------------------------------------
Message format

Messages contain a 4-byte message header that contains the length
of the following message string as a network-order signed integer,
followed by the string itself.  Note that the size does not
include the size of the 4-byte header.

       +----------------------------------------------+
       |  msg_size  |            message              |
       |  4 bytes   |         msg_size bytes          |
       +----------------------------------------------+

------------------------------------------------------------------
Message kinds

All messages are given meaning by the contents of the JSON object
inside the message. The "kind" of message (analogous to a "route"
in a RESTful API) are all given as the "kind" field on the root
JSON object in the request.

    --------------------------------------------------------------
    kind = "new_game"

    To start a game, send a request with kind set to "new_game".
    The full structure of the request is:

        {
            "kind": "new_game",
            "player_white": player ID (long int),
            "player_black": player ID (long int),
        }

    The response structure is:

        {
            "game_id": game ID (long int),
            "state": game state (see below),
            "error": null,
        }

    The error field will be set to a string description of what
    went wrong on error.

    --------------------------------------------------------------
    kind = "game_from_pgn"

    To start a game and initialize it to the state of a game after
    a series of moves, send a request with kind set to
    "game_from_pgn". The moves are encoded in Portable Game
    Notation. The full structure of the request is:

        {
            "kind": "new_game",
            "player_white": player ID (long int),
            "player_black": player ID (long int),
            "pgn": PGN data (string)
        }

    The response structure is:

        {
            "game_id": game ID (long int),
            "state": game state (see below),
            "error": null,
        }

    The error field will be set to a string description of what
    went wrong on error.

    --------------------------------------------------------------
    kind = "move"

    To make a move in a game, send a request with kind set to
    "move". The full structure of the request is:

        {
            "kind": "move",
            "player": player ID (long int),
            "game_id": game ID (long int),
            "move": algebraic notation (string),
        }

    The response structure for a successful move is:

        {
            "state": game state (see below),
            "error": null,
        }

    The response structure for an invalid move is:

        {
            "state": null,
            "error": description of error (string),
        }

    --------------------------------------------------------------
    kind = "end_game"

    To voluntarily end a game, send a request with kind set to
    "end_game". The full structure of the request is:

        {
            "kind": "end_game",
            "player": player ID (long int),
            "game_id": game ID (long int),
            "termination": termination type (string),
        }

    Valid termination strings are a subset of the termination
    types described in the game state section below. The valid
    voluntary terminations are:

        "taken_draw_white"
        "taken_draw_black"
        "resignation_white"
        "resignation_black"

    Note that "taken_draw_white" and "taken_draw_black" are only
    valid if the game is in a state in which there are draws
    available, i.e., if the "draws" constant in the game state is
    not zero.

    The response structure for a successful end-game is:

        {
            "state": game state (see below),
            "error": null,
        }

    The response structure for an invalid end-game is:

        {
            "state": null,
            "error": description of error (string),
        }

------------------------------------------------------------------
Game state

Game states are stored as a JSON document with the following
structure:

    {
        "board": [
            8 arrays of length 8, encoding the board, where each
            piece is either "undefined" (for an empty square) or a
            pair of characters, where the first character is the
            color of the piece ("w" or "b") and the second is the
            piece code ("p", "R", "N", "B", "Q" and "K").
        ]
        "available_castles":
            castles (unsigned int) is a bitset containing zero or
            more of the following bits:
                0x01: white kingside is available
                0x02: white queenside is available
                0x04: black kingside is available
                0x08: black queenside is available
        "passant_file":
            the file (encoded as an int, where "a" = 0, "b" = 1,
            etc) in which a pawn just advanced 2 squares, or -1 if
            no pawn can be captured en passant.
        "access_map": [
            8 arrays of length 8, where each element is itself an
            array. The elements in the array are locations which
            have access to that square, where locations are
            encoded as (rank, file) pairs and the rank and file
            are both zero-indexed integers.
        ]
        "ply_index":
            the number of plys that have been played in the game
            so far.
        "pgn": pgn data for the game so far
        "fen": the state of the game in Forsythe-Edwards notation
        "draws":
            draws (unsigned int) is a bitset containing zero or
            more of the following bits:
                0x01: a draw under the 50-move rule is available
                0x02: a draw under threefold repetion is available
        "termination":
            termination (unsigned int) is one of the following:
                "available_move":
                    there is an available move for the player to
                    play
                "victory_white":
                    white wins, black is in checkmate
                "victory_black":
                    black wins, white is in checkmate
                "stalemate":
                    a stalemate has been reached
                "taken_draw_white":
                    white has chosen a draw by the 50 move rule or
                    threefold repetition
                "taken_draw_black":
                    black has chosen a draw by the 50 move rule or
                    threefold repetition
                "resignation_white":
                    white has resigned, black wins by default
                "resignation_black":
                    black has resigned, white wins by default
        "in_check": boolean, true if player to move is in check
    }