Poker-Eval

VERSION 0.10

Deal, score, and estimate equity for many poker variants through a named
Poker::Game API (Hold'em, Omaha, draw, stud, Badugi, and more).


SYNOPSIS

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

    my $game = Poker::Game::Holdem->new;

    # Evaluate a 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;              # Two Pair
    say $hero->score;             # numerical strength
    say $hero->best_combo_flat;   # e.g. AsAhKdKc9s

    # Estimate preflop equity (Monte Carlo)
    $game->reset;
    $game->iterations(2000);
    my $aa = $game->deal_hole(['As', 'Ad']);
    my $kk = $game->deal_hole(['Ks', 'Kd']);
    $game->equity([ $aa, $kk ]);
    say "Hero    AA: ", $aa->ev, "%";
    say "Villain KK: ", $kk->ev, "%";
    # Typical result: AA ~82%, KK ~18%


CARD NAMES

    Rank:  2 3 4 5 6 7 8 9 T J Q K A
    Suit:  c d h s     (e.g. As, Td, 2c)
    Jokers: Jo1, Jo2   (when using a joker deck)


WHAT IS 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 total:
  - sole winner receives 1.0
  - N tied winners each receive 1/N

Results are a percentage of simulations, rounded to the nearest integer
(ev values across hands sum to about 100). Known hole cards and any
fixed board cards are dead and never re-dealt.

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


CORE METHODS (Poker::Game)

    deal_hole       Random or specific hole cards; returns a Poker::Hand
    deal_cards      Pull specific cards from the deck by name (e.g. 'As')
    flop/turn/river Community board streets (Hold'em-style games)
    runout          Deal all remaining board cards when legal
    evaluate        Best hand under this game's rules; sets score, name
    equity          Monte Carlo win share; sets hand->ev (alias: calc_ev)
    discard / draw  Draw-game discard and refill
                    (Crazy Pineapple: discard one hole card after the flop)
    reset           New shuffled deck; clear board and draw state

Stud games add street helpers (see Poker::Game::Stud):
    third_street .. seventh_street, deal_to

After evaluate, read the result from the hand:

    $hand->name             # e.g. "Two Pair"
    $hand->score            # numerical score for this ranking system
                            # (higher is better within that system)
    $hand->best_combo_flat  # cards used in the best five
    $hand->low_name         # hi-lo games only, if low qualifies
    $hand->low_score        # hi-lo games only, if low qualifies

See: perldoc Poker::Game


NAMED GAMES

    Community
      Holdem              Texas Hold'em (high)
      HoldemJokersWild    Hold'em with two jokers wild
      Pineapple           Three hole cards
      CrazyPineapple      Three hole; discard one after the flop
      Omaha / OmahaHiLo   Four hole; exactly two hole + three board
      Omaha5 / Omaha5HiLo Five-card Omaha
      Courcheval          Five-card Omaha; board dealt 1+2+1+1
      CourchevalHiLo      Courchevel high/low

    Draw
      FiveCardDraw                Highball single draw
      FiveCardDrawDeucesWild      Deuces wild
      FiveCardDrawJokersWild      Two jokers wild
      Low27SingleDraw/TripleDraw  2-7 lowball
      LowA5SingleDraw/TripleDraw  A-5 lowball

    Stud
      SevenCardStud / SevenCardStudHiLo
      Razz                        Seven-card stud A-5 low

    Badugi family
      Badugi                      Four cards, triple draw
      Badacey                     Badugi + A-5 low split
      Badeucy                     Badugi (aces high) + 2-7 low split

Advanced users can still compose Poker::Eval::* rules with
Poker::Score::* ranking systems directly.

Only Poker::Eval defines $VERSION for the distribution so CPAN indexes
a single package.

Requires: Moo, Algorithm::Combinatorics, Tie::IxHash, List::Util, Storable


INSTALLATION

    perl Makefile.PL
    make
    make test
    make install


CHANGE LOG

See the Changes file in the distribution.


SUPPORT AND DOCUMENTATION

    perldoc Poker::Eval
    perldoc Poker::Game
    perldoc Poker::Game::Holdem


LICENSE AND COPYRIGHT

Copyright (C) 2016-2026 Nathaniel Graham

This program is free software; you can redistribute it and/or modify it
under the terms of the Artistic License (2.0).