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 itsEventhistory and each player’sLegalActions.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-hostcrate’s. A table or tournament can be saved mid-hand and restored (snapshot). Tournament: several tables with blindLevels, 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 theducy-botscrate’s.
§Features
serde(default):Serialize/Deserializefor 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 fromsha2.
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::snapshotandTable::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.
- Bomb
Pots - 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.
- Hand
Outcome - The outcome of
play_hand. - Hand
Report - What happened after a hand: eliminations, moves and broken tables.
- Hand
Result - The outcome of a finished hand.
- Hand
Summary - What a bot learns when a hand ends.
- Hidden
Deal - 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).
- Legal
Actions - 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):deadgoes straight into the pot (a missed small blind),livecounts 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.
- Raise
Range - The smallest and largest legal street totals for a bet or raise.
- SeatRef
- Where someone sits: a table id and a seat at it.
- Seat
State - One seat as a viewer sees it.
- Seat
View - 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_inchips, and a player who goes broke is topped back up before the next hand (unlessTable::set_top_upturns 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. - Table
Rules - The rules for a hand: game, betting structure and forced bets. Amounts are whole chips.
- Table
Seat - One seat: who sits there and the bot that plays it when no one does.
- Table
View - 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.
- Tournament
Config - 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
Dealerthat doesn’t give the engine every card (seeHand::awaiting). - Betting
Structure - How much a player may bet or raise.
- Event
- Something that happened in the hand, in order.
- Play
Error - 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, acrate::Tableseat or acrate::Tournamententrant. Theducy-botscrate 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
seatson 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
handto the end, askingbots[seat]for each decision, then tells every bot how the hand went.