About

Game API is a simple wrapper for the famous game Go and Chess. It provides a basic room manager as host of the games and sits on the websocket protocol as communication interface.

The purpose of this api is learning how to create a good Game-AI and how to beat your enemies ass. If you want to see your ai play or want to play against the ai, try the basic go interface here.

Table of Content

• Getting Started
  • Websocket
  • Format
  • Rules
• Workflow
• Methods
  • init
  • error
  • auth-guest
  • auth-logout
  • room-all
  • room-add
  • room-join
  • room-leave
  • room-update
  • room-command
  • role-change
  • game-move
• Room Manager
  • User
  • Room
  • Roles
• Go
  • Move
  • Commands
  • State
  • Piece
  • Colors
  • Game States
• Chess
  • Move
  • State
  • Piece
  • Colors
  • Game States
  • Piece Types
• Version Notes
  • Version 1.1

Getting Started

{
    'method': Type of method
    'data': Data from request/response
}                        

Workflow

Methods

{
    'method': 'init',
    'data': {
        'version': version
    }
}                        

{
    'method': 'error',
    'data': {
        'error': error
    }
}                        

{
    'method': 'auth-guest',
    'data': {
        'username': username
    }
}                        

{
    'method': 'auth-guest',
    'data': {
        'username': username,
        'role': role
    }
}                        

{
    'method': 'auth-logout',
    'data': {}
}                        

{
    'method': 'auth-logout'
}                        

{
    'method': 'room-all',
    'data': {}
}                        

{
    'method': 'room-all',
    'data': {
        'rooms': [
            {
                //room
            },
            ...
        ]
    }
}                        

{
    'method': 'room-add',
    'data': {
        'name': name,
        'password': password, //can be an empty string
        'game': game //name of the game (see games below)
    }
}                        

{
    'method': 'room-add',
    'data': {
        //room
    }
}                        

{
    'method': 'room-join',
    'data': {
        'room': room-name,
        'password': password, //can be an empty string
    }
}                        

{
    'method': 'room-join',
    'data': {
        //room
    }
}                        

{
    'method': 'room-leave',
    'data': {}
}                        

{
    'method': 'room-leave',
    'data': {
        //see room-all response
    }
}                        

{
    'method': 'room-update',
    'data': {
        //room
    }
}                        

{
    'method': 'room-command',
    'data': {
        'command': command //room command
    }
}                        

{
    'method': 'role-change',
    'data': {
        'role': role-id
    }
}                        

{
    'method': 'role-change',
    'data': {
        //user
    }
}                        

{
    'method': 'game-move',
    'data': {
        'move': move //see valid moves in the game(s) below
    }
}                        

{
    'method': 'game-move'
}                        

Room Manager

The room manager provides a wrapper for basic interaction and consist of a User Model, Room Model and manages the Games.

User

{
    'name': username,
    'ready': true/false, //true if player is ready
    'role': role //as string
}               

Room

{
    'name': room-name,
    'password': true/false //true if password length > 0
    'deadline': {
        'date': date, //date when deadline will be reached
        'duration': duration //(in seconds) timer duration
    },
    'players_ready': true/false, //true if every player is ready
    'game': game //current game state
    'users': [...] //list of users in room
}               

Roles
[ENUM] = [role-id] = [role as string]

• PLAYER_WHITE = 1 = "white"
• PLAYER_BLACK = 2 = "black"
• PLAYER_SPECTATOR = 3 = "spectator"

Room Commands

• CMD_READY = "ready" (set player ready)
• CMD_SET_DEADLINE_DUR = "set-deadline-dur [number]" (change deadline duration)
• CMD_SURRENDER = "surrender" (surrender game)
• CMD_RESTART = "restart" (restart game)

Go

Rules and gameplay are explained in this article. Every interaction will be send over game-move

Move

Possible Commands

• pass (no move)

State

{
    'name': 'go-[width]x[height]',
    'count': turn_count,
    'turn': turn, //color of player as number
    'width': width,
    'height': height,
    'last_move': last_move, //last game-move
    'pieces': [
        {...}, //go-piece
    ],
    'state': {
        'game_state': state, //state of game
        'black': {
            'pass': true/false, //did the player pass
            'captured': captured, //amount of captured pieces
            'score': score //amount of points (will be calculated after the game)
        },
        'white': {
            'pass': true/false, //did the player pass
            'captured': captured, //amount of captured pieces
            'score': score //amount of points (will be calculated after the game)
        }
    }
}               

Go-Piece

{
    'color': color //number,
    'x': x, //0-based
    'y': y //0-based
}               

Colors

• COLOR_EMPTY = -1
• COLOR_WHITE = 0
• COLOR_BLACK = 1

Game States

• STATE_OK = 1
• STATE_ERROR = 0
• STATE_WHITE_WON = 20
• STATE_BLACK_WON = 21
• STATE_JIGO = 3

Chess

Rules and gameplay are explained in this article. Every interaction will be send over game-move

Move

• XY-XY   From-To, X=a-h, Y=1-8
• XY-XY F   Swap Pawn F=(r-rook, b-bishop, k-knight, q-queen)

State

{
    'name': 'chess',
    'count': turn_count,
    'turn': turn, //color of player as number
    'width': width,
    'height': height,
    'last_move': last_move, //last game-move
    'pieces': [
        {...}, //chess-piece
    ],
    'state': {
        'game_state': state, //state of game
        'black': state, //state of black
        'white': state //state of white
    }
}               

Chess-Piece

{
    'color': color //number,
    'x': x, //0-based
    'y': y, //0-based
    'type': type, //piece type
    'out': true/false, //true if piece has been captured
    'move_count': count //amount of move operations on this piece
}               

Colors

• COLOR_WHITE = 0
• COLOR_BLACK = 1

Game States

• STATE_OK = 1
• STATE_WHITE_WON = 4
• STATE_BLACK_WON = 3
• STATE_WHITE_WON_STALE = 6
• STATE_BLACK_WON_STALE = 5
• STATE_REMIS = 2

Player States

• PLAYER_OK = 1
• PLAYER_CHECK = 0

Piece Types

• PAWN = 1
• ROOK = 2
• BISHOP = 3
• KNIGHT = 4
• QUEEN = 5
• KING = 6

Version Notes

Version 1.1

• Game: Chess
• Room Commands
• Deadline (Timer)
• Room Commands will replace commands over moves