ci: add concurrency group to 'wasm' job to prevent concurrent page deployments

Bumps the dependencies group with 1 update: [actions/checkout](https://github.com/actions/checkout).


Updates `actions/checkout` from 4 to 5
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v4...v5)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '5'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/dependabot.yml

@@ -0,0 +1,20 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      dependencies:
+        patterns:
+          - "*"

.github/workflows/build.yaml

@@ -14,23 +14,23 @@ jobs:
           - os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
             artifact_name: pacman
-            toolchain: 1.88.0
+            toolchain: 1.86.0
           - os: macos-13
             target: x86_64-apple-darwin
             artifact_name: pacman
-            toolchain: 1.88.0
+            toolchain: 1.86.0
           - os: macos-latest
             target: aarch64-apple-darwin
             artifact_name: pacman
-            toolchain: 1.88.0
+            toolchain: 1.86.0
           - os: windows-latest
             target: x86_64-pc-windows-gnu
             artifact_name: pacman.exe
-            toolchain: 1.88.0
+            toolchain: 1.86.0
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Rust Toolchain
         uses: dtolnay/rust-toolchain@master
@@ -64,15 +64,16 @@ jobs:
         run: cargo build --release
 
       - name: Acquire Package Version
-        shell: bash
+        id: get_version
+        shell: bash # required to prevent Windows runners from failing
         run: |
-          PACKAGE_VERSION=$(cargo metadata --format-version 1 --no-deps | jq '.packages[0].version' -r)
-          echo "PACKAGE_VERSION=${PACKAGE_VERSION}" >> $GITHUB_ENV
+          set -euo pipefail # exit on error
+          echo "version=$(cargo metadata --format-version 1 --no-deps | jq '.packages[0].version' -r)" >> $GITHUB_OUTPUT
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v4
         with:
-          name: "pacman-${{ env.PACKAGE_VERSION }}-${{ matrix.target }}"
+          name: "pacman-${{ steps.get_version.outputs.version }}-${{ matrix.target }}"
           path: ./target/release/${{ matrix.artifact_name }}
           retention-days: 7
           if-no-files-found: error
@@ -83,10 +84,13 @@ jobs:
     permissions:
       pages: write
       id-token: write
+    # concurrency group is used to prevent multiple page deployments from being attempted at the same time
+    concurrency:
+      group: ${{ github.workflow }}-wasm
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Emscripten SDK
         uses: pyodide/setup-emsdk@v15
@@ -98,7 +102,7 @@ jobs:
         uses: dtolnay/rust-toolchain@master
         with:
           target: wasm32-unknown-emscripten
-          toolchain: 1.86.0 # we are unfortunately pinned to 1.86.0 for some reason, bulk-memory-opt related issues
+          toolchain: 1.86.0
 
       - name: Rust Cache
         uses: Swatinem/rust-cache@v2

.github/workflows/coverage.yaml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master

.github/workflows/tests.yaml

@@ -4,7 +4,7 @@ on: ["push", "pull_request"]
 
 env:
   CARGO_TERM_COLOR: always
-  RUST_TOOLCHAIN: 1.88.0
+  RUST_TOOLCHAIN: 1.86.0
 
 jobs:
   test:
@@ -12,7 +12,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master

.gitignore

@@ -5,3 +5,4 @@ emsdk/
 rust-sdl2-emscripten/
 assets/site/build.css
 tailwindcss-*
+lcov.info

Cargo.lock

@@ -13,9 +13,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.98"
+version = "1.0.99"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e16d2d3311acee920a9eb8d33b8cbc1787ce4a264e85f964c2404b969bdcd487"
+checksum = "b0674a1ddeecb70197781e945de4b3b8ffb61fa939a5597bcf48503737663100"
 
 [[package]]
 name = "autocfg"
