fix: avoid rendering path lines between far apart cells

.github/workflows/audit.yaml

@@ -1,27 +0,0 @@
-name: Audit
-
-on: ["push", "pull_request"]
-
-env:
-  CARGO_TERM_COLOR: always
-  RUST_TOOLCHAIN: 1.88.0
-
-jobs:
-  audit:
-    name: Audit
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@master
-        with:
-          toolchain: ${{ env.RUST_TOOLCHAIN }}
-
-      - name: Install cargo-audit
-        run: cargo install cargo-audit
-
-      - name: Run security audit
-        run: cargo audit

.github/workflows/build.yaml

@@ -1,5 +1,4 @@
 name: Builds
-
 on: ["push", "pull_request"]
 
 permissions:

.github/workflows/coverage.yaml

@@ -1,4 +1,4 @@
-name: Coverage
+name: Code Coverage
 
 on: ["push", "pull_request"]
 
@@ -8,7 +8,6 @@ env:
 
 jobs:
   coverage:
-    name: Code Coverage
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

.github/workflows/tests.yaml

@@ -1,4 +1,4 @@
-name: Tests
+name: Tests & Checks
 
 on: ["push", "pull_request"]
 
@@ -8,7 +8,6 @@ env:
 
 jobs:
   test:
-    name: Test
     runs-on: ubuntu-latest
 
     steps:
@@ -52,3 +51,8 @@ jobs:
 
       - name: Check formatting
         run: cargo fmt -- --check
+
+      - uses: taiki-e/install-action@cargo-audit
+
+      - name: Run security audit
+        run: cargo audit

README.md

@@ -2,14 +2,14 @@
 
 [![Tests Status][badge-test]][test] [![Build Status][badge-build]][build] [![Code Coverage][badge-coverage]][coverage] [![Online Demo][badge-online-demo]][demo] [![Last Commit][badge-last-commit]][commits]
 
-[badge-test]: https://github.com/Xevion/Pac-Man/actions/workflows/test.yaml/badge.svg
+[badge-test]: https://github.com/Xevion/Pac-Man/actions/workflows/tests.yaml/badge.svg
 [badge-build]: https://github.com/Xevion/Pac-Man/actions/workflows/build.yaml/badge.svg
 [badge-coverage]: https://coveralls.io/repos/github/Xevion/Pac-Man/badge.svg?branch=master
 [badge-demo]: https://img.shields.io/github/deployments/Xevion/Pac-Man/github-pages?label=GitHub%20Pages
 [badge-online-demo]: https://img.shields.io/badge/GitHub%20Pages-Demo-brightgreen
 [badge-last-commit]: https://img.shields.io/github/last-commit/Xevion/Pac-Man
 [build]: https://github.com/Xevion/Pac-Man/actions/workflows/build.yaml
-[test]: https://github.com/Xevion/Pac-Man/actions/workflows/test.yaml
+[test]: https://github.com/Xevion/Pac-Man/actions/workflows/tests.yaml
 [coverage]: https://coveralls.io/github/Xevion/Pac-Man?branch=master
 [demo]: https://xevion.github.io/Pac-Man/
 [commits]: https://github.com/Xevion/Pac-Man/commits/master

bacon.toml

@@ -0,0 +1,61 @@
+# This is a configuration file for the bacon tool
+#
+# Complete help on configuration: https://dystroy.org/bacon/config/
+#
+# You may check the current default at
+#   https://github.com/Canop/bacon/blob/main/defaults/default-bacon.toml
+
+default_job = "check"
+env.CARGO_TERM_COLOR = "always"
+
+[jobs.check]
+command = ["cargo", "check"]
+need_stdout = false
+
+[jobs.check-all]
+command = ["cargo", "check", "--all-targets"]
+need_stdout = false
+
+# Run clippy on the default target
+[jobs.clippy]
+command = ["cargo", "clippy"]
+need_stdout = false
+
+# Run clippy on all targets
+[jobs.clippy-all]
+command = ["cargo", "clippy", "--all-targets"]
+need_stdout = false
+
+[jobs.test]
+command = [
+    "cargo", "nextest", "run",
+    "--hide-progress-bar", "--failure-output", "final"
+]
+need_stdout = true
+analyzer = "nextest"
+
+[jobs.doc]
+command = ["cargo", "doc", "--no-deps"]
+need_stdout = false
+
+# If the doc compiles, then it opens in your browser and bacon switches to the previous job
+[jobs.doc-open]
+command = ["cargo", "doc", "--no-deps", "--open"]
+need_stdout = false
+on_success = "back" # so that we don't open the browser at each change
+
+[jobs.run]
+command = [
+    "cargo", "run",
+]
+need_stdout = true
+allow_warnings = true
+background = false
+on_change_strategy = "kill_then_restart"
+# kill = ["pkill", "-TERM", "-P"]'
+
+[keybindings]
+c = "job:clippy"
+alt-c = "job:check"
+ctrl-alt-c = "job:check-all"
+shift-c = "job:clippy-all"

src/entity/ghost.rs

@@ -4,19 +4,17 @@
 //! animation, and rendering. Ghosts move through the game graph using
 //! a traverser and display directional animated textures.
 
-use glam::Vec2;
+use pathfinding::prelude::dijkstra;
 use rand::prelude::*;
 use smallvec::SmallVec;
-use tracing::debug;
 
-use crate::constants::BOARD_PIXEL_OFFSET;
 use crate::entity::direction::Direction;
-use crate::entity::graph::{Edge, EdgePermissions, Graph, NodeId, Position, Traverser};
-use crate::helpers::centered_with_size;
+use crate::entity::graph::{Edge, EdgePermissions, Graph, NodeId};
+use crate::entity::r#trait::Entity;
+use crate::entity::traversal::Traverser;
 use crate::texture::animated::AnimatedTexture;
 use crate::texture::directional::DirectionalAnimatedTexture;
 use crate::texture::sprite::SpriteAtlas;
