better iter order

This reverts commit 5a52f2ab7a.

Cargo.lock

@@ -22,7 +22,7 @@ checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
 [[package]]
 name = "card_game"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "arrayvec",
 ]
@@ -132,12 +132,22 @@ dependencies = [
  "rand",
 ]
 
+[[package]]
+name = "klondike-bench"
+version = "0.1.0"
+dependencies = [
+ "card_game",
+ "klondike",
+ "rand",
+]
+
 [[package]]
 name = "klondike-cli"
 version = "0.1.0"
 dependencies = [
  "card_game",
  "klondike",
+ "rand",
 ]
 
 [[package]]

Cargo.toml

@@ -2,6 +2,22 @@
 members = [
 	"card_game",
 	"klondike",
+	"klondike-bench",
 	"klondike-cli",
 ]
 resolver = "3"
+
+[workspace.dependencies]
+card_game = { version = "0.2.0", path = "card_game", registry = "Quaternions" }
+klondike = { version = "0.1.0", path = "klondike", registry = "Quaternions" }
+
+[workspace.lints.rust]
+# unsafe_code = "forbid"
+# missing_docs = "warn"
+# missing_debug_implementations = "warn"
+single_use_lifetimes = "warn"
+trivial_casts = "warn"
+unused_lifetimes = "warn"
+unused_qualifications = "warn"
+# variant_size_differences = "warn"
+unexpected_cfgs = "warn"

card_game/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "card_game"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 repository = "https://git.aleshym.co/Quaternions/card_game"
 license = "MIT OR Apache-2.0"
@@ -10,3 +10,6 @@ keywords = ["card", "cards", "solitaire", "klondike"]
 
 [dependencies]
 arrayvec = "0.7.6"
+
+[lints]
+workspace = true

card_game/README.md

@@ -0,0 +1,32 @@
+Card Game
+=========
+
+`card_game` is a collection of algorithms, structs, and enums which are useful to implement card games.
+
+## Example
+
+```rust
+use card_game::{Card, Deck, Rank, Stack, Suit};
+
+// create a full deck (unshuffled)
+let mut deck = Stack::full_deck(Deck::Deck1);
+
+// inspect the top card
+let card = deck.pop().unwrap();
+assert_eq!(card, Card::new(Deck::Deck1, Suit::Diamonds, Rank::King));
+```
+
+#### License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
+2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+
+<br>
+
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
+</sub>

card_game/src/lib.rs

@@ -1,10 +1,15 @@
+// test readme
+#[doc = include_str!("../README.md")]
+#[cfg(doctest)]
+struct ReadmeDoctests;
+
 use core::ops::RangeBounds;
 
 // TODO: pub struct ValidInstruction<I>(I);
