ducy_play/lib.rs
1//! Play out poker hands on top of [`ducy`]: antes and blinds, betting rounds,
2//! side pots and the showdown.
3//!
4//! Supports Texas Hold'em and Omaha (4, 5 or 6 hole cards), each with
5//! no-limit or pot-limit betting.
6//!
7//! ```
8//! use ducy_play::{Action, Deal, Hand, TableRules};
9//!
10//! let rules = TableRules::no_limit_holdem(1, 2);
11//! let deal = Deal::random(rules.variant, 3, Some(42)).unwrap();
12//! let mut hand = Hand::new(rules, &[200, 200, 200], 0, deal).unwrap();
13//!
14//! // Everyone calls or checks to the river.
15//! while let Some(legal) = hand.legal_actions() {
16//! let action = if legal.can_check { Action::Check } else { Action::Call };
17//! hand.act(action).unwrap();
18//! }
19//! let result = hand.result().unwrap();
20//! assert_eq!(result.final_stacks.iter().sum::<u64>(), 600);
21//! ```
22//!
23//! # From one hand to a tournament
24//!
25//! - [`Hand`]: one hand, from the blinds to the payout, with its [`Event`]
26//! history and each player's [`LegalActions`].
27//! - [`Table`]: seats over many hands: the button moves, people sit out and
28//! come back (posting missed blinds or waiting for the big blind), and bots
29//! play their seats ([`Table::advance`]).
30//! - Hosting a table for remote players (commands in, private views out,
31//! turn clocks, chip requests) is the `ducy-host` crate's. A table or
32//! tournament can be saved mid-hand and restored ([`snapshot`]).
33//! - [`Tournament`]: several tables with blind [`Level`]s, eliminations,
34//! balancing and hand-for-hand play on the bubble.
35//! - [`Bot`]: a seat played by code, given only what that seat may see
36//! ([`play_hand`]). Ready-made bots are the `ducy-bots` crate's.
37//!
38//! # Features
39//!
40//! - `serde` (default): `Serialize`/`Deserialize` for rules, actions,
41//! events, views and snapshots (JSON for external bots and clients).
42//! - `fair-deal` (default): provably fair commit–reveal deals
43//! ([`fair_deal`], [`Deal::from_seed`], [`Table::new_hand_from_seed`]),
44//! with SHA-256 from `sha2`.
45//!
46//! A seed makes deals reproducible. Without one ([`Deal::random`] with
47//! `None`, or [`Table::with_secure_deals`]) every deal comes from fresh system
48//! randomness: use that whenever people play each other.
49
50#![warn(missing_docs)]
51
52#[doc = include_str!("../README.md")]
53#[cfg(doctest)]
54pub struct ReadmeDoctests;
55
56mod bot;
57mod deal;
58mod error;
59#[cfg(feature = "fair-deal")]
60pub mod fair_deal;
61mod hand;
62pub mod hands;
63pub mod replay;
64mod rules;
65mod showdown;
66pub mod snapshot;
67pub mod structure;
68mod table;
69mod tournament;
70
71pub use bot::{Bot, HandOutcome, HandSummary, Observation, SeatView, fallback_action, play_hand};
72pub use deal::{Deal, Dealer, HiddenDeal};
73pub use error::PlayError;
74pub use hand::{
75 Action, Awaiting, Event, Hand, HandResult, LegalActions, MAX_PLAYERS, Post, RaiseRange, Street,
76};
77pub use rules::{BettingStructure, TableRules, Variant};
78pub use showdown::{Award, Pot, best_hands};
79pub use snapshot::{
80 HandSnapshot, SNAPSHOT_VERSION, SeatSnapshot, TOURNAMENT_SNAPSHOT_VERSION, TableSnapshot,
81 TournamentSnapshot,
82};
83pub use table::{BombPots, SeatState, Table, TableSeat, TableView};
84pub use tournament::{
85 Entrant, Finish, HandReport, Level, Move, SeatRef, Standing, TOP_BB_SHARE, Tournament,
86 TournamentConfig,
87};