-use sdl2::render::{Canvas, RenderTarget};
 
 /// Determines if a ghost can traverse a given edge.
 ///
@@ -72,6 +70,42 @@ pub struct Ghost {
     speed: f32,
 }
 
+impl Entity for Ghost {
+    fn traverser(&self) -> &Traverser {
+        &self.traverser
+    }
+
+    fn traverser_mut(&mut self) -> &mut Traverser {
+        &mut self.traverser
+    }
+
+    fn texture(&self) -> &DirectionalAnimatedTexture {
+        &self.texture
+    }
+
+    fn texture_mut(&mut self) -> &mut DirectionalAnimatedTexture {
+        &mut self.texture
+    }
+
+    fn speed(&self) -> f32 {
+        self.speed
+    }
+
+    fn can_traverse(&self, edge: Edge) -> bool {
+        can_ghost_traverse(edge)
+    }
+
+    fn tick(&mut self, dt: f32, graph: &Graph) {
+        // Choose random direction when at a node
+        if self.traverser.position.is_at_node() {
+            self.choose_random_direction(graph);
+        }
+
+        self.traverser.advance(graph, dt * 60.0 * self.speed, &can_ghost_traverse);
+        self.texture.tick(dt);
+    }
+}
+
 impl Ghost {
     /// Creates a new ghost instance at the specified starting node.
     ///
@@ -112,20 +146,6 @@ impl Ghost {
         }
     }
 
-    /// Updates the ghost's position and animation state.
-    ///
-    /// Advances movement through the graph, updates texture animation,
-    /// and chooses random directions at intersections.
-    pub fn tick(&mut self, dt: f32, graph: &Graph) {
-        // Choose random direction when at a node
-        if self.traverser.position.is_at_node() {
-            self.choose_random_direction(graph);
-        }
-
-        self.traverser.advance(graph, dt * 60.0 * self.speed, &can_ghost_traverse);
-        self.texture.tick(dt);
-    }
-
     /// Chooses a random available direction at the current intersection.
     fn choose_random_direction(&mut self, graph: &Graph) {
         let current_node = self.traverser.position.from_node_id();
@@ -140,15 +160,6 @@ impl Ghost {
                 }
             }
         }
-
-        debug!(
-            "Ghost {} at node {}: available directions: {:?}, current direction: {:?}",
-            self.ghost_type.as_str(),
-            current_node,
-            available_directions,
-            self.traverser.direction
-        );
-
         // Choose a random direction (avoid reversing unless necessary)
         if !available_directions.is_empty() {
             let mut rng = SmallRng::from_os_rng();
@@ -160,57 +171,43 @@ impl Ghost {
                 .filter(|&&dir| dir != opposite || available_directions.len() <= 2)
                 .collect();
 
-            debug!(
-                "Ghost {}: filtered directions: {:?}, opposite: {:?}",
-                self.ghost_type.as_str(),
-                filtered_directions,
-                opposite
-            );
-
             if let Some(&random_direction) = filtered_directions.choose(&mut rng) {
                 self.traverser.set_next_direction(*random_direction);
-                debug!("Ghost {} chose direction: {:?}", self.ghost_type.as_str(), random_direction);
             }
         }
     }
 
-    /// Calculates the current pixel position in the game world.
+    /// Calculates the shortest path from the ghost's current position to a target node using Dijkstra's algorithm.
     ///
-    /// Converts the graph position to screen coordinates, accounting for
-    /// the board offset and centering the sprite.
-    fn get_pixel_pos(&self, graph: &Graph) -> Vec2 {
-        let pos = match self.traverser.position {
-            Position::AtNode(node_id) => graph.get_node(node_id).unwrap().position,
-            Position::BetweenNodes { from, to, traversed } => {
-                let from_pos = graph.get_node(from).unwrap().position;
-                let to_pos = graph.get_node(to).unwrap().position;
-                let edge = graph.find_edge(from, to).unwrap();
-                from_pos + (to_pos - from_pos) * (traversed / edge.distance)
-            }
-        };
+    /// Returns a vector of NodeIds representing the path, or None if no path exists.
+    /// The path includes the current node and the target node.
+    pub fn calculate_path_to_target(&self, graph: &Graph, target: NodeId) -> Option<Vec<NodeId>> {
+        let start_node = self.traverser.position.from_node_id();
 
-        Vec2::new(pos.x + BOARD_PIXEL_OFFSET.x as f32, pos.y + BOARD_PIXEL_OFFSET.y as f32)
-    }
-
-    /// Renders the ghost at its current position.
-    ///
-    /// Draws the appropriate directional sprite based on the ghost's
-    /// current movement state and direction.
-    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) {
-        let pixel_pos = self.get_pixel_pos(graph);
-        let dest = centered_with_size(
-            glam::IVec2::new(pixel_pos.x as i32, pixel_pos.y as i32),
-            glam::UVec2::new(16, 16),
+        // Use Dijkstra's algorithm to find the shortest path
+        let result = dijkstra(
+            &start_node,
+            |&node_id| {
+                // Get all edges from the current node
+                graph.adjacency_list[node_id]
+                    .edges()
+                    .filter(|edge| can_ghost_traverse(*edge))
+                    .map(|edge| (edge.target, (edge.distance * 100.0) as u32))
+                    .collect::<Vec<_>>()
+            },
+            |&node_id| node_id == target,
         );
 
-        if self.traverser.position.is_stopped() {
-            self.texture
-                .render_stopped(canvas, atlas, dest, self.traverser.direction)
-                .expect("Failed to render ghost");
-        } else {
-            self.texture
-                .render(canvas, atlas, dest, self.traverser.direction)
-                .expect("Failed to render ghost");
+        result.map(|(path, _cost)| path)
+    }
+
+    /// Returns the ghost's color for debug rendering.
+    pub fn debug_color(&self) -> sdl2::pixels::Color {
+        match self.ghost_type {
+            GhostType::Blinky => sdl2::pixels::Color::RGB(255, 0, 0),    // Red
+            GhostType::Pinky => sdl2::pixels::Color::RGB(255, 182, 255), // Pink
+            GhostType::Inky => sdl2::pixels::Color::RGB(0, 255, 255),    // Cyan
+            GhostType::Clyde => sdl2::pixels::Color::RGB(255, 182, 85),  // Orange
         }
     }
 }

src/entity/graph.rs

@@ -111,7 +111,7 @@ impl Graph {
     }
 
     /// Connects a new node to the graph and adds an edge between the existing node and the new node.
-    pub fn connect_node(&mut self, from: NodeId, direction: Direction, new_node: Node) -> Result<NodeId, &'static str> {
+    pub fn add_connected(&mut self, from: NodeId, direction: Direction, new_node: Node) -> Result<NodeId, &'static str> {
         let to = self.add_node(new_node);
         self.connect(from, to, false, None, direction)?;
         Ok(to)
@@ -236,208 +236,3 @@ impl Default for Graph {
         Self::new()
     }
 }
