maverick.game.Game

class maverick.game.Game(*, small_blind: int | None = None, big_blind: int | None = None, ante: int | None = None, min_players: int | None = 2, max_players: int | None = None, max_hands: int = 1000, exc_handling_mode: str = 'log', log_events: bool = True, rules: PokerRules | None = None, first_button_position: int | None = None)

Texas Hold’em Poker Game.

Implements a Texas Hold’em poker game using an event-driven state machine. The game manages player actions, betting rounds, dealing, and pot distribution.

Parameters:

• small_blind (int) – Amount for the small blind.

• big_blind (int) – Amount for the big blind.

• ante (int) – Amount for the ante.

• min_players (int) – Minimum number of players to start the game.

• max_players (int) – Maximum number of players allowed at the table.

• max_hands (int) – Maximum number of hands to play before ending the game. Default is 1000.

• exc_handling_mode ({"log", "raise"}) – If “raise”, exceptions in event handlers will propagate. If “log”, they will be logged. This setting only effects event handling, not game logic. If an exception occurs in game logic, it will always raise.

• log_events (bool) – If True, game events will be logged to the console. This only affects logging, not event handling. The purpose of this is allow users to have their own event handlers without excessive logging noise.

• rules (PokerRules | None) – Custom poker rules to use. If None, default Texas Hold’em rules are applied. When provided, other parameters (small_blind, big_blind, ante, min_players, max_players) will override the corresponding fields in the rules.

• first_button_position (int | None) – The seat index of the player who will be the button in the first hand. If None (the default), the button is assigned randomly using a card draw.

__init__(*, small_blind: int | None = None, big_blind: int | None = None, ante: int | None = None, min_players: int | None = 2, max_players: int | None = None, max_hands: int = 1000, exc_handling_mode: str = 'log', log_events: bool = True, rules: PokerRules | None = None, first_button_position: int | None = None)

Methods

__init__(*[, small_blind, big_blind, ante, ...])
add_player(player)	Add a player to the game.
get_current_player()	Return the player whose turn it is.
has_events()	Check if there are pending events in the queue.
remove_player(player[, flush])	Remove a player from the game.
start()	Start the poker game.
step()	Process the next event in the queue.
subscribe(event_type, handler, **kwargs)	Register a handler for a specific game event type.
unsubscribe(token)	Unsubscribe a handler using its token.

Attributes

big_blind	Returns the player currently in the big blind position, or None if no big blind assigned.
button	Returns the player currently on the button, or None if no button assigned.
game_id	use uid instead.
game_uid	Returns the unique identifier for the current game session.
history	Returns the event history.
rules	Returns the poker rules used in this game.
small_blind	Returns the player currently in the small blind position, or None if no small blind assigned.
state	Returns the current game state.
table	Returns the game table.
uid	Alias for game_uid.

property game_uid: str | None

Returns the unique identifier for the current game session.

A new game_uid is generated each time start() is called (i.e. each time the GAME_STARTED event is processed). The value is None before the game has been started.

Returns:

• str | None – A 32-character hexadecimal UUID string, or None if the game has not been started yet.

• .. versionadded:: 0.5.0

property uid: str | None

Alias for game_uid.

property game_id: str | None

use uid instead.

Type:

Deprecated

property rules: PokerRules

Returns the poker rules used in this game.

property state: GameState

Returns the current game state.

property history: list[GameEvent]

Returns the event history.

Returns:

A list of all game events in chronological order.

Return type:

list[GameEvent]

property table: Table

Returns the game table.

Added in version 0.2.0.

property button: PlayerLike | None

Returns the player currently on the button, or None if no button assigned.

Added in version 0.3.0.

property small_blind: PlayerLike | None

Returns the player currently in the small blind position, or None if no small blind assigned.

Added in version 0.3.0.

property big_blind: PlayerLike | None

Returns the player currently in the big blind position, or None if no big blind assigned.

Added in version 0.3.0.

subscribe(event_type: GameEventType, handler: EventHandler, **kwargs) → str

Register a handler for a specific game event type.

Handlers are called synchronously in registration order when the event occurs. Exceptions in handlers are caught, logged, and do not interrupt engine execution.

Parameters:

• event_type (GameEventType) – The type of event to listen for.

• handler (EventHandler) – A callable that accepts a GameEvent and returns None.

unsubscribe(token: str) → None

Unsubscribe a handler using its token.

Parameters:

token (str) – The subscription token returned by the subscribe method.

add_player(player: PlayerLike) → None

Add a player to the game.

Parameters:

player (PlayerLike) – The player to add to the game.

remove_player(player: PlayerLike, flush: bool = True) → None

Remove a player from the game.

Parameters:

• player (PlayerLike) – The player to remove from the game.

• flush (bool) – If True, immediately process the resulting events. If False, the events will be added to the queue but not processed until step() is called. Default is True.

start() → None

Start the poker game.

step() → bool

Process the next event in the queue.

has_events() → bool

Check if there are pending events in the queue.

get_current_player() → PlayerLike | None

Return the player whose turn it is.

Added in version 0.2.0.