Expand description
§Hearts Engine
Bots and strategy tooling for Hearts, built on the hearts mechanics crate. Where hearts answers “what plays are legal?”, this crate answers “which card should I play?” — plus a wasm front end you can play in the browser at https://jdh8.github.io/hearts-engine/.
The design triangle:
Strategy: a decision procedure for one seat — which three cards to pass, which card to play.View: the information a seat may legally see. The underlyingRoundexposes all four hands and every pass; strategies never touch it. AViewshows only the seat’s own hand, the public trick history, its own pass and (after the exchange) what it received, plus the common-knowledge inferences: who is void in what, and where the passed cards went.Table: the driver. It owns theRound, tracks the void table, asks strategies for decisions, and applies them — so information hygiene holds by construction.
§Bots
HeuristicBot: deterministic and fast. Passes its most dangerous cards (an unguarded Q♠ first), ducks under the trick winner, dumps the queen and high hearts when void, and stops ducking to kill a suspected moon.MonteCarloBot(featurerand): determinized Monte Carlo. At each decision it samples hidden hands consistent with theView— voids respected, its own passed cards pinned to the receiver — replays the public history into a realRoundper world, softly favors hands where the known incoming pass fits the pass policy, rolls each out, and picks the action with the best expected game equity. One candidate per decision is a moon attempt — the deciding seat shoots and the other three defend — taken only when the rollouts reach the moon in most worlds, and then carried to the end of the round.
§Quick start
A bot-vs-bot round needs no features:
use hearts::{Hand, PassDirection, Round, Rules};
use hearts_engine::{HeuristicBot, play_round};
// The sorted deck dealt round-robin, one card per seat.
let mut hands = [Hand::EMPTY; 4];
for (i, card) in Hand::ALL.into_iter().enumerate() {
hands[i % 4].insert(card);
}
let round = Round::from_deal(Rules::new(), PassDirection::Hold, hands)?;
let [mut n, mut e, mut s, mut w] = [HeuristicBot::new(); 4];
let result = play_round(round, [&mut n, &mut e, &mut s, &mut w])?;
println!("{:?}", result.points());With the (default) rand feature, deal and settle whole games:
use hearts::{Game, Rules};
use hearts_engine::{HeuristicBot, MonteCarloBot, play_game};
let mut game = Game::new(Rules::default());
let [mut n, mut e, mut s] = [HeuristicBot::new(); 3];
let mut mc = MonteCarloBot::new(rand::rng()).samples(16);
let score = play_game(&mut game, [&mut n, &mut e, &mut s, &mut mc], &mut rand::rng())?;
println!("{:?}", score.totals);Writing your own bot is implementing Strategy’s two decisions against a
View; the driver handles all bookkeeping.
§Feature flags
rand(default): the Monte Carlo bot,Table::deal,play_game, and the examples. Disable it for a dependency-free heuristic-only build.parallel: Monte Carlo rollouts across the CPU cores via rayon. Decisions are bit-identical to the serial build, each just arrives faster; worthwhile at high sample counts. Off by default.
§Examples
play: play against three bots in the terminal —cargo run --example play(--bot mc:128,--seed 7,hintat the prompt, …)arena: bot-vs-bot tournaments over duplicate deals, every bot playing all four hands of each deal —cargo run --release --example arena -- --blocks 2000 mc:64 greedy greedy greedy(--games N,--ab SPECfor a paired A/B,--csv)
§Benchmarking
The arena is the instrument. Its unit is a paired duplicate block — one
deal, or one game seed played to the target, run four times with the
lineup rotated so every bot plays all four hands — which divides seat and
card luck out of the comparison. Convention: rank (3-2-1-0 matchpoints)
is the primary A/B detector, points the interpretable magnitude, and
win the ship gate.
- Paired A/B. Within one build,
arena --games 2000 --ab mc:128 mc:64 greedy greedy greedyreruns the same blocks with the--abspec in slot 1 and prints the paired per-block delta in standard-error units. Across two builds, run each at the same--seedwith--csvand join rows per block: deal seeds are a pure function of(--seed, block), so the builds are paired card for card. Self-checks: a homogeneous deterministic field (greedyfour times) must print exactly0.000±0.000, and each block’s payoff columns sum to their constants. - Scaling ladder.
mc:32→mc:128→mc:256against a greedy field. A real improvement shifts the whole compute curve, not one rung of it. - Absolute anchor.
examples/vs_cfrbridges to brianberns’ Deep CFR Hearts over duplicate 2-v-2 seating (seetournament/README.md, including the Q♠-breaks-hearts rules caveat). The instrumented P0 baseline (2026-08-19, 1,600 deals, seed 1) puts Deep CFR’s edge overmc:128at0.94 ± 0.15payoff per seat-deal, with completed moons 193 to 59. The net moon differential explains up to 77% of the gap;docs/cfr-gap.mdrecords the earlier anchors and the campaign. - Tripwire.
cargo test --release --test strength -- --ignoredassertsmc:128beats a greedy field by at least two points a round.
§Sound credits
“Breaking Glass.wav” by Unopiate is dedicated to the public domain under CC0 1.0.
“bec low bell solo.wav” by HMTSCCSound was trimmed and faded for the Queen of Spades cue. The source is dedicated to the public domain under CC0 1.0.
“Whistle and Explosion Single_Firework” by Rudmer_Rotteveel was shortened and faded for the player shooting-the-moon cue. The source is dedicated to the public domain under CC0 1.0.
“Distant Gunshot” by adrilahan was shortened and faded for the opponent shooting-the-moon cue. The source is dedicated to the public domain under CC0 1.0.
Re-exports§
pub use hearts;
Structs§
- Assessment
- One candidate action’s Monte Carlo assessment, for a solver or hint view
- Heuristic
Bot - A deterministic knowledge-based player
- Heuristic
Config - Tuning knobs for
HeuristicBot - Monte
Carlo Bot - A determinized Monte Carlo player
- Table
- A round in progress, with common-knowledge void tracking
- View
- What one seat may legally see of a round
Enums§
- Engine
Error - An error while driving a round
Traits§
- Strategy
- A decision procedure for one seat of Hearts
Functions§
- play_
game - Deal and play rounds until the game is over, returning the settled score
- play_
round - Play one round to completion, one strategy per seat, indexed by
Seat