-
-// --- Traversal State and Logic ---
-
-/// Represents the current position of an entity traversing the graph.
-///
-/// This enum allows for precise tracking of whether an entity is exactly at a node
-/// or moving along an edge between two nodes.
-#[derive(Debug, PartialEq, Clone, Copy)]
-pub enum Position {
-    /// The traverser is located exactly at a node.
-    AtNode(NodeId),
-    /// The traverser is on an edge between two nodes.
-    BetweenNodes {
-        from: NodeId,
-        to: NodeId,
-        /// The floating-point distance traversed along the edge from the `from` node.
-        traversed: f32,
-    },
-}
-
-#[allow(dead_code)]
-impl Position {
-    /// Returns `true` if the position is exactly at a node.
-    pub fn is_at_node(&self) -> bool {
-        matches!(self, Position::AtNode(_))
-    }
-
-    /// Returns the `NodeId` of the current or most recently departed node.
-    #[allow(clippy::wrong_self_convention)]
-    pub fn from_node_id(&self) -> NodeId {
-        match self {
-            Position::AtNode(id) => *id,
-            Position::BetweenNodes { from, .. } => *from,
-        }
-    }
-
-    /// Returns the `NodeId` of the destination node, if currently on an edge.
-    #[allow(clippy::wrong_self_convention)]
-    pub fn to_node_id(&self) -> Option<NodeId> {
-        match self {
-            Position::AtNode(_) => None,
-            Position::BetweenNodes { to, .. } => Some(*to),
-        }
-    }
-
-    /// Returns `true` if the traverser is stopped at a node.
-    pub fn is_stopped(&self) -> bool {
-        matches!(self, Position::AtNode(_))
-    }
-}
-
-/// Manages an entity's movement through the graph.
-///
-/// A `Traverser` encapsulates the state of an entity's position and direction,
-/// providing a way to advance along the graph's paths based on a given distance.
-/// It also handles direction changes, buffering the next intended direction.
-pub struct Traverser {
-    /// The current position of the traverser in the graph.
-    pub position: Position,
-    /// The current direction of movement.
-    pub direction: Direction,
-    /// Buffered direction change with remaining frame count for timing.
-    ///
-    /// The `u8` value represents the number of frames remaining before
-    /// the buffered direction expires. This allows for responsive controls
-    /// by storing direction changes for a limited time.
-    pub next_direction: Option<(Direction, u8)>,
-}
-
-impl Traverser {
-    /// Creates a new traverser starting at the given node ID.
-    ///
-    /// The traverser will immediately attempt to start moving in the initial direction.
-    pub fn new<F>(graph: &Graph, start_node: NodeId, initial_direction: Direction, can_traverse: &F) -> Self
-    where
-        F: Fn(Edge) -> bool,
-    {
-        let mut traverser = Traverser {
-            position: Position::AtNode(start_node),
-            direction: initial_direction,
-            next_direction: Some((initial_direction, 1)),
-        };
-
-        // This will kickstart the traverser into motion
-        traverser.advance(graph, 0.0, can_traverse);
-
-        traverser
-    }
-
-    /// Sets the next direction for the traverser to take.
-    ///
-    /// The direction is buffered and will be applied at the next opportunity,
-    /// typically when the traverser reaches a new node. This allows for responsive
-    /// controls, as the new direction is stored for a limited time.
-    pub fn set_next_direction(&mut self, new_direction: Direction) {
-        if self.direction != new_direction {
-            self.next_direction = Some((new_direction, 30));
-        }
-    }
-
-    /// Advances the traverser along the graph by a specified distance.
-    ///
-    /// This method updates the traverser's position based on its current state
-    /// and the distance to travel.
-    ///
-    /// - If at a node, it checks for a buffered direction to start moving.
-    /// - If between nodes, it moves along the current edge.
-    /// - If it reaches a node, it attempts to transition to a new edge based on
-    ///   the buffered direction or by continuing straight.
-    /// - If no valid move is possible, it stops at the node.
-    pub fn advance<F>(&mut self, graph: &Graph, distance: f32, can_traverse: &F)
-    where
-        F: Fn(Edge) -> bool,
-    {
-        // Decrement the remaining frames for the next direction
-        if let Some((direction, remaining)) = self.next_direction {
-            if remaining > 0 {
-                self.next_direction = Some((direction, remaining - 1));
-            } else {
-                self.next_direction = None;
-            }
-        }
-
-        match self.position {
-            Position::AtNode(node_id) => {
-                // We're not moving, but a buffered direction is available.
-                if let Some((next_direction, _)) = self.next_direction {
-                    if let Some(edge) = graph.find_edge_in_direction(node_id, next_direction) {
-                        if can_traverse(edge) {
-                            // Start moving in that direction
-                            self.position = Position::BetweenNodes {
-                                from: node_id,
-                                to: edge.target,
-                                traversed: distance.max(0.0),
-                            };
-                            self.direction = next_direction;
-                        }
-                    }
-
-                    self.next_direction = None; // Consume the buffered direction regardless of whether we started moving with it
-                }
-            }
-            Position::BetweenNodes { from, to, traversed } => {
-                // There is no point in any of the next logic if we don't travel at all
-                if distance <= 0.0 {
-                    return;
-                }
-
-                let edge = graph
-                    .find_edge(from, to)
-                    .expect("Inconsistent state: Traverser is on a non-existent edge.");
-
-                let new_traversed = traversed + distance;
-
-                if new_traversed < edge.distance {
-                    // Still on the same edge, just update the distance.
-                    self.position = Position::BetweenNodes {
-                        from,
-                        to,
-                        traversed: new_traversed,
-                    };
-                } else {
-                    let overflow = new_traversed - edge.distance;
-                    let mut moved = false;
-
-                    // If we buffered a direction, try to find an edge in that direction
-                    if let Some((next_dir, _)) = self.next_direction {
-                        if let Some(edge) = graph.find_edge_in_direction(to, next_dir) {
-                            if can_traverse(edge) {
-                                self.position = Position::BetweenNodes {
-                                    from: to,
-                                    to: edge.target,
-                                    traversed: overflow,
-                                };
-
-                                self.direction = next_dir; // Remember our new direction
-                                self.next_direction = None; // Consume the buffered direction
-                                moved = true;
-                            }
-                        }
-                    }
-
-                    // If we didn't move, try to continue in the current direction
-                    if !moved {
-                        if let Some(edge) = graph.find_edge_in_direction(to, self.direction) {
-                            if can_traverse(edge) {
-                                self.position = Position::BetweenNodes {
-                                    from: to,
-                                    to: edge.target,
-                                    traversed: overflow,
-                                };
-                            } else {
-                                self.position = Position::AtNode(to);
-                                self.next_direction = None;
-                            }
-                        } else {
-                            self.position = Position::AtNode(to);
-                            self.next_direction = None;
-                        }
-                    }
-                }
-            }
-        }
-    }
-}

