Skip to main content

Crate ducy_play

Crate ducy_play 

Source
Expand description

Play out poker hands on top of ducy: antes and blinds, betting rounds, side pots and the showdown.

Supports Texas Hold’em and Omaha (4, 5 or 6 hole cards), each with no-limit or pot-limit betting.

use ducy_play::{Action, Deal, Hand, TableRules};

let rules = TableRules::no_limit_holdem(1, 2);
let deal = Deal::random(rules.variant, 3, Some(42)).unwrap();
let mut hand = Hand::new(rules, &[200, 200, 200], 0, deal).unwrap();

// Everyone calls or checks to the river.
while let Some(legal) = hand.legal_actions() {
    let action = if legal.can_check { Action::Check } else { Action::Call };
    hand.act(action).unwrap();
}
let result = hand.result().unwrap();
assert_eq!(result.final_stacks.iter().sum::<u64>(), 600);

§From one hand to a tournament

  • Hand: one hand, from the blinds to the payout, with its Event history and each player’s LegalActions.
  • Table: seats over many hands: the button moves, people sit out and come back (posting missed blinds or waiting for the big blind), and bots play their seats (Table::advance).
  • Hosting a table for remote players (commands in, private views out, turn clocks, chip requests) is the ducy-host crate’s. A table or tournament can be saved mid-hand and restored (snapshot).
  • Tournament: several tables with blind Levels, eliminations, balancing and hand-for-hand play on the bubble.
  • Bot: a seat played by code, given only what that seat may see (play_hand). Ready-made bots are the ducy-bots crate’s.

§Features

  • serde (default): Serialize/Deserialize for rules, actions, events, views and snapshots (JSON for external bots and clients).
  • fair-deal (default): provably fair commit–reveal deals (fair_deal, Deal::from_seed, Table::new_hand_from_seed), with SHA-256 from sha2.

A seed makes deals reproducible. Without one (Deal::random with None, or Table::with_secure_deals) every deal comes from fresh system randomness: use that whenever people play each other.

Re-exports§

pub use snapshot::HandSnapshot;
pub use snapshot::SNAPSHOT_VERSION;
pub use snapshot::SeatSnapshot;
pub use snapshot::TOURNAMENT_SNAPSHOT_VERSION;
pub use snapshot::TableSnapshot;
pub use snapshot::TournamentSnapshot;

Modules§

fair_deal
Provably fair deals with a commit–reveal seed (#141), an interim step before the full trustless shuffle (#134).
hands
What a table shows about the hand in play, from what a viewer sees of it (a TableView’s seats and events), for pages that draw the table:
replay
Replaying a finished hand one event at a time: the board, the pot and every seat’s stack and bet after each event, from the hand’s event list and each seat’s stack when it started. The chip accounting follows Hand’s, so a replay can’t drift from it: every frame’s stacks, bets and pot add up to the starting stacks.
snapshot
Saving a table or tournament and loading it again, e.g. so a host whose browser restarts can resume the hand in progress (see Table::snapshot and Table::restore; ducy-host saves the hosting around them).
structure
Tournament blind structures: presets scaled to a starting stack, checking a structure someone typed in, and about how long a tournament will take.

Structs§

Award
Chips one seat won from a pot.
BombPots
Bomb pots every few hands at a table (see Table::set_bomb_pots).
Deal
Every card a hand can use: each player’s hole cards and the full board. Board cards are revealed street by street as the hand is played.
Entrant
Someone entering the tournament: a person, or a bot that plays their seat.
Finish
A finished entry: who, and the place they finished in (1 = winner).
Hand
One hand of poker from the blinds to the payout.
HandOutcome
The outcome of play_hand.
HandReport
What happened after a hand: eliminations, moves and broken tables.
HandResult
The outcome of a finished hand.
HandSummary
What a bot learns when a hand ends.
HiddenDeal
A deal the engine never sees: every player’s hole cards stay with that player until showdown, and the board is dealt street by street. The cards themselves come from outside, e.g. a trustless shuffle (#134).
LegalActions
What the player to act may do.
Level
One blind level. Amounts are whole chips.
Move
A player moved between tables.
Observation
Everything the player to act is allowed to know when deciding: their own hole cards plus public information. Other players’ hole cards are never included.
Post
Blinds a player posts on coming back after missing them (see Hand::with_posts): dead goes straight into the pot (a missed small blind), live counts as their bet for the street (a missed big blind, so they may check if no one raises). Either may be 0, and both are capped at the player’s stack.
Pot
One pot (main or side) and who won it.
RaiseRange
The smallest and largest legal street totals for a bet or raise.
SeatRef
Where someone sits: a table id and a seat at it.
SeatState
One seat as a viewer sees it.
SeatView
What a bot may see about one seat: public chip counts, never hole cards.
Standing
One player still in, for standings.
Table
Hand after hand at one table. Everyone starts with buy_in chips, and a player who goes broke is topped back up before the next hand (unless Table::set_top_up turns that off: then chips carry over and a seat without chips sits out until it gets some). Each hand is dealt to the seats in play (TableSeat::plays); the hand numbers its players 0, 1, … in seat order, and the table maps them back to seats.
TableRules
The rules for a hand: game, betting structure and forced bets. Amounts are whole chips.
TableSeat
One seat: who sits there and the bot that plays it when no one does.
TableView
What a seat may see of the table: its own cards, public chip counts, and other players’ cards only once they’re shown down. Seat numbers are rotated so the viewer is seat 0 (hero).
Tournament
A multi-table tournament: random seating, blind levels, eliminations, balancing and breaking tables, and hand-for-hand play on the bubble.
TournamentConfig
How a tournament is played.

Enums§

Action
A player decision. Bet and raise amounts are the player’s total for the street (“raise to”), not the amount added.
Awaiting
What a hand is waiting for from outside before it can go on, with a Dealer that doesn’t give the engine every card (see Hand::awaiting).
BettingStructure
How much a player may bet or raise.
Event
Something that happened in the hand, in order.
PlayError
Errors from setting up or playing a hand.
Street
A betting round.
Variant
The poker game being played, which decides hole cards and showdown rules.

Constants§

MAX_PLAYERS
Most players at one table.
TOP_BB_SHARE
The blinds stop rising once the big blind is this share of the chips in play: a fifth.

Traits§

Bot
A poker player. Implement this to plug a strategy into play_hand, a crate::Table seat or a crate::Tournament entrant. The ducy-bots crate has ready-made ones, and runs bots written in other languages.
Dealer
Where a hand’s cards come from (#135).

Functions§

best_hands
The best hands among seats on a complete board, as seat numbers plus a description of the winning hand.
fallback_action
The default when a bot doesn’t give a legal action: check, else fold.
play_hand
Plays hand to the end, asking bots[seat] for each decision, then tells every bot how the hand went.