visualize forced endings

Author: Ferdinand Schober

Cargo.lock

@@ -16,6 +16,7 @@ solitaire-solver = { path = "./solitaire-solver", version = "0.0.1" }
 
 [dev-dependencies]
 rayon = "1.11.0"
+rand = "0.10"
 
 # run build.rs in release mode, otherwise it takes 100 years
 [profile.dev.build-override]

Cargo.toml

@@ -1,8 +1,11 @@
 use bevy::prelude::*;
 use bevy_vector_shapes::prelude::*;
-use solitaire_solver::{Board, Dir};
 
-use crate::{BoardPosition, CurrentBoard, board::MARKER_POS, solver::FeasibleConstellations};
+use crate::{
+    BoardPosition, CurrentBoard,
+    board::MARKER_POS,
+    solver::{FeasibleConstellations, ForcedJumps},
+};
 
 pub struct HintsPlugin;
 
@@ -12,7 +15,7 @@ impl Plugin for HintsPlugin {
         app.add_observer(update_hints);
         app.add_systems(
             Update,
-            draw_possible_moves.run_if(
+            (draw_possible_moves, draw_forced_jumps).run_if(
                 resource_exists::<ShowHints>.and_then(resource_exists::<FeasibleConstellations>),
             ),
         );
@@ -33,36 +36,89 @@ fn update_hints(_: On<ToggleHints>, mut commands: Commands, show_hints: Option<R
     }
 }
 
+/// Draws one marker per legal move: green if a win is still reachable after it, red if not.
+///
+/// Within the feasible set, a successor being feasible is exactly it being able to reach the
+/// solved board, so this two-state colouring is already complete information about the moves
+/// available *now* - including "only one of these is green", which is what makes a move
+/// forced. Colouring that case specially was tried and dropped: it told the player nothing
+/// they could not see by counting green lines. What they cannot see is
+/// [`draw_forced_jumps`].
 fn draw_possible_moves(
     mut painter: ShapePainter,
     board: Res<CurrentBoard>,
     feasible: Res<FeasibleConstellations>,
 ) {
-    let feasible = &feasible.0;
-    for y in 0..Board::SIZE {
-        for x in 0..Board::SIZE {
-            for dir in [Dir::North, Dir::East, Dir::South, Dir::West] {
-                if !board.0.occupied((y, x)) {
-                    continue;
-                }
-                if let Some(mov) = board.0.get_legal_move((y, x), dir) {
-                    let start = BoardPosition::from(mov.pos).to_world_space();
-                    let start = Vec3::from((start, MARKER_POS));
-                    let target = BoardPosition::from(mov.target).to_world_space();
-                    let target = Vec3::from((target, MARKER_POS));
-                    painter.set_color(if feasible.contains(&board.0.mov(mov).normalize()) {
-                        Color::srgba(0., 1., 0., 1.)
-                    } else {
-                        Color::srgba(1., 0., 0., 1.)
-                    });
-                    painter.set_translation(Vec3::new(0., 0., 0.1));
-                    painter.thickness_type = ThicknessType::World;
-                    painter.thickness = 0.075;
-                    painter.line(start, start + (target - start) * 0.2);
-                    painter.set_translation(start.xyz());
-                    painter.circle(0.1);
-                }
-            }
+    for mov in board.0.get_legal_moves() {
+        let start = BoardPosition::from(mov.pos).to_world_space();
+        let start = Vec3::from((start, MARKER_POS));
+        let target = BoardPosition::from(mov.target).to_world_space();
+        let target = Vec3::from((target, MARKER_POS));
+
+        let winning = feasible.0.contains(&board.0.mov(mov).normalize());
+        painter.set_color(if winning {
+            Color::srgba(0., 1., 0., 1.)
+        } else {
+            Color::srgba(1., 0., 0., 1.)
+        });
+        painter.thickness_type = ThicknessType::World;
+        painter.thickness = 0.075;
+        painter.set_translation(Vec3::new(0., 0., 0.1));
+        painter.line(start, start + (target - start) * 0.2);
+        painter.set_translation(start.xyz());
+        painter.circle(0.1);
+    }
+}
+
+/// Ghosts the jumps the player is already committed to making later on.
+///
+/// This is the one thing the per-move colouring cannot show, because it is not about the
+/// moves available now: these jumps are not legal yet, and may not be for another dozen
+/// moves, but every winning continuation from the current position makes them. See
+/// [`solitaire_solver::dominators::forced_jumps`] - and in particular why it works in the
+/// player's own frame rather than the normalized quotient, which would claim the four
+/// symmetric opening moves are one forced step.
+///
+/// Drawn unlike [`draw_possible_moves`]: the full span from origin to landing slot rather
+/// than a stub, amber, and translucent, fading with how far off the jump is. Nothing is drawn
+/// while the result is stale - it is recomputed off-thread on every move and near the opening
+/// that takes seconds, so a result for a position already left has to be suppressed rather
+/// than shown late.
+fn draw_forced_jumps(
+    mut painter: ShapePainter,
+    board: Res<CurrentBoard>,
+    forced: Option<Res<ForcedJumps>>,
+) {
+    let Some(forced) = forced else {
+        return;
+    };
+    if forced.board != board.0 {
+        return;
+    }
+
+    let pegs = board.0.count_pegs();
+    for jump in &forced.jumps {
+        // a forced jump *out of the current board* is exactly the single-green-line case, and
+        // `draw_possible_moves` already draws it
+        let ahead = pegs.saturating_sub(jump.board.count_pegs());
+        if ahead == 0 {
+            continue;
         }
+
+        let start = BoardPosition::from(jump.mov.pos).to_world_space();
+        let start = Vec3::from((start, MARKER_POS));
+        let target = BoardPosition::from(jump.mov.target).to_world_space();
+        let target = Vec3::from((target, MARKER_POS));
+
+        // the soonest forced jump reads strongest; twenty moves out is barely there
+        let fade = 1.0 - (ahead as f32 / 20.0).clamp(0.0, 1.0);
+        let alpha = 0.15f32.lerp(0.7, fade);
+        painter.set_color(Color::srgba(1.0, 0.72, 0.15, alpha));
+        painter.thickness_type = ThicknessType::World;
+        painter.thickness = 0.05;
+        painter.set_translation(Vec3::new(0., 0., 0.1));
+        painter.line(start, target);
+        painter.set_translation(target.xyz());
+        painter.circle(0.06);
     }
 }

solitaire-game/src/hints.rs

@@ -1,4 +1,5 @@
 use futures_lite::future::{self, block_on};
+use solitaire_solver::dominators::{ForcedJump, forced_jumps};
 use solitaire_solver::{HashMap, HashSet, SolutionMultiset};
 
 use bevy::{
@@ -8,6 +9,7 @@ use bevy::{
     window::RequestRedraw,
     winit::{EventLoopProxyWrapper, WinitUserEvent::WakeUp},
 };
+use crate::CurrentBoard;
 use solitaire_solver::Board;
 
 pub struct Solver;
@@ -28,6 +30,11 @@ impl Plugin for Solver {
             Update,
             calculate_unique_paths.run_if(resource_added::<FeasibleConstellations>),
         );
+        app.add_systems(
+            Update,
+            schedule_forced_jumps
+                .run_if(resource_exists::<UniquePaths>.and_then(not(resource_exists::<ForcedJumpsPending>))),
+        );
         app.add_systems(Update, poll_task);
     }
 }
@@ -42,7 +49,23 @@ pub struct RandomMoveChances(pub HashMap<Board, f64>);
 pub struct UniqueSolutions(pub Vec<SolutionMultiset>);
 
 #[derive(Resource)]
-pub struct UniquePaths(pub HashMap<Board, u64>);
+pub struct UniquePaths(pub std::sync::Arc<HashMap<Board, u64>>);
+
+/// The jumps every winning continuation from [`board`](Self::board) still has to make.
+///
+/// Carries the board it was computed for because it is computed off-thread and the player can
+/// move meanwhile: a result for a position that has since been left is worse than none, so
+/// consumers compare against [`crate::CurrentBoard`] before trusting it.
+#[derive(Resource)]
+pub struct ForcedJumps {
+    pub board: Board,
+    pub jumps: Vec<ForcedJump>,
+}
+
+/// Present while a [`ForcedJumps`] computation is in flight, so moves made during a long one
+/// queue up as "recompute when it lands" rather than stacking a task per move.
+#[derive(Resource)]
+struct ForcedJumpsPending;
 
 /// A unit of work running on the async pool, polled by [`poll_task`].
 ///
@@ -143,7 +166,56 @@ fn calculate_unique_paths(
 
         let mut command_queue = CommandQueue::default();
         command_queue.push(move |world: &mut World| {
-            world.insert_resource(UniquePaths(unique_paths));
+            world.insert_resource(UniquePaths(std::sync::Arc::new(unique_paths)));
+            world.entity_mut(entity).remove::<BackgroundTask>();
+        });
+        wake.send_event(WakeUp).unwrap();
+        command_queue
+    });
+    commands.entity(entity).insert(BackgroundTask { task });
+}
+
+/// Recomputes [`ForcedJumps`] whenever it is missing or stale for the current board.
+///
+/// Not cheap early on - the traversal covers every still-winnable board reachable from the
+/// current one, which near the opening is most of the game: measured at ~16 s and ~190 MB of
+/// transient set at 32 pegs, falling to ~460 ms by 26 pegs and under 10 ms by 24. That is why
+/// it runs on the async pool and why the result is stamped with its board instead of assumed
+/// current. It is also why it is worth doing at all rather than per-frame: the answer only
+/// changes when the board does.
+///
+/// The opening is also where it has nothing to report - the earliest position with a forced
+/// jump over 60 sampled winning lines was 27 pegs - so the expensive end of the range is the
+/// end that returns empty. Left uncapped anyway: a peg-count cutoff would be a silent claim
+/// that nothing is forced above it, which the sampling does not establish.
+fn schedule_forced_jumps(
+    mut commands: Commands,
+    board: Res<CurrentBoard>,
+    paths: Res<UniquePaths>,
+    forced: Option<Res<ForcedJumps>>,
+    wake: Res<EventLoopProxyWrapper>,
+) {
+    if forced.is_some_and(|forced| forced.board == board.0) {
+        return;
+    }
+    let thread_pool = AsyncComputeTaskPool::get();
+    let entity = commands.spawn_empty().id();
+    let target = board.0;
+    // an `Arc` clone: this runs on every move, and the counts map is one entry per
+    // feasible board - copying it per move would dwarf the traversal it feeds
+    let counts = paths.0.clone();
+    let wake = wake.clone();
+    commands.insert_resource(ForcedJumpsPending);
+    let task = thread_pool.spawn(async move {
+        let jumps = forced_jumps(target, &counts);
+
+        let mut command_queue = CommandQueue::default();
+        command_queue.push(move |world: &mut World| {
+            world.insert_resource(ForcedJumps {
+                board: target,
+                jumps,
+            });
+            world.remove_resource::<ForcedJumpsPending>();
             world.entity_mut(entity).remove::<BackgroundTask>();
         });
         wake.send_event(WakeUp).unwrap();