src/entity/mod.rs

@@ -2,3 +2,5 @@ pub mod direction;
 pub mod ghost;
 pub mod graph;
 pub mod pacman;
+pub mod r#trait;
+pub mod traversal;

src/entity/pacman.rs

@@ -4,17 +4,14 @@
 //! animation, and rendering. Pac-Man moves through the game graph using
 //! a traverser and displays directional animated textures.
 
-use glam::{UVec2, Vec2};
-
-use crate::constants::BOARD_PIXEL_OFFSET;
 use crate::entity::direction::Direction;
-use crate::entity::graph::{Edge, EdgePermissions, Graph, NodeId, Position, Traverser};
-use crate::helpers::centered_with_size;
+use crate::entity::graph::{Edge, EdgePermissions, Graph, NodeId};
+use crate::entity::r#trait::Entity;
+use crate::entity::traversal::Traverser;
 use crate::texture::animated::AnimatedTexture;
 use crate::texture::directional::DirectionalAnimatedTexture;
 use crate::texture::sprite::SpriteAtlas;
 use sdl2::keyboard::Keycode;
-use sdl2::render::{Canvas, RenderTarget};
 
 /// Determines if Pac-Man can traverse a given edge.
 ///
@@ -34,6 +31,37 @@ pub struct Pacman {
     texture: DirectionalAnimatedTexture,
 }
 
+impl Entity for Pacman {
+    fn traverser(&self) -> &Traverser {
+        &self.traverser
+    }
+
+    fn traverser_mut(&mut self) -> &mut Traverser {
+        &mut self.traverser
+    }
+
+    fn texture(&self) -> &DirectionalAnimatedTexture {
+        &self.texture
+    }
+
+    fn texture_mut(&mut self) -> &mut DirectionalAnimatedTexture {
+        &mut self.texture
+    }
+
+    fn speed(&self) -> f32 {
+        1.125
+    }
+
+    fn can_traverse(&self, edge: Edge) -> bool {
+        can_pacman_traverse(edge)
+    }
+
+    fn tick(&mut self, dt: f32, graph: &Graph) {
+        self.traverser.advance(graph, dt * 60.0 * 1.125, &can_pacman_traverse);
+        self.texture.tick(dt);
+    }
+}
+
 impl Pacman {
     /// Creates a new Pac-Man instance at the specified starting node.
     ///
@@ -69,15 +97,6 @@ impl Pacman {
         }
     }
 
-    /// Updates Pac-Man's position and animation state.
-    ///
-    /// Advances movement through the graph and updates texture animation.
-    /// Movement speed is scaled by 60 FPS and a 1.125 multiplier.
-    pub fn tick(&mut self, dt: f32, graph: &Graph) {
-        self.traverser.advance(graph, dt * 60.0 * 1.125, &can_pacman_traverse);
-        self.texture.tick(dt);
-    }
-
     /// Handles keyboard input to change Pac-Man's direction.
     ///
     /// Maps arrow keys to directions and queues the direction change
