hearts_engine/view.rs
1//! The [`View`]: what one seat may legally see of a round
2//!
3//! [`Round`](hearts::Round) exposes the whole position — all four hands and
4//! every pass — and leaves information hygiene to its consumers. This
5//! module is that hygiene: a [`View`] borrows the round privately and
6//! re-exposes only the whitelist of legally visible information.
7//!
8//! Unlike gin rummy, everything a Hearts seat may know is derivable from
9//! the public history the round already retains, so there is no hidden
10//! per-seat ledger: the only cached inference is the common-knowledge void
11//! table that the [`Table`](crate::Table) maintains (a seat that does not
12//! follow suit is void in the led suit, in front of everyone).
13
14use hearts::{Hand, PassDirection, Phase, Round, Rules, Seat, Suit, Trick};
15
16/// What one seat may legally see of a round
17///
18/// The wrapped [`Round`] is private, and these accessors are the whitelist:
19/// the other hands and the pre-exchange passes are structurally
20/// unreachable.
21pub struct View<'a> {
22 round: &'a Round,
23 seat: Seat,
24 /// Common-knowledge voids: bit `suit as u8` of `voids[seat as usize]`.
25 voids: &'a [u8; 4],
26 /// Running game totals, clockwise from this seat.
27 scores: [u16; 4],
28}
29
30impl<'a> View<'a> {
31 pub(crate) const fn new(
32 round: &'a Round,
33 seat: Seat,
34 voids: &'a [u8; 4],
35 scores: [u16; 4],
36 ) -> Self {
37 Self {
38 round,
39 seat,
40 voids,
41 scores,
42 }
43 }
44
45 /// The seat this view belongs to
46 #[must_use]
47 pub const fn seat(&self) -> Seat {
48 self.seat
49 }
50
51 /// The running game totals, clockwise from this seat:
52 /// `[mine, my left, across, my right]`
53 ///
54 /// Note the order: seat-relative, unlike [`Table::scores`], which is
55 /// indexed by [`Seat`]. All totals sit on the scoreboard in plain
56 /// sight, so they are part of the legal whitelist. `[0; 4]` for a
57 /// standalone round played outside a [`Game`](hearts::Game); the losing
58 /// threshold is [`rules().game_target`](hearts::Rules::game_target).
59 ///
60 /// [`Table::scores`]: crate::Table::scores
61 #[must_use]
62 pub const fn game_scores(&self) -> [u16; 4] {
63 self.scores
64 }
65
66 /// The rules of the round
67 #[must_use]
68 pub const fn rules(&self) -> &'a Rules {
69 self.round.rules()
70 }
71
72 /// The pass direction of the round
73 #[must_use]
74 pub const fn direction(&self) -> PassDirection {
75 self.round.direction()
76 }
77
78 /// The current phase of the round
79 #[must_use]
80 pub const fn phase(&self) -> Phase {
81 self.round.phase()
82 }
83
84 /// This seat's hand
85 #[must_use]
86 pub const fn hand(&self) -> Hand {
87 self.round.hand(self.seat)
88 }
89
90 /// The seat to play, or `None` outside the playing phase
91 #[must_use]
92 pub fn turn(&self) -> Option<Seat> {
93 self.round.turn()
94 }
95
96 /// The trick in progress; `Some` exactly during [`Phase::Playing`]
97 #[must_use]
98 pub const fn current_trick(&self) -> Option<Trick> {
99 self.round.current_trick()
100 }
101
102 /// The completed tricks in play order
103 #[must_use]
104 pub fn tricks(&self) -> &'a [Trick] {
105 self.round.tricks()
106 }
107
108 /// Every card played so far, including the trick in progress
109 #[must_use]
110 pub fn played(&self) -> Hand {
111 self.round.played()
112 }
113
114 /// Whether a heart has been played, allowing hearts to be led
115 #[must_use]
116 pub fn hearts_broken(&self) -> bool {
117 self.round.hearts_broken()
118 }
119
120 /// The cards this seat may legally play right now
121 ///
122 /// Empty when it is not this seat's turn.
123 #[must_use]
124 pub fn legal_plays(&self) -> Hand {
125 self.round.legal_plays(self.seat)
126 }
127
128 /// The penalty points `seat` has taken so far — public bookkeeping
129 #[must_use]
130 pub fn points_taken(&self, seat: Seat) -> u8 {
131 self.round.points_taken(seat)
132 }
133
134 /// How many cards `seat` holds — public arithmetic
135 #[must_use]
136 pub const fn hand_len(&self, seat: Seat) -> usize {
137 self.round.hand(seat).len()
138 }
139
140 /// The three cards this seat chose to pass, or `None` if it has not
141 /// passed (always `None` on a hold deal)
142 #[must_use]
143 pub const fn passed(&self) -> Option<Hand> {
144 self.round.passed(self.seat)
145 }
146
147 /// The three cards this seat received in the exchange
148 ///
149 /// `None` until the exchange happens and on hold deals — a seat never
150 /// sees incoming cards while passing is still open.
151 #[must_use]
152 pub fn received(&self) -> Option<Hand> {
153 match self.phase() {
154 Phase::Passing => None,
155 Phase::Playing | Phase::Finished => {
156 self.round.passed(self.direction().giver(self.seat))
157 }
158 }
159 }
160
161 /// Whether `seat` is known to be void in `suit`
162 ///
163 /// Void inference is common knowledge: everyone sees a seat fail to
164 /// follow. The table is *sound, not complete* — it records only voids
165 /// shown in play, so it lags a seat's real hand (including this seat's
166 /// own; check `hand()[suit].is_empty()` for that).
167 #[must_use]
168 pub const fn is_void(&self, seat: Seat, suit: Suit) -> bool {
169 self.voids[seat as usize] & 1 << suit as u8 != 0
170 }
171
172 /// The unplayed cards this seat *knows* `seat` holds: the passed cards
173 /// still in the receiver's hand
174 ///
175 /// Empty for every seat other than this seat's
176 /// [receiver](PassDirection::receiver), and before the exchange.
177 #[must_use]
178 pub fn known_cards(&self, seat: Seat) -> Hand {
179 let receiver = self.direction().receiver(self.seat);
180 if seat != self.seat && seat == receiver && self.phase() != Phase::Passing {
181 self.passed()
182 .map_or(Hand::EMPTY, |passed| passed - self.played())
183 } else {
184 Hand::EMPTY
185 }
186 }
187
188 /// The cards this seat cannot locate: the whole deck minus its own
189 /// hand, everything played, and its own passed cards
190 ///
191 /// Exactly the cards a determinizing bot must distribute among the
192 /// other hands. Once play begins, `unseen().len()` equals the other
193 /// hands' total minus the cards [`known_cards`](Self::known_cards)
194 /// already places. During the passing phase the identity is offset by
195 /// passes in flight — a seat that has passed holds 10 cards while its
196 /// 3 hidden passes stay unseen — so a pass-time determinizer should
197 /// sample 13-card *pre-pass* hands instead.
198 #[must_use]
199 pub fn unseen(&self) -> Hand {
200 Hand::ALL - self.hand() - self.played() - self.passed().unwrap_or(Hand::EMPTY)
201 }
202
203 /// The cards `seat` may hold, as far as this seat can tell
204 ///
205 /// This seat's own hand for itself; otherwise the unseen cards outside
206 /// `seat`'s known voids, plus the [`known_cards`](Self::known_cards).
207 #[must_use]
208 pub fn possible_cards(&self, seat: Seat) -> Hand {
209 if seat == self.seat {
210 return self.hand();
211 }
212 let mut cards = self.unseen();
213 for suit in Suit::ASC {
214 if self.is_void(seat, suit) {
215 cards[suit] = hearts::Holding::EMPTY;
216 }
217 }
218 cards | self.known_cards(seat)
219 }
220}