Are you ready to start coding?

Same as all our competitions so far, we will be handing out large amounts of prize money when the finals are over! Are you ready to claim one of the prizes by creating one of the best Texas Hold 'em bots out there? Getting started is pretty easy if you download one of the starterbots from the list to the right. Everything that your bot has to do to communicate with the server has already been implemented. You only have to change its default behaviour to make it crush its opponents.

If there is no starterbot available in the language you want to code, you can make 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 is now also available on our Github page. Use this to test your bot locally.

Starter bots

##A simple example##
import java.util.Scanner;

public class MyBot {

    private Scanner scan = new Scanner(;

    public void run()
        while(scan.hasNextLine()) {
            String line = scan.nextLine();

            if(line.length() == 0) {

            String[] parts = line.split(" ");

            if( parts.length == 3 && parts[0].equals("Action") ) { // A move is requested
                System.out.println("check 0");
            else { // Game settings, round information and opponent moves are also given
                // Store it or something

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

This is a very simple example of a working bot in Java. It reads the engines output and only does something when a move is requested by the engine: it will do a 'check'. Sometimes this is not an appropriate move, because checks are only allowed when both players bet the same. The engine will then automatically change it to a fold in that case.

Communicating with the game engine

The communication between the poker engine and your bot goes via the standard input and output channels. Every line of output the engine gives to your bot contains exactly 3 words, separated by spaces. This is done to make the parsing easy for you. Lines start with one of the following words:

  • Settings given only at the start of a match and gives general information about the settings of the game.
  • Match indicating information about the current state of the match, such as the pot size or the blind heights.
  • Action this means the engine wants your next move.
  • [botname] information about a certain bot, where [botname] can be either player1 or player2. This includes bot actions, hands and winnings.

Below you find two tables containing all possible communication between the engine and the bot, together with their meaning. Note: if you have played in the Heads up Omaha competition, notice that we have changed all the camelcase formatting to underscores.

Output from engineDescription
Settings time_bank i Maximum time in milliseconds that your bot has in its time bank
Settings time_per_move i Time in milliseconds that is added to your bot's time bank each move
Settings hands_per_level i Number of hands that is played within each blind level
Settings starting_stack i Amount of chips that each bot starts the game with
Settings your_bot b The name of your bot during this match
Match round i The number of the currently played hand, counting starts at 1
Match small_blind i The current size of the small blind
Match big_blind i The current size of the big blind
Match on_button b The name of the bot that currently has the dealer button (gets the small blind)
Match table [c,c,c,...] The cards that are currently on the table
Match max_win_pot i Total amount of chips currently in the pot (plus sidepot)
Match amount_to_call i The amount of chips your bot has to put in to call
Action b t Request for the bot's next action within given timespan
b stack i The amount of chips that the given bot has left in his stack
b post i The given bot pays a blind of the given size
b hand [c,c] The hand that the given bot has
b fold 0 The given bot folds, always followed by the number zero
b check 0 The given bot checks, always followed by the number zero
b call i The given bot calls with the given amount of chips
b raise i The given bot raises with the given amount of chips
b wins i The given bot wins an amount of chips at the end of a hand
Output from botDescription
fold 0Your bot folds. This is also the default action on wrong outputs
check 0Your bot checks. This is also the default action on no response
call 0Your bot calls, automatically with the correct amount
raise i Your bot raises with the given amount of chips

Each "i" can be any positive integer. Each "b" is represents the name of a bot (as far as the engine is concerned) and can be either player1 or player2. "t" represents the time in milliseconds that the bot has to respond to the engine. A "c" represents a card, either in the hand or on the table. This is always two characters: The first represents the card height and can be any number 2-9. T, J, Q, K, A are 10, Jack, Queen, King and Ace respectively. The second character represents the suit and can be d, c, h or s. For Diamonds, Clubs, Hearts and Spades respectively.

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, the engine will change it automatically to a logical alternative. In such cases the engine will print a warning, so you can see what happened.

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

Below you find an example of a played game, you can find this in the output of any of your own games as well. It should make a bit more clear what output is provided to your bot and how to respond.

Settings time_bank 10000
Settings time_per_move 500
Settings hands_per_level 10
Settings starting_stack 2000
Settings your_bot player1

These are the settings of this game. This information is sent at the start of a match only. Your bot is informed about the number of hands per blind level, starting stacks and what name it has during this match. Continuing with the rest of the input/output:

Match round 1
Match small_blind 10
Match big_blind 20
Match on_button player1

This is given at the start of each round. We're in round 1, small blind is 10, big blind is 20 and player1 (our bot) has the dealer button. Continuing.

player1 stack 2000
player2 stack 2000
player1 post 15
player2 post 30
player1 hand [3h,7h]

This is the information about the players at the start of each round. Namely the current stack, amount paid for the blinds and the hand of our bot. Our bot has the button, so it can do the first move:

Match max_win_pot 30
Match amount_to_call 10
Action player1 10000

The first two lines are given each time the engine is about to ask for a response, they give the total amount our bot can win and what it has to put in for a call. Then the engine asks the bot for a move, with a time limit of 10 seconds. This is the first round, so our time bank is still full. Let's say our bot takes 1000ms to respond, the time bank has 9000ms left. Each move we get 500ms extra in the time bank, so next time the engine asks for a move it will say "Action player1 9500". Continuing.

call 0 //output from bot
player1 call 10
player2 check 0

Our bot has done a legal move by calling and the engine outputs it's own move back, plus the move the opponent did. Now we move to the flop.

Match table [7s,Js,Kh]
player2 check 0
Match max_win_pot 40
Match amount_to_call 0
Action player1 9500

We get the flop that is on the table, nice, we have a pair of 7's. After the first move, the player that does not have the dealer button will start, which is our opponent. He checks. Then the engine asks our bot for a move again, it responds:

call 0 //output from bot
player1 check 0

Our bot called, but the opponent did a check, so the engine changes it to a check as well. Now the turn

Match table [7s,Js,Kh,2h]
player2 check 0
Match max_win_pot 40
Match amount_to_call 0
Action player1 98000
raise 30 //output from bot
player1 raise 30
player2 call 30

Still our best hand is a pair of 7's. player2 checks again, but we do a raise. player2 now has to call or fold, but he calls. Next, the river.

Match table [7s,Js,Kh,2h,5h]
player2 check 0
Match max_win_pot 120
Match amount_to_call 0
Action player1 10000
raise 200 //output from bot
player1 raise 200
player2 call 200

The river is on the table and we have a flush! Our bot raises by 200. player2 calls again so we have a showdown:

player1 hand [3h,7h]
player2 hand [Jd,Td]
player1 wins 520

player2 only has a pair of Jacks, so our bot won! On to the next round.