API

TexasHoldem

A no-limit Texas Holdem simulator.

Terminology

• game a single "game", where players are dealt hands, winner(s) are declared once.
• round a point or process in the game, including :preflop, :flop, :turn, :river.
• round the process of each player deciding which actions to take, until no further actions are taking.

move_buttons!(table::Table)

Move the dealer, small blind, big blind, and first-to-act buttons to the next set of players.

This is an internal method.

play!(game::Game[, ::Val{true|false}])

Play a game. Users can take a game at an instance and continue that game, by calling play! with Val(false).

tournament!(game::Game)

Play until a single player remains!

Chips(n, frac)

A stack of chips struct. This type is backed by Ints and performs exact arithmetic operations by using Rational numbers to track remainders (fractions of a chip). frac is always internally stored as less than 1.

Players can only bet/call with whole chips (n), and are not allowed to bet/call with a fraction of a chip.

We track the fractions of chips so that we can assert exact money conservation on the table until a player busts, at which point, that money is lost.

AbstractStrategy

An abstract strategy type, which users can subtype when passing to players.

Human

A human (terminal input) strategy. Use this strategy if you want to play "live" games, and not for simulating games.

Bot5050

Bot5050 is a stochastic strategy that chooses all of its actions based on a coin flip.

This bot is used for quick-start game configurations for users.

Player

Contains the poker player information:

• strategy
• cards
• bank roll
• pot investment

TODO: some of these fields should be removed, since they're only needed for flow control logic.

bank_roll(::Player)

The player's instantaneous bank roll.

We access the Int in Chips as the fractional chips are only handled by the TransactionManager.

bank_roll_chips(::Player)

The player's instantaneous bank roll in Chips (includes fractional chips).

round_bank_roll(::Player)

The player's bank roll at the beginning of the round

We access the Int in Chips as the fractional chips are only handled by the TransactionManager.

Action

An action type, to be returned by get_action during each players turn to act. This is an internal type, but documented for user understanding.

Users are expected to return an action from get_action by calling one of Action's convenience methods:

• Fold
• Check
• Call
• Raise
• AllIn

Options names ((options::Options).name) are Symbols that can be only one of:

• :NoOptions
• :CheckRaiseFold
• :CallRaiseFold
• :CallAllInFold
• :CallFold

Check()

The check action, to be returned from get_action, when a player wants to check.

Fold()

The fold action, to be returned from get_action, when a player wants to fold.

Call(game::Game)

The call action, should be returned from get_action. when a player wants to call amount amt.

Use call_amount to query how much is needed to call.

call_amount(table::Table, player::Player)

Return the amount to call inside get_action.

Raise(game::Game, amt::Int)

The raise action, should be returned from get_action. when a player wants to raise to amount amt.

Use valid_total_bet_range to query the valid range that they are allowed to raise.

When a player returns Raise(5), this means that they want to raise 5 above the current total bet.

RaiseTo(game::Game, total_bet::Int)

The raise-to action, should be returned from get_action. when a player wants to raise the current total bet amount to total_bet.

Use valid_total_bet_range to query the valid range that they are allowed to raise.

When a player returns RaiseTo(game, 5), this means that they want to raise the current total bet to 5.

AllIn(game::Game)

The all-in action, should be returned from get_action. when a player wants to raise all-in.

action = AllIn(game) will contain the amount to go all-in.

Users may call this via AllIn(game).

See valid_total_bet_range for querying the valid range that they are allowed to raise.

valid_total_bet_range(table::Table, player::Player)

A UnitRange{Int} of valid raises. Note that sometimes the range's starting and ending values are the same when, for example, all-in is the only available option.

get_action(game::Game, player::Player, options::Options)

Returns a valid action (see Action), given the allowable options. TexasHoldem calls get_action for each player on the table during each round. This function is entirely where the strategy logic resides.

Users may overload this method to develop their own poker bots. The options type is of type Options and has one of the following names

• options.name == :CheckRaiseFold
• options.name == :CallRaiseFold
• options.name == :CallAllInFold
• options.name == :CallFold

total_bet(game::Game)
total_bet(table::Table)

The total bet.

is_valid_action(game, a::Action, options::Options)

Returns a Bool indicating that the given action is valid given the options

validate_action(game::Game, action::Action, options::Options)

This method will assert that the given action is valid under the given options.

round_contribution

The contribution for the round

Options

An options type, returned by get_options. Users can use this to determine which action to give back to play.

Helper functions to return allowable options include:

• NoOptions
• CheckRaiseFold
• CallRaiseFold
• CallAllInFold
• CallFold

Actions names ((action::Action).name) are Symbols that can be only one of:

• :Fold
• :Check
• :Call
• :Raise
• :AllIn

NoOptions

The option when a player has no options (e.g., they are all-in).

CheckRaiseFold

The option when a player is only able to check, raise, or fold.

CallRaiseFold

The option when a player is only able to call, raise, or fold.

CallAllInFold

The option when a player is only able to call, raise all-in, or fold.

CallFold

The option when a player is only able to call or fold.

get_options(game[, current_player])
get_options(game, player)

Retuns the Options available to player player for the given game (state) game.

recreate_game(game, player)

Creates an exact (deep)copy of the input game, and then re-samples the unobserved cards (i.e., the opponent cards and unobserved table cards).

This is useful for repeatedly sampling a specific scenario so that we can compute the expected value of a particular action.

TODO: we could make a mutating, in-place version of this to reduce allocations.