gin-rummy 0.1.3

Cards, melds, deadwood solver, and rules-driven state machine for gin rummy
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

# Gin Rummy

[![Crates.io](https://img.shields.io/crates/v/gin-rummy)](https://crates.io/crates/gin-rummy)
[![Docs.rs](https://docs.rs/gin-rummy/badge.svg)](https://docs.rs/gin-rummy)
[![Build Status](https://github.com/jdh8/gin-rummy/actions/workflows/rust.yml/badge.svg)](https://github.com/jdh8/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`][mod-hand]: cards and card sets — [`Suit`], [`Rank`], [`Card`],
  [`Holding`], [`Hand`]
- [`meld`][mod-meld]: sets, runs, and the deadwood solver — [`Meld`],
  [`Melds`], [`best_melds`], [`deadwood`]
- [`round`][mod-round]: one deal from upcard to showdown — [`Round`],
  [`Phase`], [`RoundResult`]
- [`game`][mod-game]: the scoreboard across deals — [`Game`], [`FinalScore`]
- [`rules`][mod-rules]: scoring configuration — [`Rules`], [`Shutout`]
- [`deck`][mod-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:

```rust
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:

```rust
# #[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.

This crate aims to be the reusable one: a dependency-free core, an exact
solver, a validated state machine covering complete matches, and
school-by-school rule knobs including Oklahoma gin.  Bots and strength
benchmarks live in the sibling [gin-rummy-engine] crate.

[gin rummy]: https://www.pagat.com/rummy/ginrummy.html
[OpenSpiel]: https://github.com/google-deepmind/open_spiel
[RLCard]: https://github.com/datamllab/rlcard
[gin-rummy-eaai]: https://github.com/tneller/gin-rummy-eaai
[gin-rummy-engine]: https://crates.io/crates/gin-rummy-engine
[contract-bridge]: https://crates.io/crates/contract-bridge
[mod-hand]: https://docs.rs/gin-rummy/latest/gin_rummy/hand/
[mod-meld]: https://docs.rs/gin-rummy/latest/gin_rummy/meld/
[mod-round]: https://docs.rs/gin-rummy/latest/gin_rummy/round/
[mod-game]: https://docs.rs/gin-rummy/latest/gin_rummy/game/
[mod-rules]: https://docs.rs/gin-rummy/latest/gin_rummy/rules/
[mod-deck]: https://docs.rs/gin-rummy/latest/gin_rummy/deck/
[`Suit`]: https://docs.rs/gin-rummy/latest/gin_rummy/enum.Suit.html
[`Rank`]: https://docs.rs/gin-rummy/latest/gin_rummy/hand/struct.Rank.html
[`Card`]: https://docs.rs/gin-rummy/latest/gin_rummy/hand/struct.Card.html
[`Holding`]: https://docs.rs/gin-rummy/latest/gin_rummy/hand/struct.Holding.html
[`Hand`]: https://docs.rs/gin-rummy/latest/gin_rummy/hand/struct.Hand.html
[`Meld`]: https://docs.rs/gin-rummy/latest/gin_rummy/meld/struct.Meld.html
[`Melds`]: https://docs.rs/gin-rummy/latest/gin_rummy/meld/struct.Melds.html
[`best_melds`]: https://docs.rs/gin-rummy/latest/gin_rummy/meld/fn.best_melds.html
[`deadwood`]: https://docs.rs/gin-rummy/latest/gin_rummy/meld/fn.deadwood.html
[`Round`]: https://docs.rs/gin-rummy/latest/gin_rummy/round/struct.Round.html
[`Phase`]: https://docs.rs/gin-rummy/latest/gin_rummy/round/enum.Phase.html
[`RoundResult`]: https://docs.rs/gin-rummy/latest/gin_rummy/round/enum.RoundResult.html
[`Game`]: https://docs.rs/gin-rummy/latest/gin_rummy/game/struct.Game.html
[`FinalScore`]: https://docs.rs/gin-rummy/latest/gin_rummy/game/struct.FinalScore.html
[`Rules`]: https://docs.rs/gin-rummy/latest/gin_rummy/rules/struct.Rules.html
[`Shutout`]: https://docs.rs/gin-rummy/latest/gin_rummy/rules/enum.Shutout.html
[`Deck`]: https://docs.rs/gin-rummy/latest/gin_rummy/deck/struct.Deck.html