-pub trait Game {
-	type Stats;
-	type Config;
-	type Instruction;
+pub trait Game: Clone + core::fmt::Debug {
+	type Stats: Clone + core::fmt::Debug;
+	type Config: Clone + core::fmt::Debug;
+	type Instruction: Clone + core::fmt::Debug;
 	fn possible_instructions(&self) -> impl Iterator<Item = Self::Instruction> + use<Self>;
 	fn is_instruction_valid(&self, config: &Self::Config, instruction: Self::Instruction) -> bool;
 	fn process_instruction(
@@ -19,19 +24,19 @@ pub trait Game {
 /// card_game supports up to 4 identifiably separate decks.
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub enum Deck {
-	Deck1,
-	Deck2,
-	Deck3,
-	Deck4,
+	Deck1 = 0b00,
+	Deck2 = 0b01,
+	Deck3 = 0b10,
+	Deck4 = 0b11,
 }
 impl Deck {
 	pub const fn new(deck: u8) -> Option<Self> {
 		use Deck::*;
 		Some(match deck {
-			1 => Deck1,
-			2 => Deck2,
-			3 => Deck3,
-			4 => Deck4,
+			0b00 => Deck1,
+			0b01 => Deck2,
+			0b10 => Deck3,
+			0b11 => Deck4,
 			_ => return None,
 		})
 	}
@@ -46,12 +51,22 @@ pub enum Suit {
 }
 impl Suit {
 	pub const SUITS: [Self; 4] = [Self::Spades, Self::Hearts, Self::Clubs, Self::Diamonds];
+	pub const fn new(suit: u8) -> Option<Self> {
+		use Suit::*;
+		Some(match suit {
+			0b00 => Spades,
+			0b01 => Hearts,
+			0b10 => Clubs,
+			0b11 => Diamonds,
+			_ => return None,
+		})
+	}
 	/// Is the suit red.
-	pub fn is_red(self) -> bool {
+	pub const fn is_red(self) -> bool {
 		self as u8 & 0b01 != 0
 	}
-	/// Is the suit shape spikey.  (Bouba/kiki)
-	pub fn is_kiki(self) -> bool {
+	/// Suit value is 2 bits, is_red is the low bit.
+	pub const fn suit_high_bit(self) -> bool {
 		self as u8 & 0b10 != 0
 	}
 }
@@ -120,11 +135,11 @@ impl Rank {
 		}
 	}
 }
-/// An identifier which specifies the deck id, suit, and card value.
+
+/// A card which specifies the deck id, suit, and card value.
 /// 2 bits for deck ID
 /// 2 bits for suit ID
 /// 4 bits for card Value
-/// TODO: better encoding for slightly more decks
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct Card(core::num::NonZeroU8);
 impl Card {
@@ -137,9 +152,9 @@ impl Card {
 		Rank::new(masked).unwrap()
 	}
 	pub const fn suit(&self) -> Suit {
-		let red = self.is_red();
-		let kiki = self.is_kiki();
-		match (kiki, red) {
+		let low_bit = self.is_red();
+		let high_bit = self.suit_high_bit();
+		match (high_bit, low_bit) {
 			(false, false) => Suit::Spades,
 			(false, true) => Suit::Hearts,
 			(true, false) => Suit::Clubs,
@@ -150,8 +165,8 @@ impl Card {
 	pub const fn is_red(&self) -> bool {
 		self.0.get() & 0b010000 != 0
 	}
-	/// Is the suit shape spikey.  (Bouba/kiki)
-	pub const fn is_kiki(&self) -> bool {
+	/// Suit value is 2 bits, is_red is the low bit.
+	pub const fn suit_high_bit(&self) -> bool {
 		self.0.get() & 0b100000 != 0
 	}
 	pub const fn deck(&self) -> Deck {
@@ -159,7 +174,7 @@ impl Card {
 	}
 }
 
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
 pub struct Stack<const CAP: usize>(arrayvec::ArrayVec<Card, CAP>);
 impl<const CAP: usize> Stack<CAP> {
 	pub const fn new() -> Self {
@@ -210,19 +225,20 @@ impl<const CAP: usize> IntoIterator for Stack<CAP> {
 	}
 }
 
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+/// A pile is a stack of face down cards and a stack of face up cards.
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
 pub struct Pile<const DN: usize, const UP: usize> {
 	face_down: Stack<DN>,
 	face_up: Stack<UP>,
 }
 impl<const DN: usize, const UP: usize> Pile<DN, UP> {
-	pub fn new() -> Self {
+	pub const fn new() -> Self {
 		Self {
 			face_down: Stack::new(),
 			face_up: Stack::new(),
 		}
 	}
-	pub fn new_face_down(stack: Stack<DN>) -> Self {
+	pub const fn new_face_down(stack: Stack<DN>) -> Self {
 		Self {
 			face_down: stack,
 			face_up: Stack::new(),
@@ -277,7 +293,7 @@ impl<const CAP: usize> Pile<CAP, CAP> {
 		self.swap_up_down();
 		self.face_down.reverse();
 	}
-	pub fn swap_up_down(&mut self) {
+	pub const fn swap_up_down(&mut self) {
 		core::mem::swap(&mut self.face_up, &mut self.face_down);
 	}
 }
@@ -305,21 +321,33 @@ impl<S> SessionStats<S> {
 	}
 }
 
+#[derive(Clone, Debug)]
 pub struct Session<G: Game> {
 	stats: SessionStats<G::Stats>,
 	config: G::Config,
 	state: SessionState<G>,
 }
-#[derive(Clone, Eq, Hash, PartialEq)]
-pub struct SessionState<G: Game> {
-	seed: G,
+#[derive(Clone, Debug)]
+pub struct StateSnapshot<G: Game> {
 	state: G,
-	history: Vec<G::Instruction>,
+	instruction: G::Instruction,
+}
+impl<G: Game> StateSnapshot<G> {
+	pub const fn state(&self) -> &G {
+		&self.state
+	}
+	pub const fn instruction(&self) -> &G::Instruction {
+		&self.instruction
+	}
+}
+#[derive(Clone, Debug)]
+pub struct SessionState<G: Game> {
+	state: G,
+	history: Vec<StateSnapshot<G>>,
 }
 impl<G: Game + Clone> SessionState<G> {
 	fn new(state: G) -> Self {
 		Self {
-			seed: state.clone(),
 			state,
 			history: Vec::new(),
 		}
@@ -329,6 +357,7 @@ impl<G: Game> Session<G>
 where
 	G: Clone + Eq + core::hash::Hash,
 	G::Stats: Clone + Default,
+	G::Config: Clone,
 	G::Instruction: Clone + Eq + core::hash::Hash,
 {
 	pub fn new(state: G, config: G::Config) -> Self {
@@ -353,7 +382,7 @@ where
 	pub const fn config(&self) -> &G::Config {
 		&self.config
 	}
-	pub fn history(&self) -> &[G::Instruction] {
+	pub fn history(&self) -> &[StateSnapshot<G>] {
 		&self.state.history
 	}
 	pub fn undo(&mut self) {
@@ -373,48 +402,62 @@ where
 	pub fn is_win(&self) -> bool {
 		self.state.is_win()
 	}
-	pub fn is_winnable(&self) -> Option<Vec<G::Instruction>> {
-		let mut observed = std::collections::HashSet::new();
-		struct StateMachine<G, P, I> {
-			state: G,
-			possible_instructions_iter: P,
-			instruction: I,
-		}
-		let mut dummy_stats = self.stats.inner_stats.clone();
-		let mut state = self.state.state.clone();
-		let mut it = state.possible_instructions();
-		let mut path = Vec::new();
-		'outer: while !state.is_win() {
-			observed.insert(state.clone());
-			for instruction in &mut it {
-				let mut next_state = state.clone();
-				next_state.process_instruction(&mut dummy_stats, &self.config, instruction.clone());
-				if !observed.contains(&next_state) {
-					let possible_instructions_iter =
-						core::mem::replace(&mut it, next_state.possible_instructions());
-					let state = core::mem::replace(&mut state, next_state);
-					path.push(StateMachine {
-						state,
-						possible_instructions_iter,
-						instruction,
-					});
-					continue 'outer;
-				}
+	pub fn is_winnable(&self) -> Option<Vec<StateSnapshot<G>>> {
+		let mut state_moves = std::collections::HashMap::new();
+		let mut state = self.clone();
+		let mut i: u64 = 0;
+		while !state.is_win() {
+			// Continue existing iterator if it exists
+			let it = state_moves
+				.entry(state.state().clone())
+				.or_insert_with(|| state.state().possible_instructions());
+
+			// Run one possible move
+			if let Some(instruction) = it.next() {
+				state.process_instruction(instruction);
+				continue;
 			}
-			let Some(last_state) = path.pop() else {
+
+			// No more moves. If we can't undo we're done
+			if state.history().is_empty() {
 				return None;
-			};
-			state = last_state.state;
-			it = last_state.possible_instructions_iter;
+			} else {
+				state.undo();
+			}
 		}
-		Some(path.into_iter().map(|state| state.instruction).collect())
+
+		// history includes cycles
+		let mut state_index: std::collections::HashMap<_, _> = state
+			.history()
+			.iter()
+			.enumerate()
+			.map(|(i, snapshot)| (snapshot.state().clone(), i))
+			.collect();
+
+		// find the longest range where the start and end are the same state
+		while let Some(longest_range) = state
+			.history()
+			.iter()
+			.enumerate()
+			.filter_map(|(index, snapshot)| {
+				let &last_index = state_index.get(snapshot.state())?;
+				let longness = last_index - index;
+				(longness != 0).then_some(index..last_index)
+			})
+			.max_by_key(|range| range.len())
+		{
+			state.state.history.drain(longest_range);
+			for (i, snapshot) in state.history().iter().enumerate() {
+				state_index.insert(snapshot.state().clone(), i);
+			}
+		}
+
+		Some(state.state.history)
 	}
 }
 impl<G: Game> Game for SessionState<G>
 where
-	G: Clone,
 	G::Stats: Default,
-	G::Instruction: Clone,
 {
 	type Stats = SessionStats<G::Stats>;
 	type Config = G::Config;
@@ -440,19 +483,16 @@ where
 	) {
 		match instruction {
 			SessionInstruction::Undo => {
-				// replay the entire history of the game except one move
-				self.history.pop();
-				let mut inner_stats = G::Stats::default();
-				let mut state = self.seed.clone();
-				for instruction in &self.history {
-					state.process_instruction(&mut inner_stats, config, instruction.clone());
+				if let Some(snapshot) = self.history.pop() {
+					self.state = snapshot.state;
+					stats.increment_undos();
 				}
-				self.state = state;
-				stats.inner_stats = inner_stats;
-				stats.increment_undos();
 			}
 			SessionInstruction::InnerInstruction(instruction) => {
-				self.history.push(instruction.clone());
+				self.history.push(StateSnapshot {
+					state: self.state.clone(),
+					instruction: instruction.clone(),
+				});
 				self.state
 					.process_instruction(&mut stats.inner_stats, config, instruction);
 			}

klondike-bench/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "klondike-bench"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+card_game.workspace = true
+klondike.workspace = true
+rand = { version = "0.10.1", default-features = false }
+
+[lints]
+workspace = true

klondike-bench/src/main.rs

@@ -0,0 +1,46 @@
+use card_game::Game;
+use klondike::{Klondike, KlondikeConfig, KlondikeStats, Rng};
+
+const MAX_MOVES: usize = 250;
+
+fn play_to_win(rng: &mut Rng) -> Option<KlondikeStats> {
+	// create game session
+	let mut game = Klondike::with_rng(rng);
+	let mut stats = KlondikeStats::new();
+	const CONFIG: KlondikeConfig = KlondikeConfig {
+		draw_stock: klondike::DrawStockConfig::DrawOne,
+	};
+	// play game a bit
+	while let Some(instruction) = game.get_auto_move()
+		&& !game.is_win()
+	{
+		// quit before 250 moves
+		if MAX_MOVES < stats.moves() + 1 {
+			return None;
+		}
+
+		game.process_instruction(&mut stats, &CONFIG, instruction);
+	}
+	game.is_win().then_some(stats)
+}
+fn main() {
+	use rand::SeedableRng;
+	let mut rng = Rng::seed_from_u64(0);
+	const GAMES: u32 = 1000;
+	let mut wins = 0;
+	let mut score_tally = [0usize; MAX_MOVES * 10 / 5];
+	let mut recycle_tally = [0usize; MAX_MOVES];
+	let mut moves_tally = [0usize; MAX_MOVES];
+	for _ in 0..GAMES {
+		if let Some(stats) = play_to_win(&mut rng) {
+			wins += 1;
+			score_tally[stats.score() / 5] += 1;
+			recycle_tally[stats.recycle_count()] += 1;
+			moves_tally[stats.moves()] += 1;
+		}
+	}
+	println!("score_tally={score_tally:?}");
+	println!("recycle_tally={recycle_tally:?}");
+	println!("moves_tally={moves_tally:?}");
+	println!("wins = {wins}/{GAMES} win_rate = {}%", wins * 100 / GAMES);
+}

klondike-cli/Cargo.toml

@@ -4,5 +4,9 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
-card_game = { version = "0.1.0", path = "../card_game" }
-klondike = { version = "0.1.0", path = "../klondike" }
+card_game.workspace = true
+klondike.workspace = true
+rand = { version = "0.10.1", default-features = false, features = ["thread_rng"] }
+
+[lints]
+workspace = true

klondike-cli/src/main.rs

@@ -4,6 +4,9 @@ use klondike::{
 	KlondikePile, KlondikePileStack, KlondikeStats, SkipCards, Tableau, TableauStack,
 };
 
+#[cfg(test)]
+mod test;
+
 use std::fmt::Display;
 struct Displayed<T>(T);
 
@@ -87,10 +90,11 @@ impl Display for Displayed<&SessionStats<KlondikeStats>> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
 		write!(
 			f,
-			"recycles: {} moves: {} undos: {}",
+			"recycles: {} moves: {} undos: {} score:{}",
 			self.0.stats().recycle_count(),
 			self.0.stats().moves(),
-			self.0.undos()
+			self.0.undos(),
+			self.0.stats().score() as isize - self.0.undos() as isize * 15,
 		)
 	}
 }
@@ -208,56 +212,20 @@ fn find_valid_instruction(
 		.then_some(instruction)
 }
 
-fn get_good_move(state: &Klondike) -> Option<KlondikeInstruction> {
-	fn useless_moves(instruction: &KlondikeInstruction) -> bool {
-		!matches!(
-			instruction,
-			// foundation -> foundation is a useless move
-			KlondikeInstruction::DstFoundation(DstFoundation {
-				src: KlondikePile::Foundation(_),
-				..
-			})
-		)
-	}
-	fn instruction_priority(state: &Klondike, instruction: &KlondikeInstruction) -> usize {
-		// 1 Move into foundation
-		// 2 T->T Move to reveal new card (moving a non-king to reveal empty tableau also counts)
-		// 3 Move from stock
-		// 4 Rotate stock
-		// 5 T->T Move not revealing new card
-		// 6 Move from foundation
-		match instruction {
-			KlondikeInstruction::DstFoundation(_) => 1,
-			&KlondikeInstruction::DstTableau(dst_tableau) => match dst_tableau.src {
-				KlondikePileStack::Tableau(TableauStack {
-					tableau,
-					skip_cards: SkipCards::Skip0,
-				}) if !state.state().is_tableau_face_down_empty(tableau)
-					|| state
-						.state()
-						.stack_bottom_card(dst_tableau.src)
-						.is_some_and(|card| card.rank() != Rank::King) =>
-				{
-					2
-				}
-				KlondikePileStack::Stock => 3,
-				KlondikePileStack::Tableau(_) => 5,
-				KlondikePileStack::Foundation(_) => 6,
-			},
-			KlondikeInstruction::RotateStock => 4,
-		}
-	}
-	state
-		.possible_instructions()
-		.filter(useless_moves)
-		.min_by_key(|ins| instruction_priority(state, ins))
-}
-
 fn main() -> Result<(), std::io::Error> {
-	let mut session = Session::new_default(Klondike::new_random());
+	use rand::RngExt;
+	let mut rng = rand::rng();
+	// seed from cli argument
+	let mut seed = if let Some(seed) = std::env::args().skip(1).next() {
+		seed.parse().expect("Invalid u64 seed")
+	} else {
+		rng.random()
+	};
+	let mut session = Session::new_default(Klondike::with_seed(seed));
 	let mut input = String::new();
 	loop {
 		// display stats
+		println!("seed: {seed} ");
 		println!("{}", Displayed(session.stats()));
 		// display game
 		println!("{}", Displayed(session.state()));
@@ -272,7 +240,10 @@ fn main() -> Result<(), std::io::Error> {
 
 		// run game
 		match instruction {
-			SessionInstruction::New => session = Session::new_default(Klondike::new_random()),
+			SessionInstruction::New => {
+				seed = rng.random();
+				session = Session::new_default(Klondike::with_seed(seed))
+			}
 			SessionInstruction::Undo => session.undo(),
 			SessionInstruction::Exit => break Ok(()),
 			SessionInstruction::Hint => {
@@ -281,7 +252,7 @@ fn main() -> Result<(), std::io::Error> {
 				}
 			}
 			SessionInstruction::Auto => {
-				if let Some(instruction) = get_good_move(session.state()) {
+				if let Some(instruction) = session.state().get_auto_move() {
 					session.process_instruction(instruction);
 				} else {
 					println!("No valid moves!");

klondike-cli/src/test.rs

@@ -0,0 +1,15 @@
+use card_game::Session;
+use klondike::Klondike;
+#[test]
+fn test_is_winnable() {
+	// is winnable
+	let is_winnable = Session::new_default(Klondike::with_seed(124)).is_winnable();
+	if let Some(win_moves) = is_winnable {
+		// for (i, ins) in win_moves.into_iter().enumerate() {
+		// 	println!("{i} = {:?}", ins.instruction());
+		// }
+		println!("Game is winnable with {} moves", win_moves.len());
+	} else {
+		println!("Game is not winnable");
+	}
+}

klondike/Cargo.toml

@@ -4,5 +4,8 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
-card_game = { version = "0.1.0", path = "../card_game" }
-rand = { version = "0.10.1", default-features = false, features = ["thread_rng"] }
+card_game.workspace = true
+rand = { version = "0.10.1", default-features = false, features = ["std_rng"] }
+
+[lints]
+workspace = true

klondike/LICENSE-APACHE

@@ -0,0 +1,176 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

klondike/LICENSE-MIT

@@ -0,0 +1,23 @@
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

klondike/README.md

@@ -1,25 +1,26 @@
-Card Game
-=========
+Klondike
+========
 
-`card_game` is a library to implement card games.  Mainly interesting for the `Game` trait and the `Session` type.  Contains klondike as the reference implementation.
+`klondike` is a pure-logic implementation of Klondike using `card_game`.  Graphics not included.
 
 ## Example
 
 ```rust
-use card_game::Rng;
-use card_game::card_game::{Session, Game};
-use card_game::klondike::Klondike;
+use card_game::Session;
+use klondike::Klondike;
 
 // create game session
-let game = Klondike::new_random();
+let game = Klondike::with_seed(123);
 let mut session = Session::new_default(game);
 
-// is winnable
-let is_winnable = session.is_winnable().is_some();
-
-// play game
-while let Some(instruction) = session.possible_instructions().next() {
+// play game a bit
+while let Some(instruction) = session.state().get_auto_move() {
 	session.process_instruction(instruction);
+
+	// quit after 1000 moves
+	if 1000 < session.stats().stats().moves() {
+		break;
+	}
 }
 
 // did win
@@ -30,7 +31,6 @@ for (i, instruction) in session.history().iter().enumerate() {
 	println!("move {i} = {instruction:?}");
 }
 
-println!("is_winnable = {is_winnable}");
 println!("is_win = {is_win}");
 ```
 

klondike/src/lib.rs

@@ -1,17 +1,14 @@
-pub type Rng = rand::rngs::ThreadRng;
+pub type Rng = rand::rngs::StdRng;
 
 use card_game::{Card, Game, Pile, Rank, Stack};
 
-#[cfg(test)]
-mod test;
-
 // test readme
 #[doc = include_str!("../README.md")]
 #[cfg(doctest)]
 struct ReadmeDoctests;
 
 #[derive(Clone, Copy, Debug, Default)]
-enum DrawStockConfig {
+pub enum DrawStockConfig {
 	#[default]
 	DrawOne = 1,
 	DrawThree = 3,
@@ -19,39 +16,40 @@ enum DrawStockConfig {
 
 #[derive(Clone, Debug, Default)]
 pub struct KlondikeConfig {
-	draw_stock: DrawStockConfig,
-}
-impl KlondikeConfig {
-	pub const fn draw_one_stock() -> Self {
-		KlondikeConfig {
-			draw_stock: DrawStockConfig::DrawOne,
-		}
-	}
-	pub const fn draw_three_stock() -> Self {
-		KlondikeConfig {
-			draw_stock: DrawStockConfig::DrawThree,
-		}
-	}
+	pub draw_stock: DrawStockConfig,
 }
 
 #[derive(Clone, Debug, Default)]
 pub struct KlondikeStats {
+	score: usize,
 	recycle_count: usize,
 	moves: usize,
 }
 impl KlondikeStats {
 	pub const fn new() -> Self {
 		KlondikeStats {
+			score: 0,
 			recycle_count: 0,
 			moves: 0,
 		}
 	}
+	pub const fn score(&self) -> usize {
+		self.score
+	}
 	pub const fn recycle_count(&self) -> usize {
 		self.recycle_count
 	}
 	pub const fn moves(&self) -> usize {
 		self.moves
 	}
+	/// A card was moved to a foundation.
+	const fn increment_score_foundation(&mut self) {
+		self.score += 10;
+	}
+	/// A card was moved from stock to tableau.
+	const fn increment_score_tableau(&mut self) {
+		self.score += 5;
+	}
 	const fn increment_recycle_count(&mut self) {
 		self.recycle_count += 1;
 	}
@@ -301,6 +299,16 @@ impl KlondikeInstruction {
 			Self::RotateStock => return None,
 		})
 	}
+	/// foundation -> foundation is a useless move
+	pub fn is_useless(&self) -> bool {
+		matches!(
+			self,
+			KlondikeInstruction::DstFoundation(DstFoundation {
+				src: KlondikePile::Foundation(_),
+				..
+			})
+		)
+	}
 }
 
 const TABLEAUS: usize = 7;
@@ -525,20 +533,26 @@ impl Iterator for KlondikeIter {
 		instruction
 	}
 }
+#[test]
+fn test_klondike_iter() {
+	assert_eq!(KlondikeIter::new().count(), 721);
+}
 
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct Klondike {
 	state: KlondikeState,
 }
 impl Klondike {
-	pub fn new_random() -> Self {
-		Self::new(Rng::default())
+	pub fn with_seed(seed: u64) -> Self {
+		use rand::SeedableRng;
+		let mut rng = Rng::seed_from_u64(seed);
+		Self::with_rng(&mut rng)
 	}
-	pub fn new(mut seed: Rng) -> Self {
+	pub fn with_rng(rng: &mut Rng) -> Self {
 		// shuffle a new deck
 		let mut deck = Stack::full_deck(card_game::Deck::Deck1);
 		use rand::seq::SliceRandom;
-		deck.shuffle(&mut seed);
+		deck.shuffle(rng);
 		let mut deck = deck.into_iter();
 
 		// generate tableaus
@@ -575,6 +589,62 @@ impl Klondike {
 	pub const fn state(&self) -> &KlondikeState {
 		&self.state
 	}
+	/// Check if the game should be auto-completed
+	pub fn is_win_trivial(&self) -> bool {
+		// all face down cards empty means win
+		self.state.stock.face_down().is_empty()
+			&& self.state.tableau1.face_down().is_empty()
+			&& self.state.tableau2.face_down().is_empty()
+			&& self.state.tableau3.face_down().is_empty()
+			&& self.state.tableau4.face_down().is_empty()
+			&& self.state.tableau5.face_down().is_empty()
+			&& self.state.tableau6.face_down().is_empty()
+			&& self.state.tableau7.face_down().is_empty()
+	}
+	fn instruction_priority(&self, instruction: &KlondikeInstruction) -> usize {
+		// 1 Move into foundation
+		// 2 T->T Move to reveal new card (moving a non-king to reveal empty tableau also counts)
+		// 3 Move from stock
+		// 4 Rotate stock
+		// 5 T->T Move not revealing new card
+		// 6 Move from foundation
+		match instruction {
+			KlondikeInstruction::DstFoundation(_) => 1,
+			&KlondikeInstruction::DstTableau(dst_tableau) => match dst_tableau.src {
+				KlondikePileStack::Tableau(TableauStack {
+					tableau,
+					skip_cards: SkipCards::Skip0,
+				}) if !self.state().is_tableau_face_down_empty(tableau)
+					|| self
+						.state()
+						.stack_bottom_card(dst_tableau.src)
+						.is_some_and(|card| card.rank() != Rank::King) =>
+				{
+					2
+				}
+				KlondikePileStack::Stock => 3,
+				KlondikePileStack::Tableau(_) => 5,
+				KlondikePileStack::Foundation(_) => 6,
+			},
+			KlondikeInstruction::RotateStock => 4,
+		}
+	}
+	pub fn iter(&self) -> impl Iterator<Item = KlondikeInstruction> + use<> {
+		let state = self.state.clone();
+		KlondikeIter::new().filter(move |&instruction| state.is_instruction_valid(instruction))
+	}
+	/// A single move that usually makes progress towards a winning game
+	pub fn get_auto_move(&self) -> Option<KlondikeInstruction> {
+		self.iter()
+			.filter(|ins| !ins.is_useless())
+			.min_by_key(|ins| self.instruction_priority(ins))
+	}
+	/// A list of possible moves with useless moves filtered out and sorted by a simple priority function
+	pub fn get_sorted_moves(&self) -> Vec<KlondikeInstruction> {
+		let mut useful_moves: Vec<_> = self.iter().filter(|ins| !ins.is_useless()).collect();
+		useful_moves.sort_by_key(|ins| self.instruction_priority(ins));
+		useful_moves
+	}
 }
 
 impl Game for Klondike {
@@ -582,8 +652,7 @@ impl Game for Klondike {
 	type Config = KlondikeConfig;
 	type Instruction = KlondikeInstruction;
 	fn possible_instructions(&self) -> impl Iterator<Item = Self::Instruction> + use<> {
-		let state = self.state.clone();
-		KlondikeIter::new().filter(move |&instruction| state.is_instruction_valid(instruction))
+		self.get_sorted_moves().into_iter()
 	}
 	fn is_instruction_valid(&self, _config: &Self::Config, instruction: Self::Instruction) -> bool {
 		self.state.is_instruction_valid(instruction)
@@ -609,25 +678,28 @@ impl Game for Klondike {
 			}
 			// Move a card from anywhere to a foundation
 			KlondikeInstruction::DstFoundation(DstFoundation { src, foundation }) => {
+				stats.increment_score_foundation();
 				let card = self.state.take_top_card(src);
 				self.state.extend_foundation(foundation, card);
 			}
 			// Move a stack of cards from anywhere to a tableau
 			KlondikeInstruction::DstTableau(DstTableau { src, tableau }) => {
+				if src == KlondikePileStack::Stock {
+					stats.increment_score_tableau();
+				}
 				let cards = self.state.take_stack(src);
 				self.state.extend_tableau(tableau, cards);
 			}
 		}
 	}
 	fn is_win(&self) -> bool {
-		// all face down cards empty means win
-		self.state.stock.face_down().is_empty()
-			&& self.state.tableau1.face_down().is_empty()
-			&& self.state.tableau2.face_down().is_empty()
-			&& self.state.tableau3.face_down().is_empty()
-			&& self.state.tableau4.face_down().is_empty()
-			&& self.state.tableau5.face_down().is_empty()
-			&& self.state.tableau6.face_down().is_empty()
-			&& self.state.tableau7.face_down().is_empty()
+		// all foundations contain all ranks
+		self.state.foundations.iter().all(|foundation| {
+			foundation.len() == Rank::RANKS.len()
+				&& foundation
+					.iter()
+					.zip(Rank::RANKS)
+					.all(|(card, rank)| card.rank() == rank)
+		})
 	}
 }

klondike/src/test.rs

@@ -1,33 +0,0 @@
-use crate::Klondike;
-use card_game::Session;
-#[test]
-fn test_is_winnable() {
-	// is winnable
-	let is_winnable = Session::new_default(Klondike::new_random()).is_winnable();
-	println!("is_winnable = {is_winnable:?}");
-}
-#[test]
-fn test_klondike() {
-	// create game session
-	let game = Klondike::new_random();
-	let mut session = Session::new_default(game);
-
-	// is winnable
-	let is_winnable = session.is_winnable();
-	println!("is_winnable = {is_winnable:?}");
-
-	// play game
-	while let Some(instruction) = session.possible_instructions().next() {
-		session.process_instruction(instruction);
-	}
-
-	// did win
-	let is_win = session.is_win();
-
-	// print session history
-	for (i, instruction) in session.history().iter().enumerate() {
-		println!("move {i} = {instruction:?}");
-	}
-
-	println!("is_win = {is_win}");
-}