funman300/Ferrous-Solitaire
1
1
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 28 Wiki Activity

feat(core,engine): solver-driven hints with heuristic fallback

Browse Source 
The H-key hint now asks the v0.15.0 Klondike solver for the actual
best first move from the current game state instead of the existing
heuristic. The heuristic stays as the fallback path so hints still
work when the solver bails Inconclusive on the player's budget.

solitaire_core::solver gains a path-recording variant. The internal
DFS already enumerated moves on each frame; recording the root_move
on the stack frame is +16 bytes and one unwrap_or per expansion —
the new-game retry loop sees no measurable slowdown.

New public API (additive — try_solve unchanged):

  pub struct SolverMove { source, dest, count }
  pub struct SolveOutcome { result: SolverResult, first_move: Option<SolverMove> }
  pub fn try_solve_with_first_move(seed, draw_mode, &cfg) -> SolveOutcome
  pub fn try_solve_from_state(&GameState, &cfg) -> SolveOutcome

The internal solver-move enum was renamed InternalMove so the public
SolverMove can use engine-friendly (source, dest, count) types
instead of the compact internal form.

Engine wiring: handle_keyboard_hint calls try_solve_from_state on
the live GameStateResource. On Winnable + first_move, the hint
surfaces that exact move (no cycling — a single, optimal hint).
Unwinnable or Inconclusive falls through to the existing all_hints
cycling heuristic so hints remain useful in deals the solver gives
up on.

A new HintSolverConfig resource lets tests inject tight budgets to
force the fallback path; production uses SolverConfig::default()
and median solve time stays at 2 ms per H press.

