Make your own bot

You can do one of two things when you want to participate in any of the competitions on this website. The first thing you can do to join this competition is the easiest one. Download one of the starterbots from the right. All the basic stuff like communication with the engine is already implemented, but making the bot smart is up to you. The other option is to create your own bot from scratch. Look at the Languages page for a list of all available languages to code your bot in.

All communication between your bot and the engine works through the standard input and output channels. In the section "Communicating with the game engine" you can find a detailed explanation regarding the protocol all bots should implement to communicate with the game server.

The engine source code will be made available as soon as the competition is out of beta, so you can test your bot locally. It will be available on our Github page

Starter bots

Java
Python 3By smiley
C#By Trogatog
C++By resty
RustBy Visic

A simple example

import java.util.Scanner;

public class MyBot {

    private Scanner scan = new Scanner(System.in);

    public void run()
    {
        while(scan.hasNextLine()) {
            String line = scan.nextLine();
            if(line.length() == 0) { continue; }
            String[] parts = line.split(" ");

            switch(parts[0]) {
                case "settings":
                    // store game settings
                    break;
                case "update":
                    // store game and player updates
                    break;
                case "action":
                    System.out.println("place_move 6 8");
                    System.out.flush();
                    break;
                default:
                    // error
            }
        }
    }

    public static void main(String[] args) {
        (new MyBot()).run();
    }
}

This is a very simple example of a working bot in Java. It reads the engine's output and only does something when an action is requested by the engine: it will always try to place a stone on point x=6, y=8. Obviously, the engine will disqualify this bot after a while because that because that is not a legal move anymore after a stone was already placed there, but the basics of the bot do work in this example.

Communicating with the game engine

The communication between your bot and the engine goes via the standard input and output channels. Every single line the engine gives is a specific piece of information or a request. The response from your bot should also be just one line. We follow a standardized API. There are three types of lines, in the following format:

  • settings [type] [value] given only at the start of the game. General settings of the game are given here.
  • action [type] [time] indicates a request for an action.
  • update [player] [type] [value] this is an update of the game state. [player] indicates what bot the update is about, but could also be 'game' to indicate a general update.

In the table below you can find all specific commands your bot can expect for this competition. The format for an action response is also given.

Output from engineDescription
settings timebank t Maximum time in milliseconds that your bot can have in its time bank
settings time_per_move t Time in milliseconds that is added to your bot's time bank each move
settings player_names [b,...] A list of all player names in this match, including your bot's name
settings your_bot b The name of your bot for this match
settings your_botid i The number used in a field update as your bot's chips
settings field_width i The width, i.e. amount of columns, of the field
settings field_height i The height, i.e. amount of rows, of the field
settings max_rounds i The maximum number of rounds the game can last
update game round i The number of the current round
update game move i The amount of moves done in the game (including the current move)
update game field [s,...]The complete playing field in the current game state
update b points iThe amount of points in the game the given player currently has
update b last_move iThe last move given player has performed (given player will be opponent)
action move tRequest for a move
Output from botDescription
place_move i iThe move your bot wants to make
passOutput this to pass the turn

Each "i" can be any integer. Each "b" is represents the name of a bot (as far as the engine is concerned) and can be either player1 or player2 for this competition. "t" represents a time in milliseconds. An "s" is a point on the board. This can be a 0 for empty, -1 for illegal (Ko rule), or 1 or 2, for one of the players (given by your_botid). The updates of the playing field are given from the top-left square to the bottom-right square, from left to right, top to bottom. Finally, your bot's output should always start with place_move, followed by two numbers x (column index of whole field) and y (row index of whole field) coordinates of the square, respectively. 0 0 is the top-left square, 18 18 is the bottom right square. pass can be outputted to pass the turn; nothing will happen on the board.

The engine will always try to perform the action given by the output of your bot. In case the action is not valid in the current game situation, or when the output can't be parsed at all, the engine will output a warning and ask for an action again. If your bot fails to give an acceptable again, it automatically loses the game.

Input and output between the bot and the engine go via the standard input and output channels, but you can use the error output channel to print stuff in the error dump of your game. This will not be read by the engine and can be used for debugging.

By example

To make it a bit more clear what the inputs and outputs look like we're providing an example below. You can find this in the dump of any of your own games as well.

settings timebank 10000
settings time_per_move 500
settings player_names player1,player2
settings your_bot player1
settings your_botid 1
settings field_width 19
settings field_height 19

These are the settings of the game. This information is sent at the start of a match only. Your bot now knows the timebank settings, the player names, it's own id number, and the field dimensions. Continuing with the rest of the input/output:

update game round 1
update game move 1
update player1 points 0
update player2 points 0
update game field 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
action move 10000

Your bot gets the round number, the move number, and what the field looks like. As expected at the start of the game, the field is currently empty. These updates are given each time an action is requested. In the last line the engine requests your bot's move

place_move 1 1 // places a stone on point x=1, y=1

This is your bot's move. A blue stone (your bot is player1), will be placed on point x=1, y=1, which is near the top-left corner of the board. Now it's your opponent's turn to move, that bot will receive its own updates. After that, your next round follows:

update game round 2
update game move 3
update game field 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

Here we see the the round and move updates and another field update. If you look closely, you can see the opponent has put its stone to the right of your stone, namely on point x=1, y=2. Nothing interesting has happened so far in the game, because there are only two stones on the board. After the update shown above, another action would be requested by the engine. Then your opponent will do a move and your bot gets a field update again, and so on. Now you should know everything you need to start coding your own bot!