Gin Rummy

This crate models the mechanics of gin rummy: strongly typed cards and melds, an exact deadwood solver, and a rules-driven state machine for complete two-player rounds and games.

Gin rummy ranks the ace LOW: A-2-3 is a run, Q-K-A is not, and an ace counts one point of deadwood. Rank therefore encodes A = 1 through K = 13, unlike crates for ace-high games such as contract-bridge whose patterns this crate otherwise follows.

Hands are written as four dot-separated suit groups in ascending order, clubs first: "A23.456.789.T" holds ♣A ♣2 ♣3 ♦4 ♦5 ♦6 ♥7 ♥8 ♥9 ♠10.

Modules

hand: cards and card sets — Suit, Rank, Card, Holding, Hand
meld: sets, runs, and the deadwood solver — Meld, Melds, best_melds, deadwood
round: one deal from upcard to showdown — Round, Phase, RoundResult
game: the scoreboard across deals — Game, FinalScore
rules: scoring configuration — Rules, Shutout
deck (feature rand): shuffled dealing — Deck

Feature flags

rand: shuffled dealing (Deck, Round::deal, Game::deal)
serde: serialization for every public type, with validated deserialization of mid-game Round snapshots

Quick start

Deadwood analysis needs no features:

use gin_rummy::{best_melds, deadwood};

let hand = "A23.456.789.T".parse::<gin_rummy::Hand>()?;
assert_eq!(deadwood(hand), 10);
println!("{}", best_melds(hand));
# Ok::<(), gin_rummy::hand::ParseHandError>(())

A complete bot-vs-bot game with the rand feature:

# #[cfg(feature = "rand")]
# fn main() {
use gin_rummy::{Game, Player, Rules};

let mut game = Game::new(Rules::default(), Player::One);
while !game.is_over() {
    let mut round = game.deal(&mut rand::rng());
    drive(&mut round); // pass / draw / discard / knock / lay_off …
    game.record(round.result().expect("round finished")).unwrap();
}
println!("{:?}", game.final_score());
# }
# #[cfg(feature = "rand")]
# fn drive(round: &mut gin_rummy::Round) {
#     use gin_rummy::{Phase, best_melds, deadwood};
#     while round.result().is_none() {
#         match round.phase() {
#             Phase::Upcard => round.pass().unwrap(),
#             Phase::Draw => {
#                 round.draw_stock().unwrap();
#             }
#             Phase::Discard => {
#                 let hand = round.hand(round.turn().unwrap());
#                 let (card, rest) = hand
#                     .iter()
#                     .map(|card| (card, deadwood(hand - card.into())))
#                     .min_by_key(|&(_, rest)| rest)
#                     .unwrap();
#                 if rest <= round.knock_limit() {
#                     round.knock(card, best_melds(hand - card.into())).unwrap();
#                 } else {
#                     round.discard(card).unwrap();
#                 }
#             }
#             Phase::Layoff => {
#                 round.finish_layoffs().unwrap();
#             }
#             Phase::Finished => unreachable!(),
#         }
#     }
# }
# #[cfg(not(feature = "rand"))]
# fn main() {}

Examples

deadwood: parse hands from the command line and print their best melds — cargo run --example deadwood -- "45.456.567.789"
simulate: greedy bots play a full game — cargo run --features rand --example simulate

Alternatives

Open-source gin rummy mostly lives inside research frameworks rather than reusable libraries:

OpenSpiel's gin_rummy (C++/Python) has thoroughly tested single-hand rules with an Oklahoma option — but plays isolated hands only, with no match play: games to 100, boxes, shutouts, and dealer rotation are out of its scope.
RLCard's environment (Python) targets reinforcement learning; its deal and rewards deviate from table rules (an 11-card opening deal, no undercut bonus).
gin-rummy-eaai (Java) is the minimal framework behind the EAAI-2021 Gin Rummy AI challenge and its 13 papers — the academic reference point, though dormant since 2020 and unlicensed.