Six new tests pin the contract: 4 in solitaire_core (Winnable
returns first_move, Unwinnable returns None, deterministic, seed
and state forms agree); 2 in solitaire_engine (hint uses solver
when Winnable, falls back to heuristic when Inconclusive).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
funman300
2026-05-06 01:10:02 +00:00
parent 56647d7f0d
commit 87275bf340
2 changed files with 654 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
solitaire_core/src/solver.rs
+397 -43
View File
@@ -65,7 +65,7 @@ use std::hash::{Hash, Hasher};
use crate::card::{Card, Suit};
use crate::deck::{deal_klondike, Deck};
use crate::game_state::DrawMode;
use crate::game_state::{DrawMode, GameState};
use crate::pile::{Pile, PileType};
use crate::rules::{can_place_on_foundation, can_place_on_tableau, is_valid_tableau_sequence};
@@ -108,6 +108,42 @@ impl Default for SolverConfig {
}
}
/// A single move the solver can recommend, expressed in terms of the
/// engine-level `(source, dest, count)` triple used by `MoveRequestEvent`.
///
/// Returned as part of [`SolveOutcome::first_move`] when
/// [`try_solve_with_first_move`] or [`try_solve_from_state`] proves the
/// position winnable. The hint system surfaces this to the player as the
/// "provably best" first move.
///
/// `count` is always `1` for non-tableau-to-tableau moves (foundation moves
/// always move a single card; waste moves a single card; draws use a
/// dedicated representation that the public API surfaces as
/// `source: PileType::Stock, dest: PileType::Waste, count: 1`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SolverMove {
/// Pile the move originates from.
pub source: PileType,
/// Pile the move lands on.
pub dest: PileType,
/// Number of cards in the move (1 for non-tableau-to-tableau moves).
pub count: usize,
}
/// Solver verdict plus, when winnable, the first move on a winning path.
///
/// `result == Winnable` guarantees `first_move == Some(_)`; the inverse
/// holds only when the search proved a verdict — `Inconclusive` and
/// `Unwinnable` always carry `first_move == None`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SolveOutcome {
/// The high-level verdict (Winnable / Unwinnable / Inconclusive).
pub result: SolverResult,
/// First move on the solution path when `result == Winnable`,
/// otherwise `None`.
pub first_move: Option<SolverMove>,
}
/// Tries to solve a fresh Classic-mode game from `seed` + `draw_mode`.
///
/// This is a pure function — same input always yields the same
@@ -120,18 +156,47 @@ impl Default for SolverConfig {
/// [`is_valid_tableau_sequence`]) drive move enumeration so the
/// solver's notion of "legal" exactly matches the live game.
pub fn try_solve(seed: u64, draw_mode: DrawMode, config: &SolverConfig) -> SolverResult {
let state = SolverState::initial(seed, draw_mode);
let mut visited: HashSet<u64> = HashSet::new();
let mut moves_consumed: u64 = 0;
let mut budget_exceeded = false;
let won = state.search(config, &mut visited, &mut moves_consumed, &mut budget_exceeded);
if won {
SolverResult::Winnable
} else if budget_exceeded {
SolverResult::Inconclusive
} else {
SolverResult::Unwinnable
// Delegate to the path-recording variant and discard the move. The path
// recording is cheap (a single Option<SolverMove> per stack frame) so
// this preserves `try_solve`'s existing performance characteristics —
// the new-game retry loop, which is the hot caller, sees no slowdown.
try_solve_with_first_move(seed, draw_mode, config).result
}
/// Tries to solve a fresh Classic-mode game from `seed` + `draw_mode` and,
/// when a win is found, returns the first move on the winning path.
///
/// Same semantics as [`try_solve`] for the verdict; the only difference is
/// that the [`SolveOutcome::first_move`] is populated when `result ==
/// SolverResult::Winnable`. `Unwinnable` and `Inconclusive` always carry
/// `first_move == None`.
///
/// Used by the engine hint system to promote H-key suggestions from a
/// heuristic to the provably-optimal first move; the hint system falls
/// back to its heuristic when this returns `Inconclusive`.
pub fn try_solve_with_first_move(
seed: u64,
draw_mode: DrawMode,
config: &SolverConfig,
) -> SolveOutcome {
let state = SolverState::initial(seed, draw_mode);
state.solve(config)
}
/// Tries to solve from an existing in-progress [`GameState`].
///
/// Mirrors [`try_solve_with_first_move`] but takes a live `GameState`
/// instead of a fresh seed. The hint system uses this so it can ask the
/// solver about the actual board the player is staring at, not just the
/// initial deal.
///
/// Reads `state.draw_mode` and the current pile contents. The active
/// `GameMode` is irrelevant — the solver only models Classic Klondike
/// rules, which are a strict subset of every other mode (Zen / Challenge
/// only differ in scoring and undo-availability).
pub fn try_solve_from_state(state: &GameState, config: &SolverConfig) -> SolveOutcome {
let solver_state = SolverState::from_game_state(state);
solver_state.solve(config)
}
// ---------------------------------------------------------------------------
@@ -141,9 +206,11 @@ pub fn try_solve(seed: u64, draw_mode: DrawMode, config: &SolverConfig) -> Solve
/// The candidate moves the solver enumerates at each step. Distinct
/// from `MoveRequestEvent` (engine-level) and `move_cards` (game-level)
/// because the solver also needs to model the stock-draw + recycle as a
/// first-class move.
/// first-class move. Distinct from the public [`SolverMove`] because the
/// internal form encodes each move kind structurally for fast pattern
/// matching during enumeration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SolverMove {
enum InternalMove {
/// Move `count` cards from a tableau column to another tableau column.
TableauToTableau { from: usize, to: usize, count: usize },
/// Move the top of a tableau column to a foundation slot.
@@ -156,6 +223,41 @@ enum SolverMove {
Draw,
}
impl InternalMove {
/// Convert this internal move into the public [`SolverMove`] form
/// suitable for handing off to the engine layer. Cheap — `O(1)` field
/// rewrites with no allocation.
fn to_public(self) -> SolverMove {
match self {
InternalMove::TableauToTableau { from, to, count } => SolverMove {
source: PileType::Tableau(from),
dest: PileType::Tableau(to),
count,
},
InternalMove::TableauToFoundation { from, slot } => SolverMove {
source: PileType::Tableau(from),
dest: PileType::Foundation(slot),
count: 1,
},
InternalMove::WasteToTableau { to } => SolverMove {
source: PileType::Waste,
dest: PileType::Tableau(to),
count: 1,
},
InternalMove::WasteToFoundation { slot } => SolverMove {
source: PileType::Waste,
dest: PileType::Foundation(slot),
count: 1,
},
InternalMove::Draw => SolverMove {
source: PileType::Stock,
dest: PileType::Waste,
count: 1,
},
}
}
}
/// Compact replica of `GameState` tailored for the solver. Strips
/// undo / score / move-count tracking and replaces the `HashMap` of
/// piles with fixed arrays so the canonical hash is cheap to compute.
@@ -232,8 +334,8 @@ impl SolverState {
/// The order matters — foundation moves shrink the search frontier
/// fastest, and stock-draws are the costliest. See the top-of-file
/// algorithm note.
fn enumerate_moves(&self) -> Vec<SolverMove> {
let mut moves: Vec<SolverMove> = Vec::new();
fn enumerate_moves(&self) -> Vec<InternalMove> {
let mut moves: Vec<InternalMove> = Vec::new();
// 1) Foundation moves from tableau tops.
for (i, col) in self.tableau.iter().enumerate() {
@@ -246,7 +348,7 @@ impl SolverState {
&self.foundation[slot as usize],
);
if can_place_on_foundation(top, &foundation_pile) {
moves.push(SolverMove::TableauToFoundation { from: i, slot });
moves.push(InternalMove::TableauToFoundation { from: i, slot });
}
}
}
@@ -260,7 +362,7 @@ impl SolverState {
&self.foundation[slot as usize],
);
if can_place_on_foundation(top, &foundation_pile) {
moves.push(SolverMove::WasteToFoundation { slot });
moves.push(InternalMove::WasteToFoundation { slot });
}
}
@@ -298,7 +400,7 @@ impl SolverState {
{
continue;
}
moves.push(SolverMove::TableauToTableau { from: src, to: dst, count });
moves.push(InternalMove::TableauToTableau { from: src, to: dst, count });
}
}
}
@@ -308,7 +410,7 @@ impl SolverState {
for dst in 0..7usize {
let dst_pile = Self::pile_view(PileType::Tableau(dst), &self.tableau[dst]);
if can_place_on_tableau(top, &dst_pile) {
moves.push(SolverMove::WasteToTableau { to: dst });
moves.push(InternalMove::WasteToTableau { to: dst });
}
}
}
@@ -326,7 +428,7 @@ impl SolverState {
let cycled_without_progress =
self.consecutive_draws > stock_cycle_len.saturating_add(1);
if can_draw && !cycled_without_progress {
moves.push(SolverMove::Draw);
moves.push(InternalMove::Draw);
}
moves
@@ -334,11 +436,11 @@ impl SolverState {
/// Apply `mv` to `self`, returning the previous `consecutive_draws`
/// value so the caller can restore it on backtrack.
fn apply_move(&mut self, mv: SolverMove) -> SolverStateUndo {
fn apply_move(&mut self, mv: InternalMove) -> SolverStateUndo {
let prev_just_drew = self.just_drew;
let prev_consec = self.consecutive_draws;
match mv {
SolverMove::TableauToTableau { from, to, count } => {
InternalMove::TableauToTableau { from, to, count } => {
let start = self.tableau[from].len() - count;
let moved: Vec<Card> = self.tableau[from].split_off(start);
self.tableau[to].extend(moved);
@@ -351,7 +453,7 @@ impl SolverState {
self.just_drew = false;
self.consecutive_draws = 0;
}
SolverMove::TableauToFoundation { from, slot } => {
InternalMove::TableauToFoundation { from, slot } => {
if let Some(card) = self.tableau[from].pop() {
self.foundation[slot as usize].push(card);
if let Some(top) = self.tableau[from].last_mut()
@@ -363,21 +465,21 @@ impl SolverState {
self.just_drew = false;
self.consecutive_draws = 0;
}
SolverMove::WasteToTableau { to } => {
InternalMove::WasteToTableau { to } => {
if let Some(card) = self.waste.pop() {
self.tableau[to].push(card);
}
self.just_drew = false;
self.consecutive_draws = 0;
}
SolverMove::WasteToFoundation { slot } => {
InternalMove::WasteToFoundation { slot } => {
if let Some(card) = self.waste.pop() {
self.foundation[slot as usize].push(card);
}
self.just_drew = false;
self.consecutive_draws = 0;
}
SolverMove::Draw => {
InternalMove::Draw => {
if self.stock.is_empty() {
// Recycle waste back to stock face-down, reversed.
let mut recycled: Vec<Card> = self.waste.drain(..).collect();
@@ -415,39 +517,55 @@ impl SolverState {
/// stack lives on the heap and grows only with `Vec` capacity, not
/// with thread-stack pages.
///
/// Returns `true` as soon as a winning leaf is found. Sets
/// `*budget_exceeded = true` if either budget trips before a
/// verdict.
/// Returns `Some(first_move)` (the move applied at the root that led
/// to a winning leaf) as soon as a winning leaf is found. Returns
/// `None` if the search exhausts (Unwinnable) or a budget trips —
/// callers distinguish those two cases via `*budget_exceeded`.
///
/// Path recording is implemented by stashing the root-level move on
/// each pushed frame and propagating it unchanged into deeper
/// children. Cost: one `Option<InternalMove>` (≤ 16 bytes) per
/// frame and one branch on push. Negligible on the hot path; the
/// new-game retry loop sees no measurable slowdown.
fn search(
self,
config: &SolverConfig,
visited: &mut HashSet<u64>,
moves_consumed: &mut u64,
budget_exceeded: &mut bool,
) -> bool {
) -> Option<SolverMove> {
// Each stack frame keeps a state plus the move iterator we
// haven't yet expanded. Popping a frame is the backtrack.
struct Frame {
state: SolverState,
pending: std::vec::IntoIter<SolverMove>,
pending: std::vec::IntoIter<InternalMove>,
/// First move on the path from the root to this frame's
/// state. `None` for the root frame; populated when a child
/// frame is pushed. Propagates unchanged from parent to deeper
/// children so any winning leaf can read it directly.
root_move: Option<InternalMove>,
}
// Quick exits before allocating the stack.
// Quick exits before allocating the stack. An already-won state
// surfaces as Winnable with no move to recommend (the player has
// nothing left to do); the engine treats this gracefully —
// `is_won` callers gate H-key hints on `!is_won` already.
if self.is_won() {
return true;
return None;
}
if *moves_consumed >= config.move_budget || visited.len() >= config.state_budget {
*budget_exceeded = true;
return false;
return None;
}
let root_hash = self.canonical_hash();
if !visited.insert(root_hash) {
return false;
return None;
}
let root_moves = self.enumerate_moves();
let mut stack: Vec<Frame> = Vec::new();
stack.push(Frame {
state: self,
pending: root_moves.into_iter(),
root_move: None,
});
while let Some(frame) = stack.last_mut() {
@@ -457,7 +575,7 @@ impl SolverState {
|| visited.len() >= config.state_budget
{
*budget_exceeded = true;
return false;
return None;
}
let Some(mv) = frame.pending.next() else {
// Exhausted this frame's children — backtrack.
@@ -465,10 +583,15 @@ impl SolverState {
continue;
};
*moves_consumed = moves_consumed.saturating_add(1);
// Determine the root-level move for the *child* we are about
// to push: if the current frame is the root (root_move is
// None) then the child's root move is `mv` itself; otherwise
// it inherits from the parent.
let child_root_move = frame.root_move.unwrap_or(mv);
let mut next = frame.state.clone();
next.apply_move(mv);
if next.is_won() {
return true;
return Some(child_root_move.to_public());
}
let h = next.canonical_hash();
if !visited.insert(h) {
@@ -478,9 +601,74 @@ impl SolverState {
stack.push(Frame {
state: next,
pending: next_moves.into_iter(),
root_move: Some(child_root_move),
});
}
false
None
}
/// Drive [`SolverState::search`] and convert the raw outcome into a
/// public [`SolveOutcome`]. Shared by [`try_solve_with_first_move`]
/// and [`try_solve_from_state`].
fn solve(self, config: &SolverConfig) -> SolveOutcome {
let mut visited: HashSet<u64> = HashSet::new();
let mut moves_consumed: u64 = 0;
let mut budget_exceeded = false;
let already_won = self.is_won();
let first_move = self.search(config, &mut visited, &mut moves_consumed, &mut budget_exceeded);
let result = if already_won || first_move.is_some() {
SolverResult::Winnable
} else if budget_exceeded {
SolverResult::Inconclusive
} else {
SolverResult::Unwinnable
};
SolveOutcome { result, first_move }
}
/// Build a `SolverState` from an in-progress [`GameState`].
///
/// Reads the live pile contents and `draw_mode`. Missing piles are
/// treated as empty — the engine's `GameState::new` always populates
/// every pile slot, but defensive code keeps this loader safe in the
/// face of partially-constructed test fixtures.
///
/// The search-metadata fields (`just_drew`, `consecutive_draws`)
/// reset to "no draws yet" — the solver is concerned with future
/// reachability from this position, not the engine's own draw
/// history.
fn from_game_state(game: &GameState) -> Self {
let tableau: [Vec<Card>; 7] = core::array::from_fn(|i| {
game.piles
.get(&PileType::Tableau(i))
.map(|p| p.cards.clone())
.unwrap_or_default()
});
let foundation: [Vec<Card>; 4] = core::array::from_fn(|i| {
game.piles
.get(&PileType::Foundation(i as u8))
.map(|p| p.cards.clone())
.unwrap_or_default()
});
let stock = game
.piles
.get(&PileType::Stock)
.map(|p| p.cards.clone())
.unwrap_or_default();
let waste = game
.piles
.get(&PileType::Waste)
.map(|p| p.cards.clone())
.unwrap_or_default();
Self {
tableau,
foundation,
stock,
waste,
draw_mode: game.draw_mode.clone(),
just_drew: false,
consecutive_draws: 0,
}
}
/// Build a deterministic 64-bit hash of the visible game state.
@@ -656,9 +844,9 @@ mod tests {
let mut moves_consumed: u64 = 0;
let mut budget_exceeded = false;
let cfg = SolverConfig::default();
let won = state.search(&cfg, &mut visited, &mut moves_consumed, &mut budget_exceeded);
let first_move = state.search(&cfg, &mut visited, &mut moves_consumed, &mut budget_exceeded);
assert!(won, "obviously-winnable position must be recognised as Winnable");
assert!(first_move.is_some(), "obviously-winnable position must be recognised as Winnable");
assert!(!budget_exceeded);
assert!(
moves_consumed < 1000,
@@ -699,8 +887,8 @@ mod tests {
let mut visited: HashSet<u64> = HashSet::new();
let mut moves_consumed: u64 = 0;
let mut budget_exceeded = false;
let won = state.search(&cfg, &mut visited, &mut moves_consumed, &mut budget_exceeded);
assert!(!won, "buried Ace under same-suit Two with no recovery must not solve");
let first_move = state.search(&cfg, &mut visited, &mut moves_consumed, &mut budget_exceeded);
assert!(first_move.is_none(), "buried Ace under same-suit Two with no recovery must not solve");
assert!(!budget_exceeded, "small synthetic state must complete within budget");
}
@@ -890,4 +1078,170 @@ mod tests {
counts[0], counts[1], counts[2],
);
}
// -----------------------------------------------------------------------
// First-move-recording API: try_solve_with_first_move /
// try_solve_from_state. Exercised by the engine hint system.
// -----------------------------------------------------------------------
/// A synthetic GameState with each foundation holding A..Q for its
/// suit, the four Kings sitting on tableau columns 0..3, empty stock
/// and empty waste. Exactly four legal moves exist — one Tableau→
/// Foundation per King — and any one of them is the first move on a
/// solution path.
fn near_finished_game_state() -> GameState {
use crate::card::Rank;
let mut game = GameState::new(1, DrawMode::DrawOne);
// Wipe every pile.
for slot in 0..4_u8 {
game.piles
.get_mut(&PileType::Foundation(slot))
.unwrap()
.cards
.clear();
}
for i in 0..7_usize {
game.piles
.get_mut(&PileType::Tableau(i))
.unwrap()
.cards
.clear();
}
game.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
game.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
// Foundations: A through Q for each suit. Slot 0=Clubs,
// 1=Diamonds, 2=Hearts, 3=Spades to match
// `target_foundation_slot` ordering.
let suit_for_slot = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
let ranks_below_king = [
Rank::Ace, Rank::Two, Rank::Three, Rank::Four, Rank::Five,
Rank::Six, Rank::Seven, Rank::Eight, Rank::Nine, Rank::Ten,
Rank::Jack, Rank::Queen,
];
for (slot, suit) in suit_for_slot.iter().enumerate() {
let pile = game
.piles
.get_mut(&PileType::Foundation(slot as u8))
.unwrap();
for (i, rank) in ranks_below_king.iter().enumerate() {
pile.cards.push(Card {
id: (slot as u32) * 13 + i as u32,
suit: *suit,
rank: *rank,
face_up: true,
});
}
}
// Tableau 0..3: one King each, face-up.
for (col, suit) in suit_for_slot.iter().enumerate() {
game.piles
.get_mut(&PileType::Tableau(col))
.unwrap()
.cards
.push(Card {
id: 100 + col as u32,
suit: *suit,
rank: Rank::King,
face_up: true,
});
}
game
}
#[test]
fn try_solve_with_first_move_returns_some_move_for_winnable_state() {
let game = near_finished_game_state();
let cfg = SolverConfig::default();
let outcome = try_solve_from_state(&game, &cfg);
assert_eq!(
outcome.result,
SolverResult::Winnable,
"near-finished state must solve as Winnable"
);
let mv = outcome.first_move.expect("Winnable must include a first_move");
// The first move must be a King going from a tableau column to
// its matching foundation slot. Single-card move.
assert_eq!(mv.count, 1);
assert!(matches!(mv.source, PileType::Tableau(c) if c < 4));
assert!(matches!(mv.dest, PileType::Foundation(s) if s < 4));
}
#[test]
fn try_solve_with_first_move_returns_none_for_unwinnable_state() {
use crate::card::Rank;
// The "buried Ace under same-suit Two with no recovery" fixture
// used by `solver_recognises_obviously_unwinnable_deal`, lifted
// into a real `GameState` so we can exercise `try_solve_from_state`.
let mut game = GameState::new(1, DrawMode::DrawOne);
for slot in 0..4_u8 {
game.piles
.get_mut(&PileType::Foundation(slot))
.unwrap()
.cards
.clear();
}
for i in 0..7_usize {
game.piles
.get_mut(&PileType::Tableau(i))
.unwrap()
.cards
.clear();
}
game.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
game.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
// Tableau 0: A♠ on the bottom, 2♠ on top — the 2♠ has no legal
// destination, so the Ace is buried forever.
let t0 = game.piles.get_mut(&PileType::Tableau(0)).unwrap();
t0.cards.push(Card { id: 0, suit: Suit::Spades, rank: Rank::Ace, face_up: true });
t0.cards.push(Card { id: 1, suit: Suit::Spades, rank: Rank::Two, face_up: true });
// Tableau 1: a face-up King with nothing else — irrelevant; the
// pruning check elides "King → empty" no-ops.
game.piles
.get_mut(&PileType::Tableau(1))
.unwrap()
.cards
.push(Card { id: 2, suit: Suit::Clubs, rank: Rank::King, face_up: true });
let cfg = SolverConfig::default();
let outcome = try_solve_from_state(&game, &cfg);
assert_eq!(
outcome.result,
SolverResult::Unwinnable,
"buried-Ace fixture must be proved Unwinnable"
);
assert!(
outcome.first_move.is_none(),
"Unwinnable verdict must carry first_move == None"
);
}
#[test]
fn try_solve_with_first_move_is_deterministic() {
// Same state run multiple times yields the same first_move.
let game = near_finished_game_state();
let cfg = SolverConfig::default();
let a = try_solve_from_state(&game, &cfg);
let b = try_solve_from_state(&game, &cfg);
let c = try_solve_from_state(&game, &cfg);
assert_eq!(a, b, "repeat solves must yield the same outcome");
assert_eq!(b, c);
}
#[test]
fn try_solve_with_first_move_seed_form_matches_state_form() {
// For a fresh seed, the two public entry points must agree —
// they share the same internal `solve()` implementation, but
// route through different state constructors. This is the
// smoke test that catches drift between them.
let cfg = SolverConfig {
move_budget: 5_000,
state_budget: 5_000,
};
let a = try_solve_with_first_move(7, DrawMode::DrawOne, &cfg);
let game = GameState::new(7, DrawMode::DrawOne);
let b = try_solve_from_state(&game, &cfg);
assert_eq!(a.result, b.result, "verdicts must match across the two entry points");
assert_eq!(a.first_move, b.first_move, "first_move must match across the two entry points");
}
}
solitaire_engine/src/input_plugin.rs
+257 -9
View File
@@ -54,6 +54,16 @@ use crate::time_attack_plugin::TimeAttackResource;
/// Z-depth used for cards while being dragged — above all resting cards.
const DRAG_Z: f32 = 500.0;
/// Solver budgets used by the H-key hint system.
///
/// Wraps `solitaire_core::solver::SolverConfig` as a Bevy resource so
/// tests can inject tighter budgets to exercise the heuristic-fallback
/// path. Production initialises this to `SolverConfig::default()` (100k
/// move / 200k state budgets, the same numbers the new-game retry loop
/// uses).
#[derive(Resource, Debug, Clone, Default)]
pub struct HintSolverConfig(pub solitaire_core::solver::SolverConfig);
/// Shared countdown state for the new-game double-press confirmation
/// flow.
///
@@ -89,6 +99,7 @@ pub struct InputPlugin;
impl Plugin for InputPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<HintCycleIndex>()
.init_resource::<HintSolverConfig>()
.init_resource::<KeyboardConfirmState>()
.add_message::<NewGameConfirmEvent>()
.add_message::<StartZenRequestEvent>()
@@ -236,20 +247,34 @@ fn handle_keyboard_core(
// Esc is handled by `PausePlugin` (overlay toggle + paused flag).
}
/// Handles the H key: cycles through all available hints, highlighting the
/// source card yellow for 2 s and showing a descriptive toast.
/// Handles the H key: surface the solver's provably-best first move when
/// the position is winnable; otherwise fall back to cycling through the
/// heuristic hints.
///
/// The hint index wraps around once all hints have been cycled through. When no
/// moves are available a "No hints available" toast is shown instead.
/// The solver (`solitaire_core::solver::try_solve_from_state`) is run
/// synchronously on each H press — median ~2 ms on real positions, with a
/// hard cap from `SolverConfig::default()`'s budgets. When the verdict is
/// `Winnable`, the returned `first_move` is shown as a single, stable hint
/// (no cycling — the optimal move doesn't change between identical
/// presses). When the verdict is `Unwinnable` or `Inconclusive`, the
/// handler falls back to the legacy heuristic in `all_hints`, which still
/// cycles through every legal move.
///
/// When no moves are available a "No hints available" toast is shown
/// instead. The H key always produces a hint when any legal move exists.
///
/// TODO: if profiling ever shows >100 ms solver calls in practice, move
/// the solver call to `AsyncComputeTaskPool` to keep input latency low.
#[allow(clippy::too_many_arguments)]
fn handle_keyboard_hint(
keys: Res<ButtonInput<KeyCode>>,
paused: Option<Res<PausedResource>>,
game: Option<Res<GameStateResource>>,
layout: Option<Res<LayoutResource>>,
solver_config: Res<HintSolverConfig>,
mut hint_cycle: ResMut<HintCycleIndex>,
mut commands: Commands,
mut card_entities: Query<(Entity, &CardEntity, &mut Sprite)>,
card_entities: Query<(Entity, &CardEntity, &mut Sprite)>,
mut info_toast: MessageWriter<InfoToastEvent>,
mut hint_visual: MessageWriter<HintVisualEvent>,
) {
@@ -269,6 +294,25 @@ fn handle_keyboard_hint(
let Some(_layout_res) = layout else { return };
// First pass: ask the solver for the provably-best move. The
// solver is deterministic, so repeated H presses on the same
// position keep showing the same hint (cycling is reserved for
// the heuristic fallback path).
use solitaire_core::solver::{try_solve_from_state, SolverResult};
let outcome = try_solve_from_state(&g.0, &solver_config.0);
if outcome.result == SolverResult::Winnable
&& let Some(mv) = outcome.first_move
{
let from = mv.source.clone();
let to = mv.dest.clone();
emit_hint_visuals(&g.0, &from, &to, &mut commands, card_entities, &mut info_toast, &mut hint_visual);
return;
}
// Fallback: heuristic cycling hint. Used when the solver verdict
// is `Unwinnable` (no legal winning path — but a legal *move* may
// still exist, e.g. drawing from stock) or `Inconclusive` (budget
// exhausted on a complex mid-game position).
let hints = all_hints(&g.0);
if hints.is_empty() {
info_toast.write(InfoToastEvent("No hints available".to_string()));
@@ -278,14 +322,29 @@ fn handle_keyboard_hint(
// Pick the hint at the current cycle index (wrapping) and advance.
let idx = hint_cycle.0 % hints.len();
hint_cycle.0 = hint_cycle.0.wrapping_add(1);
let (from, to, _count) = &hints[idx];
let (from, to, _count) = hints[idx].clone();
emit_hint_visuals(&g.0, &from, &to, &mut commands, card_entities, &mut info_toast, &mut hint_visual);
}
/// Apply the visual + toast effects for a single chosen hint move.
///
/// Shared between the solver-driven and heuristic-driven hint paths so
/// both produce identical player-facing feedback.
fn emit_hint_visuals(
game: &GameState,
from: &PileType,
to: &PileType,
commands: &mut Commands,
mut card_entities: Query<(Entity, &CardEntity, &mut Sprite)>,
info_toast: &mut MessageWriter<InfoToastEvent>,
hint_visual: &mut MessageWriter<HintVisualEvent>,
) {
// When the hint points at the stock (draw suggestion) there is no
// face-up card to highlight — show a toast instead.
// If the stock is empty, pressing D will recycle the waste rather
// than draw a card, so the toast text must reflect that.
if *from == PileType::Stock {
let stock_empty = g.0.piles
let stock_empty = game.piles
.get(&PileType::Stock)
.is_some_and(|p| p.cards.is_empty());
let msg = if stock_empty {
@@ -298,7 +357,7 @@ fn handle_keyboard_hint(
}
// Find the top face-up card in the source pile and highlight it.
let top_card_id = g.0.piles.get(from)
let top_card_id = game.piles.get(from)
.and_then(|p| p.cards.last().filter(|c| c.face_up))
.map(|c| c.id);
if let Some(card_id) = top_card_id {
@@ -327,7 +386,7 @@ fn handle_keyboard_hint(
// player keeps thinking in suit terms; otherwise fall back to "foundation".
let msg = match to {
PileType::Foundation(_) => {
let claimed = g.0.piles.get(to).and_then(|p| p.claimed_suit());
let claimed = game.piles.get(to).and_then(|p| p.claimed_suit());
if let Some(suit) = claimed {
let suit_name = match suit {
Suit::Clubs => "Clubs",
@@ -2125,5 +2184,194 @@ mod tests {
anim.end_z
);
}
// -----------------------------------------------------------------------
// Hint system — solver promotion (v0.16.0+)
//
// The H-key hint is now backed by `solitaire_core::solver::try_solve_from_state`.
// When the solver proves the position winnable, the hint is the
// first move on the solver's solution path. When the solver returns
// Inconclusive (budget exhausted) or Unwinnable, the legacy
// heuristic in `all_hints` supplies the hint instead so the H key
// always produces feedback while any legal move exists.
// -----------------------------------------------------------------------
/// Build a minimal Bevy app that registers only the resources and
/// messages needed to drive `handle_keyboard_hint` end-to-end.
/// Skips every other input system — the test only exercises the hint
/// path and we want the assertions to be unaffected by other handlers.
fn hint_test_app() -> App {
let mut app = App::new();
app.add_plugins(MinimalPlugins);
app.add_message::<InfoToastEvent>();
app.add_message::<HintVisualEvent>();
app.init_resource::<HintCycleIndex>();
app.init_resource::<HintSolverConfig>();
app.init_resource::<ButtonInput<KeyCode>>();
// Layout: a fixed 1280x800 layout — `handle_keyboard_hint` only
// checks the resource is present, never reads coordinates.
app.insert_resource(crate::layout::LayoutResource(
crate::layout::compute_layout(Vec2::new(1280.0, 800.0)),
));
app.add_systems(Update, handle_keyboard_hint);
app
}
/// Helper: simulate "the player just pressed H this frame".
fn press_h(app: &mut App) {
let mut input = app.world_mut().resource_mut::<ButtonInput<KeyCode>>();
input.release(KeyCode::KeyH);
input.clear();
input.press(KeyCode::KeyH);
}
/// Build a near-finished `GameState`: foundations hold A..Q for each
/// suit, four Kings sit on tableau columns 0..3, stock and waste
/// empty. Solver-side equivalent of the `near_finished_game_state`
/// helper in `solitaire_core::solver::tests`.
fn near_finished_game_state() -> GameState {
use solitaire_core::card::{Card, Rank, Suit};
let mut game = GameState::new(1, DrawMode::DrawOne);
for slot in 0..4_u8 {
game.piles
.get_mut(&PileType::Foundation(slot))
.unwrap()
.cards
.clear();
}
for i in 0..7_usize {
game.piles
.get_mut(&PileType::Tableau(i))
.unwrap()
.cards
.clear();
}
game.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
game.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
let suit_for_slot = [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades];
let ranks_below_king = [
Rank::Ace, Rank::Two, Rank::Three, Rank::Four, Rank::Five,
Rank::Six, Rank::Seven, Rank::Eight, Rank::Nine, Rank::Ten,
Rank::Jack, Rank::Queen,
];
for (slot, suit) in suit_for_slot.iter().enumerate() {
let pile = game
.piles
.get_mut(&PileType::Foundation(slot as u8))
.unwrap();
for (i, rank) in ranks_below_king.iter().enumerate() {
pile.cards.push(Card {
id: (slot as u32) * 13 + i as u32,
suit: *suit,
rank: *rank,
face_up: true,
});
}
}
for (col, suit) in suit_for_slot.iter().enumerate() {
game.piles
.get_mut(&PileType::Tableau(col))
.unwrap()
.cards
.push(Card {
id: 100 + col as u32,
suit: *suit,
rank: Rank::King,
face_up: true,
});
}
game
}
/// When the solver verdict is Winnable, the hint must come from the
/// solver: in our near-finished fixture, four Tableau→Foundation
/// moves are legal and the solver returns one of them. The
/// `HintVisualEvent` source card must be one of the four Kings and
/// the destination must be a foundation slot.
#[test]
fn hint_uses_solver_when_winnable() {
use solitaire_core::card::Rank;
let mut app = hint_test_app();
let game = near_finished_game_state();
// Track the 4 King ids so we can assert the hint source matches.
let king_ids: Vec<u32> = (0..4_u8)
.map(|c| {
game.piles
.get(&PileType::Tableau(c as usize))
.unwrap()
.cards
.last()
.filter(|c| c.rank == Rank::King)
.map(|c| c.id)
.expect("each tableau col 0..3 has a King on top")
})
.collect();
app.insert_resource(GameStateResource(game));
press_h(&mut app);
app.update();
// Read out the messages via the standard cursor API.
let messages = app.world().resource::<Messages<HintVisualEvent>>();
let mut cursor = messages.get_cursor();
let collected: Vec<HintVisualEvent> = cursor.read(messages).cloned().collect();
assert_eq!(
collected.len(), 1,
"exactly one HintVisualEvent must fire on a winnable solver verdict"
);
let event = &collected[0];
assert!(
king_ids.contains(&event.source_card_id),
"solver hint must point at one of the four Kings; got id {}",
event.source_card_id
);
assert!(
matches!(event.dest_pile, PileType::Foundation(_)),
"solver hint destination must be a foundation slot; got {:?}",
event.dest_pile
);
}
/// When the solver returns Inconclusive (e.g. tight budgets force an
/// early bail), the heuristic fallback must still produce a hint
/// event so the H key never feels broken.
///
/// We force the solver inconclusive by setting both budgets to 0 —
/// the search bails on the very first iteration, returning
/// `SolverResult::Inconclusive`. The heuristic fallback then runs on
/// the fresh deal and finds at least one legal move.
#[test]
fn hint_falls_back_to_heuristic_when_solver_inconclusive() {
use solitaire_core::solver::SolverConfig;
let mut app = hint_test_app();
// Force solver to bail before exploring anything.
app.insert_resource(HintSolverConfig(SolverConfig {
move_budget: 0,
state_budget: 0,
}));
// A fresh seeded deal — guaranteed to have at least one legal
// move (the standard Klondike opening always has draws available
// even if no immediate tableau move exists).
let game = GameState::new(42, DrawMode::DrawOne);
app.insert_resource(GameStateResource(game));
press_h(&mut app);
app.update();
let world = app.world();
let visuals = world.resource::<Messages<HintVisualEvent>>();
let mut visual_cursor = visuals.get_cursor();
let collected: Vec<HintVisualEvent> = visual_cursor.read(visuals).cloned().collect();
// Either a card-move hint (most fresh deals) or a draw suggestion.
// A draw suggestion fires no `HintVisualEvent` (only an
// `InfoToastEvent`), so we accept zero-or-one HintVisualEvent so
// long as at least one feedback signal was emitted overall.
let toasts = world.resource::<Messages<InfoToastEvent>>();
let mut toast_cursor = toasts.get_cursor();
let toast_count = toast_cursor.read(toasts).count();
assert!(
!collected.is_empty() || toast_count > 0,
"heuristic fallback must produce a hint signal (visual or toast)"
);
}
}