@@ -79,9 +79,9 @@ dependencies = [
 
 [[package]]
 name = "glam"
-version = "0.30.4"
+version = "0.30.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50a99dbe56b72736564cfa4b85bf9a33079f16ae8b74983ab06af3b1a3696b11"
+checksum = "f2d1aab06663bdce00d6ca5e5ed586ec8d18033a771906c993a1e3755b368d85"
 
 [[package]]
 name = "hashbrown"
@@ -89,6 +89,12 @@ version = "0.15.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5971ac85611da7067dbfcabef3c70ebb5606018acd9e2a3903a0da507521e0d5"
 
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
 [[package]]
 name = "indexmap"
 version = "2.10.0"
@@ -122,9 +128,9 @@ checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
 [[package]]
 name = "libc"
-version = "0.2.174"
+version = "0.2.175"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1171693293099992e19cddea4e8b849964e9846f4acee11b3948bcc337be8776"
+checksum = "6a82ae493e598baaea5209805c49bbf2ea7de956d50d7da0da1164f9c6d28543"
 
 [[package]]
 name = "log"
@@ -194,7 +200,9 @@ dependencies = [
  "serde_json",
  "smallvec",
  "spin_sleep",
- "thiserror 1.0.69",
+ "strum",
+ "strum_macros",
+ "thiserror",
  "tracing",
  "tracing-error",
  "tracing-subscriber",
@@ -212,7 +220,7 @@ dependencies = [
  "integer-sqrt",
  "num-traits",
  "rustc-hash",
- "thiserror 2.0.12",
+ "thiserror",
 ]
 
 [[package]]
@@ -372,9 +380,9 @@ dependencies = [
 
 [[package]]
 name = "serde_json"
-version = "1.0.141"
+version = "1.0.142"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30b9eff21ebe718216c6ec64e1d9ac57087aad11efc64e32002bce4a0d4c03d3"
+checksum = "030fedb782600dcbd6f02d479bf0d817ac3bb40d644745b769d6a96bc3afc5a7"
 dependencies = [
  "itoa",
  "memchr",
@@ -406,6 +414,24 @@ dependencies = [
  "windows-sys",
 ]
 
+[[package]]
+name = "strum"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af23d6f6c1a224baef9d3f61e287d2761385a5b88fdab4eb4c6f11aeb54c4bcf"
+
+[[package]]
+name = "strum_macros"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7695ce3845ea4b33927c055a39dc438a45b059f7c1b3d91d38d10355fb8cbca7"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "syn"
 version = "2.0.104"
@@ -417,33 +443,13 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "thiserror"
-version = "1.0.69"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
-dependencies = [
- "thiserror-impl 1.0.69",
-]
-
 [[package]]
 name = "thiserror"
 version = "2.0.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "567b8a2dae586314f7be2a752ec7474332959c6460e02bde30d702a66d488708"
 dependencies = [
- "thiserror-impl 2.0.12",
-]
-
-[[package]]
-name = "thiserror-impl"
-version = "1.0.69"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
+ "thiserror-impl",
 ]
 
 [[package]]

Cargo.toml

@@ -15,12 +15,14 @@ spin_sleep = "1.3.2"
 rand = { version = "0.9.2", default-features = false, features = ["small_rng", "os_rng"] }
 pathfinding = "4.14"
 once_cell = "1.21.3"
-thiserror = "1.0"
+thiserror = "2.0"
 anyhow = "1.0"
-glam = { version = "0.30.4", features = [] }
+glam = { version = "0.30.5", features = [] }
 serde = { version = "1.0.219", features = ["derive"] }
-serde_json = "1.0.141"
+serde_json = "1.0.142"
 smallvec = "1.15.1"
+strum = "0.27.2"
+strum_macros = "0.27.2"
 
 [profile.release]
 lto = true
@@ -54,4 +56,4 @@ x86_64-apple-darwin = { triplet = "x64-osx" }
 aarch64-apple-darwin = { triplet = "arm64-osx" }
 
 [target.'cfg(target_os = "emscripten")'.dependencies]
-libc = "0.2.16"
+libc = "0.2.175"

README.md

@@ -72,6 +72,8 @@ I wanted to hit a log of goals and features, making it a 'perfect' project that
 
 Since this project is still in progress, I'm only going to cover non-obvious build details. By reading the code, build scripts, and copying the online build workflows, you should be able to replicate the build process.
 
+- We use rustc 1.86.0 for the build, due to bulk-memory-opt related issues on wasm32-unknown-emscripten.
+  - Technically, we could probably use stable or even nightly on desktop targets, but using different versions for different targets is a pain, mainly because of clippy warnings changing between versions.
 - Install `cargo-vcpkg` with `cargo install cargo-vcpkg`, then run `cargo vcpkg build` to build the requisite dependencies via vcpkg.
 - For the WASM build, you need to have the Emscripten SDK cloned; you can do so with `git clone https://github.com/emscripten-core/emsdk.git`
   - The first time you clone, you'll need to install the appropriate SDK version with `./emsdk install 3.1.43` and then activate it with `./emsdk activate 3.1.43`. On Windows, use `./emsdk/emsdk.ps1` instead.

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"

rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+# we are unfortunately pinned to 1.86.0 for some reason, bulk-memory-opt related issues on wasm32-unknown-emscripten
+channel = "1.86.0"
+components = ["rustfmt", "llvm-tools-preview", "clippy"]

src/app.rs

@@ -1,6 +1,5 @@
 use std::time::{Duration, Instant};
 
-use anyhow::{anyhow, Result};
 use glam::Vec2;
 use sdl2::event::{Event, WindowEvent};
 use sdl2::keyboard::Keycode;
@@ -9,6 +8,8 @@ use sdl2::video::{Window, WindowContext};
 use sdl2::EventPump;
 use tracing::{error, event};
 
+use crate::error::{GameError, GameResult};
+
 use crate::constants::{CANVAS_SIZE, LOOP_TIME, SCALE};
 use crate::game::Game;
 use crate::platform::get_platform;
@@ -24,14 +25,14 @@ pub struct App<'a> {
 }
 
 impl App<'_> {
-    pub fn new() -> Result<Self> {
+    pub fn new() -> GameResult<Self> {
         // Initialize platform-specific console
-        get_platform().init_console().map_err(|e| anyhow!(e))?;
+        get_platform().init_console()?;
 
-        let sdl_context = sdl2::init().map_err(|e| anyhow!(e))?;
-        let video_subsystem = sdl_context.video().map_err(|e| anyhow!(e))?;
-        let audio_subsystem = sdl_context.audio().map_err(|e| anyhow!(e))?;
-        let ttf_context = sdl2::ttf::init().map_err(|e| anyhow!(e.to_string()))?;
+        let sdl_context = sdl2::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let video_subsystem = sdl_context.video().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let audio_subsystem = sdl_context.audio().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let ttf_context = sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?;
 
         let window = video_subsystem
             .window(
@@ -41,24 +42,31 @@ impl App<'_> {
             )
             .resizable()
             .position_centered()
-            .build()?;
+            .build()
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
 
-        let mut canvas = window.into_canvas().build()?;
-        canvas.set_logical_size(CANVAS_SIZE.x, CANVAS_SIZE.y)?;
+        let mut canvas = window.into_canvas().build().map_err(|e| GameError::Sdl(e.to_string()))?;
+        canvas
+            .set_logical_size(CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
 
         let texture_creator_static: &'static TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
 
-        let mut game = Game::new(texture_creator_static, &ttf_context, &audio_subsystem);
+        let mut game = Game::new(texture_creator_static, &ttf_context, &audio_subsystem)?;
         game.audio.set_mute(cfg!(debug_assertions));
 
-        let mut backbuffer = texture_creator_static.create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)?;
+        let mut backbuffer = texture_creator_static
+            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
         backbuffer.set_scale_mode(ScaleMode::Nearest);
 
-        let event_pump = sdl_context.event_pump().map_err(|e| anyhow!(e))?;
+        let event_pump = sdl_context.event_pump().map_err(|e| GameError::Sdl(e.to_string()))?;
 
         // Initial draw
-        game.draw(&mut canvas, &mut backbuffer)?;
-        game.present_backbuffer(&mut canvas, &backbuffer, glam::Vec2::ZERO)?;
+        game.draw(&mut canvas, &mut backbuffer)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        game.present_backbuffer(&mut canvas, &backbuffer, glam::Vec2::ZERO)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
 
         Ok(Self {
             game,
@@ -109,8 +117,8 @@ impl App<'_> {
                     } => {
                         self.game.debug_mode = !self.game.debug_mode;
                     }
-                    Event::KeyDown { keycode, .. } => {
-                        self.game.keyboard_event(keycode.unwrap());
+                    Event::KeyDown { keycode: Some(key), .. } => {
+                        self.game.keyboard_event(key);
                     }
                     Event::MouseMotion { x, y, .. } => {
                         // Convert window coordinates to logical coordinates
@@ -126,13 +134,13 @@ impl App<'_> {
             if !self.paused {
                 self.game.tick(dt);
                 if let Err(e) = self.game.draw(&mut self.canvas, &mut self.backbuffer) {
-                    error!("Failed to draw game: {e}");
+                    error!("Failed to draw game: {}", e);
                 }
                 if let Err(e) = self
                     .game
                     .present_backbuffer(&mut self.canvas, &self.backbuffer, self.cursor_pos)
                 {
-                    error!("Failed to present backbuffer: {e}");
+                    error!("Failed to present backbuffer: {}", e);
                 }
             }
 

src/entity/collision.rs

@@ -0,0 +1,128 @@
+use smallvec::SmallVec;
+use std::collections::HashMap;
+
+use crate::entity::traversal::Position;
+
+/// Trait for entities that can participate in collision detection.
+pub trait Collidable {
+    /// Returns the current position of this entity.
+    fn position(&self) -> Position;
+
+    /// Checks if this entity is colliding with another entity.
+    #[allow(dead_code)]
+    fn is_colliding_with(&self, other: &dyn Collidable) -> bool {
+        positions_overlap(&self.position(), &other.position())
+    }
+}
+
+/// System for tracking entities by their positions for efficient collision detection.
+#[derive(Default)]
+pub struct CollisionSystem {
+    /// Maps node IDs to lists of entity IDs that are at that node
+    node_entities: HashMap<usize, Vec<EntityId>>,
+    /// Maps entity IDs to their current positions
+    entity_positions: HashMap<EntityId, Position>,
+    /// Next available entity ID
+    next_id: EntityId,
+}
+
+/// Unique identifier for an entity in the collision system
+pub type EntityId = u32;
+
+impl CollisionSystem {
+    /// Registers an entity with the collision system and returns its ID
+    pub fn register_entity(&mut self, position: Position) -> EntityId {
+        let id = self.next_id;
+        self.next_id += 1;
+
+        self.entity_positions.insert(id, position);
+        self.update_node_entities(id, position);
+
+        id
+    }
+
+    /// Updates an entity's position
+    pub fn update_position(&mut self, entity_id: EntityId, new_position: Position) {
+        if let Some(old_position) = self.entity_positions.get(&entity_id) {
+            // Remove from old nodes
+            self.remove_from_nodes(entity_id, *old_position);
+        }
+
+        // Update position and add to new nodes
+        self.entity_positions.insert(entity_id, new_position);
+        self.update_node_entities(entity_id, new_position);
+    }
+
+    /// Removes an entity from the collision system
+    #[allow(dead_code)]
+    pub fn remove_entity(&mut self, entity_id: EntityId) {
+        if let Some(position) = self.entity_positions.remove(&entity_id) {
+            self.remove_from_nodes(entity_id, position);
+        }
+    }
+
+    /// Gets all entity IDs at a specific node
+    pub fn entities_at_node(&self, node: usize) -> &[EntityId] {
+        self.node_entities.get(&node).map(|v| v.as_slice()).unwrap_or(&[])
+    }
+
+    /// Gets all entity IDs that could collide with an entity at the given position
+    pub fn potential_collisions(&self, position: &Position) -> Vec<EntityId> {
+        let mut collisions = Vec::new();
+        let nodes = get_nodes(position);
+
+        for node in nodes {
+            collisions.extend(self.entities_at_node(node));
+        }
+
+        // Remove duplicates
+        collisions.sort_unstable();
+        collisions.dedup();
+        collisions
+    }
+
+    /// Updates the node_entities map when an entity's position changes
+    fn update_node_entities(&mut self, entity_id: EntityId, position: Position) {
+        let nodes = get_nodes(&position);
+        for node in nodes {
+            self.node_entities.entry(node).or_default().push(entity_id);
+        }
+    }
+
+    /// Removes an entity from all nodes it was previously at
+    fn remove_from_nodes(&mut self, entity_id: EntityId, position: Position) {
+        let nodes = get_nodes(&position);
+        for node in nodes {
+            if let Some(entities) = self.node_entities.get_mut(&node) {
+                entities.retain(|&id| id != entity_id);
+                if entities.is_empty() {
+                    self.node_entities.remove(&node);
+                }
+            }
+        }
+    }
+}
+
+/// Checks if two positions overlap (entities are at the same location).
+fn positions_overlap(a: &Position, b: &Position) -> bool {
+    let a_nodes = get_nodes(a);
+    let b_nodes = get_nodes(b);
+
+    // Check if any nodes overlap
+    a_nodes.iter().any(|a_node| b_nodes.contains(a_node))
+
+    // TODO: More complex overlap detection, the above is a simple check, but it could become an early filter for more precise calculations later
+}
+
+/// Gets all nodes that an entity is currently at or between.
+fn get_nodes(pos: &Position) -> SmallVec<[usize; 2]> {
+    let mut nodes = SmallVec::new();
+    match pos {
+        Position::AtNode(node) => nodes.push(*node),
+        Position::BetweenNodes { from, to, .. } => {
+            nodes.push(*from);
+            nodes.push(*to);
+        }
+    }
+    nodes
+}

src/entity/ghost.rs

@@ -4,19 +4,23 @@
 //! 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 tracing::error;
 
-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::{
+    collision::Collidable,
+    direction::Direction,
+    graph::{Edge, EdgePermissions, Graph, NodeId},
+    r#trait::Entity,
+    traversal::Traverser,
+};
 use crate::texture::animated::AnimatedTexture;
 use crate::texture::directional::DirectionalAnimatedTexture;
 use crate::texture::sprite::SpriteAtlas;
-use sdl2::render::{Canvas, RenderTarget};
+
+use crate::error::{EntityError, GameError, GameResult, TextureError};
 
 /// Determines if a ghost can traverse a given edge.
 ///
@@ -72,12 +76,50 @@ 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);
+        }
+
+        if let Err(e) = self.traverser.advance(graph, dt * 60.0 * self.speed, &can_ghost_traverse) {
+            error!("Ghost movement error: {}", e);
+        }
+        self.texture.tick(dt);
+    }
+}
+
 impl Ghost {
     /// Creates a new ghost instance at the specified starting node.
     ///
     /// Sets up animated textures for all four directions with moving and stopped states.
     /// The moving animation cycles through two sprite variants.
-    pub fn new(graph: &Graph, start_node: NodeId, ghost_type: GhostType, atlas: &SpriteAtlas) -> Self {
+    pub fn new(graph: &Graph, start_node: NodeId, ghost_type: GhostType, atlas: &SpriteAtlas) -> GameResult<Self> {
         let mut textures = [None, None, None, None];
         let mut stopped_textures = [None, None, None, None];
 
@@ -89,41 +131,51 @@ impl Ghost {
                 Direction::Right => "right",
             };
             let moving_tiles = vec![
-                SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "a")).unwrap(),
-                SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "b")).unwrap(),
+                SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "a"))
+                    .ok_or_else(|| {
+                        GameError::Texture(TextureError::AtlasTileNotFound(format!(
+                            "ghost/{}/{}_{}.png",
+                            ghost_type.as_str(),
+                            moving_prefix,
+                            "a"
+                        )))
+                    })?,
+                SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "b"))
+                    .ok_or_else(|| {
+                        GameError::Texture(TextureError::AtlasTileNotFound(format!(
+                            "ghost/{}/{}_{}.png",
+                            ghost_type.as_str(),
+                            moving_prefix,
+                            "b"
+                        )))
+                    })?,
             ];
 
             let stopped_tiles =
                 vec![
                     SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "a"))
-                        .unwrap(),
+                        .ok_or_else(|| {
+                            GameError::Texture(TextureError::AtlasTileNotFound(format!(
+                                "ghost/{}/{}_{}.png",
+                                ghost_type.as_str(),
+                                moving_prefix,
+                                "a"
+                            )))
+                        })?,
                 ];
 
-            textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.2).expect("Invalid frame duration"));
+            textures[direction.as_usize()] =
+                Some(AnimatedTexture::new(moving_tiles, 0.2).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
             stopped_textures[direction.as_usize()] =
-                Some(AnimatedTexture::new(stopped_tiles, 0.1).expect("Invalid frame duration"));
+                Some(AnimatedTexture::new(stopped_tiles, 0.1).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
         }
 
-        Self {
+        Ok(Self {
             traverser: Traverser::new(graph, start_node, Direction::Left, &can_ghost_traverse),
             ghost_type,
             texture: DirectionalAnimatedTexture::new(textures, stopped_textures),
             speed: ghost_type.base_speed(),
-        }
-    }
-
-    /// 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.
@@ -140,15 +192,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 +203,54 @@ 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 an error if pathfinding fails.
+    /// The path includes the current node and the target node.
+    pub fn calculate_path_to_target(&self, graph: &Graph, target: NodeId) -> GameResult<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).ok_or_else(|| {
+            GameError::Entity(EntityError::PathfindingFailed(format!(
+                "No path found from node {} to target {}",
+                start_node, target
+            )))
+        })
+    }
+
+    /// 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
         }
     }
 }
+
+impl Collidable for Ghost {
+    fn position(&self) -> crate::entity::traversal::Position {
+        self.traverser.position
+    }
+}

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/item.rs

