Player API

Players are simple web services that need to respond to POST requests. The post always includes an action variable, that specifies the action to be taken by the player. For some actions another game_state variable is also included, and contains a JSON document describing the entire current game state.

If Lean Poker is started through the Lean Poker Live web application, it creates a GitHub repository with a player framework in it. The player frameworks handle the incoming POST requests.

Actions

check

This action is used to check if the player is running. It does not receive anything, and should respond with HTTP 200 OK. The string returned is not used.

Curl example: curl -d 'action=check' localhost

The player frameworks handle this action.

version

This should return a version identifier. It will be displayed on the tournament leader board, so that teams can make sure their code has been correctly deployed. It's worth changing this whenever the players behavior is expected to change. Note that if the player is not available, the version displayed will be Unknown.

The player frameworks should define a constant in the Player class (or similar construct in languages where there is no class) and return the value of that constant.

Curl example: curl -d 'action=version' localhost

bet_request

This action is called, when the player is on turn. A game state document is passed to aid the decision. A single integer should be returned, that represents the amount of chips that should be added to the pot on behalf of the player.

The player frameworks should define a bet_request method in the Player class (or a similar construct) and the method should return zero. When the action is called, it should be delegated to this method. This method should be changed by teams to implement new strategies.

A bet of 0 is treated as a check when the current_buy_in is equal to the current bet of the player, and as a fold otherwise.

To call the player needs to return current_buy_in - players[in_action][bet], that is the largest bet from any of the players minus the bet already made by the current player. Any bet smaller than this amount is treated as a fold.

To raise, the player has to return an amount larger than current_buy_in - players[in_action][bet] + minimum_raise. This is the amount necessary to call plus the smallest valid raise. Smaller bets are either treated as call or fold depending on the amount.

Curl example:

curl -d 'action=bet_request&game_state={
  "players":[
    {
      "name":"Player 1",
      "stack":1000,
      "status":"active",
      "bet":0,
      "hole_cards":[],
      "version":"Version name 1",
      "id":0
    },
    {
      "name":"Player 2",
      "stack":1000,
      "status":"active",
      "bet":0,
      "hole_cards":[],
      "version":"Version name 2",
      "id":1
    }
  ],
  "tournament_id":"550d1d68cd7bd10003000003",
  "game_id":"550da1cb2d909006e90004b1",
  "round":0,
  "bet_index":0,
  "small_blind":10,
  "orbits":0,
  "dealer":0,
  "community_cards":[],
  "current_buy_in":0,
  "pot":0
}' localhost

showdown

This action is called at the end of each round. The game state document is sent, but this time the hole cards of the opponents are also included if those cards were revealed during showdown.

The player frameworks should define a showdown void method in the Player class (or a similar construct). When the action is called, it should be delegated to this method. This method should be changed by teams to implement learning algorithms.

The string returned is not used.

Curl example:

curl -d 'action=showdown&game_state={
  "players":[
    {
      "name":"Player 1",
      "stack":1000,
      "status":"active",
      "bet":0,
      "hole_cards":[],
      "version":"Version name 1",
      "id":0
    },
    {
      "name":"Player 2",
      "stack":1000,
      "status":"active",
      "bet":0,
      "hole_cards":[],
      "version":"Version name 2",
      "id":1
    }
  ],
  "tournament_id":"550d1d68cd7bd10003000003",
  "game_id":"550da1cb2d909006e90004b1",
  "round":0,
  "bet_index":0,
  "small_blind":10,
  "orbits":0,
  "dealer":0,
  "community_cards":[],
  "current_buy_in":0,
  "pot":0
}' localhost

Game state

{
    // Id of the current tournament
    "tournament_id":"550d1d68cd7bd10003000003",     

    // Id of the current sit'n'go game. You can use this to link a
    // sequence of game states together for logging purposes, or to
    // make sure that the same strategy is played for an entire game
    "game_id":"550da1cb2d909006e90004b1",

    // Index of the current round within a sit'n'go
    "round":0,                                      

    // Index of the betting opportunity within a round 
    "bet_index":0,                                  

    // The small blind in the current round. The big blind is twice  
    // the small blind
    "small_blind": 10,                              

    // The amount of the largest current bet from any one player 
    "current_buy_in": 320,                          

    // The size of the pot (sum of the player bets) 
    "pot": 400,                                     

    // Minimum raise amount. To raise you have to return at least: 
    // current_buy_in - players[in_action][bet] + minimum_raise
    "minimum_raise": 240,                           

    // The index of the player on the dealer button in this round 
    // The first player is (dealer+1)%(players.length)
    "dealer": 1,                                    

    // Number of orbits completed. (The number of times the dealer 
    //     button returned to the same player.)
    "orbits": 7,                                    

    // The index of your player, in the players array 
    "in_action": 1,                                 

    // An array of the players. The order stays the same during the
    //     entire tournament
    "players": [                                    
        {
            // Id of the player (same as the index) 
            "id": 0,                                

            // Name specified in the tournament config 
            "name": "Albert",                       

            // Status of the player: 
            //   - active: the player can make bets, and win 
            //     the current pot
            //   - folded: the player folded, and gave up interest in
            //     the current pot. They can return in the next round.
            //   - out: the player lost all chips, and is out of this 
            //     sit'n'go
            "status": "active",                     

            // Version identifier returned by the player 
            "version": "Default random player",     

            // Amount of chips still available for the player. 
            // (Not including the chips the player bet in 
            // this round.)
            "stack": 1010,                          

            // The amount of chips the player put into the pot 
            "bet": 320                              
        },
        {
            // Your own player looks similar, with one extension. 
            "id": 1,                                
            "name": "Bob",
            "status": "active",
            "version": "Default random player",
            "stack": 1590,
            "bet": 80,
            // The cards of the player. This is only visible for 
            // your own player except after showdown, when cards
            // revealed are also included.
            "hole_cards": [                         
                {
                    // Rank of the card. Possible values are 
                    // numbers 2-10 and J,Q,K,A 
                    "rank": "6",                    
                    // Suit of the card. Possible values are: 
                    // clubs,spades,hearts,diamonds 
                    "suit": "hearts"                
                },
                {
                    "rank": "K",
                    "suit": "spades"
                }
            ]
        },
        {
            "id": 2,
            "name": "Chuck",
            "status": "out",
            "version": "Default random player",
            "stack": 0,
            "bet": 0
        }
    ],
    // Finally the array of community cards. 
    "community_cards": [                            
        {
            "rank": "4",
            "suit": "spades"
        },
        {
            "rank": "A",
            "suit": "hearts"
        },
        {
            "rank": "6",
            "suit": "clubs"
        }
    ]
}