/ 
Poker-Eval-0.10
/ Poker::Game

NAME

Poker::Game - Base class for named poker variants

SYNOPSIS

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

my $game = Poker::Game::Holdem->new( iterations => 2000 );

# Made hand on a full board
my $hero = $game->deal_hole(['As', 'Kd']);
$game->flop(['Ah', '7c', '2d']);
$game->turn('9s');
$game->river('3c');
$game->evaluate($hero);
say $hero->name;               # e.g. Two Pair
say $hero->score;              # numerical strength
say $hero->best_combo_flat;

# Preflop equity
$game->reset;
my $aa = $game->deal_hole(['As', 'Ad']);
my $kk = $game->deal_hole(['Ks', 'Kd']);
$game->equity([ $aa, $kk ]);
say "AA: ", $aa->ev, "%";     # integer percent, ~82
say "KK: ", $kk->ev, "%";

DESCRIPTION

Poker::Game is the product-facing layer over Poker::Eval and Poker::Score. Concrete subclasses (Poker::Game::Holdem, Poker::Game::Omaha, ...) set hole/board counts and wire the correct eval and scoring engines.

Prefer a named subclass over constructing Poker::Game directly.

Card names use rank 2..9TJQKA plus suit c d h s (e.g. As, Td). Jokers are Jo1, Jo2 when the dealer was built with jokers.

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

$hand->ev is that share as a rounded integer percentage of simulations (so the ev values across the hands in a call sum to about 100). Sample size is controlled by iterations (default 1000).

Known hole cards and any fixed board cards are already removed from the dealer's deck; each simulation clones and shuffles that residual pack.

$game->iterations(5000);
$game->equity([ $hero, $villain ]);

calc_ev is a backward-compatible alias for equity.

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

Shuffle a fresh deck; clear board and draw/discard state.

STUD GAMES

Seven-card stud variants extend Poker::Game::Stud, which adds third_street, fourth_street, fifth_street, sixth_street, seventh_street (alias river), and deal_to. See Poker::Game::Stud, Poker::Game::SevenCardStud, Poker::Game::Razz.

SEE ALSO

Poker::Game::Holdem, Poker::Game::Stud, Poker::Eval, Poker::Score, Poker::Hand

AUTHOR

Nathaniel Graham, <ngraham at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2016-2026 Nathaniel Graham.