@@ -0,0 +1,115 @@
+use crate::{
+    constants,
+    entity::{collision::Collidable, graph::Graph},
+    error::EntityError,
+    texture::sprite::{Sprite, SpriteAtlas},
+};
+use sdl2::render::{Canvas, RenderTarget};
+use strum_macros::{EnumCount, EnumIter};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ItemType {
+    Pellet,
+    Energizer,
+    #[allow(dead_code)]
+    Fruit {
+        kind: FruitKind,
+    },
+}
+
+impl ItemType {
+    pub fn get_score(self) -> u32 {
+        match self {
+            ItemType::Pellet => 10,
+            ItemType::Energizer => 50,
+            ItemType::Fruit { kind } => kind.get_score(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, EnumIter, EnumCount)]
+#[allow(dead_code)]
+pub enum FruitKind {
+    Apple,
+    Strawberry,
+    Orange,
+    Melon,
+    Bell,
+    Key,
+    Galaxian,
+}
+
+impl FruitKind {
+    #[allow(dead_code)]
+    pub fn index(self) -> u8 {
+        match self {
+            FruitKind::Apple => 0,
+            FruitKind::Strawberry => 1,
+            FruitKind::Orange => 2,
+            FruitKind::Melon => 3,
+            FruitKind::Bell => 4,
+            FruitKind::Key => 5,
+            FruitKind::Galaxian => 6,
+        }
+    }
+
+    pub fn get_score(self) -> u32 {
+        match self {
+            FruitKind::Apple => 100,
+            FruitKind::Strawberry => 300,
+            FruitKind::Orange => 500,
+            FruitKind::Melon => 700,
+            FruitKind::Bell => 1000,
+            FruitKind::Key => 2000,
+            FruitKind::Galaxian => 3000,
+        }
+    }
+}
+
+pub struct Item {
+    pub node_index: usize,
+    pub item_type: ItemType,
+    pub sprite: Sprite,
+    pub collected: bool,
+}
+
+impl Item {
+    pub fn new(node_index: usize, item_type: ItemType, sprite: Sprite) -> Self {
+        Self {
+            node_index,
+            item_type,
+            sprite,
+            collected: false,
+        }
+    }
+
+    pub fn is_collected(&self) -> bool {
+        self.collected
+    }
+
+    pub fn collect(&mut self) {
+        self.collected = true;
+    }
+
+    pub fn get_score(&self) -> u32 {
+        self.item_type.get_score()
+    }
+
+    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) -> anyhow::Result<()> {
+        if !self.collected {
+            let node = graph
+                .get_node(self.node_index)
+                .ok_or(EntityError::NodeNotFound(self.node_index))?;
+            let position = node.position + constants::BOARD_PIXEL_OFFSET.as_vec2();
+            self.sprite.render(canvas, atlas, position)
+        } else {
+            Ok(())
+        }
+    }
+}
+
+impl Collidable for Item {
+    fn position(&self) -> crate::entity::traversal::Position {
+        crate::entity::traversal::Position::AtNode(self.node_index)
+    }
+}

src/entity/mod.rs

@@ -1,4 +1,8 @@
+pub mod collision;
 pub mod direction;
 pub mod ghost;
 pub mod graph;
+pub mod item;
 pub mod pacman;
+pub mod r#trait;
+pub mod traversal;

src/entity/pacman.rs

@@ -4,17 +4,20 @@
 //! 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::{
+    collision::Collidable,
+    direction::Direction,
+    graph::{Edge, EdgePermissions, Graph, NodeId},
+    r#trait::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};
+use tracing::error;
+
+use crate::error::{GameError, GameResult, TextureError};
 
 /// Determines if Pac-Man can traverse a given edge.
 ///
@@ -34,12 +37,45 @@ 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) {
+        if let Err(e) = self.traverser.advance(graph, dt * 60.0 * 1.125, &can_pacman_traverse) {
+            error!("Pac-Man movement error: {}", e);
+        }
+        self.texture.tick(dt);
+    }
+}
+
 impl Pacman {
     /// Creates a new Pac-Man instance at the specified starting node.
     ///
     /// Sets up animated textures for all four directions with moving and stopped states.
     /// The moving animation cycles through open mouth, closed mouth, and full sprites.
-    pub fn new(graph: &Graph, start_node: NodeId, atlas: &SpriteAtlas) -> Self {
+    pub fn new(graph: &Graph, start_node: NodeId, atlas: &SpriteAtlas) -> GameResult<Self> {
         let mut textures = [None, None, None, None];
         let mut stopped_textures = [None, None, None, None];
 
@@ -51,31 +87,27 @@ impl Pacman {
                 Direction::Right => "pacman/right",
             };
             let moving_tiles = vec![
-                SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_a.png")).unwrap(),
-                SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_b.png")).unwrap(),
-                SpriteAtlas::get_tile(atlas, "pacman/full.png").unwrap(),
+                SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_a.png"))
+                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_a.png"))))?,
+                SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_b.png"))
+                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?,
+                SpriteAtlas::get_tile(atlas, "pacman/full.png")
+                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("pacman/full.png".to_string())))?,
             ];
 
-            let stopped_tiles = vec![SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_b.png")).unwrap()];
+            let stopped_tiles = vec![SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_b.png"))
+                .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?];
 
-            textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.08).expect("Invalid frame duration"));
+            textures[direction.as_usize()] =
+                Some(AnimatedTexture::new(moving_tiles, 0.08).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
             stopped_textures[direction.as_usize()] =
-                Some(AnimatedTexture::new(stopped_tiles, 0.1).expect("Invalid frame duration"));
+                Some(AnimatedTexture::new(stopped_tiles, 0.1).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
         }
 
-        Self {
+        Ok(Self {
             traverser: Traverser::new(graph, start_node, Direction::Left, &can_pacman_traverse),
             texture: DirectionalAnimatedTexture::new(textures, stopped_textures),
-        }
-    }
-
-    /// 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.
@@ -95,36 +127,10 @@ 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();
-        }
+impl Collidable for Pacman {
+    fn position(&self) -> crate::entity::traversal::Position {
+        self.traverser.position
     }
 }

src/entity/trait.rs

@@ -0,0 +1,114 @@
+//! 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::error::{EntityError, GameError, GameResult, TextureError};
+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) -> GameResult<Vec2> {
+        let pos = match self.traverser().position {
+            Position::AtNode(node_id) => {
+                let node = graph.get_node(node_id).ok_or(EntityError::NodeNotFound(node_id))?;
+                node.position
+            }
+            Position::BetweenNodes { from, to, traversed } => {
+                let from_node = graph.get_node(from).ok_or(EntityError::NodeNotFound(from))?;
+                let to_node = graph.get_node(to).ok_or(EntityError::NodeNotFound(to))?;
+                let edge = graph.find_edge(from, to).ok_or(EntityError::EdgeNotFound { from, to })?;
+                from_node.position + (to_node.position - from_node.position) * (traversed / edge.distance)
+            }
+        };
+
+        Ok(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) -> GameResult<()> {
+        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)
+                .map_err(|e| GameError::Texture(TextureError::RenderFailed(e.to_string())))?;
+        } else {
+            self.texture()
+                .render(canvas, atlas, dest, self.traverser().direction)
+                .map_err(|e| GameError::Texture(TextureError::RenderFailed(e.to_string())))?;
+        }
+
+        Ok(())
+    }
+}

src/entity/traversal.rs

@@ -0,0 +1,229 @@
+use tracing::error;
+
+use crate::error::GameResult;
+
+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
+        if let Err(e) = traverser.advance(graph, 0.0, can_traverse) {
+            error!("Traverser initialization error: {}", e);
+        }
+
+        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.
+    ///
+    /// Returns an error if the movement is invalid (e.g., trying to move in an impossible direction).
+    pub fn advance<F>(&mut self, graph: &Graph, distance: f32, can_traverse: &F) -> GameResult<()>
+    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;
+                        } else {
+                            return Err(crate::error::GameError::Entity(crate::error::EntityError::InvalidMovement(
+                                format!(
+                                    "Cannot traverse edge from {} to {} in direction {:?}",
+                                    node_id, edge.target, next_direction
+                                ),
+                            )));
+                        }
+                    } else {
+                        return Err(crate::error::GameError::Entity(crate::error::EntityError::InvalidMovement(
+                            format!("No edge found in direction {:?} from node {}", next_direction, node_id),
+                        )));
+                    }
+
+                    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 Ok(());
+                }
+
+                let edge = graph.find_edge(from, to).ok_or_else(|| {
+                    crate::error::GameError::Entity(crate::error::EntityError::InvalidMovement(format!(
+                        "Inconsistent state: Traverser is on a non-existent edge from {} to {}.",
+                        from, to
+                    )))
+                })?;
+
+                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;
+                        }
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+}

src/error.rs