@@ -95,36 +114,4 @@ impl Pacman {
             self.traverser.set_next_direction(direction);
         }
     }
-
-    /// Calculates the current pixel position in the game world.
-    ///
-    /// Interpolates between nodes when moving between them.
-    fn get_pixel_pos(&self, graph: &Graph) -> Vec2 {
-        match self.traverser.position {
-            Position::AtNode(node_id) => graph.get_node(node_id).unwrap().position,
-            Position::BetweenNodes { from, to, traversed } => {
-                let from_pos = graph.get_node(from).unwrap().position;
-                let to_pos = graph.get_node(to).unwrap().position;
-                from_pos.lerp(to_pos, traversed / from_pos.distance(to_pos))
-            }
-        }
-    }
-
-    /// Renders Pac-Man to the canvas.
-    ///
-    /// Calculates screen position, determines if Pac-Man is stopped,
-    /// and renders the appropriate directional texture.
-    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) {
-        let pixel_pos = self.get_pixel_pos(graph).round().as_ivec2() + BOARD_PIXEL_OFFSET.as_ivec2();
-        let dest = centered_with_size(pixel_pos, UVec2::new(16, 16));
-        let is_stopped = self.traverser.position.is_stopped();
-
-        if is_stopped {
-            self.texture
-                .render_stopped(canvas, atlas, dest, self.traverser.direction)
-                .unwrap();
-        } else {
-            self.texture.render(canvas, atlas, dest, self.traverser.direction).unwrap();
-        }
-    }
 }

src/entity/trait.rs

@@ -0,0 +1,108 @@
+//! Entity trait for common movement and rendering functionality.
+//!
+//! This module defines a trait that captures the shared behavior between
+//! different game entities like Ghosts and Pac-Man, including movement,
+//! rendering, and position calculations.
+
+use glam::Vec2;
+use sdl2::render::{Canvas, RenderTarget};
+
+use crate::entity::direction::Direction;
+use crate::entity::graph::{Edge, Graph, NodeId};
+use crate::entity::traversal::{Position, Traverser};
+use crate::texture::directional::DirectionalAnimatedTexture;
+use crate::texture::sprite::SpriteAtlas;
+
+/// Trait defining common functionality for game entities that move through the graph.
+///
+/// This trait provides a unified interface for entities that:
+/// - Move through the game graph using a traverser
+/// - Render using directional animated textures
+/// - Have position calculations and movement speed
+#[allow(dead_code)]
+pub trait Entity {
+    /// Returns a reference to the entity's traverser for movement control.
+    fn traverser(&self) -> &Traverser;
+
+    /// Returns a mutable reference to the entity's traverser for movement control.
+    fn traverser_mut(&mut self) -> &mut Traverser;
+
+    /// Returns a reference to the entity's directional animated texture.
+    fn texture(&self) -> &DirectionalAnimatedTexture;
+
+    /// Returns a mutable reference to the entity's directional animated texture.
+    fn texture_mut(&mut self) -> &mut DirectionalAnimatedTexture;
+
+    /// Returns the movement speed multiplier for this entity.
+    fn speed(&self) -> f32;
+
+    /// Determines if this entity can traverse a given edge.
+    fn can_traverse(&self, edge: Edge) -> bool;
+
+    /// Updates the entity's position and animation state.
+    ///
+    /// This method advances movement through the graph and updates texture animation.
+    fn tick(&mut self, dt: f32, graph: &Graph);
+
+    /// Calculates the current pixel position in the game world.
+    ///
+    /// Converts the graph position to screen coordinates, accounting for
+    /// the board offset and centering the sprite.
+    fn get_pixel_pos(&self, graph: &Graph) -> Vec2 {
+        let pos = match self.traverser().position {
+            Position::AtNode(node_id) => graph.get_node(node_id).unwrap().position,
+            Position::BetweenNodes { from, to, traversed } => {
+                let from_pos = graph.get_node(from).unwrap().position;
+                let to_pos = graph.get_node(to).unwrap().position;
+                let edge = graph.find_edge(from, to).unwrap();
+                from_pos + (to_pos - from_pos) * (traversed / edge.distance)
+            }
+        };
+
+        Vec2::new(
+            pos.x + crate::constants::BOARD_PIXEL_OFFSET.x as f32,
+            pos.y + crate::constants::BOARD_PIXEL_OFFSET.y as f32,
+        )
+    }
+
+    /// Returns the current node ID that the entity is at or moving towards.
+    ///
+    /// If the entity is at a node, returns that node ID.
+    /// If the entity is between nodes, returns the node it's moving towards.
+    fn current_node_id(&self) -> NodeId {
+        match self.traverser().position {
+            Position::AtNode(node_id) => node_id,
+            Position::BetweenNodes { to, .. } => to,
+        }
+    }
+
+    /// Sets the next direction for the entity to take.
+    ///
+    /// The direction is buffered and will be applied at the next opportunity,
+    /// typically when the entity reaches a new node.
+    fn set_next_direction(&mut self, direction: Direction) {
+        self.traverser_mut().set_next_direction(direction);
+    }
+
+    /// Renders the entity at its current position.
+    ///
+    /// Draws the appropriate directional sprite based on the entity's
+    /// current movement state and direction.
+    fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) {
+        let pixel_pos = self.get_pixel_pos(graph);
+        let dest = crate::helpers::centered_with_size(
+            glam::IVec2::new(pixel_pos.x as i32, pixel_pos.y as i32),
+            glam::UVec2::new(16, 16),
+        );
+
+        if self.traverser().position.is_stopped() {
+            self.texture()
+                .render_stopped(canvas, atlas, dest, self.traverser().direction)
+                .expect("Failed to render entity");
+        } else {
+            self.texture()
+                .render(canvas, atlas, dest, self.traverser().direction)
+                .expect("Failed to render entity");
+        }
+    }
+}

