/ 
Poker-Eval-0.12
/ Poker::Game

NAME

Poker::Game - Base class for named poker variants

SYNOPSIS

use Poker::Game::Holdem;
use feature qw(say);

# choose a game
my $game = Poker::Game::Holdem->new( iterations => 1000 );

# deal hole cards
my $hero    = $game->deal_hole(['As', 'Kd']);
my $villain = $game->deal_hole(['7h', '7c']);
# or $game->deal_hole() for random cards;

# calculate equity for each player
$game->equity([ $hero, $villain ]);

# hero has ~45 percent equity 
say $hero->ev;

# villain has ~55 percent equity
say $villain->ev;

# here comes the flop
$game->flop(['Ah', 'Kc', '2d']);
# or $game->flop() for random cards;

# calculate equity again after the flop
$game->equity([ $hero, $villain ]);

# hero now has ~93 percent equity after making two pair
say $hero->ev;

# turn and river
$game->turn('9s'); # deal specific card
$game->river();    # deal random card

# see who won and why
$game->evaluate($hero);
say $game->board_string;    # AsKdAhKc9d
say $hero->name;            # Two Pair
say $hero->score;           # numerical strength
say $hero->best_combo_flat; # show cards in human readable form

# reset board and shuffle deck for the next game
$game->reset;

DESCRIPTION

For a full list of games, eval engines, and scorers, see "AVAILABLE COMPONENTS" in Poker::Eval.

EQUITY

Equity is the estimated share of the pot a hand wins if the remaining board is completed many times at random from the undealt cards.

Each simulation awards 1.0 pot unit in total:

  • Sole winner: that hand receives 1.0

  • N hands tied for best: each receives 1/N

ATTRIBUTES

hole_count

How many hole cards each player is dealt (set by the subclass).

board_size

Number of community cards (0 for draw/stud/Badugi).

iterations

Monte Carlo sample size for equity (default 1000).

max_draw_rounds / draws_left

Draw-game discard rounds allowed / remaining.

pending_discards / pending_draws

Phase flags. Crazy Pineapple sets pending_discards after the flop until each player discards; draw games set pending_draws after discard until draw.

METHODS

deal_hole

my $hand = $game->deal_hole;              # random hole_count cards
my $hand = $game->deal_hole(2);           # random N cards
my $hand = $game->deal_hole(['As','Kd']); # specific cards

Returns a Poker::Hand.

deal_cards

my $cards = $game->deal_cards(['As', 'Kd']);

Remove specific cards from the deck by name. Jokers are Jo1, Jo2, ...

board_string

Community cards as a flat string (e.g. Ah7c2d).

flop / turn / river

$game->flop(['Ah','7c','2d']);  # or random if omitted
$game->turn('9s');
$game->river('3c');

Deal the next community street. turn and river die if discards or draws are still pending (e.g. Crazy Pineapple before the mandatory discard).

can_runout

True when the game uses community cards, the board is incomplete, and no discards/draws are pending.

runout

$game->runout;                    # random remaining board
$game->runout(['9s','3c']);       # specific cards

Deal all remaining community cards. Dies unless can_runout is true.

discard

$game->discard($hand, '7c');
$game->discard($hand, ['7c', '2h']);

Remove one or more hole cards from $hand.

Draw games: sets pending_draws so draw is expected next, and decrements toward max_draw_rounds.

Crazy Pineapple: after the flop each player must discard exactly one hole card (clearing pending_discards) before turn / river are allowed. That path does not use draw.

draw

$game->draw($hand);              # random refill to hole_count
$game->draw($hand, ['As','Kd']); # specific replacements

Replace discarded cards up to hole_count. Decrements draws_left. Used by five-card draw and lowball draw games, not by Crazy Pineapple.

evaluate

$game->evaluate($hand);
my $result = $game->evaluate(['As','Kd']);  # or raw card list

Score the best hand under this game's rules. On a Poker::Hand, sets:

  • score -- numerical strength for this ranking system (higher is better within that system)

  • name -- English label (e.g. Two Pair)

  • best_combo -- cards used

  • low_score, low_name, low_combo -- hi-lo games only, when the hand qualifies for low

equity

$game->equity([ $hand1, $hand2, ... ]);

Monte Carlo equity from the current board state. Sets $hand->ev on each hand (see "EQUITY"). Alias: calc_ev.

reset

Reset board and shuffle a fresh deck

AUTHOR

Nathaniel Graham, <ngraham at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2016-2026 Nathaniel Graham.