@@ -0,0 +1,156 @@
+//! Centralized error types for the Pac-Man game.
+//!
+//! This module defines all error types used throughout the application,
+//! providing a consistent error handling approach.
+
+use thiserror::Error;
+
+/// Main error type for the Pac-Man game.
+///
+/// This is the primary error type that should be used in public APIs.
+/// It can represent any error that can occur during game operation.
+#[derive(Error, Debug)]
+pub enum GameError {
+    #[error("Asset error: {0}")]
+    Asset(#[from] crate::asset::AssetError),
+
+    #[error("Platform error: {0}")]
+    Platform(#[from] crate::platform::PlatformError),
+
+    #[error("Map parsing error: {0}")]
+    MapParse(#[from] crate::map::parser::ParseError),
+
+    #[error("Map error: {0}")]
+    Map(#[from] MapError),
+
+    #[error("Texture error: {0}")]
+    Texture(#[from] TextureError),
+
+    #[error("Entity error: {0}")]
+    Entity(#[from] EntityError),
+
+    #[error("Game state error: {0}")]
+    GameState(#[from] GameStateError),
+
+    #[error("SDL error: {0}")]
+    Sdl(String),
+
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("Serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+
+    #[error("Invalid state: {0}")]
+    InvalidState(String),
+
+    #[error("Resource not found: {0}")]
+    NotFound(String),
+
+    #[error("Configuration error: {0}")]
+    Config(String),
+}
+
+/// Errors related to texture operations.
+#[derive(Error, Debug)]
+pub enum TextureError {
+    #[error("Animated texture error: {0}")]
+    Animated(#[from] crate::texture::animated::AnimatedTextureError),
+
+    #[error("Failed to load texture: {0}")]
+    LoadFailed(String),
+
+    #[error("Texture not found in atlas: {0}")]
+    AtlasTileNotFound(String),
+
+    #[error("Invalid texture format: {0}")]
+    InvalidFormat(String),
+
+    #[error("Rendering failed: {0}")]
+    RenderFailed(String),
+}
+
+/// Errors related to entity operations.
+#[derive(Error, Debug)]
+pub enum EntityError {
+    #[error("Node not found in graph: {0}")]
+    NodeNotFound(usize),
+
+    #[error("Edge not found: from {from} to {to}")]
+    EdgeNotFound { from: usize, to: usize },
+
+    #[error("Invalid movement: {0}")]
+    InvalidMovement(String),
+
+    #[error("Pathfinding failed: {0}")]
+    PathfindingFailed(String),
+}
+
+/// Errors related to game state operations.
+#[derive(Error, Debug)]
+pub enum GameStateError {}
+
+/// Errors related to map operations.
+#[derive(Error, Debug)]
+pub enum MapError {
+    #[error("Node not found: {0}")]
+    NodeNotFound(usize),
+
+    #[error("Invalid map configuration: {0}")]
+    InvalidConfig(String),
+}
+
+/// Result type for game operations.
+pub type GameResult<T> = Result<T, GameError>;
+
+/// Helper trait for converting other error types to GameError.
+pub trait IntoGameError<T> {
+    #[allow(dead_code)]
+    fn into_game_error(self) -> GameResult<T>;
+}
+
+impl<T, E> IntoGameError<T> for Result<T, E>
+where
+    E: std::error::Error + Send + Sync + 'static,
+{
+    fn into_game_error(self) -> GameResult<T> {
+        self.map_err(|e| GameError::InvalidState(e.to_string()))
+    }
+}
+
+/// Helper trait for converting Option to GameResult with a custom error.
+pub trait OptionExt<T> {
+    #[allow(dead_code)]
+    fn ok_or_game_error<F>(self, f: F) -> GameResult<T>
+    where
+        F: FnOnce() -> GameError;
+}
+
+impl<T> OptionExt<T> for Option<T> {
+    fn ok_or_game_error<F>(self, f: F) -> GameResult<T>
+    where
+        F: FnOnce() -> GameError,
+    {
+        self.ok_or_else(f)
+    }
+}
+
+/// Helper trait for converting Result to GameResult with context.
+pub trait ResultExt<T, E> {
+    #[allow(dead_code)]
+    fn with_context<F>(self, f: F) -> GameResult<T>
+    where
+        F: FnOnce(&E) -> GameError;
+}
+
+impl<T, E> ResultExt<T, E> for Result<T, E>
+where
+    E: std::error::Error + Send + Sync + 'static,
+{
+    fn with_context<F>(self, f: F) -> GameResult<T>
+    where
+        F: FnOnce(&E) -> GameError,
+    {
+        self.map_err(|e| f(&e))
+    }
+}

src/game.rs

@@ -1,7 +1,6 @@
 //! 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,
@@ -11,13 +10,18 @@ use sdl2::{
     video::WindowContext,
 };
 
+use crate::error::{EntityError, GameError, GameResult, TextureError};
+
 use crate::{
     asset::{get_asset_bytes, Asset},
     audio::Audio,
-    constants::RAW_BOARD,
+    constants::{CELL_SIZE, RAW_BOARD},
     entity::{
+        collision::{Collidable, CollisionSystem, EntityId},
         ghost::{Ghost, GhostType},
+        item::Item,
         pacman::Pacman,
+        r#trait::Entity,
     },
     map::Map,
     texture::{
@@ -35,8 +39,15 @@ pub struct Game {
     pub map: Map,
     pub pacman: Pacman,
     pub ghosts: Vec<Ghost>,
+    pub items: Vec<Item>,
     pub debug_mode: bool,
 
+    // Collision system
+    collision_system: CollisionSystem,
+    pacman_id: EntityId,
+    ghost_ids: Vec<EntityId>,
+    item_ids: Vec<EntityId>,
+
     // Rendering resources
     atlas: SpriteAtlas,
     map_texture: AtlasTile,
@@ -51,56 +62,96 @@ impl Game {
         texture_creator: &TextureCreator<WindowContext>,
         _ttf_context: &sdl2::ttf::Sdl2TtfContext,
         _audio_subsystem: &sdl2::AudioSubsystem,
-    ) -> Game {
-        let map = Map::new(RAW_BOARD);
+    ) -> GameResult<Game> {
+        let map = Map::new(RAW_BOARD)?;
 
-        let pacman_start_pos = map.find_starting_position(0).unwrap();
+        let pacman_start_pos = map
+            .find_starting_position(0)
+            .ok_or_else(|| GameError::NotFound("Pac-Man starting position".to_string()))?;
         let pacman_start_node = *map
             .grid_to_node
             .get(&glam::IVec2::new(pacman_start_pos.x as i32, pacman_start_pos.y as i32))
-            .expect("Pac-Man starting position not found in graph");
+            .ok_or_else(|| GameError::NotFound("Pac-Man starting position not found in graph".to_string()))?;
 
-        let atlas_bytes = get_asset_bytes(Asset::Atlas).expect("Failed to load asset");
+        let atlas_bytes = get_asset_bytes(Asset::Atlas)?;
         let atlas_texture = unsafe {
-            let texture = texture_creator
-                .load_texture_bytes(&atlas_bytes)
-                .expect("Could not load atlas texture from asset API");
+            let texture = texture_creator.load_texture_bytes(&atlas_bytes).map_err(|e| {
+                if e.to_string().contains("format") || e.to_string().contains("unsupported") {
+                    GameError::Texture(TextureError::InvalidFormat(format!("Unsupported texture format: {e}")))
+                } else {
+                    GameError::Texture(TextureError::LoadFailed(e.to_string()))
+                }
+            })?;
             sprite::texture_to_static(texture)
         };
-        let atlas_json = get_asset_bytes(Asset::AtlasJson).expect("Failed to load asset");
-        let atlas_mapper: AtlasMapper = serde_json::from_slice(&atlas_json).expect("Could not parse atlas JSON");
+        let atlas_json = get_asset_bytes(Asset::AtlasJson)?;
+        let atlas_mapper: AtlasMapper = serde_json::from_slice(&atlas_json)?;
         let atlas = SpriteAtlas::new(atlas_texture, atlas_mapper);
 
-        let mut map_texture = SpriteAtlas::get_tile(&atlas, "maze/full.png").expect("Failed to load map tile");
+        let mut map_texture = SpriteAtlas::get_tile(&atlas, "maze/full.png")
+            .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("maze/full.png".to_string())))?;
         map_texture.color = Some(Color::RGB(0x20, 0x20, 0xf9));
 
         let text_texture = TextTexture::new(1.0);
         let audio = Audio::new();
-        let pacman = Pacman::new(&map.graph, pacman_start_node, &atlas);
+        let pacman = Pacman::new(&map.graph, pacman_start_node, &atlas)?;
+
+        // Generate items (pellets and energizers)
+        let items = map.generate_items(&atlas)?;
 
         // Create ghosts at random positions
         let mut ghosts = Vec::new();
         let ghost_types = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde];
         let mut rng = SmallRng::from_os_rng();
 
+        if map.graph.node_count() == 0 {
+            return Err(GameError::Config("Game map has no nodes - invalid configuration".to_string()));
+            // TODO: This is a bug, we should handle this better
+        }
+
         for &ghost_type in &ghost_types {
             // Find a random node for the ghost to start at
             let random_node = rng.random_range(0..map.graph.node_count());
-            let ghost = Ghost::new(&map.graph, random_node, ghost_type, &atlas);
+            let ghost = Ghost::new(&map.graph, random_node, ghost_type, &atlas)?;
             ghosts.push(ghost);
         }
 
-        Game {
+        // Initialize collision system
+        let mut collision_system = CollisionSystem::default();
+
+        // Register Pac-Man
+        let pacman_id = collision_system.register_entity(pacman.position());
+
+        // Register items
+        let mut item_ids = Vec::new();
+        for item in &items {
+            let item_id = collision_system.register_entity(item.position());
+            item_ids.push(item_id);
+        }
+
+        // Register ghosts
+        let mut ghost_ids = Vec::new();
+        for ghost in &ghosts {
+            let ghost_id = collision_system.register_entity(ghost.position());
+            ghost_ids.push(ghost_id);
+        }
+
+        Ok(Game {
             score: 0,
             map,
             pacman,
             ghosts,
+            items,
             debug_mode: false,
+            collision_system,
+            pacman_id,
+            ghost_ids,
+            item_ids,
             map_texture,
             text_texture,
             audio,
             atlas,
-        }
+        })
     }
 
     pub fn keyboard_event(&mut self, keycode: Keycode) {
@@ -111,21 +162,29 @@ impl Game {
         }
 
         if keycode == Keycode::R {
-            self.reset_game_state();
+            if let Err(e) = self.reset_game_state() {
+                tracing::error!("Failed to reset game state: {}", e);
+            }
         }
     }
 
     /// Resets the game state, randomizing ghost positions and resetting Pac-Man
-    fn reset_game_state(&mut self) {
+    fn reset_game_state(&mut self) -> GameResult<()> {
         // Reset Pac-Man to starting position
-        let pacman_start_pos = self.map.find_starting_position(0).unwrap();
+        let pacman_start_pos = self
+            .map
+            .find_starting_position(0)
+            .ok_or_else(|| GameError::NotFound("Pac-Man starting position".to_string()))?;
         let pacman_start_node = *self
             .map
             .grid_to_node
             .get(&glam::IVec2::new(pacman_start_pos.x as i32, pacman_start_pos.y as i32))
-            .expect("Pac-Man starting position not found in graph");
+            .ok_or_else(|| GameError::NotFound("Pac-Man starting position not found in graph".to_string()))?;
 
-        self.pacman = Pacman::new(&self.map.graph, pacman_start_node, &self.atlas);
+        self.pacman = Pacman::new(&self.map.graph, pacman_start_node, &self.atlas)?;
+
+        // Reset items
+        self.items = self.map.generate_items(&self.atlas)?;
 
         // Randomize ghost positions
         let ghost_types = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde];
@@ -133,8 +192,30 @@ impl Game {
 
         for (i, ghost) in self.ghosts.iter_mut().enumerate() {
             let random_node = rng.random_range(0..self.map.graph.node_count());
-            *ghost = Ghost::new(&self.map.graph, random_node, ghost_types[i], &self.atlas);
+            *ghost = Ghost::new(&self.map.graph, random_node, ghost_types[i], &self.atlas)?;
         }
+
+        // Reset collision system
+        self.collision_system = CollisionSystem::default();
+
+        // Re-register Pac-Man
+        self.pacman_id = self.collision_system.register_entity(self.pacman.position());
+
+        // Re-register items
+        self.item_ids.clear();
+        for item in &self.items {
+            let item_id = self.collision_system.register_entity(item.position());
+            self.item_ids.push(item_id);
+        }
+
+        // Re-register ghosts
+        self.ghost_ids.clear();
+        for ghost in &self.ghosts {
+            let ghost_id = self.collision_system.register_entity(ghost.position());
+            self.ghost_ids.push(ghost_id);
+        }
+
+        Ok(())
     }
 
     pub fn tick(&mut self, dt: f32) {
@@ -144,21 +225,88 @@ impl Game {
         for ghost in &mut self.ghosts {
             ghost.tick(dt, &self.map.graph);
         }
+
+        // Update collision system positions
+        self.update_collision_positions();
+
+        // Check for collisions
+        self.check_collisions();
     }
 
-    pub fn draw<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>, backbuffer: &mut Texture) -> Result<()> {
-        canvas.with_texture_canvas(backbuffer, |canvas| {
-            canvas.set_draw_color(Color::BLACK);
-            canvas.clear();
-            self.map.render(canvas, &mut self.atlas, &mut self.map_texture);
+    fn update_collision_positions(&mut self) {
+        // Update Pac-Man's position
+        self.collision_system.update_position(self.pacman_id, self.pacman.position());
 
-            // Render all ghosts
-            for ghost in &self.ghosts {
-                ghost.render(canvas, &mut self.atlas, &self.map.graph);
+        // Update ghost positions
+        for (ghost, &ghost_id) in self.ghosts.iter().zip(&self.ghost_ids) {
+            self.collision_system.update_position(ghost_id, ghost.position());
+        }
+    }
+
+    fn check_collisions(&mut self) {
+        // Check Pac-Man vs Items
+        let potential_collisions = self.collision_system.potential_collisions(&self.pacman.position());
+
+        for entity_id in potential_collisions {
+            if entity_id != self.pacman_id {
+                // Check if this is an item collision
+                if let Some(item_index) = self.find_item_by_id(entity_id) {
+                    let item = &mut self.items[item_index];
+                    if !item.is_collected() {
+                        item.collect();
+                        self.score += item.get_score();
+
+                        // Handle energizer effects
+                        if matches!(item.item_type, crate::entity::item::ItemType::Energizer) {
+                            // TODO: Make ghosts frightened
+                            tracing::info!("Energizer collected! Ghosts should become frightened.");
+                        }
+                    }
+                }
+
+                // Check if this is a ghost collision
+                if let Some(_ghost_index) = self.find_ghost_by_id(entity_id) {
+                    // TODO: Handle Pac-Man being eaten by ghost
+                    tracing::info!("Pac-Man collided with ghost!");
+                }
             }
+        }
+    }
 
-            self.pacman.render(canvas, &mut self.atlas, &self.map.graph);
-        })?;
+    fn find_item_by_id(&self, entity_id: EntityId) -> Option<usize> {
+        self.item_ids.iter().position(|&id| id == entity_id)
+    }
+
+    fn find_ghost_by_id(&self, entity_id: EntityId) -> Option<usize> {
+        self.ghost_ids.iter().position(|&id| id == entity_id)
+    }
+
+    pub fn draw<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>, backbuffer: &mut Texture) -> GameResult<()> {
+        canvas
+            .with_texture_canvas(backbuffer, |canvas| {
+                canvas.set_draw_color(Color::BLACK);
+                canvas.clear();
+                self.map.render(canvas, &mut self.atlas, &mut self.map_texture);
+
+                // Render all items
+                for item in &self.items {
+                    if let Err(e) = item.render(canvas, &mut self.atlas, &self.map.graph) {
+                        tracing::error!("Failed to render item: {}", e);
+                    }
+                }
+
+                // Render all ghosts
+                for ghost in &self.ghosts {
+                    if let Err(e) = ghost.render(canvas, &mut self.atlas, &self.map.graph) {
+                        tracing::error!("Failed to render ghost: {}", e);
+                    }
+                }
+
+                if let Err(e) = self.pacman.render(canvas, &mut self.atlas, &self.map.graph) {
+                    tracing::error!("Failed to render pacman: {}", e);
+                }
+            })
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
 
         Ok(())
     }
@@ -168,18 +316,88 @@ impl Game {
         canvas: &mut Canvas<T>,
         backbuffer: &Texture,
         cursor_pos: glam::Vec2,
-    ) -> Result<()> {
-        canvas.copy(backbuffer, None, None).map_err(anyhow::Error::msg)?;
+    ) -> GameResult<()> {
+        canvas
+            .copy(backbuffer, None, None)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
         if self.debug_mode {
-            self.map
-                .debug_render_with_cursor(canvas, &mut self.text_texture, &mut self.atlas, cursor_pos);
+            if let Err(e) = self
+                .map
+                .debug_render_with_cursor(canvas, &mut self.text_texture, &mut self.atlas, cursor_pos)
+            {
+                tracing::error!("Failed to render debug cursor: {}", e);
+            }
+            self.render_pathfinding_debug(canvas)?;
         }
         self.draw_hud(canvas)?;
         canvas.present();
         Ok(())
     }
 
-    fn draw_hud<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>) -> Result<()> {
+    /// 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>) -> GameResult<()> {
+        let pacman_node = self.pacman.current_node_id();
+
+        for ghost in self.ghosts.iter() {
+            if let Ok(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)
+                        .ok_or(GameError::Entity(EntityError::NodeNotFound(node_id)))?;
+                    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(|e| GameError::Sdl(e.to_string()))?;
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn draw_hud<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>) -> GameResult<()> {
         let lives = 3;
         let score_text = format!("{:02}", self.score);
         let x_offset = 4;
@@ -187,18 +405,22 @@ impl Game {
         let lives_offset = 3;
         let score_offset = 7 - (score_text.len() as i32);
         self.text_texture.set_scale(1.0);
-        let _ = self.text_texture.render(
+        if let Err(e) = self.text_texture.render(
             canvas,
             &mut self.atlas,
             &format!("{lives}UP   HIGH SCORE   "),
             UVec2::new(8 * lives_offset as u32 + x_offset, y_offset),
-        );
-        let _ = self.text_texture.render(
+        ) {
+            tracing::error!("Failed to render HUD text: {}", e);
+        }
+        if let Err(e) = self.text_texture.render(
             canvas,
             &mut self.atlas,
             &score_text,
             UVec2::new(8 * score_offset as u32 + x_offset, 8 + y_offset),
-        );
+        ) {
+            tracing::error!("Failed to render score text: {}", e);
+        }
 
         // Display FPS information in top-left corner
         // let fps_text = format!("FPS: {:.1} (1s) / {:.1} (10s)", self.fps_1s, self.fps_10s);

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/lib.rs

@@ -5,6 +5,7 @@ pub mod asset;
 pub mod audio;
 pub mod constants;
 pub mod entity;
+pub mod error;
 pub mod game;
 pub mod helpers;
 pub mod map;

src/main.rs

@@ -11,6 +11,7 @@ mod audio;
 mod constants;
 
 mod entity;
+mod error;
 mod game;
 mod helpers;
 mod map;

src/map/builder.rs

@@ -1,16 +1,19 @@
 //! Map construction and building functionality.
 
-use crate::constants::{MapTile, BOARD_CELL_SIZE, CELL_SIZE};
+use crate::constants::{MapTile, BOARD_CELL_SIZE, CELL_SIZE, RAW_BOARD};
 use crate::entity::direction::Direction;
 use crate::entity::graph::{EdgePermissions, Graph, Node, NodeId};
+use crate::entity::item::{Item, ItemType};
 use crate::map::parser::MapTileParser;
 use crate::map::render::MapRenderer;
-use crate::texture::sprite::{AtlasTile, SpriteAtlas};
+use crate::texture::sprite::{AtlasTile, Sprite, SpriteAtlas};
 use glam::{IVec2, UVec2, Vec2};
 use sdl2::render::{Canvas, RenderTarget};
 use std::collections::{HashMap, VecDeque};
 use tracing::debug;
 
+use crate::error::{GameResult, MapError};
+
 /// The starting positions of the entities in the game.
 #[allow(dead_code)]
 pub struct NodePositions {
@@ -47,8 +50,8 @@ impl Map {
     ///
     /// This function will panic if the board layout contains unknown characters or if
     /// the house door is not defined by exactly two '=' characters.
-    pub fn new(raw_board: [&str; BOARD_CELL_SIZE.y as usize]) -> Map {
-        let parsed_map = MapTileParser::parse_board(raw_board).expect("Failed to parse board layout");
+    pub fn new(raw_board: [&str; BOARD_CELL_SIZE.y as usize]) -> GameResult<Map> {
+        let parsed_map = MapTileParser::parse_board(raw_board)?;
 
         let map = parsed_map.tiles;
         let house_door = parsed_map.house_door;
@@ -61,7 +64,8 @@ impl Map {
         let cell_offset = Vec2::splat(CELL_SIZE as f32 / 2.0);
 
         // Find a starting point for the graph generation, preferably Pac-Man's position.
-        let start_pos = pacman_start.expect("Pac-Man's starting position not found");
+        let start_pos =
+            pacman_start.ok_or_else(|| MapError::InvalidConfig("Pac-Man's starting position not found".to_string()))?;
 
         // Add the starting position to the graph/queue
         let mut queue = VecDeque::new();
@@ -114,7 +118,7 @@ impl Map {
                     // Connect the new node to the source node
                     graph
                         .connect(*source_node_id, new_node_id, false, None, dir)
-                        .expect("Failed to add edge");
+                        .map_err(|e| MapError::InvalidConfig(format!("Failed to add edge: {e}")))?;
                 }
             }
         }
@@ -129,7 +133,7 @@ impl Map {
                     if let Some(&neighbor_id) = grid_to_node.get(&neighbor) {
                         graph
                             .connect(node_id, neighbor_id, false, None, dir)
-                            .expect("Failed to add edge");
+                            .map_err(|e| MapError::InvalidConfig(format!("Failed to add edge: {e}")))?;
                     }
                 }
             }
@@ -137,7 +141,7 @@ impl Map {
 
         // Build house structure
         let (house_entrance_node_id, left_center_node_id, center_center_node_id, right_center_node_id) =
-            Self::build_house(&mut graph, &grid_to_node, &house_door);
+            Self::build_house(&mut graph, &grid_to_node, &house_door)?;
 
         let start_positions = NodePositions {
             pacman: grid_to_node[&start_pos],
@@ -148,15 +152,15 @@ impl Map {
         };
 
         // Build tunnel connections
-        Self::build_tunnels(&mut graph, &grid_to_node, &tunnel_ends);
+        Self::build_tunnels(&mut graph, &grid_to_node, &tunnel_ends)?;
 
-        Map {
+        Ok(Map {
             current: map,
             graph,
             grid_to_node,
             start_positions,
             pacman_start,
-        }
+        })
     }
 
     /// Finds the starting position for a given entity ID.
@@ -184,6 +188,44 @@ impl Map {
         MapRenderer::render_map(canvas, atlas, map_texture);
     }
 
+    /// Generates Item entities for pellets and energizers from the parsed map.
+    pub fn generate_items(&self, atlas: &SpriteAtlas) -> GameResult<Vec<Item>> {
+        // Pre-load sprites to avoid repeated texture lookups
+        let pellet_sprite = SpriteAtlas::get_tile(atlas, "maze/pellet.png")
+            .ok_or_else(|| MapError::InvalidConfig("Pellet texture not found".to_string()))?;
+        let energizer_sprite = SpriteAtlas::get_tile(atlas, "maze/energizer.png")
+            .ok_or_else(|| MapError::InvalidConfig("Energizer texture not found".to_string()))?;
+
+        // Pre-allocate with estimated capacity (typical Pac-Man maps have ~240 pellets + 4 energizers)
+        let mut items = Vec::with_capacity(250);
+
+        // Parse the raw board once
+        let parsed_map = MapTileParser::parse_board(RAW_BOARD)?;
+        let map = parsed_map.tiles;
+
+        // Iterate through the map and collect items more efficiently
+        for (x, row) in map.iter().enumerate() {
+            for (y, tile) in row.iter().enumerate() {
+                match tile {
+                    MapTile::Pellet | MapTile::PowerPellet => {
+                        let grid_pos = IVec2::new(x as i32, y as i32);
+                        if let Some(&node_id) = self.grid_to_node.get(&grid_pos) {
+                            let (item_type, sprite) = match tile {
+                                MapTile::Pellet => (ItemType::Pellet, Sprite::new(pellet_sprite)),
+                                MapTile::PowerPellet => (ItemType::Energizer, Sprite::new(energizer_sprite)),
+                                _ => unreachable!(), // We already filtered for these types
+                            };
+                            items.push(Item::new(node_id, item_type, sprite));
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        Ok(items)
+    }
+
     /// Renders a debug visualization with cursor-based highlighting.
     ///
     /// This function provides interactive debugging by highlighting the nearest node
@@ -194,8 +236,8 @@ impl Map {
         text_renderer: &mut crate::texture::text::TextTexture,
         atlas: &mut SpriteAtlas,
         cursor_pos: glam::Vec2,
-    ) {
-        MapRenderer::debug_render_with_cursor(&self.graph, canvas, text_renderer, atlas, cursor_pos);
+    ) -> GameResult<()> {
+        MapRenderer::debug_render_with_cursor(&self.graph, canvas, text_renderer, atlas, cursor_pos)
     }
 
     /// Builds the house structure in the graph.
@@ -203,21 +245,32 @@ impl Map {
         graph: &mut Graph,
         grid_to_node: &HashMap<IVec2, NodeId>,
         house_door: &[Option<IVec2>; 2],
-    ) -> (usize, usize, usize, usize) {
+    ) -> GameResult<(usize, usize, usize, usize)> {
         // Calculate the position of the house entrance node
         let (house_entrance_node_id, house_entrance_node_position) = {
             // Translate the grid positions to the actual node ids
             let left_node = grid_to_node
-                .get(&(house_door[0].expect("First house door position not acquired") + Direction::Left.as_ivec2()))
-                .expect("Left house door node  not found");
+                .get(
+                    &(house_door[0]
+                        .ok_or_else(|| MapError::InvalidConfig("First house door position not acquired".to_string()))?
+                        + Direction::Left.as_ivec2()),
+                )
+                .ok_or_else(|| MapError::InvalidConfig("Left house door node not found".to_string()))?;
             let right_node = grid_to_node
-                .get(&(house_door[1].expect("Second house door position not acquired") + Direction::Right.as_ivec2()))
-                .expect("Right house door node  not found");
+                .get(
+                    &(house_door[1]
+                        .ok_or_else(|| MapError::InvalidConfig("Second house door position not acquired".to_string()))?
+                        + Direction::Right.as_ivec2()),
+                )
+                .ok_or_else(|| MapError::InvalidConfig("Right house door node not found".to_string()))?;
 
             // Calculate the position of the house node
             let (node_id, node_position) = {
-                let left_pos = graph.get_node(*left_node).unwrap().position;
-                let right_pos = graph.get_node(*right_node).unwrap().position;
+                let left_pos = graph.get_node(*left_node).ok_or(MapError::NodeNotFound(*left_node))?.position;
+                let right_pos = graph
+                    .get_node(*right_node)
+                    .ok_or(MapError::NodeNotFound(*right_node))?
+                    .position;
                 let house_node = graph.add_node(Node {
                     position: left_pos.lerp(right_pos, 0.5),
                 });
@@ -227,16 +280,16 @@ impl Map {
             // Connect the house door to the left and right nodes
             graph
                 .connect(node_id, *left_node, true, None, Direction::Left)
-                .expect("Failed to connect house door to left node");
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house door to left node: {e}")))?;
             graph
                 .connect(node_id, *right_node, true, None, Direction::Right)
-                .expect("Failed to connect house door to right node");
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house door to right node: {e}")))?;
 
             (node_id, node_position)
         };
 
         // A helper function to help create the various 'lines' of nodes within the house
-        let create_house_line = |graph: &mut Graph, center_pos: Vec2| -> (NodeId, NodeId) {
+        let create_house_line = |graph: &mut Graph, center_pos: Vec2| -> GameResult<(NodeId, NodeId)> {
             // Place the nodes at, above, and below the center position
             let center_node_id = graph.add_node(Node { position: center_pos });
             let top_node_id = graph.add_node(Node {
@@ -249,12 +302,12 @@ impl Map {
             // Connect the center node to the top and bottom nodes
             graph
                 .connect(center_node_id, top_node_id, false, None, Direction::Up)
-                .expect("Failed to connect house line to left node");
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house line to top node: {e}")))?;
             graph
                 .connect(center_node_id, bottom_node_id, false, None, Direction::Down)
-                .expect("Failed to connect house line to right node");
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house line to bottom node: {e}")))?;
 
-            (center_node_id, top_node_id)
+            Ok((center_node_id, top_node_id))
         };
 
         // Calculate the position of the center line's center node
@@ -262,7 +315,7 @@ impl Map {
             house_entrance_node_position + (Direction::Down.as_ivec2() * (3 * CELL_SIZE as i32)).as_vec2();
 
         // Create the center line
-        let (center_center_node_id, center_top_node_id) = create_house_line(graph, center_line_center_position);
+        let (center_center_node_id, center_top_node_id) = create_house_line(graph, center_line_center_position)?;
 
         // Create a ghost-only, two-way connection for the house door.
         // This prevents Pac-Man from entering or exiting through the door.
@@ -275,7 +328,7 @@ impl Map {
                 Direction::Down,
                 EdgePermissions::GhostsOnly,
             )
-            .expect("Failed to create ghost-only entrance to house");
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to create ghost-only entrance to house: {e}")))?;
 
         graph
             .add_edge(
@@ -286,52 +339,57 @@ impl Map {
                 Direction::Up,
                 EdgePermissions::GhostsOnly,
             )
-            .expect("Failed to create ghost-only exit from house");
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to create ghost-only exit from house: {e}")))?;
 
         // Create the left line
         let (left_center_node_id, _) = create_house_line(
             graph,
             center_line_center_position + (Direction::Left.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
-        );
+        )?;
 
         // Create the right line
         let (right_center_node_id, _) = create_house_line(
             graph,
             center_line_center_position + (Direction::Right.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
-        );
+        )?;
 
         debug!("Left center node id: {left_center_node_id}");
 
         // Connect the center line to the left and right lines
         graph
             .connect(center_center_node_id, left_center_node_id, false, None, Direction::Left)
-            .expect("Failed to connect house entrance to left top line");
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house entrance to left top line: {e}")))?;
 
         graph
             .connect(center_center_node_id, right_center_node_id, false, None, Direction::Right)
-            .expect("Failed to connect house entrance to right top line");
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house entrance to right top line: {e}")))?;
 
         debug!("House entrance node id: {house_entrance_node_id}");
 
-        (
+        Ok((
             house_entrance_node_id,
             left_center_node_id,
             center_center_node_id,
             right_center_node_id,
-        )
+        ))
     }
 
     /// Builds the tunnel connections in the graph.
-    fn build_tunnels(graph: &mut Graph, grid_to_node: &HashMap<IVec2, NodeId>, tunnel_ends: &[Option<IVec2>; 2]) {
+    fn build_tunnels(
+        graph: &mut Graph,
+        grid_to_node: &HashMap<IVec2, NodeId>,
+        tunnel_ends: &[Option<IVec2>; 2],
+    ) -> GameResult<()> {
         // Create the hidden tunnel nodes
         let left_tunnel_hidden_node_id = {
-            let left_tunnel_entrance_node_id = grid_to_node[&tunnel_ends[0].expect("Left tunnel end not found")];
+            let left_tunnel_entrance_node_id =
+                grid_to_node[&tunnel_ends[0].ok_or_else(|| MapError::InvalidConfig("Left tunnel end not found".to_string()))?];
             let left_tunnel_entrance_node = graph
                 .get_node(left_tunnel_entrance_node_id)
-                .expect("Left tunnel entrance node not found");
+                .ok_or_else(|| MapError::InvalidConfig("Left tunnel entrance node not found".to_string()))?;
 
             graph
-                .connect_node(
+                .add_connected(
                     left_tunnel_entrance_node_id,
                     Direction::Left,
                     Node {
@@ -339,18 +397,24 @@ impl Map {
                             + (Direction::Left.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
                     },
                 )
-                .expect("Failed to connect left tunnel entrance to left tunnel hidden node")
+                .map_err(|e| {
+                    MapError::InvalidConfig(format!(
+                        "Failed to connect left tunnel entrance to left tunnel hidden node: {}",
+                        e
+                    ))
+                })?
         };
 
         // Create the right tunnel nodes
         let right_tunnel_hidden_node_id = {
-            let right_tunnel_entrance_node_id = grid_to_node[&tunnel_ends[1].expect("Right tunnel end not found")];
+            let right_tunnel_entrance_node_id =
+                grid_to_node[&tunnel_ends[1].ok_or_else(|| MapError::InvalidConfig("Right tunnel end not found".to_string()))?];
             let right_tunnel_entrance_node = graph
                 .get_node(right_tunnel_entrance_node_id)
-                .expect("Right tunnel entrance node not found");
+                .ok_or_else(|| MapError::InvalidConfig("Right tunnel entrance node not found".to_string()))?;
 
             graph
-                .connect_node(
+                .add_connected(
                     right_tunnel_entrance_node_id,
                     Direction::Right,
                     Node {
@@ -358,7 +422,12 @@ impl Map {
                             + (Direction::Right.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
                     },
                 )
-                .expect("Failed to connect right tunnel entrance to right tunnel hidden node")
+                .map_err(|e| {
+                    MapError::InvalidConfig(format!(
+                        "Failed to connect right tunnel entrance to right tunnel hidden node: {}",
+                        e
+                    ))
+                })?
         };
 
         // Connect the left tunnel hidden node to the right tunnel hidden node
@@ -370,6 +439,13 @@ impl Map {
                 Some(0.0),
                 Direction::Left,
             )
-            .expect("Failed to connect left tunnel hidden node to right tunnel hidden node");
+            .map_err(|e| {
+                MapError::InvalidConfig(format!(
+                    "Failed to connect left tunnel hidden node to right tunnel hidden node: {}",
+                    e
+                ))
+            })?;
+
+        Ok(())
     }
 }

src/map/parser.rs

@@ -11,6 +11,8 @@ pub enum ParseError {
     UnknownCharacter(char),
     #[error("House door must have exactly 2 positions, found {0}")]
     InvalidHouseDoorCount(usize),
+    #[error("Map parsing failed: {0}")]
+    ParseFailed(String),
 }
 
 /// Represents the parsed data from a raw board layout.
@@ -67,6 +69,25 @@ impl MapTileParser {
     /// Returns an error if the board contains unknown characters or if the house door
     /// is not properly defined by exactly two '=' characters.
     pub fn parse_board(raw_board: [&str; BOARD_CELL_SIZE.y as usize]) -> Result<ParsedMap, ParseError> {
+        // Validate board dimensions
+        if raw_board.len() != BOARD_CELL_SIZE.y as usize {
+            return Err(ParseError::ParseFailed(format!(
+                "Invalid board height: expected {}, got {}",
+                BOARD_CELL_SIZE.y,
+                raw_board.len()
+            )));
+        }
+
+        for (i, line) in raw_board.iter().enumerate() {
+            if line.len() != BOARD_CELL_SIZE.x as usize {
+                return Err(ParseError::ParseFailed(format!(
+                    "Invalid board width at line {}: expected {}, got {}",
+                    i,
+                    BOARD_CELL_SIZE.x,
+                    line.len()
+                )));
+            }
+        }
         let mut tiles = [[MapTile::Empty; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize];
         let mut house_door = [None; 2];
         let mut tunnel_ends = [None; 2];

src/map/render.rs

@@ -7,6 +7,8 @@ use sdl2::pixels::Color;
 use sdl2::rect::{Point, Rect};
 use sdl2::render::{Canvas, RenderTarget};
 
+use crate::error::{EntityError, GameError, GameResult};
+
 /// Handles rendering operations for the map.
 pub struct MapRenderer;
 
@@ -22,7 +24,9 @@ impl MapRenderer {
             crate::constants::BOARD_PIXEL_SIZE.x,
             crate::constants::BOARD_PIXEL_SIZE.y,
         );
-        let _ = map_texture.render(canvas, atlas, dest);
+        if let Err(e) = map_texture.render(canvas, atlas, dest) {
+            tracing::error!("Failed to render map: {}", e);
+        }
     }
 
     /// Renders a debug visualization with cursor-based highlighting.
@@ -35,55 +39,67 @@ impl MapRenderer {
         text_renderer: &mut TextTexture,
         atlas: &mut SpriteAtlas,
         cursor_pos: Vec2,
-    ) {
+    ) -> GameResult<()> {
         // Find the nearest node to the cursor
         let nearest_node = Self::find_nearest_node(graph, cursor_pos);
 
         // Draw all connections in blue
         canvas.set_draw_color(Color::RGB(0, 0, 128)); // Dark blue for regular connections
         for i in 0..graph.node_count() {
-            let node = graph.get_node(i).unwrap();
+            let node = graph.get_node(i).ok_or(GameError::Entity(EntityError::NodeNotFound(i)))?;
             let pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
 
             for edge in graph.adjacency_list[i].edges() {
-                let end_pos = graph.get_node(edge.target).unwrap().position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
+                let end_pos = graph
+                    .get_node(edge.target)
+                    .ok_or(GameError::Entity(EntityError::NodeNotFound(edge.target)))?
+                    .position
+                    + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
                 canvas
                     .draw_line((pos.x as i32, pos.y as i32), (end_pos.x as i32, end_pos.y as i32))
-                    .unwrap();
+                    .map_err(|e| GameError::Sdl(e.to_string()))?;
             }
         }
 
         // Draw all nodes in green
         canvas.set_draw_color(Color::RGB(0, 128, 0)); // Dark green for regular nodes
         for i in 0..graph.node_count() {
-            let node = graph.get_node(i).unwrap();
+            let node = graph.get_node(i).ok_or(GameError::Entity(EntityError::NodeNotFound(i)))?;
             let pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
 
             canvas
                 .fill_rect(Rect::new(0, 0, 3, 3).centered_on(Point::new(pos.x as i32, pos.y as i32)))
-                .unwrap();
+                .map_err(|e| GameError::Sdl(e.to_string()))?;
         }
 
         // Highlight connections from the nearest node in bright blue
         if let Some(nearest_id) = nearest_node {
-            let nearest_pos = graph.get_node(nearest_id).unwrap().position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
+            let nearest_pos = graph
+                .get_node(nearest_id)
+                .ok_or(GameError::Entity(EntityError::NodeNotFound(nearest_id)))?
+                .position
+                + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
 
             canvas.set_draw_color(Color::RGB(0, 255, 255)); // Bright cyan for highlighted connections
             for edge in graph.adjacency_list[nearest_id].edges() {
-                let end_pos = graph.get_node(edge.target).unwrap().position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
+                let end_pos = graph
+                    .get_node(edge.target)
+                    .ok_or(GameError::Entity(EntityError::NodeNotFound(edge.target)))?
+                    .position
+                    + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
                 canvas
                     .draw_line(
                         (nearest_pos.x as i32, nearest_pos.y as i32),
                         (end_pos.x as i32, end_pos.y as i32),
                     )
-                    .unwrap();
+                    .map_err(|e| GameError::Sdl(e.to_string()))?;
             }
 
             // Highlight the nearest node in bright green
             canvas.set_draw_color(Color::RGB(0, 255, 0)); // Bright green for highlighted node
             canvas
                 .fill_rect(Rect::new(0, 0, 5, 5).centered_on(Point::new(nearest_pos.x as i32, nearest_pos.y as i32)))
-                .unwrap();
+                .map_err(|e| GameError::Sdl(e.to_string()))?;
 
             // Draw node ID text (small, offset to top right)
             text_renderer.set_scale(0.5); // Small text
@@ -92,8 +108,12 @@ impl MapRenderer {
                 (nearest_pos.x + 4.0) as u32, // Offset to the right
                 (nearest_pos.y - 6.0) as u32, // Offset to the top
             );
-            let _ = text_renderer.render(canvas, atlas, &id_text, text_pos);
+            if let Err(e) = text_renderer.render(canvas, atlas, &id_text, text_pos) {
+                tracing::error!("Failed to render node ID text: {}", e);
+            }
         }
+
+        Ok(())
     }
 
     /// Finds the nearest node to the given cursor position.
@@ -102,13 +122,14 @@ impl MapRenderer {
         let mut nearest_distance = f32::INFINITY;
 
         for i in 0..graph.node_count() {
-            let node = graph.get_node(i).unwrap();
-            let node_pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-            let distance = cursor_pos.distance(node_pos);
+            if let Some(node) = graph.get_node(i) {
+                let node_pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
+                let distance = cursor_pos.distance(node_pos);
 
-            if distance < nearest_distance {
-                nearest_distance = distance;
-                nearest_id = Some(i);
+                if distance < nearest_distance {
+                    nearest_distance = distance;
+                    nearest_id = Some(i);
+                }
             }
         }
 

src/texture/sprite.rs

@@ -6,6 +6,27 @@ use sdl2::render::{Canvas, RenderTarget, Texture};
 use serde::Deserialize;
 use std::collections::HashMap;
 
+/// A simple sprite for stationary items like pellets and energizers.
+#[derive(Clone, Debug)]
+pub struct Sprite {
+    pub atlas_tile: AtlasTile,
+}
+
+impl Sprite {
+    pub fn new(atlas_tile: AtlasTile) -> Self {
+        Self { atlas_tile }
+    }
+
+    pub fn render<C: RenderTarget>(&self, canvas: &mut Canvas<C>, atlas: &mut SpriteAtlas, position: glam::Vec2) -> Result<()> {
+        let dest = crate::helpers::centered_with_size(
+            glam::IVec2::new(position.x as i32, position.y as i32),
+            glam::UVec2::new(self.atlas_tile.size.x as u32, self.atlas_tile.size.y as u32),
+        );
+        let mut tile = self.atlas_tile;
+        tile.render(canvas, atlas, dest)
+    }
+}
+
 #[derive(Clone, Debug, Deserialize)]
 pub struct AtlasMapper {
     pub frames: HashMap<String, MapperFrame>,

tests/blinking.rs

@@ -16,16 +16,16 @@ fn test_blinking_texture() {
     let tile = mock_atlas_tile(1);
     let mut texture = BlinkingTexture::new(tile, 0.5);
 
-    assert_eq!(texture.is_on(), true);
+    assert!(texture.is_on());
 
     texture.tick(0.5);
-    assert_eq!(texture.is_on(), false);
+    assert!(!texture.is_on());
 
     texture.tick(0.5);
-    assert_eq!(texture.is_on(), true);
+    assert!(texture.is_on());
 
     texture.tick(0.5);
-    assert_eq!(texture.is_on(), false);
+    assert!(!texture.is_on());
 }
 
 #[test]
@@ -34,7 +34,7 @@ fn test_blinking_texture_partial_duration() {
     let mut texture = BlinkingTexture::new(tile, 0.5);
 
     texture.tick(0.625);
-    assert_eq!(texture.is_on(), false);
+    assert!(!texture.is_on());
     assert_eq!(texture.time_bank(), 0.125);
 }
 
@@ -44,6 +44,6 @@ fn test_blinking_texture_negative_time() {
     let mut texture = BlinkingTexture::new(tile, 0.5);
 
     texture.tick(-0.1);
-    assert_eq!(texture.is_on(), true);
+    assert!(texture.is_on());
     assert_eq!(texture.time_bank(), -0.1);
 }

tests/collision.rs

@@ -0,0 +1,119 @@
+use pacman::entity::collision::{Collidable, CollisionSystem};
+use pacman::entity::traversal::Position;
+
+struct MockCollidable {
+    pos: Position,
+}
+
+impl Collidable for MockCollidable {
+    fn position(&self) -> Position {
+        self.pos
+    }
+}
+
+#[test]
+fn test_is_colliding_with() {
+    let entity1 = MockCollidable {
+        pos: Position::AtNode(1),
+    };
+    let entity2 = MockCollidable {
+        pos: Position::AtNode(1),
+    };
+    let entity3 = MockCollidable {
+        pos: Position::AtNode(2),
+    };
+    let entity4 = MockCollidable {
+        pos: Position::BetweenNodes {
+            from: 1,
+            to: 2,
+            traversed: 0.5,
+        },
+    };
+
+    assert!(entity1.is_colliding_with(&entity2));
+    assert!(!entity1.is_colliding_with(&entity3));
+    assert!(entity1.is_colliding_with(&entity4));
+    assert!(entity3.is_colliding_with(&entity4));
+}
+
+#[test]
+fn test_collision_system_register_and_query() {
+    let mut collision_system = CollisionSystem::default();
+
+    let pos1 = Position::AtNode(1);
+    let entity1 = collision_system.register_entity(pos1);
+
+    let pos2 = Position::BetweenNodes {
+        from: 1,
+        to: 2,
+        traversed: 0.5,
+    };
+    let entity2 = collision_system.register_entity(pos2);
+
+    let pos3 = Position::AtNode(3);
+    let entity3 = collision_system.register_entity(pos3);
+
+    // Test entities_at_node
+    assert_eq!(collision_system.entities_at_node(1), &[entity1, entity2]);
+    assert_eq!(collision_system.entities_at_node(2), &[entity2]);
+    assert_eq!(collision_system.entities_at_node(3), &[entity3]);
+    assert_eq!(collision_system.entities_at_node(4), &[] as &[u32]);
+
+    // Test potential_collisions
+    let mut collisions1 = collision_system.potential_collisions(&pos1);
+    collisions1.sort_unstable();
+    assert_eq!(collisions1, vec![entity1, entity2]);
+
+    let mut collisions2 = collision_system.potential_collisions(&pos2);
+    collisions2.sort_unstable();
+    assert_eq!(collisions2, vec![entity1, entity2]);
+
+    let mut collisions3 = collision_system.potential_collisions(&pos3);
+    collisions3.sort_unstable();
+    assert_eq!(collisions3, vec![entity3]);
+}
+
+#[test]
+fn test_collision_system_update() {
+    let mut collision_system = CollisionSystem::default();
+
+    let entity1 = collision_system.register_entity(Position::AtNode(1));
+
+    assert_eq!(collision_system.entities_at_node(1), &[entity1]);
+    assert_eq!(collision_system.entities_at_node(2), &[] as &[u32]);
+
+    collision_system.update_position(entity1, Position::AtNode(2));
+
+    assert_eq!(collision_system.entities_at_node(1), &[] as &[u32]);
+    assert_eq!(collision_system.entities_at_node(2), &[entity1]);
+
+    collision_system.update_position(
+        entity1,
+        Position::BetweenNodes {
+            from: 2,
+            to: 3,
+            traversed: 0.1,
+        },
+    );
+
+    assert_eq!(collision_system.entities_at_node(1), &[] as &[u32]);
+    assert_eq!(collision_system.entities_at_node(2), &[entity1]);
+    assert_eq!(collision_system.entities_at_node(3), &[entity1]);
+}
+
+#[test]
+fn test_collision_system_remove() {
+    let mut collision_system = CollisionSystem::default();
+
+    let entity1 = collision_system.register_entity(Position::AtNode(1));
+    let entity2 = collision_system.register_entity(Position::AtNode(1));
+
+    assert_eq!(collision_system.entities_at_node(1), &[entity1, entity2]);
+
+    collision_system.remove_entity(entity1);
+
+    assert_eq!(collision_system.entities_at_node(1), &[entity2]);
+
+    collision_system.remove_entity(entity2);
+    assert_eq!(collision_system.entities_at_node(1), &[] as &[u32]);
+}

tests/directional.rs

@@ -52,3 +52,26 @@ fn test_directional_texture_all_directions() {
         assert!(texture.has_direction(*direction));
     }
 }
+
+#[test]
+fn test_directional_texture_stopped() {
+    let mut stopped_textures = [None, None, None, None];
+    stopped_textures[Direction::Up.as_usize()] = Some(mock_animated_texture(1));
+
+    let texture = DirectionalAnimatedTexture::new([None, None, None, None], stopped_textures);
+
+    assert_eq!(texture.stopped_texture_count(), 1);
+    assert!(texture.has_stopped_direction(Direction::Up));
+    assert!(!texture.has_stopped_direction(Direction::Down));
+}
+
+#[test]
+fn test_directional_texture_tick() {
+    let mut textures = [None, None, None, None];
+    textures[Direction::Up.as_usize()] = Some(mock_animated_texture(1));
+    let mut texture = DirectionalAnimatedTexture::new(textures, [None, None, None, None]);
+
+    // This is a bit of a placeholder, since we can't inspect the inner state easily.
+    // We're just ensuring the tick method runs without panicking.
+    texture.tick(0.1);
+}

tests/game.rs

@@ -1,9 +1,12 @@
 use pacman::constants::RAW_BOARD;
 use pacman::map::Map;
 
+mod collision;
+mod item;
+
 #[test]
 fn test_game_map_creation() {
-    let map = Map::new(RAW_BOARD);
+    let map = Map::new(RAW_BOARD).unwrap();
 
     assert!(map.graph.node_count() > 0);
     assert!(!map.grid_to_node.is_empty());
@@ -16,6 +19,6 @@ fn test_game_map_creation() {
 #[test]
 fn test_game_score_initialization() {
     // This would require creating a full Game instance, but we can test the concept
-    let map = Map::new(RAW_BOARD);
+    let map = Map::new(RAW_BOARD).unwrap();
     assert!(map.find_starting_position(0).is_some());
 }

tests/ghost.rs

@@ -41,7 +41,7 @@ fn test_ghost_creation() {
     let graph = Graph::new();
     let atlas = create_test_atlas();
 
-    let ghost = Ghost::new(&graph, 0, GhostType::Blinky, &atlas);
+    let ghost = Ghost::new(&graph, 0, GhostType::Blinky, &atlas).unwrap();
 
     assert_eq!(ghost.ghost_type, GhostType::Blinky);
     assert_eq!(ghost.traverser.position.from_node_id(), 0);

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();
@@ -100,7 +101,7 @@ fn test_traverser_advance() {
     let graph = create_test_graph();
     let mut traverser = Traverser::new(&graph, 0, Direction::Right, &|_| true);
 
-    traverser.advance(&graph, 5.0, &|_| true);
+    traverser.advance(&graph, 5.0, &|_| true).unwrap();
 
     match traverser.position {
         Position::BetweenNodes { from, to, traversed } => {
@@ -111,7 +112,7 @@ fn test_traverser_advance() {
         _ => panic!("Expected to be between nodes"),
     }
 
-    traverser.advance(&graph, 3.0, &|_| true);
+    traverser.advance(&graph, 3.0, &|_| true).unwrap();
 
     match traverser.position {
         Position::BetweenNodes { from, to, traversed } => {
@@ -142,7 +143,9 @@ fn test_traverser_with_permissions() {
         matches!(edge.permissions, EdgePermissions::All)
     });
 
-    traverser.advance(&graph, 5.0, &|edge| matches!(edge.permissions, EdgePermissions::All));
+    traverser
+        .advance(&graph, 5.0, &|edge| matches!(edge.permissions, EdgePermissions::All))
+        .unwrap();
 
     // Should still be at the node since it can't traverse
     assert!(traverser.position.is_at_node());

tests/item.rs

@@ -0,0 +1,53 @@
+use glam::U16Vec2;
+use pacman::{
+    entity::{
+        collision::Collidable,
+        item::{FruitKind, Item, ItemType},
+    },
+    texture::sprite::{AtlasTile, Sprite},
+};
+use strum::{EnumCount, IntoEnumIterator};
+
+#[test]
+fn test_item_type_get_score() {
+    assert_eq!(ItemType::Pellet.get_score(), 10);
+    assert_eq!(ItemType::Energizer.get_score(), 50);
+
+    let fruit = ItemType::Fruit { kind: FruitKind::Apple };
+    assert_eq!(fruit.get_score(), 100);
+}
+
+#[test]
+fn test_fruit_kind_increasing_score() {
+    // Build a list of fruit kinds, sorted by their index
+    let mut kinds = FruitKind::iter()
+        .map(|kind| (kind.index(), kind.get_score()))
+        .collect::<Vec<_>>();
+    kinds.sort_unstable_by_key(|(index, _)| *index);
+
+    assert_eq!(kinds.len(), FruitKind::COUNT as usize);
+
+    // Check that the score increases as expected
+    for window in kinds.windows(2) {
+        let ((_, prev), (_, next)) = (window[0], window[1]);
+        assert!(prev < next, "Fruits should have increasing scores, but {prev:?} < {next:?}");
+    }
+}
+
+#[test]
+fn test_item_creation_and_collection() {
+    let atlas_tile = AtlasTile {
+        pos: U16Vec2::new(0, 0),
+        size: U16Vec2::new(16, 16),
+        color: None,
+    };
+    let sprite = Sprite::new(atlas_tile);
+    let mut item = Item::new(0, ItemType::Pellet, sprite);
+
+    assert!(!item.is_collected());
+    assert_eq!(item.get_score(), 10);
+    assert_eq!(item.position().from_node_id(), 0);
+
+    item.collect();
+    assert!(item.is_collected());
+}

tests/map_builder.rs

@@ -1,47 +1,11 @@
 use glam::Vec2;
-use pacman::constants::{BOARD_CELL_SIZE, CELL_SIZE};
+use pacman::constants::{BOARD_CELL_SIZE, CELL_SIZE, RAW_BOARD};
 use pacman::map::Map;
-
-fn create_minimal_test_board() -> [&'static str; BOARD_CELL_SIZE.y as usize] {
-    let mut board = [""; BOARD_CELL_SIZE.y as usize];
-    board[0] = "############################";
-    board[1] = "#............##............#";
-    board[2] = "#.####.#####.##.#####.####.#";
-    board[3] = "#o####.#####.##.#####.####o#";
-    board[4] = "#.####.#####.##.#####.####.#";
-    board[5] = "#..........................#";
-    board[6] = "#.####.##.########.##.####.#";
-    board[7] = "#.####.##.########.##.####.#";
-    board[8] = "#......##....##....##......#";
-    board[9] = "######.##### ## #####.######";
-    board[10] = "     #.##### ## #####.#     ";
-    board[11] = "     #.##    ==    ##.#     ";
-    board[12] = "     #.## ######## ##.#     ";
-    board[13] = "######.## ######## ##.######";
-    board[14] = "T     .   ########   .     T";
-    board[15] = "######.## ######## ##.######";
-    board[16] = "     #.## ######## ##.#     ";
-    board[17] = "     #.##          ##.#     ";
-    board[18] = "     #.## ######## ##.#     ";
-    board[19] = "######.## ######## ##.######";
-    board[20] = "#............##............#";
-    board[21] = "#.####.#####.##.#####.####.#";
-    board[22] = "#.####.#####.##.#####.####.#";
-    board[23] = "#o..##.......X .......##..o#";
-    board[24] = "###.##.##.########.##.##.###";
-    board[25] = "###.##.##.########.##.##.###";
-    board[26] = "#......##....##....##......#";
-    board[27] = "#.##########.##.##########.#";
-    board[28] = "#.##########.##.##########.#";
-    board[29] = "#..........................#";
-    board[30] = "############################";
-    board
-}
+use sdl2::render::Texture;
 
 #[test]
 fn test_map_creation() {
-    let board = create_minimal_test_board();
-    let map = Map::new(board);
+    let map = Map::new(RAW_BOARD).unwrap();
 
     assert!(map.graph.node_count() > 0);
     assert!(!map.grid_to_node.is_empty());
@@ -59,8 +23,7 @@ fn test_map_creation() {
 
 #[test]
 fn test_map_starting_positions() {
-    let board = create_minimal_test_board();
-    let map = Map::new(board);
+    let map = Map::new(RAW_BOARD).unwrap();
 
     let pacman_pos = map.find_starting_position(0);
     assert!(pacman_pos.is_some());
@@ -73,8 +36,7 @@ fn test_map_starting_positions() {
 
 #[test]
 fn test_map_node_positions() {
-    let board = create_minimal_test_board();
-    let map = Map::new(board);
+    let map = Map::new(RAW_BOARD).unwrap();
 
     for (grid_pos, &node_id) in &map.grid_to_node {
         let node = map.graph.get_node(node_id).unwrap();
@@ -84,3 +46,61 @@ fn test_map_node_positions() {
         assert_eq!(node.position, expected_pos);
     }
 }
+
+#[test]
+fn test_generate_items() {
+    use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
+    use std::collections::HashMap;
+
+    let map = Map::new(RAW_BOARD).unwrap();
+
+    // Create a minimal atlas for testing
+    let mut frames = HashMap::new();
+    frames.insert(
+        "maze/pellet.png".to_string(),
+        MapperFrame {
+            x: 0,
+            y: 0,
+            width: 8,
+            height: 8,
+        },
+    );
+    frames.insert(
+        "maze/energizer.png".to_string(),
+        MapperFrame {
+            x: 8,
+            y: 0,
+            width: 8,
+            height: 8,
+        },
+    );
+
+    let mapper = AtlasMapper { frames };
+    let texture = unsafe { std::mem::transmute::<usize, Texture<'static>>(0usize) };
+    let atlas = SpriteAtlas::new(texture, mapper);
+
+    let items = map.generate_items(&atlas).unwrap();
+
+    // Verify we have items
+    assert!(!items.is_empty());
+
+    // Count different types
+    let pellet_count = items
+        .iter()
+        .filter(|item| matches!(item.item_type, pacman::entity::item::ItemType::Pellet))
+        .count();
+    let energizer_count = items
+        .iter()
+        .filter(|item| matches!(item.item_type, pacman::entity::item::ItemType::Energizer))
+        .count();
+
+    // Should have both types
+    assert_eq!(pellet_count, 240);
+    assert_eq!(energizer_count, 4);
+
+    // All items should be uncollected initially
+    assert!(items.iter().all(|item| !item.is_collected()));
+
+    // All items should have valid node indices
+    assert!(items.iter().all(|item| item.node_index < map.graph.node_count()));
+}

tests/pacman.rs

@@ -67,7 +67,7 @@ fn create_test_atlas() -> SpriteAtlas {
 fn test_pacman_creation() {
     let graph = create_test_graph();
     let atlas = create_test_atlas();
-    let pacman = Pacman::new(&graph, 0, &atlas);
+    let pacman = Pacman::new(&graph, 0, &atlas).unwrap();
 
     assert!(pacman.traverser.position.is_at_node());
     assert_eq!(pacman.traverser.direction, Direction::Left);
@@ -77,7 +77,7 @@ fn test_pacman_creation() {
 fn test_pacman_key_handling() {
     let graph = create_test_graph();
     let atlas = create_test_atlas();
-    let mut pacman = Pacman::new(&graph, 0, &atlas);
+    let mut pacman = Pacman::new(&graph, 0, &atlas).unwrap();
 
     let test_cases = [
         (Keycode::Up, Direction::Up),
@@ -96,7 +96,7 @@ fn test_pacman_key_handling() {
 fn test_pacman_invalid_key() {
     let graph = create_test_graph();
     let atlas = create_test_atlas();
-    let mut pacman = Pacman::new(&graph, 0, &atlas);
+    let mut pacman = Pacman::new(&graph, 0, &atlas).unwrap();
 
     let original_direction = pacman.traverser.direction;
     let original_next_direction = pacman.traverser.next_direction;

tests/parser.rs

@@ -37,10 +37,10 @@ fn test_parse_board() {
 
 #[test]
 fn test_parse_board_invalid_character() {
-    let mut invalid_board = RAW_BOARD.clone();
-    invalid_board[0] = "###########################Z";
+    let mut invalid_board = RAW_BOARD.map(|s| s.to_string());
+    invalid_board[0] = "###########################Z".to_string();
 
-    let result = MapTileParser::parse_board(invalid_board);
+    let result = MapTileParser::parse_board(invalid_board.each_ref().map(|s| s.as_str()));
     assert!(result.is_err());
     assert!(matches!(result.unwrap_err(), ParseError::UnknownCharacter('Z')));
 }

tests/pathfinding.rs

@@ -0,0 +1,120 @@
+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).unwrap();
+
+    // Test pathfinding from node 0 to node 2
+    let path = ghost.calculate_path_to_target(&graph, node2);
+
+    assert!(path.is_ok());
+    let path = path.unwrap();
+    assert!(
+        path == vec![node0, node1, node2] || path == vec![node2, node1, node0],
+        "Path was not what was expected"
+    );
+}
+
+#[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).unwrap();
+
+    // Test pathfinding when no path exists
+    let path = ghost.calculate_path_to_target(&graph, node1);
+
+    assert!(path.is_err());
+}
+
+#[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).unwrap();
+    let pinky = Ghost::new(&graph, node, GhostType::Pinky, &atlas).unwrap();
+    let inky = Ghost::new(&graph, node, GhostType::Inky, &atlas).unwrap();
+    let clyde = Ghost::new(&graph, node, GhostType::Clyde, &atlas).unwrap();
+
+    // 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");
+}

tests/sprite.rs

@@ -1,4 +1,5 @@
-use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
+use glam::U16Vec2;
+use pacman::texture::sprite::{AtlasMapper, AtlasTile, MapperFrame, Sprite, SpriteAtlas};
 use sdl2::pixels::Color;
 use std::collections::HashMap;
 
@@ -76,3 +77,27 @@ fn test_sprite_atlas_color() {
     atlas.set_color(color);
     assert_eq!(atlas.default_color(), Some(color));
 }
+
+#[test]
+fn test_atlas_tile_new_and_with_color() {
+    let pos = U16Vec2::new(10, 20);
+    let size = U16Vec2::new(30, 40);
+    let color = Color::RGB(100, 150, 200);
+
+    let tile = AtlasTile::new(pos, size, None);
+    assert_eq!(tile.pos, pos);
+    assert_eq!(tile.size, size);
+    assert_eq!(tile.color, None);
+
+    let tile_with_color = tile.with_color(color);
+    assert_eq!(tile_with_color.color, Some(color));
+}
+
+#[test]
+fn test_sprite_new() {
+    let atlas_tile = AtlasTile::new(U16Vec2::new(0, 0), U16Vec2::new(16, 16), None);
+    let sprite = Sprite::new(atlas_tile);
+
+    assert_eq!(sprite.atlas_tile.pos, atlas_tile.pos);
+    assert_eq!(sprite.atlas_tile.size, atlas_tile.size);
+}