src/entity/traversal.rs

@@ -0,0 +1,205 @@
+use super::direction::Direction;
+use super::graph::{Edge, Graph, NodeId};
+
+/// Represents the current position of an entity traversing the graph.
+///
+/// This enum allows for precise tracking of whether an entity is exactly at a node
+/// or moving along an edge between two nodes.
+#[derive(Debug, PartialEq, Clone, Copy)]
+pub enum Position {
+    /// The traverser is located exactly at a node.
+    AtNode(NodeId),
+    /// The traverser is on an edge between two nodes.
+    BetweenNodes {
+        from: NodeId,
+        to: NodeId,
+        /// The floating-point distance traversed along the edge from the `from` node.
+        traversed: f32,
+    },
+}
+
+#[allow(dead_code)]
+impl Position {
+    /// Returns `true` if the position is exactly at a node.
+    pub fn is_at_node(&self) -> bool {
+        matches!(self, Position::AtNode(_))
+    }
+
+    /// Returns the `NodeId` of the current or most recently departed node.
+    #[allow(clippy::wrong_self_convention)]
+    pub fn from_node_id(&self) -> NodeId {
+        match self {
+            Position::AtNode(id) => *id,
+            Position::BetweenNodes { from, .. } => *from,
+        }
+    }
+
+    /// Returns the `NodeId` of the destination node, if currently on an edge.
+    #[allow(clippy::wrong_self_convention)]
+    pub fn to_node_id(&self) -> Option<NodeId> {
+        match self {
+            Position::AtNode(_) => None,
+            Position::BetweenNodes { to, .. } => Some(*to),
+        }
+    }
+
+    /// Returns `true` if the traverser is stopped at a node.
+    pub fn is_stopped(&self) -> bool {
+        matches!(self, Position::AtNode(_))
+    }
+}
+
+/// Manages an entity's movement through the graph.
+///
+/// A `Traverser` encapsulates the state of an entity's position and direction,
+/// providing a way to advance along the graph's paths based on a given distance.
+/// It also handles direction changes, buffering the next intended direction.
+pub struct Traverser {
+    /// The current position of the traverser in the graph.
+    pub position: Position,
+    /// The current direction of movement.
+    pub direction: Direction,
+    /// Buffered direction change with remaining frame count for timing.
+    ///
+    /// The `u8` value represents the number of frames remaining before
+    /// the buffered direction expires. This allows for responsive controls
+    /// by storing direction changes for a limited time.
+    pub next_direction: Option<(Direction, u8)>,
+}
+
+impl Traverser {
+    /// Creates a new traverser starting at the given node ID.
+    ///
+    /// The traverser will immediately attempt to start moving in the initial direction.
+    pub fn new<F>(graph: &Graph, start_node: NodeId, initial_direction: Direction, can_traverse: &F) -> Self
+    where
+        F: Fn(Edge) -> bool,
+    {
+        let mut traverser = Traverser {
+            position: Position::AtNode(start_node),
+            direction: initial_direction,
+            next_direction: Some((initial_direction, 1)),
+        };
+
+        // This will kickstart the traverser into motion
+        traverser.advance(graph, 0.0, can_traverse);
+
+        traverser
+    }
+
+    /// Sets the next direction for the traverser to take.
+    ///
+    /// The direction is buffered and will be applied at the next opportunity,
+    /// typically when the traverser reaches a new node. This allows for responsive
+    /// controls, as the new direction is stored for a limited time.
+    pub fn set_next_direction(&mut self, new_direction: Direction) {
+        if self.direction != new_direction {
+            self.next_direction = Some((new_direction, 30));
+        }
+    }
+
+    /// Advances the traverser along the graph by a specified distance.
+    ///
+    /// This method updates the traverser's position based on its current state
+    /// and the distance to travel.
+    ///
+    /// - If at a node, it checks for a buffered direction to start moving.
+    /// - If between nodes, it moves along the current edge.
+    /// - If it reaches a node, it attempts to transition to a new edge based on
+    ///   the buffered direction or by continuing straight.
+    /// - If no valid move is possible, it stops at the node.
+    pub fn advance<F>(&mut self, graph: &Graph, distance: f32, can_traverse: &F)
+    where
+        F: Fn(Edge) -> bool,
+    {
+        // Decrement the remaining frames for the next direction
+        if let Some((direction, remaining)) = self.next_direction {
+            if remaining > 0 {
+                self.next_direction = Some((direction, remaining - 1));
+            } else {
+                self.next_direction = None;
+            }
+        }
+
+        match self.position {
+            Position::AtNode(node_id) => {
+                // We're not moving, but a buffered direction is available.
+                if let Some((next_direction, _)) = self.next_direction {
+                    if let Some(edge) = graph.find_edge_in_direction(node_id, next_direction) {
+                        if can_traverse(edge) {
+                            // Start moving in that direction
+                            self.position = Position::BetweenNodes {
+                                from: node_id,
+                                to: edge.target,
+                                traversed: distance.max(0.0),
+                            };
+                            self.direction = next_direction;
+                        }
+                    }
+
+                    self.next_direction = None; // Consume the buffered direction regardless of whether we started moving with it
+                }
+            }
+            Position::BetweenNodes { from, to, traversed } => {
+                // There is no point in any of the next logic if we don't travel at all
+                if distance <= 0.0 {
+                    return;
+                }
+
+                let edge = graph
+                    .find_edge(from, to)
+                    .expect("Inconsistent state: Traverser is on a non-existent edge.");
+
+                let new_traversed = traversed + distance;
+
+                if new_traversed < edge.distance {
+                    // Still on the same edge, just update the distance.
+                    self.position = Position::BetweenNodes {
+                        from,
+                        to,
+                        traversed: new_traversed,
+                    };
+                } else {
+                    let overflow = new_traversed - edge.distance;
+                    let mut moved = false;
+
+                    // If we buffered a direction, try to find an edge in that direction
+                    if let Some((next_dir, _)) = self.next_direction {
+                        if let Some(edge) = graph.find_edge_in_direction(to, next_dir) {
+                            if can_traverse(edge) {
+                                self.position = Position::BetweenNodes {
+                                    from: to,
+                                    to: edge.target,
+                                    traversed: overflow,
+                                };
+
+                                self.direction = next_dir; // Remember our new direction
+                                self.next_direction = None; // Consume the buffered direction
+                                moved = true;
+                            }
+                        }
+                    }
+
+                    // If we didn't move, try to continue in the current direction
+                    if !moved {
+                        if let Some(edge) = graph.find_edge_in_direction(to, self.direction) {
+                            if can_traverse(edge) {
+                                self.position = Position::BetweenNodes {
+                                    from: to,
+                                    to: edge.target,
+                                    traversed: overflow,
+                                };
+                            } else {
+                                self.position = Position::AtNode(to);
+                                self.next_direction = None;
+                            }
+                        } else {
+                            self.position = Position::AtNode(to);
+                            self.next_direction = None;
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

src/game.rs

@@ -1,7 +1,7 @@
 //! This module contains the main game logic and state.
 
 use anyhow::Result;
-use glam::UVec2;
+use glam::{UVec2, Vec2};
 use rand::{rngs::SmallRng, Rng, SeedableRng};
 use sdl2::{
     image::LoadTexture,
@@ -14,10 +14,11 @@ use sdl2::{
 use crate::{
     asset::{get_asset_bytes, Asset},
     audio::Audio,
-    constants::RAW_BOARD,
+    constants::{CELL_SIZE, RAW_BOARD},
     entity::{
         ghost::{Ghost, GhostType},
         pacman::Pacman,
+        r#trait::Entity,
     },
     map::Map,
     texture::{
@@ -173,12 +174,72 @@ impl Game {
         if self.debug_mode {
             self.map
                 .debug_render_with_cursor(canvas, &mut self.text_texture, &mut self.atlas, cursor_pos);
+            self.render_pathfinding_debug(canvas)?;
         }
         self.draw_hud(canvas)?;
         canvas.present();
         Ok(())
     }
 
+    /// Renders pathfinding debug lines from each ghost to Pac-Man.
+    ///
+    /// Each ghost's path is drawn in its respective color with a small offset
+    /// to prevent overlapping lines.
+    fn render_pathfinding_debug<T: RenderTarget>(&self, canvas: &mut Canvas<T>) -> Result<()> {
+        let pacman_node = self.pacman.current_node_id();
+
+        for ghost in self.ghosts.iter() {
+            if let Some(path) = ghost.calculate_path_to_target(&self.map.graph, pacman_node) {
+                if path.len() < 2 {
+                    continue; // Skip if path is too short
+                }
+
+                // Set the ghost's color
+                canvas.set_draw_color(ghost.debug_color());
+
+                // Calculate offset based on ghost index to prevent overlapping lines
+                // let offset = (i as f32) * 2.0 - 3.0; // Offset range: -3.0 to 3.0
+
+                // Calculate a consistent offset direction for the entire path
+                // let first_node = self.map.graph.get_node(path[0]).unwrap();
+                // let last_node = self.map.graph.get_node(path[path.len() - 1]).unwrap();
+
+                // Use the overall direction from start to end to determine the perpendicular offset
+                let offset = match ghost.ghost_type {
+                    GhostType::Blinky => Vec2::new(0.25, 0.5),
+                    GhostType::Pinky => Vec2::new(-0.25, -0.25),
+                    GhostType::Inky => Vec2::new(0.5, -0.5),
+                    GhostType::Clyde => Vec2::new(-0.5, 0.25),
+                } * 5.0;
+
+                // Calculate offset positions for all nodes using the same perpendicular direction
+                let mut offset_positions = Vec::new();
+                for &node_id in &path {
+                    let node = self.map.graph.get_node(node_id).unwrap();
+                    let pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
+                    offset_positions.push(pos + offset);
+                }
+
+                // Draw lines between the offset positions
+                for window in offset_positions.windows(2) {
+                    if let (Some(from), Some(to)) = (window.first(), window.get(1)) {
+                        // Skip if the distance is too far (used for preventing lines between tunnel portals)
+                        if from.distance_squared(*to) > (CELL_SIZE * 16).pow(2) as f32 {
+                            continue;
+                        }
+
+                        // Draw the line
+                        canvas
+                            .draw_line((from.x as i32, from.y as i32), (to.x as i32, to.y as i32))
+                            .map_err(anyhow::Error::msg)?;
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+
     fn draw_hud<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>) -> Result<()> {
         let lives = 3;
         let score_text = format!("{:02}", self.score);

src/helpers.rs

@@ -2,10 +2,9 @@ use glam::{IVec2, UVec2};
 use sdl2::rect::Rect;
 
 pub fn centered_with_size(pixel_pos: IVec2, size: UVec2) -> Rect {
-    Rect::new(
-        pixel_pos.x - size.x as i32 / 2,
-        pixel_pos.y - size.y as i32 / 2,
-        size.x,
-        size.y,
-    )
+    // Ensure the position doesn't cause integer overflow when centering
+    let x = pixel_pos.x.saturating_sub(size.x as i32 / 2);
+    let y = pixel_pos.y.saturating_sub(size.y as i32 / 2);
+
+    Rect::new(x, y, size.x, size.y)
 }

src/map/builder.rs

@@ -331,7 +331,7 @@ impl Map {
                 .expect("Left tunnel entrance node not found");
 
             graph
-                .connect_node(
+                .add_connected(
                     left_tunnel_entrance_node_id,
                     Direction::Left,
                     Node {
@@ -350,7 +350,7 @@ impl Map {
                 .expect("Right tunnel entrance node not found");
 
             graph
-                .connect_node(
+                .add_connected(
                     right_tunnel_entrance_node_id,
                     Direction::Right,
                     Node {

src/map/render.rs

@@ -87,7 +87,7 @@ impl MapRenderer {
 
             // Draw node ID text (small, offset to top right)
             text_renderer.set_scale(0.5); // Small text
-            let id_text = format!("#{}", nearest_id);
+            let id_text = format!("#{nearest_id}");
             let text_pos = glam::UVec2::new(
                 (nearest_pos.x + 4.0) as u32, // Offset to the right
                 (nearest_pos.y - 6.0) as u32, // Offset to the top

tests/graph.rs

@@ -1,5 +1,6 @@
 use pacman::entity::direction::Direction;
-use pacman::entity::graph::{EdgePermissions, Graph, Node, Position, Traverser};
+use pacman::entity::graph::{EdgePermissions, Graph, Node};
+use pacman::entity::traversal::{Position, Traverser};
 
 fn create_test_graph() -> Graph {
     let mut graph = Graph::new();

tests/pathfinding.rs

@@ -0,0 +1,117 @@
+use pacman::entity::direction::Direction;
+use pacman::entity::ghost::{Ghost, GhostType};
+use pacman::entity::graph::{Graph, Node};
+use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
+use std::collections::HashMap;
+
+fn create_test_atlas() -> SpriteAtlas {
+    let mut frames = HashMap::new();
+    let directions = ["up", "down", "left", "right"];
+    let ghost_types = ["blinky", "pinky", "inky", "clyde"];
+
+    for ghost_type in &ghost_types {
+        for (i, dir) in directions.iter().enumerate() {
+            frames.insert(
+                format!("ghost/{}/{}_{}.png", ghost_type, dir, "a"),
+                MapperFrame {
+                    x: i as u16 * 16,
+                    y: 0,
+                    width: 16,
+                    height: 16,
+                },
+            );
+            frames.insert(
+                format!("ghost/{}/{}_{}.png", ghost_type, dir, "b"),
+                MapperFrame {
+                    x: i as u16 * 16,
+                    y: 16,
+                    width: 16,
+                    height: 16,
+                },
+            );
+        }
+    }
+
+    let mapper = AtlasMapper { frames };
+    let dummy_texture = unsafe { std::mem::zeroed() };
+    SpriteAtlas::new(dummy_texture, mapper)
+}
+
+#[test]
+fn test_ghost_pathfinding() {
+    // Create a simple test graph
+    let mut graph = Graph::new();
+
+    // Add nodes in a simple line: 0 -> 1 -> 2
+    let node0 = graph.add_node(Node {
+        position: glam::Vec2::new(0.0, 0.0),
+    });
+    let node1 = graph.add_node(Node {
+        position: glam::Vec2::new(10.0, 0.0),
+    });
+    let node2 = graph.add_node(Node {
+        position: glam::Vec2::new(20.0, 0.0),
+    });
+
+    // Connect the nodes
+    graph.connect(node0, node1, false, None, Direction::Right).unwrap();
+    graph.connect(node1, node2, false, None, Direction::Right).unwrap();
+
+    // Create a test atlas for the ghost
+    let atlas = create_test_atlas();
+
+    // Create a ghost at node 0
+    let ghost = Ghost::new(&graph, node0, GhostType::Blinky, &atlas);
+
+    // Test pathfinding from node 0 to node 2
+    let path = ghost.calculate_path_to_target(&graph, node2);
+
+    assert!(path.is_some());
+    let path = path.unwrap();
+    assert_eq!(path, vec![node0, node1, node2]);
+}
+
+#[test]
+fn test_ghost_pathfinding_no_path() {
+    // Create a test graph with disconnected components
+    let mut graph = Graph::new();
+
+    let node0 = graph.add_node(Node {
+        position: glam::Vec2::new(0.0, 0.0),
+    });
+    let node1 = graph.add_node(Node {
+        position: glam::Vec2::new(10.0, 0.0),
+    });
+
+    // Don't connect the nodes
+    let atlas = create_test_atlas();
+    let ghost = Ghost::new(&graph, node0, GhostType::Blinky, &atlas);
+
+    // Test pathfinding when no path exists
+    let path = ghost.calculate_path_to_target(&graph, node1);
+
+    assert!(path.is_none());
+}
+
+#[test]
+fn test_ghost_debug_colors() {
+    let atlas = create_test_atlas();
+    let mut graph = Graph::new();
+    let node = graph.add_node(Node {
+        position: glam::Vec2::new(0.0, 0.0),
+    });
+
+    let blinky = Ghost::new(&graph, node, GhostType::Blinky, &atlas);
+    let pinky = Ghost::new(&graph, node, GhostType::Pinky, &atlas);
+    let inky = Ghost::new(&graph, node, GhostType::Inky, &atlas);
+    let clyde = Ghost::new(&graph, node, GhostType::Clyde, &atlas);
+
+    // Test that each ghost has a different debug color
+    let colors = std::collections::HashSet::from([
+        blinky.debug_color(),
+        pinky.debug_color(),
+        inky.debug_color(),
+        clyde.debug_color(),
+    ]);
+    assert_eq!(colors.len(), 4, "All ghost colors should be unique");
+}