feat: stage sequence, ghost collisions & energizer logic, text color method, scheduler ordering

minor format updates from copilot's commit

.pre-commit-config.yaml

@@ -20,3 +20,15 @@ repos:
         language: system
         types: [rust]
         pass_filenames: false
+      - id: cargo-check
+        name: cargo check
+        entry: cargo check --all-targets
+        language: system
+        types_or: [rust, cargo, cargo-lock]
+        pass_filenames: false
+      - id: cargo-check-wasm
+        name: cargo check for wasm32-unknown-emscripten
+        entry: cargo check --all-targets --target=wasm32-unknown-emscripten
+        language: system
+        types_or: [rust, cargo, cargo-lock]
+        pass_filenames: false

Cargo.lock

@@ -252,6 +252,12 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
 
+[[package]]
+name = "circular-buffer"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23bdce1da528cadbac4654b5632bfcd8c6c63e25b1d42cea919a95958790b51d"
+
 [[package]]
 name = "concurrent-queue"
 version = "2.5.0"
@@ -316,6 +322,12 @@ dependencies = [
  "unicode-xid",
 ]
 
+[[package]]
+name = "diff"
+version = "0.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56254986775e3233ffa9c4d7d3faaf6d36a2c09d30b20687e9f88bc8bafc16c8"
+
 [[package]]
 name = "disqualified"
 version = "1.0.0"
@@ -528,6 +540,12 @@ version = "2.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a282da65faaf38286cf3be983213fcf1d2e2a58700e808f83f4ea9a4804bc0"
 
+[[package]]
+name = "micromap"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18c087666f377f857b49564f8791b481260c67825d6b337e1e38ddf54a985a88"
+
 [[package]]
 name = "nonmax"
 version = "0.5.5"
@@ -553,6 +571,12 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "num-width"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "faede9396d7883a8c9c989e0b53c984bf770defb5cb8ed6c345b4c0566cf32b9"
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -572,13 +596,17 @@ dependencies = [
  "anyhow",
  "bevy_ecs",
  "bitflags 2.9.1",
+ "circular-buffer",
  "glam 0.30.5",
  "lazy_static",
  "libc",
+ "micromap",
+ "num-width",
  "once_cell",
  "parking_lot",
  "pathfinding",
  "phf",
+ "pretty_assertions",
  "rand",
  "sdl2",
  "serde",
@@ -588,6 +616,7 @@ dependencies = [
  "strum",
  "strum_macros",
  "thiserror",
+ "thousands",
  "tracing",
  "tracing-error",
  "tracing-subscriber",
@@ -701,6 +730,16 @@ dependencies = [
  "portable-atomic",
 ]
 
+[[package]]
+name = "pretty_assertions"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ae130e2f271fbc2ac3a40fb1d07180839cdbbe443c7a27e1e3c13c5cac0116d"
+dependencies = [
+ "diff",
+ "yansi",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.95"
@@ -992,6 +1031,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "thousands"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3bf63baf9f5039dadc247375c29eb13706706cfde997d0330d05aa63a77d8820"
+
 [[package]]
 name = "thread_local"
 version = "1.1.7"
@@ -1415,3 +1460,9 @@ checksum = "6f42320e61fe2cfd34354ecb597f86f413484a798ba44a8ca1165c58d42da6c1"
 dependencies = [
  "bitflags 2.9.1",
 ]
+
+[[package]]
+name = "yansi"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"

Cargo.toml

@@ -27,6 +27,11 @@ phf = { version = "0.12.1", features = ["macros"] }
 bevy_ecs = "0.16.1"
 bitflags = "2.9.1"
 parking_lot = "0.12.3"
+micromap = "0.1.0"
+thousands = "0.2.0"
+pretty_assertions = "1.4.1"
+num-width = "0.1.0"
+circular-buffer = "1.1.0"
 
 [profile.release]
 lto = true

src/app.rs

@@ -1,27 +1,38 @@
 use std::time::{Duration, Instant};
 
-use glam::Vec2;
 use sdl2::render::TextureCreator;
 use sdl2::ttf::Sdl2TtfContext;
 use sdl2::video::WindowContext;
 use sdl2::{AudioSubsystem, EventPump, Sdl, VideoSubsystem};
-use tracing::{field, info, warn};
 
 use crate::error::{GameError, GameResult};
 
 use crate::constants::{CANVAS_SIZE, LOOP_TIME, SCALE};
 use crate::game::Game;
 use crate::platform::get_platform;
-use crate::systems::profiling::SystemTimings;
 
+/// Main application wrapper that manages SDL initialization, window lifecycle, and the game loop.
+///
+/// Handles platform-specific setup, maintains consistent frame timing, and delegates
+/// game logic to the contained `Game` instance. The app manages focus state to
+/// optimize CPU usage when the window loses focus.
 pub struct App {
     pub game: Game,
     last_tick: Instant,
     focused: bool,
-    _cursor_pos: Vec2,
 }
 
 impl App {
+    /// Initializes SDL subsystems, creates the game window, and sets up the game state.
+    ///
+    /// Performs comprehensive initialization including video/audio subsystems, platform-specific
+    /// console setup, window creation with proper scaling, and canvas configuration. All SDL
+    /// resources are leaked to maintain 'static lifetimes required by the game architecture.
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError::Sdl` if any SDL initialization step fails, or propagates
+    /// errors from `Game::new()` during game state setup.
     pub fn new() -> GameResult<Self> {
         let sdl_context: &'static Sdl = Box::leak(Box::new(sdl2::init().map_err(|e| GameError::Sdl(e.to_string()))?));
         let video_subsystem: &'static VideoSubsystem =
@@ -68,10 +79,19 @@ impl App {
             game,
             focused: true,
             last_tick: Instant::now(),
-            _cursor_pos: Vec2::ZERO,
         })
     }
 
+    /// Executes a single frame of the game loop with consistent timing and optional sleep.
+    ///
+    /// Calculates delta time since the last frame, runs game logic via `game.tick()`,
+    /// and implements frame rate limiting by sleeping for remaining time if the frame
+    /// completed faster than the target `LOOP_TIME`. Sleep behavior varies based on
+    /// window focus to conserve CPU when the game is not active.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the game should continue running, `false` if the game requested exit.
     pub fn run(&mut self) -> bool {
         {
             let start = Instant::now();
@@ -110,17 +130,6 @@ impl App {
                 return false;
             }
 
-            // Show timings if the loop took more than 25% of the loop time
-            let show_timings = start.elapsed() > (LOOP_TIME / 4);
-            if show_timings || true {
-                if let Some(timings) = self.game.world.get_resource::<SystemTimings>() {
-                    let mut timings = timings.timings.lock();
-                    let total = timings.values().sum::<Duration>();
-                    info!("Total: {:?}, Timings: {:?}", total, field::debug(&timings));
-                    timings.clear();
-                }
-            }
-
             // Sleep if we still have time left
             if start.elapsed() < LOOP_TIME {
                 let time = LOOP_TIME.saturating_sub(start.elapsed());

src/asset.rs

@@ -5,16 +5,28 @@
 use std::borrow::Cow;
 use strum_macros::EnumIter;
 
+/// Enumeration of all game assets with cross-platform loading support.
+///
+/// Each variant corresponds to a specific file that can be loaded either from
+/// binary-embedded data or embedded filesystem (Emscripten).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, EnumIter)]
 pub enum Asset {
     Wav1,
     Wav2,
     Wav3,
     Wav4,
-    Atlas,
+    /// Main sprite atlas containing all game graphics (atlas.png)
+    AtlasImage,
+    /// Terminal Vector font for text rendering (TerminalVector.ttf)
+    Font,
 }
 
 impl Asset {
+    /// Returns the relative file path for this asset within the game's asset directory.
+    ///
+    /// Paths are consistent across platforms and used by the Emscripten backend
+    /// for filesystem loading. Desktop builds embed assets directly and don't
+    /// use these paths at runtime.
     #[allow(dead_code)]
     pub fn path(&self) -> &str {
         use Asset::*;
@@ -23,7 +35,8 @@ impl Asset {
             Wav2 => "sound/waka/2.ogg",
             Wav3 => "sound/waka/3.ogg",
             Wav4 => "sound/waka/4.ogg",
-            Atlas => "atlas.png",
+            AtlasImage => "atlas.png",
+            Font => "TerminalVector.ttf",
         }
     }
 }
@@ -33,7 +46,17 @@ mod imp {
     use crate::error::AssetError;
     use crate::platform::get_platform;
 
-    /// Returns the raw bytes of the given asset.
+    /// Loads asset bytes using the appropriate platform-specific method.
+    ///
+    /// On desktop platforms, returns embedded compile-time data via `include_bytes!`.
+    /// On Emscripten, loads from the filesystem using the asset's path. The returned
+    /// `Cow` allows zero-copy access to embedded data while supporting owned data
+    /// when loaded from disk.
+    ///
+    /// # Errors
+    ///
+    /// Returns `AssetError::NotFound` if the asset file cannot be located (Emscripten only),
+    /// or `AssetError::Io` for filesystem I/O failures.
     pub fn get_asset_bytes(asset: Asset) -> Result<Cow<'static, [u8]>, AssetError> {
         get_platform().get_asset_bytes(asset)
     }

src/audio.rs

@@ -114,9 +114,11 @@ impl Audio {
         }
     }
 
-    /// Plays the "eat" sound effect.
+    /// Plays the next waka eating sound in the cycle of four variants.
     ///
-    /// If audio is disabled or muted, this function does nothing.
+    /// Automatically rotates through the four eating sound assets. The sound plays on channel 0 and the internal sound index
+    /// advances to the next variant. Silently returns if audio is disabled, muted,
+    /// or no sounds were loaded successfully.
     #[allow(dead_code)]
     pub fn eat(&mut self) {
         if self.disabled || self.muted || self.sounds.is_empty() {
@@ -136,9 +138,11 @@ impl Audio {
         self.next_sound_index = (self.next_sound_index + 1) % self.sounds.len();
     }
 
-    /// Instantly mute or unmute all channels.
+    /// Instantly mutes or unmutes all audio channels by adjusting their volume.
     ///
-    /// If audio is disabled, this function does nothing.
+    /// Sets all 4 mixer channels to zero volume when muting, or restores them to
+    /// their default volume (32) when unmuting. The mute state is tracked internally
+    /// regardless of whether audio is disabled, allowing the state to be preserved.
     pub fn set_mute(&mut self, mute: bool) {
         if !self.disabled {
             let channels = 4;
@@ -151,12 +155,19 @@ impl Audio {
         self.muted = mute;
     }
 
-    /// Returns `true` if the audio is muted.
+    /// Returns the current mute state regardless of whether audio is functional.
+    ///
+    /// This tracks the user's mute preference and will return `true` if muted
+    /// even when the audio system is disabled due to initialization failures.
     pub fn is_muted(&self) -> bool {
         self.muted
     }
 
-    /// Returns `true` if the audio system is disabled.
+    /// Returns whether the audio system failed to initialize and is non-functional.
+    ///
+    /// Audio can be disabled due to SDL2_mixer initialization failures, missing
+    /// audio device, or failure to load any sound assets. When disabled, all
+    /// audio operations become no-ops.
     #[allow(dead_code)]
     pub fn is_disabled(&self) -> bool {
         self.disabled

src/constants.rs

@@ -4,6 +4,11 @@ use std::time::Duration;
 
 use glam::UVec2;
 
+/// Target frame duration for 60 FPS game loop timing.
+///
+/// Calculated as 1/60th of a second (≈16.67ms).
+///
+/// Written out explicitly to satisfy const-eval constraints.
 pub const LOOP_TIME: Duration = Duration::from_nanos((1_000_000_000.0 / 60.0) as u64);
 
 /// The size of each cell, in pixels.
@@ -14,9 +19,16 @@ pub const BOARD_CELL_SIZE: UVec2 = UVec2::new(28, 31);
 /// The scale factor for the window (integer zoom)
 pub const SCALE: f32 = 2.6;
 
-/// The offset of the game board from the top-left corner of the window, in cells.
+/// Game board offset from window origin to reserve space for HUD elements.
+///
+/// The 3-cell vertical offset (24 pixels) provides space at the top of the
+/// screen for score display, player lives, and other UI elements.
 pub const BOARD_CELL_OFFSET: UVec2 = UVec2::new(0, 3);
-/// The offset of the game board from the top-left corner of the window, in pixels.
+
+/// Pixel-space equivalent of `BOARD_CELL_OFFSET` for rendering calculations.
+///
+/// Automatically calculated from the cell offset to maintain consistency
+/// when the cell size changes. Used for positioning sprites and debug overlays.
 pub const BOARD_PIXEL_OFFSET: UVec2 = UVec2::new(BOARD_CELL_OFFSET.x * CELL_SIZE, BOARD_CELL_OFFSET.y * CELL_SIZE);
 /// The size of the canvas, in pixels.
 pub const CANVAS_SIZE: UVec2 = UVec2::new(
@@ -24,22 +36,24 @@ pub const CANVAS_SIZE: UVec2 = UVec2::new(
     (BOARD_CELL_SIZE.y + BOARD_CELL_OFFSET.y) * CELL_SIZE,
 );
 
-/// An enum representing the different types of tiles on the map.
+/// Map tile types that define gameplay behavior and collision properties.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum MapTile {
-    /// An empty tile.
+    /// Traversable space with no collectible items
     Empty,
-    /// A wall tile.
     Wall,
-    /// A regular pellet.
+    /// Small collectible. Implicitly a traversable tile.
     Pellet,
-    /// A power pellet.
+    /// Large collectible. Implicitly a traversable tile.
     PowerPellet,
-    /// A tunnel tile.
+    /// Special traversable tile that connects to tunnel portals.
     Tunnel,
 }
 
-/// The raw layout of the game board, as a 2D array of characters.
+/// ASCII art representation of the classic Pac-Man maze layout.
+///
+/// Uses character symbols to define the game world. This layout is parsed by `MapTileParser`
+/// to generate the navigable graph and collision geometry.
 pub const RAW_BOARD: [&str; BOARD_CELL_SIZE.y as usize] = [
     "############################",
     "#............##............#",

src/entity/collision.rs

@@ -1,128 +0,0 @@
-// use smallvec::SmallVec;
-// use std::collections::HashMap;
-
-// use crate::entity::{graph::NodeId, 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<NodeId, 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: NodeId) -> &[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<[NodeId; 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

@@ -1,254 +0,0 @@
-// //! Ghost entity implementation.
-// //!
-// //! This module contains the ghost character logic, including movement,
-// //! animation, and rendering. Ghosts move through the game graph using
-// //! a traverser and display directional animated textures.
-
-// use pathfinding::prelude::dijkstra;
-// use rand::prelude::*;
-// use smallvec::SmallVec;
-// use tracing::error;
-
-// 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 crate::error::{EntityError, GameError, GameResult, TextureError};
-
-// /// Determines if a ghost can traverse a given edge.
-// ///
-// /// Ghosts can move through edges that allow all entities or ghost-only edges.
-// fn can_ghost_traverse(edge: Edge) -> bool {
-//     matches!(edge.permissions, EdgePermissions::All | EdgePermissions::GhostsOnly)
-// }
-
-// /// The four classic ghost types.
-// #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-// pub enum GhostType {
-//     Blinky,
-//     Pinky,
-//     Inky,
-//     Clyde,
-// }
-
-// impl GhostType {
-//     /// Returns the ghost type name for atlas lookups.
-//     pub fn as_str(self) -> &'static str {
-//         match self {
-//             GhostType::Blinky => "blinky",
-//             GhostType::Pinky => "pinky",
-//             GhostType::Inky => "inky",
-//             GhostType::Clyde => "clyde",
-//         }
-//     }
-
-//     /// Returns the base movement speed for this ghost type.
-//     pub fn base_speed(self) -> f32 {
-//         match self {
-//             GhostType::Blinky => 1.0,
-//             GhostType::Pinky => 0.95,
-//             GhostType::Inky => 0.9,
-//             GhostType::Clyde => 0.85,
-//         }
-//     }
-// }
-
-// /// A ghost entity that roams the game world.
-// ///
-// /// Ghosts move through the game world using a graph-based navigation system
-// /// and display directional animated sprites. They randomly choose directions
-// /// at each intersection.
-// pub struct Ghost {
-//     /// Handles movement through the game graph
-//     pub traverser: Traverser,
-//     /// The type of ghost (affects appearance and speed)
-//     pub ghost_type: GhostType,
-//     /// Manages directional animated textures for different movement states
-//     texture: DirectionalAnimatedTexture,
-//     /// Current movement speed
-//     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) -> GameResult<Self> {
-//         let mut textures = [None, None, None, None];
-//         let mut stopped_textures = [None, None, None, None];
-
-//         for direction in Direction::DIRECTIONS {
-//             let moving_prefix = match direction {
-//                 Direction::Up => "up",
-//                 Direction::Down => "down",
-//                 Direction::Left => "left",
-//                 Direction::Right => "right",
-//             };
-//             let moving_tiles = vec![
-//                 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"))
-//                         .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)?);
-//             stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
-//         }
-
-//         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(),
-//         })
-//     }
-
-//     /// Chooses a random available direction at the current intersection.
-//     fn choose_random_direction(&mut self, graph: &Graph) {
-//         let current_node = self.traverser.position.from_node_id();
-//         let intersection = &graph.adjacency_list[current_node];
-
-//         // Collect all available directions
-//         let mut available_directions = SmallVec::<[_; 4]>::new();
-//         for direction in Direction::DIRECTIONS {
-//             if let Some(edge) = intersection.get(direction) {
-//                 if can_ghost_traverse(edge) {
-//                     available_directions.push(direction);
-//                 }
-//             }
-//         }
-//         // Choose a random direction (avoid reversing unless necessary)
-//         if !available_directions.is_empty() {
-//             let mut rng = SmallRng::from_os_rng();
-
-//             // Filter out the opposite direction if possible, but allow it if we have limited options
-//             let opposite = self.traverser.direction.opposite();
-//             let filtered_directions: Vec<_> = available_directions
-//                 .iter()
-//                 .filter(|&&dir| dir != opposite || available_directions.len() <= 2)
-//                 .collect();
-
-//             if let Some(&random_direction) = filtered_directions.choose(&mut rng) {
-//                 self.traverser.set_next_direction(*random_direction);
-//             }
-//         }
-//     }
-
-//     /// Calculates the shortest path from the ghost's current position to a target node using Dijkstra's algorithm.
-//     ///
-//     /// 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();
-
-//         // 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,
-//         );
-
-//         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/item.rs

@@ -1,117 +0,0 @@
-// use crate::{
-//     constants,
-//     entity::{collision::Collidable, graph::Graph},
-//     error::{EntityError, GameResult},
-//     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) -> GameResult<()> {
-//         if self.collected {
-//             return Ok(());
-//         }
-
-//         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)?;
-//         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,7 +0,0 @@
-pub mod collision;
-pub mod direction;
-pub mod ghost;
-pub mod graph;
-pub mod item;
-pub mod pacman;
-pub mod r#trait;

src/entity/pacman.rs

@@ -1,115 +0,0 @@
-// //! Pac-Man entity implementation.
-// //!
-// //! This module contains the main player character logic, including movement,
-// //! animation, and rendering. Pac-Man moves through the game graph using
-// //! a traverser and displays directional animated textures.
-
-// 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 tracing::error;
-
-// use crate::error::{GameError, GameResult, TextureError};
-
-// /// Determines if Pac-Man can traverse a given edge.
-// ///
-// /// Pac-Man can only move through edges that allow all entities.
-// fn can_pacman_traverse(edge: Edge) -> bool {
-//     matches!(edge.permissions, EdgePermissions::All)
-// }
-
-// /// The main player character entity.
-// ///
-// /// Pac-Man moves through the game world using a graph-based navigation system
-// /// and displays directional animated sprites based on movement state.
-// pub struct Pacman {
-//     /// Handles movement through the game graph
-//     pub traverser: Traverser,
-//     /// Manages directional animated textures for different movement states
-//     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) -> GameResult<Self> {
-//         let mut textures = [None, None, None, None];
-//         let mut stopped_textures = [None, None, None, None];
-
-//         for direction in Direction::DIRECTIONS {
-//             let moving_prefix = match direction {
-//                 Direction::Up => "pacman/up",
-//                 Direction::Down => "pacman/down",
-//                 Direction::Left => "pacman/left",
-//                 Direction::Right => "pacman/right",
-//             };
-//             let moving_tiles = vec![
-//                 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"))
-//                 .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?];
-
-//             textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.08)?);
-//             stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
-//         }
-
-//         Ok(Self {
-//             traverser: Traverser::new(graph, start_node, Direction::Left, &can_pacman_traverse),
-//             texture: DirectionalAnimatedTexture::new(textures, stopped_textures),
-//         })
-//     }
-// }
-
-// impl Collidable for Pacman {
-//     fn position(&self) -> crate::entity::traversal::Position {
-//         self.traverser.position
-//     }
-// }

src/entity/trait.rs

@@ -1,114 +0,0 @@
-// //! 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/error.rs

@@ -31,9 +31,6 @@ pub enum GameError {
     #[error("Entity error: {0}")]
     Entity(#[from] EntityError),
 
-    #[error("Game state error: {0}")]
-    GameState(#[from] GameStateError),
-
     #[error("SDL error: {0}")]
     Sdl(String),
 
@@ -51,6 +48,8 @@ pub enum GameError {
 pub enum AssetError {
     #[error("IO error: {0}")]
     Io(#[from] io::Error),
+
+    #[allow(dead_code)]
     #[error("Asset not found: {0}")]
     NotFound(String),
 }
@@ -109,18 +108,8 @@ pub enum EntityError {
 
     #[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(thiserror::Error, Debug)]
-pub enum GameStateError {}
-
 /// Errors related to map operations.
 #[derive(thiserror::Error, Debug)]
 pub enum MapError {

src/events.rs

@@ -1,18 +1,37 @@
-use bevy_ecs::prelude::*;
+use bevy_ecs::{entity::Entity, event::Event};
 
+use crate::map::direction::Direction;
+
+/// Player input commands that trigger specific game actions.
+///
+/// Commands are generated by the input system in response to keyboard events
+/// and processed by appropriate game systems to modify state or behavior.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum GameCommand {
+    /// Request immediate game shutdown
     Exit,
-    MovePlayer(crate::entity::direction::Direction),
+    /// Set Pac-Man's movement direction
+    MovePlayer(Direction),
+    /// Cycle through debug visualization modes
     ToggleDebug,
+    /// Toggle audio mute state
     MuteAudio,
+    /// Restart the current level with fresh entity positions and items
     ResetLevel,
+    /// Pause or resume game ticking logic
     TogglePause,
 }
 
+/// Global events that flow through the ECS event system to coordinate game behavior.
+///
+/// Events enable loose coupling between systems - input generates commands, collision
+/// detection reports overlaps, and various systems respond appropriately without
+/// direct dependencies.
 #[derive(Event, Clone, Copy, Debug, PartialEq, Eq)]
 pub enum GameEvent {
+    /// Player input command to be processed by relevant game systems
     Command(GameCommand),
+    /// Physical overlap detected between two entities requiring gameplay response
     Collision(Entity, Entity),
 }
 

src/game.rs

@@ -0,0 +1,562 @@
+//! This module contains the main game logic and state.
+
+include!(concat!(env!("OUT_DIR"), "/atlas_data.rs"));
+
+use crate::constants::CANVAS_SIZE;
+use crate::error::{GameError, GameResult, TextureError};
+use crate::events::GameEvent;
+use crate::map::builder::Map;
+use crate::map::direction::Direction;
+use crate::systems;
+use crate::systems::blinking::Blinking;
+
+use crate::systems::movement::{BufferedDirection, Position, Velocity};
+use crate::systems::profiling::SystemId;
+use crate::systems::render::RenderDirty;
+use crate::systems::{
+    audio::{audio_system, AudioEvent, AudioResource},
+    blinking::blinking_system,
+    collision::collision_system,
+    components::{
+        AudioState, Collider, DeltaTime, DirectionalAnimated, EntityType, Frozen, Ghost, GhostBundle, GhostCollider, GlobalState,
+        ItemBundle, ItemCollider, LevelTiming, PacmanCollider, PlayerBundle, PlayerControlled, PlayerStateBundle, Renderable,
+        ScoreResource, StartupSequence,
+    },
+    debug::{debug_render_system, DebugFontResource, DebugState, DebugTextureResource},
+    ghost::{ghost_collision_system, ghost_movement_system},
+    item::item_system,
+    profiling::{profile, SystemTimings},
+    render::{
+        directional_render_system, dirty_render_system, hud_render_system, ready_visibility_system, render_system,
+        BackbufferResource, MapTextureResource,
+    },
+};
+use crate::texture::animated::AnimatedTexture;
+use bevy_ecs::event::EventRegistry;
+use bevy_ecs::observer::Trigger;
+use bevy_ecs::prelude::SystemSet;
+use bevy_ecs::schedule::{IntoScheduleConfigs, Schedule};
+use bevy_ecs::system::{NonSendMut, Res, ResMut};
+use bevy_ecs::world::World;
+use sdl2::image::LoadTexture;
+use sdl2::render::{Canvas, ScaleMode, TextureCreator};
+use sdl2::rwops::RWops;
+use sdl2::video::{Window, WindowContext};
+use sdl2::EventPump;
+
+use crate::{
+    asset::{get_asset_bytes, Asset},
+    constants,
+    events::GameCommand,
+    map::render::MapRenderer,
+    systems::input::{Bindings, CursorPosition},
+    texture::sprite::{AtlasMapper, SpriteAtlas},
+};
+
+/// System set for all rendering systems to ensure they run after gameplay logic
+#[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
+pub struct RenderSet;
+
+/// Core game state manager built on the Bevy ECS architecture.
+///
+/// Orchestrates all game systems through a centralized `World` containing entities,
+/// components, and resources, while a `Schedule` defines system execution order.
+/// Handles initialization of graphics resources, entity spawning, and per-frame
+/// game logic coordination. SDL2 resources are stored as `NonSend` to respect
+/// thread safety requirements while integrating with the ECS.
+pub struct Game {
+    pub world: World,
+    pub schedule: Schedule,
+}
+
+impl Game {
+    /// Initializes the complete game state including ECS world, graphics, and entity spawning.
+    ///
+    /// Performs extensive setup: creates render targets and debug textures, loads and parses
+    /// the sprite atlas, renders the static map to a cached texture, builds the navigation
+    /// graph from the board layout, spawns Pac-Man with directional animations, creates
+    /// all four ghosts with their AI behavior, and places collectible items throughout
+    /// the maze. Registers event types and configures the system execution schedule.
+    ///
+    /// # Arguments
+    ///
+    /// * `canvas` - SDL2 rendering context with static lifetime for ECS storage
+    /// * `texture_creator` - SDL2 texture factory for creating render targets
+    /// * `event_pump` - SDL2 event polling interface for input handling
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError` for SDL2 failures, asset loading problems, atlas parsing
+    /// errors, or entity initialization issues.
+    pub fn new(
+        canvas: &'static mut Canvas<Window>,
+        texture_creator: &'static mut TextureCreator<WindowContext>,
+        event_pump: &'static mut EventPump,
+    ) -> GameResult<Game> {
+        let mut world = World::default();
+        let mut schedule = Schedule::default();
+        let ttf_context = Box::leak(Box::new(sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?));
+
+        EventRegistry::register_event::<GameError>(&mut world);
+        EventRegistry::register_event::<GameEvent>(&mut world);
+        EventRegistry::register_event::<AudioEvent>(&mut world);
+
+        let mut backbuffer = texture_creator
+            .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 mut map_texture = texture_creator
+            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        map_texture.set_scale_mode(ScaleMode::Nearest);
+
+        // Create debug texture at output resolution for crisp debug rendering
+        let output_size = canvas.output_size().unwrap();
+        let mut debug_texture = texture_creator
+            .create_texture_target(None, output_size.0, output_size.1)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        debug_texture.set_scale_mode(ScaleMode::Nearest);
+
+        let font_data = get_asset_bytes(Asset::Font)?;
+        let static_font_data: &'static [u8] = Box::leak(font_data.to_vec().into_boxed_slice());
+        let font_asset = RWops::from_bytes(static_font_data).map_err(|_| GameError::Sdl("Failed to load font".to_string()))?;
+        let debug_font = ttf_context
+            .load_font_from_rwops(font_asset, 12)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        // Initialize audio system
+        let audio = crate::audio::Audio::new();
+
+        // Load atlas and create map texture
+        let atlas_bytes = get_asset_bytes(Asset::AtlasImage)?;
+        let atlas_texture = texture_creator.load_texture_bytes(&atlas_bytes).map_err(|e| {
+            if e.to_string().contains("format") || e.to_string().contains("unsupported") {
+                GameError::Texture(crate::error::TextureError::InvalidFormat(format!(
+                    "Unsupported texture format: {e}"
+                )))
+            } else {
+                GameError::Texture(crate::error::TextureError::LoadFailed(e.to_string()))
+            }
+        })?;
+
+        let atlas_mapper = AtlasMapper {
+            frames: ATLAS_FRAMES.into_iter().map(|(k, v)| (k.to_string(), *v)).collect(),
+        };
+        let mut atlas = SpriteAtlas::new(atlas_texture, atlas_mapper);
+
+        // Create map tiles
+        let mut map_tiles = Vec::with_capacity(35);
+        for i in 0..35 {
+            let tile_name = format!("maze/tiles/{}.png", i);
+            let tile = atlas.get_tile(&tile_name).unwrap();
+            map_tiles.push(tile);
+        }
+
+        // Render map to texture
+        canvas
+            .with_texture_canvas(&mut map_texture, |map_canvas| {
+                MapRenderer::render_map(map_canvas, &mut atlas, &map_tiles);
+            })
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        let map = Map::new(constants::RAW_BOARD)?;
+        let pacman_start_node = map.start_positions.pacman;
+
+        let mut textures = [None, None, None, None];
+        let mut stopped_textures = [None, None, None, None];
+
+        for direction in Direction::DIRECTIONS {
+            let moving_prefix = match direction {
+                Direction::Up => "pacman/up",
+                Direction::Down => "pacman/down",
+                Direction::Left => "pacman/left",
+                Direction::Right => "pacman/right",
+            };
+            let moving_tiles = vec![
+                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"))
+                .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?];
+
+            textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.08)?);
+            stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
+        }
+
+        let player = PlayerBundle {
+            player: PlayerControlled,
+            position: Position::Stopped { node: pacman_start_node },
+            velocity: Velocity {
+                speed: 1.15,
+                direction: Direction::Left,
+            },
+            buffered_direction: BufferedDirection::None,
+            sprite: Renderable {
+                sprite: SpriteAtlas::get_tile(&atlas, "pacman/full.png")
+                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("pacman/full.png".to_string())))?,
+                layer: 0,
+                visible: true,
+            },
+            directional_animated: DirectionalAnimated {
+                textures,
+                stopped_textures,
+            },
+            entity_type: EntityType::Player,
+            collider: Collider {
+                size: constants::CELL_SIZE as f32 * 1.375,
+            },
+            pacman_collider: PacmanCollider,
+        };
+
+        // Spawn player and attach initial state bundle
+        let player_entity = world.spawn(player).id();
+        world.entity_mut(player_entity).insert(PlayerStateBundle::default());
+        world.entity_mut(player_entity).insert(Frozen);
+
+        world.insert_non_send_resource(atlas);
+        world.insert_non_send_resource(event_pump);
+        world.insert_non_send_resource(canvas);
+        world.insert_non_send_resource(BackbufferResource(backbuffer));
+        world.insert_non_send_resource(MapTextureResource(map_texture));
+        world.insert_non_send_resource(DebugTextureResource(debug_texture));
+        world.insert_non_send_resource(DebugFontResource(debug_font));
+        world.insert_non_send_resource(AudioResource(audio));
+
+        world.insert_resource(map);
+        world.insert_resource(GlobalState { exit: false });
+        world.insert_resource(ScoreResource(0));
+        world.insert_resource(SystemTimings::default());
+        world.insert_resource(Bindings::default());
+        world.insert_resource(DeltaTime(0f32));
+        world.insert_resource(RenderDirty::default());
+        world.insert_resource(DebugState::default());
+        world.insert_resource(AudioState::default());
+        world.insert_resource(CursorPosition::default());
+        world.insert_resource(LevelTiming::for_level(1));
+
+        world.add_observer(
+            |event: Trigger<GameEvent>, mut state: ResMut<GlobalState>, _score: ResMut<ScoreResource>| {
+                if matches!(*event, GameEvent::Command(GameCommand::Exit)) {
+                    state.exit = true;
+                }
+            },
+        );
+
+        let input_system = profile(SystemId::Input, systems::input::input_system);
+        let player_control_system = profile(SystemId::PlayerControls, systems::player::player_control_system);
+        let player_movement_system = profile(SystemId::PlayerMovement, systems::player::player_movement_system);
+        let startup_stage_system = profile(SystemId::Stage, systems::stage::startup_stage_system);
+        let player_tunnel_slowdown_system = profile(SystemId::PlayerMovement, systems::player::player_tunnel_slowdown_system);
+        let ghost_movement_system = profile(SystemId::Ghost, ghost_movement_system);
+        let collision_system = profile(SystemId::Collision, collision_system);
+        let ghost_collision_system = profile(SystemId::GhostCollision, ghost_collision_system);
+        let item_system = profile(SystemId::Item, item_system);
+        let audio_system = profile(SystemId::Audio, audio_system);
+        let blinking_system = profile(SystemId::Blinking, blinking_system);
+        let directional_render_system = profile(SystemId::DirectionalRender, directional_render_system);
+        let dirty_render_system = profile(SystemId::DirtyRender, dirty_render_system);
+        let hud_render_system = profile(SystemId::HudRender, hud_render_system);
+        let render_system = profile(SystemId::Render, render_system);
+        let debug_render_system = profile(SystemId::DebugRender, debug_render_system);
+
+        let present_system = profile(
+            SystemId::Present,
+            |mut canvas: NonSendMut<&mut Canvas<Window>>, debug_state: Res<DebugState>, mut dirty: ResMut<RenderDirty>| {
+                if dirty.0 || debug_state.enabled {
+                    // Only copy backbuffer to main canvas if debug rendering is off
+                    // (debug rendering draws directly to main canvas)
+                    if !debug_state.enabled {
+                        canvas.present();
+                    }
+                    dirty.0 = false;
+                }
+            },
+        );
+
+        schedule.add_systems((
+            (
+                input_system,
+                player_control_system,
+                player_movement_system,
+                startup_stage_system,
+            )
+                .chain(),
+            player_tunnel_slowdown_system,
+            ghost_movement_system,
+            (collision_system, ghost_collision_system, item_system).chain(),
+            audio_system,
+            blinking_system,
+            ready_visibility_system,
+            (
+                directional_render_system,
+                dirty_render_system,
+                render_system,
+                hud_render_system,
+                debug_render_system,
+                present_system,
+            )
+                .chain(),
+        ));
+
+        // Initialize StartupSequence as a global resource
+        let ready_duration_ticks = {
+            let duration = world
+                .get_resource::<LevelTiming>()
+                .map(|t| t.spawn_freeze_duration)
+                .unwrap_or(1.5);
+            (duration * 60.0) as u32 // Convert to ticks at 60 FPS
+        };
+        world.insert_resource(StartupSequence::new(ready_duration_ticks, 60));
+
+        // Spawn ghosts
+        Self::spawn_ghosts(&mut world)?;
+
+        // Spawn items
+        let pellet_sprite = SpriteAtlas::get_tile(world.non_send_resource::<SpriteAtlas>(), "maze/pellet.png")
+            .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("maze/pellet.png".to_string())))?;
+        let energizer_sprite = SpriteAtlas::get_tile(world.non_send_resource::<SpriteAtlas>(), "maze/energizer.png")
+            .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("maze/energizer.png".to_string())))?;
+
+        let nodes: Vec<_> = world.resource::<Map>().iter_nodes().map(|(id, tile)| (*id, *tile)).collect();
+
+        for (node_id, tile) in nodes {
+            let (item_type, sprite, size) = match tile {
+                crate::constants::MapTile::Pellet => (EntityType::Pellet, pellet_sprite, constants::CELL_SIZE as f32 * 0.4),
+                crate::constants::MapTile::PowerPellet => {
+                    (EntityType::PowerPellet, energizer_sprite, constants::CELL_SIZE as f32 * 0.95)
+                }
+                _ => continue,
+            };
+
+            let mut item = world.spawn(ItemBundle {
+                position: Position::Stopped { node: node_id },
+                sprite: Renderable {
+                    sprite,
+                    layer: 1,
+                    visible: true,
+                },
+                entity_type: item_type,
+                collider: Collider { size },
+                item_collider: ItemCollider,
+            });
+
+            if item_type == EntityType::PowerPellet {
+                item.insert(Blinking {
+                    timer: 0.0,
+                    interval: 0.2,
+                });
+            }
+        }
+
+        Ok(Game { world, schedule })
+    }
+
+    /// Creates and spawns all four ghosts with unique AI personalities and directional animations.
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError::Texture` if any ghost sprite cannot be found in the atlas,
+    /// typically indicating missing or misnamed sprite files.
+    fn spawn_ghosts(world: &mut World) -> GameResult<()> {
+        // Extract the data we need first to avoid borrow conflicts
+        let ghost_start_positions = {
+            let map = world.resource::<Map>();
+            [
+                (Ghost::Blinky, map.start_positions.blinky),
+                (Ghost::Pinky, map.start_positions.pinky),
+                (Ghost::Inky, map.start_positions.inky),
+                (Ghost::Clyde, map.start_positions.clyde),
+            ]
+        };
+
+        for (ghost_type, start_node) in ghost_start_positions {
+            // Create the ghost bundle in a separate scope to manage borrows
+            let ghost = {
+                let atlas = world.non_send_resource::<SpriteAtlas>();
+
+                // Create directional animated textures for the ghost
+                let mut textures = [None, None, None, None];
+                let mut stopped_textures = [None, None, None, None];
+
+                for direction in Direction::DIRECTIONS {
+                    let moving_prefix = match direction {
+                        Direction::Up => "up",
+                        Direction::Down => "down",
+                        Direction::Left => "left",
+                        Direction::Right => "right",
+                    };
+
+                    let moving_tiles = vec![
+                        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"),
+                    )
+                    .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)?);
+                    stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
+                }
+
+                GhostBundle {
+                    ghost: ghost_type,
+                    position: Position::Stopped { node: start_node },
+                    velocity: Velocity {
+                        speed: ghost_type.base_speed(),
+                        direction: Direction::Left,
+                    },
+                    sprite: Renderable {
+                        sprite: SpriteAtlas::get_tile(atlas, &format!("ghost/{}/left_a.png", ghost_type.as_str())).ok_or_else(
+                            || {
+                                GameError::Texture(TextureError::AtlasTileNotFound(format!(
+                                    "ghost/{}/left_a.png",
+                                    ghost_type.as_str()
+                                )))
+                            },
+                        )?,
+                        layer: 0,
+                        visible: true,
+                    },
+                    directional_animated: DirectionalAnimated {
+                        textures,
+                        stopped_textures,
+                    },
+                    entity_type: EntityType::Ghost,
+                    collider: Collider {
+                        size: crate::constants::CELL_SIZE as f32 * 1.375,
+                    },
+                    ghost_collider: GhostCollider,
+                }
+            };
+
+            world.spawn(ghost).insert(Frozen);
+        }
+
+        Ok(())
+    }
+
+    /// Executes one frame of game logic by running all scheduled ECS systems.
+    ///
+    /// Updates the world's delta time resource and runs the complete system pipeline:
+    /// input processing, entity movement, collision detection, item collection,
+    /// audio playback, animation updates, and rendering. Each system operates on
+    /// relevant entities and modifies world state, with the schedule ensuring
+    /// proper execution order and data dependencies.
+    ///
+    /// # Arguments
+    ///
+    /// * `dt` - Frame delta time in seconds for time-based animations and movement
+    ///
+    /// # Returns
+    ///
+    /// `true` if the game should terminate (exit command received), `false` to continue
+    pub fn tick(&mut self, dt: f32) -> bool {
+        self.world.insert_resource(DeltaTime(dt));
+
+        // Run all systems
+        self.schedule.run(&mut self.world);
+
+        let state = self
+            .world
+            .get_resource::<GlobalState>()
+            .expect("GlobalState could not be acquired");
+
+        state.exit
+    }
+
+    // /// 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: sdl2::render::RenderTarget>(&self, canvas: &mut Canvas<T>) -> GameResult<()> {
+    //     let pacman_node = self.state.pacman.current_node_id();
+
+    //     for ghost in self.state.ghosts.iter() {
+    //         if let Ok(path) = ghost.calculate_path_to_target(&self.state.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 => glam::Vec2::new(0.25, 0.5),
+    //                 GhostType::Pinky => glam::Vec2::new(-0.25, -0.25),
+    //                 GhostType::Inky => glam::Vec2::new(0.5, -0.5),
+    //                 GhostType::Clyde => glam::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
+    //                     .state
+    //                     .map
+    //                     .graph
+    //                     .get_node(node_id)
+    //                     .ok_or(crate::error::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) > (crate::constants::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| crate::error::GameError::Sdl(e.to_string()))?;
+    //                 }
+    //             }
+    //         }
+    //     }
+
+    //     Ok(())
+    // }
+}

src/game/mod.rs

@@ -1,596 +0,0 @@
-//! This module contains the main game logic and state.
-
-include!(concat!(env!("OUT_DIR"), "/atlas_data.rs"));
-
-use crate::constants::CANVAS_SIZE;
-use crate::entity::direction::Direction;
-use crate::error::{GameError, GameResult, TextureError};
-use crate::events::GameEvent;
-use crate::map::builder::Map;
-use crate::systems::blinking::Blinking;
-use crate::systems::movement::{Movable, MovementState, Position};
-use crate::systems::{
-    blinking::blinking_system,
-    collision::collision_system,
-    components::{
-        Collider, CollisionLayer, DeltaTime, DirectionalAnimated, EntityType, GlobalState, ItemBundle, ItemCollider,
-        PacmanCollider, PlayerBundle, PlayerControlled, Renderable, Score, ScoreResource,
-    },
-    control::player_system,
-    input::input_system,
-    movement::movement_system,
-    profiling::{profile, SystemTimings},
-    render::{directional_render_system, render_system, BackbufferResource, MapTextureResource},
-};
-use crate::texture::animated::AnimatedTexture;
-use bevy_ecs::schedule::IntoScheduleConfigs;
-use bevy_ecs::{event::EventRegistry, observer::Trigger, schedule::Schedule, system::ResMut, world::World};
-use sdl2::image::LoadTexture;
-use sdl2::render::{Canvas, ScaleMode, TextureCreator};
-use sdl2::video::{Window, WindowContext};
-use sdl2::EventPump;
-
-use crate::{
-    asset::{get_asset_bytes, Asset},
-    constants,
-    events::GameCommand,
-    map::render::MapRenderer,
-    systems::input::Bindings,
-    texture::sprite::{AtlasMapper, SpriteAtlas},
-};
-
-pub mod state;
-
-/// The `Game` struct is the main entry point for the game.
-///
-/// It contains the game's state and logic, and is responsible for
-/// handling user input, updating the game state, and rendering the game.
-pub struct Game {
-    pub world: World,
-    pub schedule: Schedule,
-}
-
-impl Game {
-    pub fn new(
-        canvas: &'static mut Canvas<Window>,
-        texture_creator: &'static mut TextureCreator<WindowContext>,
-        event_pump: &'static mut EventPump,
-    ) -> GameResult<Game> {
-        let mut world = World::default();
-        let mut schedule = Schedule::default();
-
-        EventRegistry::register_event::<GameError>(&mut world);
-        EventRegistry::register_event::<GameEvent>(&mut world);
-
-        let mut backbuffer = texture_creator
-            .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 mut map_texture = texture_creator
-            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
-            .map_err(|e| GameError::Sdl(e.to_string()))?;
-        map_texture.set_scale_mode(ScaleMode::Nearest);
-
-        // Load atlas and create map texture
-        let atlas_bytes = get_asset_bytes(Asset::Atlas)?;
-        let atlas_texture = texture_creator.load_texture_bytes(&atlas_bytes).map_err(|e| {
-            if e.to_string().contains("format") || e.to_string().contains("unsupported") {
-                GameError::Texture(crate::error::TextureError::InvalidFormat(format!(
-                    "Unsupported texture format: {e}"
-                )))
-            } else {
-                GameError::Texture(crate::error::TextureError::LoadFailed(e.to_string()))
-            }
-        })?;
-
-        let atlas_mapper = AtlasMapper {
-            frames: ATLAS_FRAMES.into_iter().map(|(k, v)| (k.to_string(), *v)).collect(),
-        };
-        let mut atlas = SpriteAtlas::new(atlas_texture, atlas_mapper);
-
-        // Create map tiles
-        let mut map_tiles = Vec::with_capacity(35);
-        for i in 0..35 {
-            let tile_name = format!("maze/tiles/{}.png", i);
-            let tile = atlas.get_tile(&tile_name).unwrap();
-            map_tiles.push(tile);
-        }
-
-        // Render map to texture
-        canvas
-            .with_texture_canvas(&mut map_texture, |map_canvas| {
-                MapRenderer::render_map(map_canvas, &mut atlas, &map_tiles);
-            })
-            .map_err(|e| GameError::Sdl(e.to_string()))?;
-
-        let map = Map::new(constants::RAW_BOARD)?;
-        let pacman_start_node = map.start_positions.pacman;
-
-        let mut textures = [None, None, None, None];
-        let mut stopped_textures = [None, None, None, None];
-
-        for direction in Direction::DIRECTIONS {
-            let moving_prefix = match direction {
-                Direction::Up => "pacman/up",
-                Direction::Down => "pacman/down",
-                Direction::Left => "pacman/left",
-                Direction::Right => "pacman/right",
-            };
-            let moving_tiles = vec![
-                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"))
-                .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?];
-
-            textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.08)?);
-            stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
-        }
-
-        let player = PlayerBundle {
-            player: PlayerControlled,
-            position: Position {
-                node: pacman_start_node,
-                edge_progress: None,
-            },
-            movement_state: MovementState::Stopped,
-            movable: Movable {
-                speed: 1.15,
-                current_direction: Direction::Left,
-                requested_direction: Some(Direction::Left), // Start moving left immediately
-            },
-            sprite: Renderable {
-                sprite: SpriteAtlas::get_tile(&atlas, "pacman/full.png")
-                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("pacman/full.png".to_string())))?,
-                layer: 0,
-                visible: true,
-            },
-            directional_animated: DirectionalAnimated {
-                textures,
-                stopped_textures,
-            },
-            entity_type: EntityType::Player,
-            collider: Collider {
-                size: constants::CELL_SIZE as f32 * 1.25,
-                layer: CollisionLayer::PACMAN,
-            },
-            pacman_collider: PacmanCollider,
-        };
-
-        world.insert_non_send_resource(atlas);
-        world.insert_non_send_resource(event_pump);
-        world.insert_non_send_resource(canvas);
-        world.insert_non_send_resource(BackbufferResource(backbuffer));
-        world.insert_non_send_resource(MapTextureResource(map_texture));
-
-        world.insert_resource(map);
-        world.insert_resource(GlobalState { exit: false });
-        world.insert_resource(ScoreResource(0));
-        world.insert_resource(SystemTimings::default());
-        world.insert_resource(Bindings::default());
-        world.insert_resource(DeltaTime(0f32));
-
-        world.add_observer(
-            |event: Trigger<GameEvent>, mut state: ResMut<GlobalState>, _score: ResMut<ScoreResource>| match *event {
-                GameEvent::Command(command) => match command {
-                    GameCommand::Exit => {
-                        state.exit = true;
-                    }
-                    _ => {}
-                },
-                GameEvent::Collision(_a, _b) => {}
-            },
-        );
-
-        schedule.add_systems(
-            (
-                profile("input", input_system),
-                profile("player", player_system),
-                profile("movement", movement_system),
-                profile("collision", collision_system),
-                profile("blinking", blinking_system),
-                profile("directional_render", directional_render_system),
-            )
-                .chain(),
-        );
-        schedule.add_systems(profile("render", render_system));
-
-        // Spawn player
-        world.spawn(player);
-
-        // Spawn items
-        let pellet_sprite = SpriteAtlas::get_tile(world.non_send_resource::<SpriteAtlas>(), "maze/pellet.png")
-            .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("maze/pellet.png".to_string())))?;
-        let energizer_sprite = SpriteAtlas::get_tile(world.non_send_resource::<SpriteAtlas>(), "maze/energizer.png")
-            .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("maze/energizer.png".to_string())))?;
-
-        let nodes: Vec<_> = world.resource::<Map>().iter_nodes().map(|(id, tile)| (*id, *tile)).collect();
-
-        for (node_id, tile) in nodes {
-            let (item_type, score, sprite, size) = match tile {
-                crate::constants::MapTile::Pellet => (EntityType::Pellet, 10, pellet_sprite, constants::CELL_SIZE as f32 * 0.2),
-                crate::constants::MapTile::PowerPellet => (
-                    EntityType::PowerPellet,
-                    50,
-                    energizer_sprite,
-                    constants::CELL_SIZE as f32 * 0.9,
-                ),
-                _ => continue,
-            };
-
-            let mut item = world.spawn(ItemBundle {
-                position: Position {
-                    node: node_id,
-                    edge_progress: None,
-                },
-                sprite: Renderable {
-                    sprite,
-                    layer: 1,
-                    visible: true,
-                },
-                entity_type: item_type,
-                score: Score(score),
-                collider: Collider {
-                    size,
-                    layer: CollisionLayer::ITEM,
-                },
-                item_collider: ItemCollider,
-            });
-
-            if item_type == EntityType::PowerPellet {
-                item.insert(Blinking {
-                    timer: 0.0,
-                    interval: 0.2,
-                });
-            }
-        }
-
-        Ok(Game { world, schedule })
-    }
-
-    // fn handle_command(&mut self, command: crate::input::commands::GameCommand) {
-    //     use crate::input::commands::GameCommand;
-    //     match command {
-    //         GameCommand::MovePlayer(direction) => {
-    //             self.state.pacman.set_next_direction(direction);
-    //         }
-    //         GameCommand::ToggleDebug => {
-    //             self.toggle_debug_mode();
-    //         }
-    //         GameCommand::MuteAudio => {
-    //             let is_muted = self.state.audio.is_muted();
-    //             self.state.audio.set_mute(!is_muted);
-    //         }
-    //         GameCommand::ResetLevel => {
-    //             if let Err(e) = self.reset_game_state() {
-    //                 tracing::error!("Failed to reset game state: {}", e);
-    //             }
-    //         }
-    //         GameCommand::TogglePause => {
-    //             self.state.paused = !self.state.paused;
-    //         }
-    //         GameCommand::Exit => {}
-    //     }
-    // }
-
-    // fn process_events(&mut self) {
-    //     while let Some(event) = self.state.event_queue.pop_front() {
-    //         match event {
-    //             GameEvent::Command(command) => self.handle_command(command),
-    //         }
-    // }
-
-    // /// Resets the game state, randomizing ghost positions and resetting Pac-Man
-    // fn reset_game_state(&mut self) -> GameResult<()> {
-    //     let pacman_start_node = self.state.map.start_positions.pacman;
-    //     self.state.pacman = Pacman::new(&self.state.map.graph, pacman_start_node, &self.state.atlas)?;
-
-    //     // Reset items
-    //     self.state.items = self.state.map.generate_items(&self.state.atlas)?;
-
-    //     // Randomize ghost positions
-    //     let ghost_types = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde];
-    //     let mut rng = SmallRng::from_os_rng();
-
-    //     for (i, ghost) in self.state.ghosts.iter_mut().enumerate() {
-    //         let random_node = rng.random_range(0..self.state.map.graph.node_count());
-    //         *ghost = Ghost::new(&self.state.map.graph, random_node, ghost_types[i], &self.state.atlas)?;
-    //     }
-
-    //     // Reset collision system
-    //     self.state.collision_system = CollisionSystem::default();
-
-    //     // Re-register Pac-Man
-    //     self.state.pacman_id = self.state.collision_system.register_entity(self.state.pacman.position());
-
-    //     // Re-register items
-    //     self.state.item_ids.clear();
-    //     for item in &self.state.items {
-    //         let item_id = self.state.collision_system.register_entity(item.position());
-    //         self.state.item_ids.push(item_id);
-    //     }
-
-    //     // Re-register ghosts
-    //     self.state.ghost_ids.clear();
-    //     for ghost in &self.state.ghosts {
-    //         let ghost_id = self.state.collision_system.register_entity(ghost.position());
-    //         self.state.ghost_ids.push(ghost_id);
-    //     }
-
-    //     Ok(())
-    // }
-
-    /// Ticks the game state.
-    ///
-    /// Returns true if the game should exit.
-    pub fn tick(&mut self, dt: f32) -> bool {
-        self.world.insert_resource(DeltaTime(dt));
-
-        // Run all systems
-        self.schedule.run(&mut self.world);
-
-        let state = self
-            .world
-            .get_resource::<GlobalState>()
-            .expect("GlobalState could not be acquired");
-
-        return state.exit;
-
-        // // Process any events that have been posted (such as unpausing)
-        // self.process_events();
-
-        // // If the game is paused, we don't need to do anything beyond returning
-        // if self.state.paused {
-        //     return false;
-        // }
-
-        // self.schedule.run(&mut self.world);
-
-        // self.state.pacman.tick(dt, &self.state.map.graph);
-
-        // // Update all ghosts
-        // for ghost in &mut self.state.ghosts {
-        //     ghost.tick(dt, &self.state.map.graph);
-        // }
-
-        // // Update collision system positions
-        // self.update_collision_positions();
-
-        // // Check for collisions
-        // self.check_collisions();
-    }
-
-    // /// Toggles the debug mode on and off.
-    // ///
-    // /// When debug mode is enabled, the game will render additional information
-    // /// that is useful for debugging, such as the collision grid and entity paths.
-    // pub fn toggle_debug_mode(&mut self) {
-    //     self.state.debug_mode = !self.state.debug_mode;
-    // }
-
-    // fn update_collision_positions(&mut self) {
-    //     // Update Pac-Man's position
-    //     self.state
-    //         .collision_system
-    //         .update_position(self.state.pacman_id, self.state.pacman.position());
-
-    //     // Update ghost positions
-    //     for (ghost, &ghost_id) in self.state.ghosts.iter().zip(&self.state.ghost_ids) {
-    //         self.state.collision_system.update_position(ghost_id, ghost.position());
-    //     }
-    // }
-
-    // fn check_collisions(&mut self) {
-    //     // Check Pac-Man vs Items
-    //     let potential_collisions = self
-    //         .state
-    //         .collision_system
-    //         .potential_collisions(&self.state.pacman.position());
-
-    //     for entity_id in potential_collisions {
-    //         if entity_id != self.state.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.state.items[item_index];
-    //                 if !item.is_collected() {
-    //                     item.collect();
-    //                     self.state.score += item.get_score();
-    //                     self.state.audio.eat();
-
-    //                     // 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!");
-    //             }
-    //         }
-    //     }
-    // }
-
-    // fn find_item_by_id(&self, entity_id: EntityId) -> Option<usize> {
-    //     self.state.item_ids.iter().position(|&id| id == entity_id)
-    // }
-
-    // fn find_ghost_by_id(&self, entity_id: EntityId) -> Option<usize> {
-    //     self.state.ghost_ids.iter().position(|&id| id == entity_id)
-    // }
-
-    // pub fn draw<T: sdl2::render::RenderTarget>(&mut self, canvas: &mut Canvas<T>, backbuffer: &mut Texture) -> GameResult<()> {
-    //     // Only render the map texture once and cache it
-    //     if !self.state.map_rendered {
-    //         let mut map_texture = self
-    //             .state
-    //             .texture_creator
-    //             .create_texture_target(None, constants::CANVAS_SIZE.x, constants::CANVAS_SIZE.y)
-    //             .map_err(|e| crate::error::GameError::Sdl(e.to_string()))?;
-
-    //         canvas
-    //             .with_texture_canvas(&mut map_texture, |map_canvas| {
-    //                 let mut map_tiles = Vec::with_capacity(35);
-    //                 for i in 0..35 {
-    //                     let tile_name = format!("maze/tiles/{}.png", i);
-    //                     let tile = SpriteAtlas::get_tile(&self.state.atlas, &tile_name).unwrap();
-    //                     map_tiles.push(tile);
-    //                 }
-    //                 MapRenderer::render_map(map_canvas, &mut self.state.atlas, &mut map_tiles);
-    //             })
-    //             .map_err(|e| crate::error::GameError::Sdl(e.to_string()))?;
-    //         self.state.map_texture = Some(map_texture);
-    //         self.state.map_rendered = true;
-    //     }
-
-    //     canvas.set_draw_color(Color::BLACK);
-    //     canvas.clear();
-    //     if let Some(ref map_texture) = self.state.map_texture {
-    //         canvas.copy(map_texture, None, None).unwrap();
-    //     }
-
-    //     // Render all items
-    //     for item in &self.state.items {
-    //         if let Err(e) = item.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
-    //             tracing::error!("Failed to render item: {}", e);
-    //         }
-    //     }
-
-    //     // Render all ghosts
-    //     for ghost in &self.state.ghosts {
-    //         if let Err(e) = ghost.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
-    //             tracing::error!("Failed to render ghost: {}", e);
-    //         }
-    //     }
-
-    //     if let Err(e) = self.state.pacman.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
-    //         tracing::error!("Failed to render pacman: {}", e);
-    //     }
-
-    //     if self.state.debug_mode {
-    //         if let Err(e) =
-    //             self.state
-    //                 .map
-    //                 .debug_render_with_cursor(canvas, &mut self.state.text_texture, &mut self.state.atlas, cursor_pos)
-    //         {
-    //             tracing::error!("Failed to render debug cursor: {}", e);
-    //         }
-    //         self.render_pathfinding_debug(canvas)?;
-    //     }
-    //     self.draw_hud(canvas)?;
-    //     canvas.present();
-
-    //     Ok(())
-    // }
-
-    // /// Renders pathfinding debug lines from each ghost to Pac-Man.
-    // ///
-    // /// Each ghost's path is drawn in its respective color with a small offset
-    // /// to prevent overlapping lines.
-    // fn render_pathfinding_debug<T: sdl2::render::RenderTarget>(&self, canvas: &mut Canvas<T>) -> GameResult<()> {
-    //     let pacman_node = self.state.pacman.current_node_id();
-
-    //     for ghost in self.state.ghosts.iter() {
-    //         if let Ok(path) = ghost.calculate_path_to_target(&self.state.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 => glam::Vec2::new(0.25, 0.5),
-    //                 GhostType::Pinky => glam::Vec2::new(-0.25, -0.25),
-    //                 GhostType::Inky => glam::Vec2::new(0.5, -0.5),
-    //                 GhostType::Clyde => glam::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
-    //                     .state
-    //                     .map
-    //                     .graph
-    //                     .get_node(node_id)
-    //                     .ok_or(crate::error::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) > (crate::constants::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| crate::error::GameError::Sdl(e.to_string()))?;
-    //                 }
-    //             }
-    //         }
-    //     }
-
-    //     Ok(())
-    // }
-
-    // fn draw_hud<T: sdl2::render::RenderTarget>(&mut self, canvas: &mut Canvas<T>) -> GameResult<()> {
-    //     let lives = 3;
-    //     let score_text = format!("{:02}", self.state.score);
-    //     let x_offset = 4;
-    //     let y_offset = 2;
-    //     let lives_offset = 3;
-    //     let score_offset = 7 - (score_text.len() as i32);
-    //     self.state.text_texture.set_scale(1.0);
-    //     if let Err(e) = self.state.text_texture.render(
-    //         canvas,
-    //         &mut self.state.atlas,
-    //         &format!("{lives}UP   HIGH SCORE   "),
-    //         glam::UVec2::new(8 * lives_offset as u32 + x_offset, y_offset),
-    //     ) {
-    //         tracing::error!("Failed to render HUD text: {}", e);
-    //     }
-    //     if let Err(e) = self.state.text_texture.render(
-    //         canvas,
-    //         &mut self.state.atlas,
-    //         &score_text,
-    //         glam::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);
-    //     // self.render_text_on(
-    //     //     canvas,
-    //     //     &*texture_creator,
-    //     //     &fps_text,
-    //     //     IVec2::new(10, 10),
-    //     //     Color::RGB(255, 255, 0), // Yellow color for FPS display
-    //     // );
-
-    //     Ok(())
-    // }
-}

src/game/state.rs

@@ -1,153 +0,0 @@
-// use std::collections::VecDeque;
-
-// use sdl2::{
-//     image::LoadTexture,
-//     render::{Texture, TextureCreator},
-//     video::WindowContext,
-// };
-// use smallvec::SmallVec;
-
-// use crate::{
-//     asset::{get_asset_bytes, Asset},
-//     audio::Audio,
-//     constants::RAW_BOARD,
-//     entity::{
-//         collision::{Collidable, CollisionSystem, EntityId},
-//         ghost::{Ghost, GhostType},
-//         item::Item,
-//         pacman::Pacman,
-//     },
-//     error::{GameError, GameResult, TextureError},
-//     game::events::GameEvent,
-//     map::builder::Map,
-//     texture::{
-//         sprite::{AtlasMapper, SpriteAtlas},
-//         text::TextTexture,
-//     },
-// };
-
-// include!(concat!(env!("OUT_DIR"), "/atlas_data.rs"));
-
-// /// The `GameState` struct holds all the essential data for the game.
-// ///
-// /// This includes the score, map, entities (Pac-Man, ghosts, items),
-// /// collision system, and rendering resources. By centralizing the game's state,
-// /// we can cleanly separate it from the game's logic, making it easier to manage
-// /// and reason about.
-// pub struct GameState {
-//     pub paused: bool,
-
-//     pub score: u32,
-//     pub map: Map,
-//     pub pacman: Pacman,
-//     pub pacman_id: EntityId,
-//     pub ghosts: SmallVec<[Ghost; 4]>,
-//     pub ghost_ids: SmallVec<[EntityId; 4]>,
-//     pub items: Vec<Item>,
-//     pub item_ids: Vec<EntityId>,
-//     pub debug_mode: bool,
-//     pub event_queue: VecDeque<GameEvent>,
-
-//     // Collision system
-//     pub(crate) collision_system: CollisionSystem,
-
-//     // Rendering resources
-//     pub(crate) atlas: SpriteAtlas,
-//     pub(crate) text_texture: TextTexture,
-
-//     // Audio
-//     pub audio: Audio,
-
-//     // Map texture pre-rendering
-//     pub(crate) map_texture: Option<Texture<'static>>,
-//     pub(crate) map_rendered: bool,
-//     pub(crate) texture_creator: &'static TextureCreator<WindowContext>,
-// }
-
-// impl GameState {
-//     /// Creates a new `GameState` by initializing all the game's data.
-//     ///
-//     /// This function sets up the map, Pac-Man, ghosts, items, collision system,
-//     /// and all rendering resources required to start the game. It returns a `GameResult`
-//     /// to handle any potential errors during initialization.
-//     pub fn new(texture_creator: &'static TextureCreator<WindowContext>) -> GameResult<Self> {
-//         let map = Map::new(RAW_BOARD)?;
-
-//         let start_node = map.start_positions.pacman;
-
-//         let atlas_bytes = get_asset_bytes(Asset::Atlas)?;
-//         let atlas_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()))
-//             }
-//         })?;
-
-//         let atlas_mapper = AtlasMapper {
-//             frames: ATLAS_FRAMES.into_iter().map(|(k, v)| (k.to_string(), *v)).collect(),
-//         };
-//         let atlas = SpriteAtlas::new(atlas_texture, atlas_mapper);
-
-//         let text_texture = TextTexture::new(1.0);
-//         let audio = Audio::new();
-//         let pacman = Pacman::new(&map.graph, start_node, &atlas)?;
-
-//         // Generate items (pellets and energizers)
-//         let items = map.generate_items(&atlas)?;
-
-//         // Initialize collision system
-//         let mut collision_system = CollisionSystem::default();
-
-//         // Register Pac-Man
-//         let pacman_id = collision_system.register_entity(pacman.position());
-
-//         // Register items
-//         let item_ids = items
-//             .iter()
-//             .map(|item| collision_system.register_entity(item.position()))
-//             .collect();
-
-//         // Create and register ghosts
-//         let ghosts = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde]
-//             .iter()
-//             .zip(
-//                 [
-//                     map.start_positions.blinky,
-//                     map.start_positions.pinky,
-//                     map.start_positions.inky,
-//                     map.start_positions.clyde,
-//                 ]
-//                 .iter(),
-//             )
-//             .map(|(ghost_type, start_node)| Ghost::new(&map.graph, *start_node, *ghost_type, &atlas))
-//             .collect::<GameResult<SmallVec<[_; 4]>>>()?;
-
-//         // Register ghosts
-//         let ghost_ids = ghosts
-//             .iter()
-//             .map(|ghost| collision_system.register_entity(ghost.position()))
-//             .collect();
-
-//         Ok(Self {
-//             paused: false,
-//             map,
-//             atlas,
-//             pacman,
-//             pacman_id,
-//             ghosts,
-//             ghost_ids,
-//             items,
-//             item_ids,
-//             text_texture,
-//             audio,
-//             score: 0,
-//             debug_mode: false,
-//             collision_system,
-//             map_texture: None,
-//             map_rendered: false,
-//             texture_creator,
-//             event_queue: VecDeque::new(),
-//         })
-//     }
-// }

src/helpers.rs

@@ -1,10 +0,0 @@
-use glam::{IVec2, UVec2};
-use sdl2::rect::Rect;
-
-pub fn centered_with_size(pixel_pos: IVec2, size: UVec2) -> Rect {
-    // 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

@@ -4,11 +4,9 @@ pub mod app;
 pub mod asset;
 pub mod audio;
 pub mod constants;
-pub mod entity;
 pub mod error;
 pub mod events;
 pub mod game;
-pub mod helpers;
 pub mod map;
 pub mod platform;
 pub mod systems;

src/main.rs

@@ -10,11 +10,9 @@ mod asset;
 mod audio;
 mod constants;
 
-mod entity;
 mod error;
 mod events;
 mod game;
-mod helpers;
 mod map;
 mod platform;
 mod systems;

src/map/builder.rs

@@ -1,38 +1,47 @@
 //! Map construction and building functionality.
 use crate::constants::{MapTile, BOARD_CELL_SIZE, CELL_SIZE};
-use crate::entity::direction::Direction;
-use crate::entity::graph::{Graph, Node, TraversalFlags};
+use crate::map::direction::Direction;
+use crate::map::graph::{Graph, Node, TraversalFlags};
 use crate::map::parser::MapTileParser;
-use crate::map::render::MapRenderer;
 use crate::systems::movement::NodeId;
-use crate::texture::sprite::SpriteAtlas;
 use bevy_ecs::resource::Resource;
 use glam::{IVec2, 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.
+/// Predefined spawn locations for all game entities within the navigation graph.
+///
+/// These positions are determined during map parsing and graph construction.
 pub struct NodePositions {
+    /// Pac-Man's starting position in the lower section of the maze
     pub pacman: NodeId,
+    /// Blinky starts at the ghost house entrance
     pub blinky: NodeId,
+    /// Pinky starts in the left area of the ghost house
     pub pinky: NodeId,
+    /// Inky starts in the right area of the ghost house
     pub inky: NodeId,
+    /// Clyde starts in the center of the ghost house
     pub clyde: NodeId,
 }
 
-/// The main map structure containing the game board and navigation graph.
+/// Complete maze representation combining visual layout with navigation pathfinding.
+///
+/// Transforms the ASCII board layout into a fully connected navigation graph
+/// while preserving tile-based collision and rendering data. The graph enables
+/// smooth entity movement with proper pathfinding, while the grid mapping allows
+/// efficient spatial queries and debug visualization.
 #[derive(Resource)]
 pub struct Map {
-    /// The node map for entity movement.
+    /// Connected graph of navigable positions.
     pub graph: Graph,
-    /// A mapping from grid positions to node IDs.
+    /// Bidirectional mapping between 2D grid coordinates and graph node indices.
     pub grid_to_node: HashMap<IVec2, NodeId>,
-    /// A mapping of the starting positions of the entities.
+    /// Predetermined spawn locations for all game entities
     pub start_positions: NodePositions,
-    /// The raw tile data for the map.
+    /// 2D array of tile types for collision detection and rendering
     tiles: [[MapTile; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize],
 }
 
@@ -165,21 +174,29 @@ impl Map {
         })
     }
 
-    /// Renders a debug visualization with cursor-based highlighting.
-    ///
-    /// This function provides interactive debugging by highlighting the nearest node
-    /// to the cursor, showing its ID, and highlighting its connections.
-    pub fn debug_render_with_cursor<T: RenderTarget>(
-        &self,
-        canvas: &mut Canvas<T>,
-        text_renderer: &mut crate::texture::text::TextTexture,
-        atlas: &mut SpriteAtlas,
-        cursor_pos: glam::Vec2,
-    ) -> GameResult<()> {
-        MapRenderer::debug_render_with_cursor(&self.graph, canvas, text_renderer, atlas, cursor_pos)
+    /// Returns the `MapTile` at a given node id.
+    pub fn tile_at_node(&self, node_id: NodeId) -> Option<MapTile> {
+        // reverse lookup: node -> grid
+        for (grid_pos, id) in &self.grid_to_node {
+            if *id == node_id {
+                return Some(self.tiles[grid_pos.x as usize][grid_pos.y as usize]);
+            }
+        }
+        None
     }
 
-    /// Builds the house structure in the graph.
+    /// Constructs the ghost house area with restricted access and internal navigation.
+    ///
+    /// Creates a multi-level ghost house with entrance control, internal movement
+    /// areas, and starting positions for each ghost. The house entrance uses
+    /// ghost-only traversal flags to prevent Pac-Man from entering while allowing
+    /// ghosts to exit. Internal nodes are arranged in vertical lines to provide
+    /// distinct starting areas for each ghost character.
+    ///
+    /// # Returns
+    ///
+    /// Tuple of node IDs: (house_entrance, left_center, center_center, right_center)
+    /// representing the four key positions within the ghost house structure.
     fn build_house(
         graph: &mut Graph,
         grid_to_node: &HashMap<IVec2, NodeId>,
@@ -313,7 +330,10 @@ impl Map {
         ))
     }
 
-    /// Builds the tunnel connections in the graph.
+    /// Creates horizontal tunnel portals for instant teleportation across the maze.
+    ///
+    /// Establishes the tunnel system that allows entities to instantly travel from the left edge of the maze to the right edge.
+    /// Creates hidden intermediate nodes beyond the visible tunnel entrances and connects them with zero-distance edges for instantaneous traversal.
     fn build_tunnels(
         graph: &mut Graph,
         grid_to_node: &HashMap<IVec2, NodeId>,

src/map/graph.rs

@@ -218,9 +218,17 @@ impl Graph {
         self.nodes.get(id)
     }
 
-    /// Returns the total number of nodes in the graph.
-    pub fn node_count(&self) -> usize {
-        self.nodes.len()
+    /// Returns an iterator over all nodes in the graph.
+    pub fn nodes(&self) -> impl Iterator<Item = &Node> {
+        self.nodes.iter()
+    }
+
+    /// Returns an iterator over all edges in the graph.
+    pub fn edges(&self) -> impl Iterator<Item = (NodeId, Edge)> + '_ {
+        self.adjacency_list
+            .iter()
+            .enumerate()
+            .flat_map(|(node_id, intersection)| intersection.edges().map(move |edge| (node_id, edge)))
     }
 
     /// Finds a specific edge from a source node to a target node.

src/map/mod.rs

@@ -1,6 +1,8 @@
 //! This module defines the game map and provides functions for interacting with it.
 
 pub mod builder;
+pub mod direction;
+pub mod graph;
 pub mod layout;
 pub mod parser;
 pub mod render;

src/map/parser.rs

@@ -4,16 +4,21 @@ use crate::constants::{MapTile, BOARD_CELL_SIZE};
 use crate::error::ParseError;
 use glam::IVec2;
 
-/// Represents the parsed data from a raw board layout.
+/// Structured representation of parsed ASCII board layout with extracted special positions.
+///
+/// Contains the complete board state after character-to-tile conversion, along with
+/// the locations of special gameplay elements that require additional processing
+/// during graph construction. Special positions are extracted during parsing to
+/// enable proper map builder initialization.
 #[derive(Debug)]
 pub struct ParsedMap {
-    /// The parsed tile layout.
+    /// 2D array of tiles converted from ASCII characters
     pub tiles: [[MapTile; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize],
-    /// The positions of the house door tiles.
+    /// Two positions marking the ghost house entrance (represented by '=' characters)
     pub house_door: [Option<IVec2>; 2],
-    /// The positions of the tunnel end tiles.
+    /// Two positions marking tunnel portals for wraparound teleportation ('T' characters)
     pub tunnel_ends: [Option<IVec2>; 2],
-    /// Pac-Man's starting position.
+    /// Starting position for Pac-Man (marked by 'X' character in the layout)
     pub pacman_start: Option<IVec2>,
 }
 
@@ -21,15 +26,18 @@ pub struct ParsedMap {
 pub struct MapTileParser;
 
 impl MapTileParser {
-    /// Parses a single character into a map tile.
+    /// Converts ASCII characters from the board layout into corresponding tile types.
     ///
-    /// # Arguments
+    /// Interprets the character-based maze representation: walls (`#`), collectible
+    /// pellets (`.` and `o`), traversable spaces (` `), tunnel entrances (`T`),
+    /// ghost house doors (`=`), and entity spawn markers (`X`). Special characters
+    /// that don't represent tiles in the final map (like spawn markers) are
+    /// converted to `Empty` tiles while their positions are tracked separately.
     ///
-    /// * `c` - The character to parse
+    /// # Errors
     ///
-    /// # Returns
-    ///
-    /// The parsed map tile, or an error if the character is unknown.
+    /// Returns `ParseError::UnknownCharacter` for any character not defined
+    /// in the game's ASCII art vocabulary.
     pub fn parse_character(c: char) -> Result<MapTile, ParseError> {
         match c {
             '#' => Ok(MapTile::Wall),

src/map/render.rs

@@ -3,14 +3,10 @@
 use crate::constants::{BOARD_CELL_OFFSET, CELL_SIZE};
 use crate::map::layout::TILE_MAP;
 use crate::texture::sprite::{AtlasTile, SpriteAtlas};
-use crate::texture::text::TextTexture;
-use glam::Vec2;
 use sdl2::pixels::Color;
-use sdl2::rect::{Point, Rect};
+use sdl2::rect::Rect;
 use sdl2::render::{Canvas, RenderTarget};
 
-use crate::error::{EntityError, GameError, GameResult};
-
 /// Handles rendering operations for the map.
 pub struct MapRenderer;
 
@@ -37,111 +33,4 @@ impl MapRenderer {
             }
         }
     }
-
-    /// Renders a debug visualization with cursor-based highlighting.
-    ///
-    /// This function provides interactive debugging by highlighting the nearest node
-    /// to the cursor, showing its ID, and highlighting its connections.
-    pub fn debug_render_with_cursor<T: RenderTarget>(
-        graph: &crate::entity::graph::Graph,
-        canvas: &mut Canvas<T>,
-        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).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)
-                    .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))
-                    .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).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)))
-                .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)
-                .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)
-                    .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),
-                    )
-                    .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)))
-                .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
-            let id_text = format!("#{nearest_id}");
-            let text_pos = glam::UVec2::new(
-                (nearest_pos.x + 4.0) as u32, // Offset to the right
-                (nearest_pos.y - 6.0) as u32, // Offset to the top
-            );
-            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.
-    pub fn find_nearest_node(graph: &crate::entity::graph::Graph, cursor_pos: Vec2) -> Option<usize> {
-        let mut nearest_id = None;
-        let mut nearest_distance = f32::INFINITY;
-
-        for i in 0..graph.node_count() {
-            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);
-                }
-            }
-        }
-
-        nearest_id
-    }
 }

src/platform/desktop.rs

@@ -5,12 +5,12 @@ use std::time::Duration;
 
 use crate::asset::Asset;
 use crate::error::{AssetError, PlatformError};
-use crate::platform::Platform;
+use crate::platform::CommonPlatform;
 
 /// Desktop platform implementation.
-pub struct DesktopPlatform;
+pub struct Platform;
 
-impl Platform for DesktopPlatform {
+impl CommonPlatform for Platform {
     fn sleep(&self, duration: Duration, focused: bool) {
         if focused {
             spin_sleep::sleep(duration);
@@ -75,7 +75,8 @@ impl Platform for DesktopPlatform {
             Asset::Wav2 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/2.ogg"))),
             Asset::Wav3 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/3.ogg"))),
             Asset::Wav4 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/4.ogg"))),
-            Asset::Atlas => Ok(Cow::Borrowed(include_bytes!("../../assets/game/atlas.png"))),
+            Asset::AtlasImage => Ok(Cow::Borrowed(include_bytes!("../../assets/game/atlas.png"))),
+            Asset::Font => Ok(Cow::Borrowed(include_bytes!("../../assets/game/TerminalVector.ttf"))),
         }
     }
 }

src/platform/emscripten.rs

@@ -5,12 +5,12 @@ use std::time::Duration;
 
 use crate::asset::Asset;
 use crate::error::{AssetError, PlatformError};
-use crate::platform::Platform;
+use crate::platform::CommonPlatform;
 
 /// Emscripten platform implementation.
-pub struct EmscriptenPlatform;
+pub struct Platform;
 
-impl Platform for EmscriptenPlatform {
+impl CommonPlatform for Platform {
     fn sleep(&self, duration: Duration, _focused: bool) {
         unsafe {
             emscripten_sleep(duration.as_millis() as u32);

src/platform/mod.rs

@@ -5,44 +5,42 @@ use crate::error::{AssetError, PlatformError};
 use std::borrow::Cow;
 use std::time::Duration;
 
-pub mod desktop;
-pub mod emscripten;
+#[cfg(not(target_os = "emscripten"))]
+mod desktop;
+#[cfg(target_os = "emscripten")]
+mod emscripten;
 
-/// Platform abstraction trait that defines cross-platform functionality.
-pub trait Platform {
-    /// Sleep for the specified duration using platform-appropriate method.
+/// Cross-platform abstraction layer providing unified APIs for platform-specific operations.
+pub trait CommonPlatform {
+    /// Platform-specific sleep function (required due to Emscripten's non-standard sleep requirements).
+    ///
+    /// Provides access to current window focus state, useful for changing sleep algorithm conditionally.
     fn sleep(&self, duration: Duration, focused: bool);
 
-    /// Get the current time in seconds since some reference point.
-    /// This is available for future use in timing and performance monitoring.
     #[allow(dead_code)]
     fn get_time(&self) -> f64;
 
-    /// Initialize platform-specific console functionality.
+    /// Configures platform-specific console and debugging output capabilities.
     fn init_console(&self) -> Result<(), PlatformError>;
 
-    /// Get canvas size for platforms that need it (e.g., Emscripten).
-    /// This is available for future use in responsive design.
+    /// Retrieves the actual display canvas dimensions.
     #[allow(dead_code)]
     fn get_canvas_size(&self) -> Option<(u32, u32)>;
 
-    /// Load asset bytes using platform-appropriate method.
+    /// Loads raw asset data using the appropriate platform-specific method.
     fn get_asset_bytes(&self, asset: Asset) -> Result<Cow<'static, [u8]>, AssetError>;
 }
 
-/// Get the current platform implementation.
+/// Returns the appropriate platform implementation based on compile-time target.
 #[allow(dead_code)]
-pub fn get_platform() -> &'static dyn Platform {
-    static DESKTOP: desktop::DesktopPlatform = desktop::DesktopPlatform;
-    static EMSCRIPTEN: emscripten::EmscriptenPlatform = emscripten::EmscriptenPlatform;
-
+pub fn get_platform() -> &'static dyn CommonPlatform {
     #[cfg(not(target_os = "emscripten"))]
     {
-        &DESKTOP
+        &desktop::Platform
     }
 
     #[cfg(target_os = "emscripten")]
     {
-        &EMSCRIPTEN
+        &emscripten::Platform
     }
 }

src/systems/audio.rs

@@ -0,0 +1,54 @@
+//! Audio system for handling sound playback in the Pac-Man game.
+//!
+//! This module provides an ECS-based audio system that integrates with SDL2_mixer
+//! for playing sound effects. The system uses NonSendMut resources to handle SDL2's
+//! main-thread requirements while maintaining Bevy ECS compatibility.
+
+use bevy_ecs::{
+    event::{Event, EventReader, EventWriter},
+    system::{NonSendMut, ResMut},
+};
+
+use crate::{audio::Audio, error::GameError, systems::components::AudioState};
+
+/// Events for triggering audio playback
+#[derive(Event, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AudioEvent {
+    /// Play the "eat" sound when Pac-Man consumes a pellet
+    PlayEat,
+}
+
+/// Non-send resource wrapper for SDL2 audio system
+///
+/// This wrapper is needed because SDL2 audio components are not Send,
+/// but Bevy ECS requires Send for regular resources. Using NonSendMut
+/// allows us to use SDL2 audio on the main thread while integrating
+/// with the ECS system.
+pub struct AudioResource(pub Audio);
+
+/// System that processes audio events and plays sounds
+pub fn audio_system(
+    mut audio: NonSendMut<AudioResource>,
+    mut audio_state: ResMut<AudioState>,
+    mut audio_events: EventReader<AudioEvent>,
+    _errors: EventWriter<GameError>,
+) {
+    // Set mute state if it has changed
+    if audio.0.is_muted() != audio_state.muted {
+        audio.0.set_mute(audio_state.muted);
+    }
+
+    // Process audio events
+    for event in audio_events.read() {
+        match event {
+            AudioEvent::PlayEat => {
+                if !audio.0.is_disabled() && !audio_state.muted {
+                    audio.0.eat();
+                    // Update the sound index for cycling through sounds
+                    audio_state.sound_index = (audio_state.sound_index + 1) % 4;
+                    // 4 eat sounds available
+                }
+            }
+        }
+    }
+}

src/systems/collision.rs

@@ -6,43 +6,79 @@ use bevy_ecs::system::{Query, Res};
 use crate::error::GameError;
 use crate::events::GameEvent;
 use crate::map::builder::Map;
-use crate::systems::components::{Collider, ItemCollider, PacmanCollider};
+use crate::systems::components::{Collider, GhostCollider, ItemCollider, PacmanCollider};
 use crate::systems::movement::Position;
 
+/// Helper function to check collision between two entities with colliders.
+pub fn check_collision(
+    pos1: &Position,
+    collider1: &Collider,
+    pos2: &Position,
+    collider2: &Collider,
+    map: &Map,
+) -> Result<bool, GameError> {
+    let pixel1 = pos1
+        .get_pixel_position(&map.graph)
+        .map_err(|e| GameError::InvalidState(format!("Failed to get pixel position for entity 1: {}", e)))?;
+    let pixel2 = pos2
+        .get_pixel_position(&map.graph)
+        .map_err(|e| GameError::InvalidState(format!("Failed to get pixel position for entity 2: {}", e)))?;
+
+    let distance = pixel1.distance(pixel2);
+    Ok(collider1.collides_with(collider2.size, distance))
+}
+
+/// Detects overlapping entities and generates collision events for gameplay systems.
+///
+/// Performs distance-based collision detection between Pac-Man and collectible items
+/// using each entity's position and collision radius. When entities overlap, emits
+/// a `GameEvent::Collision` for the item system to handle scoring and removal.
+/// Collision detection accounts for both entities being in motion and supports
+/// circular collision boundaries for accurate gameplay feel.
+///
+/// Also detects collisions between Pac-Man and ghosts for gameplay mechanics like
+/// power pellet effects, ghost eating, and player death.
 pub fn collision_system(
     map: Res<Map>,
     pacman_query: Query<(Entity, &Position, &Collider), With<PacmanCollider>>,
     item_query: Query<(Entity, &Position, &Collider), With<ItemCollider>>,
+    ghost_query: Query<(Entity, &Position, &Collider), With<GhostCollider>>,
     mut events: EventWriter<GameEvent>,
     mut errors: EventWriter<GameError>,
 ) {
     // Check PACMAN × ITEM collisions
     for (pacman_entity, pacman_pos, pacman_collider) in pacman_query.iter() {
         for (item_entity, item_pos, item_collider) in item_query.iter() {
-            match (pacman_pos.get_pixel_pos(&map.graph), item_pos.get_pixel_pos(&map.graph)) {
-                (Ok(pacman_pixel), Ok(item_pixel)) => {
-                    // Calculate the distance between the two entities's precise pixel positions
-                    let distance = pacman_pixel.distance(item_pixel);
-                    // Calculate the distance at which the two entities will collide
-                    let collision_distance = (pacman_collider.size + item_collider.size) / 2.0;
-
-                    // If the distance between the two entities is less than the collision distance, then the two entities are colliding
-                    if distance < collision_distance {
+            match check_collision(pacman_pos, pacman_collider, item_pos, item_collider, &map) {
+                Ok(colliding) => {
+                    if colliding {
                         events.write(GameEvent::Collision(pacman_entity, item_entity));
                     }
                 }
-                // Either or both of the pixel positions failed to get, so we need to report the error
-                (result_a, result_b) => {
-                    for result in [result_a, result_b] {
-                        if let Err(e) = result {
+                Err(e) => {
                     errors.write(GameError::InvalidState(format!(
-                                "Collision system failed to get pixel positions for entities {:?} and {:?}: {}",
+                        "Collision system failed to check collision between entities {:?} and {:?}: {}",
                         pacman_entity, item_entity, e
                     )));
                 }
             }
         }
+
+        // Check PACMAN × GHOST collisions
+        for (ghost_entity, ghost_pos, ghost_collider) in ghost_query.iter() {
+            match check_collision(pacman_pos, pacman_collider, ghost_pos, ghost_collider, &map) {
+                Ok(colliding) => {
+                    if colliding {
+                        events.write(GameEvent::Collision(pacman_entity, ghost_entity));
+                    }
+                }
+                Err(e) => {
+                    errors.write(GameError::InvalidState(format!(
+                        "Collision system failed to check collision between entities {:?} and {:?}: {}",
+                        pacman_entity, ghost_entity, e
+                    )));
+                }
+            }
+        }
     }
 }
-    }
-}

src/systems/components.rs

@@ -2,8 +2,8 @@ use bevy_ecs::{bundle::Bundle, component::Component, resource::Resource};
 use bitflags::bitflags;
 
 use crate::{
-    entity::graph::TraversalFlags,
-    systems::movement::{Movable, MovementState, Position},
+    map::graph::TraversalFlags,
+    systems::movement::{BufferedDirection, Position, Velocity},
     texture::{animated::AnimatedTexture, sprite::AtlasTile},
 };
 
@@ -11,6 +11,47 @@ use crate::{
 #[derive(Default, Component)]
 pub struct PlayerControlled;
 
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Ghost {
+    Blinky,
+    Pinky,
+    Inky,
+    Clyde,
+}
+
+impl Ghost {
+    /// Returns the ghost type name for atlas lookups.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Ghost::Blinky => "blinky",
+            Ghost::Pinky => "pinky",
+            Ghost::Inky => "inky",
+            Ghost::Clyde => "clyde",
+        }
+    }
+
+    /// Returns the base movement speed for this ghost type.
+    pub fn base_speed(self) -> f32 {
+        match self {
+            Ghost::Blinky => 1.0,
+            Ghost::Pinky => 0.95,
+            Ghost::Inky => 0.9,
+            Ghost::Clyde => 0.85,
+        }
+    }
+
+    /// Returns the ghost's color for debug rendering.
+    #[allow(dead_code)]
+    pub fn debug_color(&self) -> sdl2::pixels::Color {
+        match self {
+            Ghost::Blinky => sdl2::pixels::Color::RGB(255, 0, 0),    // Red
+            Ghost::Pinky => sdl2::pixels::Color::RGB(255, 182, 255), // Pink
+            Ghost::Inky => sdl2::pixels::Color::RGB(0, 255, 255),    // Cyan
+            Ghost::Clyde => sdl2::pixels::Color::RGB(255, 182, 85),  // Orange
+        }
+    }
+}
+
 /// A tag component denoting the type of entity.
 #[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum EntityType {
@@ -29,6 +70,17 @@ impl EntityType {
             _ => TraversalFlags::empty(), // Static entities don't traverse
         }
     }
+    pub fn score_value(&self) -> Option<u32> {
+        match self {
+            EntityType::Pellet => Some(10),
+            EntityType::PowerPellet => Some(50),
+            _ => None,
+        }
+    }
+
+    pub fn is_collectible(&self) -> bool {
+        matches!(self, EntityType::Pellet | EntityType::PowerPellet)
+    }
 }
 
 /// A component for entities that have a sprite, with a layer for ordering.
@@ -60,7 +112,14 @@ bitflags! {
 #[derive(Component)]
 pub struct Collider {
     pub size: f32,
-    pub layer: CollisionLayer,
+}
+
+impl Collider {
+    /// Checks if this collider collides with another collider at the given distance.
+    pub fn collides_with(&self, other_size: f32, distance: f32) -> bool {
+        let collision_distance = (self.size + other_size) / 2.0;
+        distance < collision_distance
+    }
 }
 
 /// Marker components for collision filtering optimization
@@ -73,15 +132,12 @@ pub struct GhostCollider;
 #[derive(Component)]
 pub struct ItemCollider;
 
-#[derive(Component)]
-pub struct Score(pub u32);
-
 #[derive(Bundle)]
 pub struct PlayerBundle {
     pub player: PlayerControlled,
     pub position: Position,
-    pub movement_state: MovementState,
-    pub movable: Movable,
+    pub velocity: Velocity,
+    pub buffered_direction: BufferedDirection,
     pub sprite: Renderable,
     pub directional_animated: DirectionalAnimated,
     pub entity_type: EntityType,
@@ -94,11 +150,22 @@ pub struct ItemBundle {
     pub position: Position,
     pub sprite: Renderable,
     pub entity_type: EntityType,
-    pub score: Score,
     pub collider: Collider,
     pub item_collider: ItemCollider,
 }
 
+#[derive(Bundle)]
+pub struct GhostBundle {
+    pub ghost: Ghost,
+    pub position: Position,
+    pub velocity: Velocity,
+    pub sprite: Renderable,
+    pub directional_animated: DirectionalAnimated,
+    pub entity_type: EntityType,
+    pub collider: Collider,
+    pub ghost_collider: GhostCollider,
+}
+
 #[derive(Resource)]
 pub struct GlobalState {
     pub exit: bool,
@@ -109,3 +176,237 @@ pub struct ScoreResource(pub u32);
 
 #[derive(Resource)]
 pub struct DeltaTime(pub f32);
+
+/// Resource for tracking audio state
+#[derive(Resource, Debug, Clone, Default)]
+pub struct AudioState {
+    /// Whether audio is currently muted
+    pub muted: bool,
+    /// Current sound index for cycling through eat sounds
+    pub sound_index: usize,
+}
+
+/// Lifecycle state for the player entity.
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PlayerLifecycle {
+    Spawning,
+    Alive,
+    Dying,
+    Respawning,
+}
+
+impl PlayerLifecycle {
+    /// Returns true when gameplay input and movement should be active
+    pub fn is_interactive(self) -> bool {
+        matches!(self, PlayerLifecycle::Alive)
+    }
+}
+
+impl Default for PlayerLifecycle {
+    fn default() -> Self {
+        PlayerLifecycle::Spawning
+    }
+}
+
+/// Whether player input should be processed.
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ControlState {
+    InputEnabled,
+    InputLocked,
+}
+
+impl Default for ControlState {
+    fn default() -> Self {
+        Self::InputLocked
+    }
+}
+
+/// Combat-related state for Pac-Man. Tick-based energizer logic.
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CombatState {
+    Normal,
+    Energized {
+        /// Remaining energizer duration in ticks (frames)
+        remaining_ticks: u32,
+        /// Ticks until flashing begins (counts down to 0, then flashing is active)
+        flash_countdown_ticks: u32,
+    },
+}
+
+impl Default for CombatState {
+    fn default() -> Self {
+        CombatState::Normal
+    }
+}
+
+impl CombatState {
+    pub fn is_energized(&self) -> bool {
+        matches!(self, CombatState::Energized { .. })
+    }
+
+    pub fn is_flashing(&self) -> bool {
+        matches!(self, CombatState::Energized { flash_countdown_ticks, .. } if *flash_countdown_ticks == 0)
+    }
+
+    pub fn deactivate_energizer(&mut self) {
+        *self = CombatState::Normal;
+    }
+
+    /// Activate energizer using tick-based durations.
+    pub fn activate_energizer_ticks(&mut self, total_ticks: u32, flash_lead_ticks: u32) {
+        let flash_countdown_ticks = total_ticks.saturating_sub(flash_lead_ticks);
+        *self = CombatState::Energized {
+            remaining_ticks: total_ticks,
+            flash_countdown_ticks,
+        };
+    }
+
+    /// Advance one frame. When ticks reach zero, returns to Normal.
+    pub fn tick_frame(&mut self) {
+        if let CombatState::Energized {
+            remaining_ticks,
+            flash_countdown_ticks,
+        } = self
+        {
+            if *remaining_ticks > 0 {
+                *remaining_ticks -= 1;
+                if *flash_countdown_ticks > 0 {
+                    *flash_countdown_ticks -= 1;
+                }
+            }
+            if *remaining_ticks == 0 {
+                *self = CombatState::Normal;
+            }
+        }
+    }
+}
+
+/// Movement modifiers that can affect Pac-Man's speed or handling.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct MovementModifiers {
+    /// Multiplier applied to base speed (e.g., tunnels)
+    pub speed_multiplier: f32,
+    /// True when currently in a tunnel slowdown region
+    pub tunnel_slowdown_active: bool,
+}
+
+impl Default for MovementModifiers {
+    fn default() -> Self {
+        Self {
+            speed_multiplier: 1.0,
+            tunnel_slowdown_active: false,
+        }
+    }
+}
+
+/// Level-dependent timing configuration
+#[derive(Resource, Debug, Clone, Copy)]
+pub struct LevelTiming {
+    /// Duration of energizer effect in seconds
+    pub energizer_duration: f32,
+    /// Freeze duration at spawn/ready in seconds
+    pub spawn_freeze_duration: f32,
+    /// When to start flashing relative to energizer end (seconds)
+    pub energizer_flash_threshold: f32,
+}
+
+impl Default for LevelTiming {
+    fn default() -> Self {
+        Self {
+            energizer_duration: 6.0,
+            spawn_freeze_duration: 1.5,
+            energizer_flash_threshold: 2.0,
+        }
+    }
+}
+
+impl LevelTiming {
+    /// Returns timing configuration for a given level.
+    pub fn for_level(_level: u32) -> Self {
+        // Placeholder: tune per the Pac-Man Dossier tables
+        Self::default()
+    }
+}
+
+/// Tag component for entities that should be frozen during startup
+#[derive(Component, Debug, Clone, Copy)]
+pub struct Frozen;
+
+/// Convenience bundle for attaching the hybrid FSM to the player entity
+#[derive(Bundle, Default)]
+pub struct PlayerStateBundle {
+    pub lifecycle: PlayerLifecycle,
+    pub control: ControlState,
+    pub combat: CombatState,
+    pub movement_modifiers: MovementModifiers,
+}
+
+#[derive(Resource, Debug, Clone, Copy)]
+pub enum StartupSequence {
+    /// Stage 1: Text-only stage
+    /// - Player & ghosts are hidden
+    /// - READY! and PLAYER ONE text are shown
+    /// - Energizers do not blink
+    TextOnly {
+        /// Remaining ticks in this stage
+        remaining_ticks: u32,
+    },
+    /// Stage 2: Characters visible stage
+    /// - PLAYER ONE text is hidden, READY! text remains
+    /// - Ghosts and Pac-Man are now shown
+    CharactersVisible {
+        /// Remaining ticks in this stage
+        remaining_ticks: u32,
+    },
+    /// Stage 3: Game begins
+    /// - Final state, game is fully active
+    GameActive,
+}
+
+impl StartupSequence {
+    /// Creates a new StartupSequence with the specified duration in ticks
+    pub fn new(text_only_ticks: u32, _characters_visible_ticks: u32) -> Self {
+        Self::TextOnly {
+            remaining_ticks: text_only_ticks,
+        }
+    }
+
+    /// Returns true if the timer is still active (not in GameActive state)
+    pub fn is_active(&self) -> bool {
+        !matches!(self, StartupSequence::GameActive)
+    }
+
+    /// Returns true if we're in the game active stage
+    pub fn is_game_active(&self) -> bool {
+        matches!(self, StartupSequence::GameActive)
+    }
+
+    /// Ticks the timer by one frame, returning transition information if state changes
+    pub fn tick(&mut self) -> Option<(StartupSequence, StartupSequence)> {
+        match self {
+            StartupSequence::TextOnly { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    *remaining_ticks -= 1;
+                    None
+                } else {
+                    let from = *self;
+                    *self = StartupSequence::CharactersVisible {
+                        remaining_ticks: 60, // 1 second at 60 FPS
+                    };
+                    Some((from, *self))
+                }
+            }
+            StartupSequence::CharactersVisible { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    *remaining_ticks -= 1;
+                    None
+                } else {
+                    let from = *self;
+                    *self = StartupSequence::GameActive;
+                    Some((from, *self))
+                }
+            }
+            StartupSequence::GameActive => None,
+        }
+    }
+}

src/systems/control.rs

@@ -1,45 +0,0 @@
-use bevy_ecs::{
-    event::{EventReader, EventWriter},
-    prelude::ResMut,
-    query::With,
-    system::Query,
-};
-
-use crate::{
-    error::GameError,
-    events::{GameCommand, GameEvent},
-    systems::components::{GlobalState, PlayerControlled},
-    systems::movement::Movable,
-};
-
-// Handles player input and control
-pub fn player_system(
-    mut events: EventReader<GameEvent>,
-    mut state: ResMut<GlobalState>,
-    mut players: Query<&mut Movable, With<PlayerControlled>>,
-    mut errors: EventWriter<GameError>,
-) {
-    // Get the player's movable component (ensuring there is only one player)
-    let mut movable = match players.single_mut() {
-        Ok(movable) => movable,
-        Err(e) => {
-            errors.write(GameError::InvalidState(format!("No/multiple entities queried for player system: {}", e)).into());
-            return;
-        }
-    };
-
-    // Handle events
-    for event in events.read() {
-        if let GameEvent::Command(command) = event {
-            match command {
-                GameCommand::MovePlayer(direction) => {
-                    movable.requested_direction = Some(*direction);
-                }
-                GameCommand::Exit => {
-                    state.exit = true;
-                }
-                _ => {}
-            }
-        }
-    }
-}

src/systems/debug.rs

@@ -0,0 +1,224 @@
+//! Debug rendering system
+use std::cmp::Ordering;
+
+use crate::constants::BOARD_PIXEL_OFFSET;
+use crate::map::builder::Map;
+use crate::systems::components::Collider;
+use crate::systems::input::CursorPosition;
+use crate::systems::movement::Position;
+use crate::systems::profiling::SystemTimings;
+use crate::systems::render::BackbufferResource;
+use bevy_ecs::prelude::*;
+use glam::{IVec2, UVec2, Vec2};
+use sdl2::pixels::Color;
+use sdl2::rect::{Point, Rect};
+use sdl2::render::{Canvas, Texture, TextureCreator};
+use sdl2::ttf::Font;
+use sdl2::video::{Window, WindowContext};
+
+#[derive(Resource, Default, Debug, Copy, Clone)]
+pub struct DebugState {
+    pub enabled: bool,
+}
+
+fn f32_to_u8(value: f32) -> u8 {
+    (value * 255.0) as u8
+}
+
+/// Resource to hold the debug texture for persistent rendering
+pub struct DebugTextureResource(pub Texture<'static>);
+
+/// Resource to hold the debug font
+pub struct DebugFontResource(pub Font<'static, 'static>);
+
+/// Transforms a position from logical canvas coordinates to output canvas coordinates (with board offset)
+fn transform_position_with_offset(pos: Vec2, scale: f32) -> IVec2 {
+    ((pos + BOARD_PIXEL_OFFSET.as_vec2()) * scale).as_ivec2()
+}
+
+/// Renders timing information in the top-left corner of the screen
+fn render_timing_display(
+    canvas: &mut Canvas<Window>,
+    texture_creator: &mut TextureCreator<WindowContext>,
+    timings: &SystemTimings,
+    font: &Font,
+) {
+    // Format timing information using the formatting module
+    let lines = timings.format_timing_display();
+    let line_height = 14; // Approximate line height for 12pt font
+    let padding = 10;
+
+    // Calculate background dimensions
+    let max_width = lines
+        .iter()
+        .filter(|l| !l.is_empty()) // Don't consider empty lines for width
+        .map(|line| font.size_of(line).unwrap().0)
+        .max()
+        .unwrap_or(0);
+
+    // Only draw background if there is text to display
+    if max_width > 0 {
+        let total_height = (lines.len() as u32) * line_height as u32;
+        let bg_padding = 5;
+
+        // Draw background
+        let bg_rect = Rect::new(
+            padding - bg_padding,
+            padding - bg_padding,
+            max_width + (bg_padding * 2) as u32,
+            total_height + bg_padding as u32,
+        );
+        canvas.set_blend_mode(sdl2::render::BlendMode::Blend);
+        canvas.set_draw_color(Color::RGBA(40, 40, 40, 180));
+        canvas.fill_rect(bg_rect).unwrap();
+    }
+
+    for (i, line) in lines.iter().enumerate() {
+        if line.is_empty() {
+            continue;
+        }
+
+        // Render each line
+        let surface = font.render(line).blended(Color::RGBA(255, 255, 255, 200)).unwrap();
+        let texture = texture_creator.create_texture_from_surface(&surface).unwrap();
+
+        // Position each line below the previous one
+        let y_pos = padding + (i * line_height) as i32;
+        let dest = Rect::new(padding, y_pos, texture.query().width, texture.query().height);
+        canvas.copy(&texture, None, dest).unwrap();
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn debug_render_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    backbuffer: NonSendMut<BackbufferResource>,
+    mut debug_texture: NonSendMut<DebugTextureResource>,
+    debug_font: NonSendMut<DebugFontResource>,
+    debug_state: Res<DebugState>,
+    timings: Res<SystemTimings>,
+    map: Res<Map>,
+    colliders: Query<(&Collider, &Position)>,
+    cursor: Res<CursorPosition>,
+) {
+    if !debug_state.enabled {
+        return;
+    }
+    let scale =
+        (UVec2::from(canvas.output_size().unwrap()).as_vec2() / UVec2::from(canvas.logical_size()).as_vec2()).min_element();
+
+    // Copy the current backbuffer to the debug texture
+    canvas
+        .with_texture_canvas(&mut debug_texture.0, |debug_canvas| {
+            // Clear the debug canvas
+            debug_canvas.set_draw_color(Color::BLACK);
+            debug_canvas.clear();
+
+            // Copy the backbuffer to the debug canvas
+            debug_canvas.copy(&backbuffer.0, None, None).unwrap();
+        })
+        .unwrap();
+
+    // Get texture creator before entering the closure to avoid borrowing conflicts
+    let mut texture_creator = canvas.texture_creator();
+    let font = &debug_font.0;
+
+    let cursor_world_pos = match *cursor {
+        CursorPosition::None => None,
+        CursorPosition::Some { position, .. } => Some(position - BOARD_PIXEL_OFFSET.as_vec2()),
+    };
+
+    // Draw debug info on the high-resolution debug texture
+    canvas
+        .with_texture_canvas(&mut debug_texture.0, |debug_canvas| {
+            // Find the closest node to the cursor
+
+            let closest_node = if let Some(cursor_world_pos) = cursor_world_pos {
+                map.graph
+                    .nodes()
+                    .map(|node| node.position.distance(cursor_world_pos))
+                    .enumerate()
+                    .min_by(|(_, a), (_, b)| a.partial_cmp(b).unwrap_or(Ordering::Less))
+                    .map(|(id, _)| id)
+            } else {
+                None
+            };
+
+            debug_canvas.set_draw_color(Color::GREEN);
+            for (collider, position) in colliders.iter() {
+                let pos = position.get_pixel_position(&map.graph).unwrap();
+
+                // Transform position and size using common methods
+                let pos = (pos * scale).as_ivec2();
+                let size = (collider.size * scale) as u32;
+
+                let rect = Rect::from_center(Point::from((pos.x, pos.y)), size, size);
+                debug_canvas.draw_rect(rect).unwrap();
+            }
+
+            debug_canvas.set_draw_color(Color {
+                a: f32_to_u8(0.4),
+                ..Color::RED
+            });
+            debug_canvas.set_blend_mode(sdl2::render::BlendMode::Blend);
+            for (start_node, end_node) in map.graph.edges() {
+                let start_node_model = map.graph.get_node(start_node).unwrap();
+                let end_node = map.graph.get_node(end_node.target).unwrap().position;
+
+                // Transform positions using common method
+                let start = transform_position_with_offset(start_node_model.position, scale);
+                let end = transform_position_with_offset(end_node, scale);
+
+                debug_canvas
+                    .draw_line(Point::from((start.x, start.y)), Point::from((end.x, end.y)))
+                    .unwrap();
+            }
+
+            for (id, node) in map.graph.nodes().enumerate() {
+                let pos = node.position;
+
+                // Set color based on whether the node is the closest to the cursor
+                debug_canvas.set_draw_color(Color {
+                    a: f32_to_u8(if Some(id) == closest_node { 0.75 } else { 0.6 }),
+                    ..(if Some(id) == closest_node {
+                        Color::YELLOW
+                    } else {
+                        Color::BLUE
+                    })
+                });
+
+                // Transform position using common method
+                let pos = transform_position_with_offset(pos, scale);
+                let size = (2.0 * scale) as u32;
+
+                debug_canvas
+                    .fill_rect(Rect::new(pos.x - (size as i32 / 2), pos.y - (size as i32 / 2), size, size))
+                    .unwrap();
+            }
+
+            // Render node ID if a node is highlighted
+            if let Some(closest_node_id) = closest_node {
+                let node = map.graph.get_node(closest_node_id).unwrap();
+                let pos = transform_position_with_offset(node.position, scale);
+
+                let surface = font
+                    .render(&closest_node_id.to_string())
+                    .blended(Color {
+                        a: f32_to_u8(0.4),
+                        ..Color::WHITE
+                    })
+                    .unwrap();
+                let texture = texture_creator.create_texture_from_surface(&surface).unwrap();
+                let dest = Rect::new(pos.x + 10, pos.y - 5, texture.query().width, texture.query().height);
+                debug_canvas.copy(&texture, None, dest).unwrap();
+            }
+
+            // Render timing information in the top-left corner
+            render_timing_display(debug_canvas, &mut texture_creator, &timings, font);
+        })
+        .unwrap();
+
+    // Draw the debug texture directly onto the main canvas at full resolution
+    canvas.copy(&debug_texture.0, None, None).unwrap();
+    canvas.present();
+}

src/systems/formatting.rs

@@ -0,0 +1,107 @@
+use num_width::NumberWidth;
+use smallvec::SmallVec;
+use std::time::Duration;
+use strum::EnumCount;
+
+use crate::systems::profiling::SystemId;
+
+// Helper to split a duration into a integer, decimal, and unit
+fn get_value(duration: &Duration) -> (u64, u32, &'static str) {
+    let (int, decimal, unit) = match duration {
+        // if greater than 1 second, return as seconds
+        n if n >= &Duration::from_secs(1) => {
+            let secs = n.as_secs();
+            let decimal = n.as_millis() as u64 % 1000;
+            (secs, decimal as u32, "s")
+        }
+        // if greater than 1 millisecond, return as milliseconds
+        n if n >= &Duration::from_millis(1) => {
+            let ms = n.as_millis() as u64;
+            let decimal = n.as_micros() as u64 % 1000;
+            (ms, decimal as u32, "ms")
+        }
+        // if greater than 1 microsecond, return as microseconds
+        n if n >= &Duration::from_micros(1) => {
+            let us = n.as_micros() as u64;
+            let decimal = n.as_nanos() as u64 % 1000;
+            (us, decimal as u32, "µs")
+        }
+        // otherwise, return as nanoseconds
+        n => {
+            let ns = n.as_nanos() as u64;
+            (ns, 0, "ns")
+        }
+    };
+
+    (int, decimal, unit)
+}
+
+/// Formats timing data into a vector of strings with proper alignment
+pub fn format_timing_display(
+    timing_data: impl IntoIterator<Item = (String, Duration, Duration)>,
+) -> SmallVec<[String; SystemId::COUNT]> {
+    let mut iter = timing_data.into_iter().peekable();
+    if iter.peek().is_none() {
+        return SmallVec::new();
+    }
+
+    struct Entry {
+        name: String,
+        avg_int: u64,
+        avg_decimal: u32,
+        avg_unit: &'static str,
+        std_int: u64,
+        std_decimal: u32,
+        std_unit: &'static str,
+    }
+
+    let entries = iter
+        .map(|(name, avg, std_dev)| {
+            let (avg_int, avg_decimal, avg_unit) = get_value(&avg);
+            let (std_int, std_decimal, std_unit) = get_value(&std_dev);
+
+            Entry {
+                name: name.clone(),
+                avg_int,
+                avg_decimal,
+                avg_unit,
+                std_int,
+                std_decimal,
+                std_unit,
+            }
+        })
+        .collect::<SmallVec<[Entry; 12]>>();
+
+    let (max_name_width, max_avg_int_width, max_avg_decimal_width, max_std_int_width, max_std_decimal_width) = entries
+        .iter()
+        .fold((0, 0, 3, 0, 3), |(name_w, avg_int_w, avg_dec_w, std_int_w, std_dec_w), e| {
+            (
+                name_w.max(e.name.len()),
+                avg_int_w.max(e.avg_int.width() as usize),
+                avg_dec_w.max(e.avg_decimal.width() as usize),
+                std_int_w.max(e.std_int.width() as usize),
+                std_dec_w.max(e.std_decimal.width() as usize),
+            )
+        });
+
+    entries.iter().map(|e| {
+            format!(
+                "{name:max_name_width$} : {avg_int:max_avg_int_width$}.{avg_decimal:<max_avg_decimal_width$}{avg_unit} ± {std_int:max_std_int_width$}.{std_decimal:<max_std_decimal_width$}{std_unit}",
+                // Content
+                name = e.name,
+                avg_int = e.avg_int,
+                avg_decimal = e.avg_decimal,
+                std_int = e.std_int,
+                std_decimal = e.std_decimal,
+                // Units
+                avg_unit = e.avg_unit,
+                std_unit = e.std_unit,
+                // Padding
+                max_name_width = max_name_width,
+                max_avg_int_width = max_avg_int_width,
+                max_avg_decimal_width = max_avg_decimal_width,
+                max_std_int_width = max_std_int_width,
+                max_std_decimal_width = max_std_decimal_width
+            )
+        }).collect::<SmallVec<[String; SystemId::COUNT]>>()
+}

src/systems/ghost.rs

@@ -0,0 +1,118 @@
+use bevy_ecs::entity::Entity;
+use bevy_ecs::event::{EventReader, EventWriter};
+use bevy_ecs::query::{With, Without};
+use bevy_ecs::system::{Commands, Query, Res, ResMut};
+use rand::rngs::SmallRng;
+use rand::seq::IndexedRandom;
+use rand::SeedableRng;
+use smallvec::SmallVec;
+
+use crate::events::GameEvent;
+use crate::systems::audio::AudioEvent;
+use crate::systems::components::{Frozen, GhostCollider, ScoreResource};
+use crate::{
+    map::{
+        builder::Map,
+        direction::Direction,
+        graph::{Edge, TraversalFlags},
+    },
+    systems::{
+        components::{CombatState, DeltaTime, Ghost, PlayerControlled},
+        movement::{Position, Velocity},
+    },
+};
+
+/// Autonomous ghost AI system implementing randomized movement with backtracking avoidance.
+pub fn ghost_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut ghosts: Query<(&Ghost, &mut Velocity, &mut Position), Without<Frozen>>,
+) {
+    for (_ghost, mut velocity, mut position) in ghosts.iter_mut() {
+        let mut distance = velocity.speed * 60.0 * delta_time.0;
+        loop {
+            match *position {
+                Position::Stopped { node: current_node } => {
+                    let intersection = &map.graph.adjacency_list[current_node];
+                    let opposite = velocity.direction.opposite();
+
+                    let mut non_opposite_options: SmallVec<[Edge; 3]> = SmallVec::new();
+
+                    // Collect all available directions that ghosts can traverse
+                    for edge in Direction::DIRECTIONS.iter().flat_map(|d| intersection.get(*d)) {
+                        if edge.traversal_flags.contains(TraversalFlags::GHOST) && edge.direction != opposite {
+                            non_opposite_options.push(edge);
+                        }
+                    }
+
+                    let new_edge: Edge = if non_opposite_options.is_empty() {
+                        if let Some(edge) = intersection.get(opposite) {
+                            edge
+                        } else {
+                            break;
+                        }
+                    } else {
+                        *non_opposite_options.choose(&mut SmallRng::from_os_rng()).unwrap()
+                    };
+
+                    velocity.direction = new_edge.direction;
+                    *position = Position::Moving {
+                        from: current_node,
+                        to: new_edge.target,
+                        remaining_distance: new_edge.distance,
+                    };
+                }
+                Position::Moving { .. } => {
+                    if let Some(overflow) = position.tick(distance) {
+                        distance = overflow;
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+
+pub fn ghost_collision_system(
+    mut commands: Commands,
+    mut collision_events: EventReader<GameEvent>,
+    mut score: ResMut<ScoreResource>,
+    pacman_query: Query<&CombatState, With<PlayerControlled>>,
+    ghost_query: Query<(Entity, &Ghost), With<GhostCollider>>,
+    mut events: EventWriter<AudioEvent>,
+) {
+    for event in collision_events.read() {
+        if let GameEvent::Collision(entity1, entity2) = event {
+            // Check if one is Pacman and the other is a ghost
+            let (pacman_entity, ghost_entity) = if pacman_query.get(*entity1).is_ok() && ghost_query.get(*entity2).is_ok() {
+                (*entity1, *entity2)
+            } else if pacman_query.get(*entity2).is_ok() && ghost_query.get(*entity1).is_ok() {
+                (*entity2, *entity1)
+            } else {
+                continue;
+            };
+
+            // Check if Pac-Man is energized
+            if let Ok(combat_state) = pacman_query.get(pacman_entity) {
+                if combat_state.is_energized() {
+                    // Pac-Man eats the ghost
+                    if let Ok((ghost_ent, _ghost_type)) = ghost_query.get(ghost_entity) {
+                        // Add score (200 points per ghost eaten)
+                        score.0 += 200;
+
+                        // Remove the ghost
+                        commands.entity(ghost_ent).despawn();
+
+                        // Play eat sound
+                        events.write(AudioEvent::PlayEat);
+                    }
+                } else {
+                    // Pac-Man dies (this would need a death system)
+                    // For now, just log it
+                    tracing::warn!("Pac-Man collided with ghost while not energized!");
+                }
+            }
+        }
+    }
+}

src/systems/input.rs

@@ -1,16 +1,34 @@
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 
-use bevy_ecs::{event::EventWriter, prelude::Res, resource::Resource, system::NonSendMut};
+use bevy_ecs::{
+    event::EventWriter,
+    resource::Resource,
+    system::{NonSendMut, Res, ResMut},
+};
+use glam::Vec2;
 use sdl2::{event::Event, keyboard::Keycode, EventPump};
 
+use crate::systems::components::DeltaTime;
 use crate::{
-    entity::direction::Direction,
     events::{GameCommand, GameEvent},
+    map::direction::Direction,
 };
 
-#[derive(Debug, Clone, Resource)]
+#[derive(Resource, Default, Debug, Copy, Clone)]
+pub enum CursorPosition {
+    #[default]
+    None,
+    Some {
+        position: Vec2,
+        remaining_time: f32,
+    },
+}
+
+#[derive(Resource, Debug, Clone)]
 pub struct Bindings {
     key_bindings: HashMap<Keycode, GameCommand>,
+    movement_keys: HashSet<Keycode>,
+    pressed_movement_keys: Vec<Keycode>,
 }
 
 impl Default for Bindings {
@@ -35,24 +53,130 @@ impl Default for Bindings {
         key_bindings.insert(Keycode::Escape, GameCommand::Exit);
         key_bindings.insert(Keycode::Q, GameCommand::Exit);
 
-        Self { key_bindings }
+        let movement_keys = HashSet::from([
+            Keycode::W,
+            Keycode::A,
+            Keycode::S,
+            Keycode::D,
+            Keycode::Up,
+            Keycode::Down,
+            Keycode::Left,
+            Keycode::Right,
+        ]);
+
+        Self {
+            key_bindings,
+            movement_keys,
+            pressed_movement_keys: Vec::new(),
+        }
     }
 }
 
-pub fn input_system(bindings: Res<Bindings>, mut writer: EventWriter<GameEvent>, mut pump: NonSendMut<&'static mut EventPump>) {
-    for event in pump.poll_iter() {
-        match event {
+/// A simplified input event used for deterministic testing and logic reuse
+/// without depending on SDL's event pump.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SimpleKeyEvent {
+    KeyDown(Keycode),
+    KeyUp(Keycode),
+}
+
+/// Processes a frame's worth of simplified key events and returns the resulting
+/// `GameEvent`s that would be emitted by the input system for that frame.
+///
+/// This mirrors the behavior of `input_system` for keyboard-related logic:
+/// - KeyDown emits the bound command immediately (movement or otherwise)
+/// - Tracks pressed movement keys in order to continue movement on subsequent frames
+/// - KeyUp removes movement keys; if another movement key remains, it resumes
+pub fn process_simple_key_events(bindings: &mut Bindings, frame_events: &[SimpleKeyEvent]) -> Vec<GameEvent> {
+    let mut emitted_events = Vec::new();
+    let mut movement_key_pressed = false;
+
+    for event in frame_events {
+        match *event {
+            SimpleKeyEvent::KeyDown(key) => {
+                if let Some(command) = bindings.key_bindings.get(&key).copied() {
+                    emitted_events.push(GameEvent::Command(command));
+                }
+
+                if bindings.movement_keys.contains(&key) {
+                    movement_key_pressed = true;
+                    if !bindings.pressed_movement_keys.contains(&key) {
+                        bindings.pressed_movement_keys.push(key);
+                    }
+                }
+            }
+            SimpleKeyEvent::KeyUp(key) => {
+                if bindings.movement_keys.contains(&key) {
+                    bindings.pressed_movement_keys.retain(|&k| k != key);
+                }
+            }
+        }
+    }
+
+    if !movement_key_pressed {
+        if let Some(&last_movement_key) = bindings.pressed_movement_keys.last() {
+            if let Some(command) = bindings.key_bindings.get(&last_movement_key).copied() {
+                emitted_events.push(GameEvent::Command(command));
+            }
+        }
+    }
+
+    emitted_events
+}
+
+pub fn input_system(
+    delta_time: Res<DeltaTime>,
+    mut bindings: ResMut<Bindings>,
+    mut writer: EventWriter<GameEvent>,
+    mut pump: NonSendMut<&'static mut EventPump>,
+    mut cursor: ResMut<CursorPosition>,
+) {
+    let mut cursor_seen = false;
+    // Collect all events for this frame.
+    let frame_events: Vec<Event> = pump.poll_iter().collect();
+
+    // Handle non-keyboard events inline and build a simplified keyboard event stream.
+    let mut simple_key_events = Vec::new();
+    for event in &frame_events {
+        match *event {
             Event::Quit { .. } => {
                 writer.write(GameEvent::Command(GameCommand::Exit));
             }
-            Event::KeyDown { keycode: Some(key), .. } => {
-                let command = bindings.key_bindings.get(&key).copied();
-                if let Some(command) = command {
-                    tracing::info!("triggering command: {:?}", command);
-                    writer.write(GameEvent::Command(command));
+            Event::MouseMotion { x, y, .. } => {
+                *cursor = CursorPosition::Some {
+                    position: Vec2::new(x as f32, y as f32),
+                    remaining_time: 0.20,
+                };
+                cursor_seen = true;
             }
+            Event::KeyDown {
+                keycode: Some(key),
+                repeat: false,
+                ..
+            } => {
+                simple_key_events.push(SimpleKeyEvent::KeyDown(key));
+            }
+            Event::KeyUp {
+                keycode: Some(key),
+                repeat: false,
+                ..
+            } => {
+                simple_key_events.push(SimpleKeyEvent::KeyUp(key));
             }
             _ => {}
         }
     }
+
+    // Delegate keyboard handling to shared logic used by tests and production.
+    let emitted = process_simple_key_events(&mut bindings, &simple_key_events);
+    for event in emitted {
+        writer.write(event);
+    }
+
+    if let (false, CursorPosition::Some { remaining_time, .. }) = (cursor_seen, &mut *cursor) {
+        *remaining_time -= delta_time.0;
+        if *remaining_time <= 0.0 {
+            *cursor = CursorPosition::None;
+        }
+    }
 }

src/systems/item.rs

@@ -0,0 +1,72 @@
+use bevy_ecs::{event::EventReader, prelude::*, query::With, system::Query};
+
+use crate::{
+    events::GameEvent,
+    systems::{
+        audio::AudioEvent,
+        components::{CombatState, EntityType, ItemCollider, LevelTiming, PacmanCollider, ScoreResource},
+    },
+};
+
+/// Determines if a collision between two entity types should be handled by the item system.
+///
+/// Returns `true` if one entity is a player and the other is a collectible item.
+#[allow(dead_code)]
+pub fn is_valid_item_collision(entity1: EntityType, entity2: EntityType) -> bool {
+    match (entity1, entity2) {
+        (EntityType::Player, entity) | (entity, EntityType::Player) => entity.is_collectible(),
+        _ => false,
+    }
+}
+
+pub fn item_system(
+    mut commands: Commands,
+    mut collision_events: EventReader<GameEvent>,
+    mut score: ResMut<ScoreResource>,
+    pacman_query: Query<Entity, With<PacmanCollider>>,
+    mut combat_q: Query<&mut CombatState, With<PacmanCollider>>,
+    item_query: Query<(Entity, &EntityType), With<ItemCollider>>,
+    mut events: EventWriter<AudioEvent>,
+    level_timing: Res<LevelTiming>,
+) {
+    for event in collision_events.read() {
+        if let GameEvent::Collision(entity1, entity2) = event {
+            // Check if one is Pacman and the other is an item
+            let (_pacman_entity, item_entity) = if pacman_query.get(*entity1).is_ok() && item_query.get(*entity2).is_ok() {
+                (*entity1, *entity2)
+            } else if pacman_query.get(*entity2).is_ok() && item_query.get(*entity1).is_ok() {
+                (*entity2, *entity1)
+            } else {
+                continue;
+            };
+
+            // Get the item type and update score
+            if let Ok((item_ent, entity_type)) = item_query.get(item_entity) {
+                if let Some(score_value) = entity_type.score_value() {
+                    score.0 += score_value;
+
+                    // Remove the collected item
+                    commands.entity(item_ent).despawn();
+
+                    // Trigger audio if appropriate
+                    if entity_type.is_collectible() {
+                        events.write(AudioEvent::PlayEat);
+                    }
+
+                    // Activate energizer on power pellet using tick-based durations
+                    if *entity_type == EntityType::PowerPellet {
+                        if let Ok(mut combat) = combat_q.single_mut() {
+                            // Convert seconds to frames (assumes 60 FPS)
+                            let total_ticks = (level_timing.energizer_duration * 60.0).round().clamp(0.0, u32::MAX as f32) as u32;
+                            // Flash lead: e.g., 3 seconds (180 ticks) before end; ensure it doesn't underflow
+                            let flash_lead_ticks = (level_timing.energizer_flash_threshold * 60.0)
+                                .round()
+                                .clamp(0.0, u32::MAX as f32) as u32;
+                            combat.activate_energizer_ticks(total_ticks, flash_lead_ticks);
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

src/systems/mod.rs

@@ -3,11 +3,17 @@
 //! This module contains all the ECS-related logic, including components, systems,
 //! and resources.
 
+pub mod audio;
 pub mod blinking;
 pub mod collision;
 pub mod components;
-pub mod control;
+pub mod debug;
+pub mod formatting;
+pub mod ghost;
 pub mod input;
+pub mod item;
 pub mod movement;
+pub mod player;
 pub mod profiling;
 pub mod render;
+pub mod stage;

src/systems/movement.rs

@@ -1,46 +1,47 @@
-use crate::entity::graph::Graph;
-use crate::entity::{direction::Direction, graph::Edge};
-use crate::error::{EntityError, GameError, GameResult};
-use crate::map::builder::Map;
-use crate::systems::components::{DeltaTime, EntityType};
+use crate::error::{EntityError, GameResult};
+use crate::map::direction::Direction;
+use crate::map::graph::Graph;
 use bevy_ecs::component::Component;
-use bevy_ecs::event::EventWriter;
-use bevy_ecs::system::{Query, Res};
 use glam::Vec2;
 
-/// A unique identifier for a node, represented by its index in the graph's storage.
+/// Zero-based index identifying a specific node in the navigation graph.
+///
+/// Nodes represent discrete movement targets in the maze. The index directly corresponds to the node's position in the
+/// graph's internal storage arrays.
 pub type NodeId = usize;
 
-/// Progress along an edge between two nodes.
-#[derive(Debug, Clone, Copy, PartialEq)]
-pub struct EdgeProgress {
-    pub target_node: NodeId,
-    /// Progress from 0.0 (at source node) to 1.0 (at target node)
-    pub progress: f32,
-}
-
-/// Pure spatial position component - works for both static and dynamic entities.
+/// A component that represents the speed and cardinal direction of an entity.
+/// Speed is static, only applied when the entity has an edge to traverse.
+/// Direction is dynamic, but is controlled externally.
 #[derive(Component, Debug, Copy, Clone, PartialEq)]
-pub struct Position {
-    /// The current/primary node this entity is at or traveling from
-    pub node: NodeId,
-    /// If Some, entity is traveling between nodes. If None, entity is stationary at node.
-    pub edge_progress: Option<EdgeProgress>,
-}
-
-/// Explicit movement state - only for entities that can move.
-#[derive(Component, Debug, Clone, Copy, PartialEq)]
-pub enum MovementState {
-    Stopped,
-    Moving { direction: Direction },
-}
-
-/// Movement capability and parameters - only for entities that can move.
-#[derive(Component, Debug, Clone, Copy)]
-pub struct Movable {
+pub struct Velocity {
     pub speed: f32,
-    pub current_direction: Direction,
-    pub requested_direction: Option<Direction>,
+    pub direction: Direction,
+}
+
+/// A component that represents a direction change that is only remembered for a period of time.
+/// This is used to allow entities to change direction before they reach their current target node (which consumes their buffered direction).
+#[derive(Component, Debug, Copy, Clone, PartialEq)]
+pub enum BufferedDirection {
+    None,
+    Some { direction: Direction, remaining_time: f32 },
+}
+
+/// Entity position state that handles both stationary entities and moving entities.
+///
+/// Supports precise positioning during movement between discrete navigation nodes.
+/// When moving, entities smoothly interpolate along edges while tracking exact distance remaining to the target node.
+#[derive(Component, Debug, Copy, Clone, PartialEq)]
+pub enum Position {
+    /// Entity is stationary at a specific graph node.
+    Stopped { node: NodeId },
+    /// Entity is traveling between two nodes.
+    Moving {
+        from: NodeId,
+        to: NodeId,
+        /// Distance remaining to reach the target node.
+        remaining_distance: f32,
+    },
 }
 
 impl Position {
@@ -52,26 +53,32 @@ impl Position {
     /// # Errors
     ///
     /// Returns an `EntityError` if the node or edge is not found.
-    pub fn get_pixel_pos(&self, graph: &Graph) -> GameResult<Vec2> {
-        let pos = match &self.edge_progress {
-            None => {
+    pub fn get_pixel_position(&self, graph: &Graph) -> GameResult<Vec2> {
+        let pos = match &self {
+            Position::Stopped { node } => {
                 // Entity is stationary at a node
-                let node = graph.get_node(self.node).ok_or(EntityError::NodeNotFound(self.node))?;
+                let node = graph.get_node(*node).ok_or(EntityError::NodeNotFound(*node))?;
                 node.position
             }
-            Some(edge_progress) => {
+            Position::Moving {
+                from,
+                to,
+                remaining_distance,
+            } => {
                 // Entity is traveling between nodes
-                let from_node = graph.get_node(self.node).ok_or(EntityError::NodeNotFound(self.node))?;
-                let to_node = graph
-                    .get_node(edge_progress.target_node)
-                    .ok_or(EntityError::NodeNotFound(edge_progress.target_node))?;
+                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: *from, to: *to })?;
 
                 // For zero-distance edges (tunnels), progress >= 1.0 means we're at the target
-                if edge_progress.progress >= 1.0 {
+                if edge.distance == 0.0 {
                     to_node.position
                 } else {
                     // Interpolate position based on progress
-                    from_node.position + (to_node.position - from_node.position) * edge_progress.progress
+                    let progress = 1.0 - (*remaining_distance / edge.distance);
+                    from_node.position.lerp(to_node.position, progress)
                 }
             }
         };
@@ -81,192 +88,61 @@ impl Position {
             pos.y + crate::constants::BOARD_PIXEL_OFFSET.y as f32,
         ))
     }
+
+    /// Advances movement progress by the specified distance with overflow handling.
+    ///
+    /// For moving entities, decreases the remaining distance to the target node.
+    /// If the distance would overshoot the target, the entity transitions to
+    /// `Stopped` state and returns the excess distance for chaining movement
+    /// to the next edge in the same frame.
+    ///
+    /// # Arguments
+    ///
+    /// * `distance` - Distance to travel this frame (typically speed × delta_time)
+    ///
+    /// # Returns
+    ///
+    /// `Some(overflow)` if the target was reached with distance remaining,
+    /// `None` if still moving or already stopped.
+    pub fn tick(&mut self, distance: f32) -> Option<f32> {
+        if distance <= 0.0 || self.is_at_node() {
+            return None;
         }
 
-impl Default for Position {
-    fn default() -> Self {
-        Position {
-            node: 0,
-            edge_progress: None,
+        match self {
+            Position::Moving {
+                to, remaining_distance, ..
+            } => {
+                // If the remaining distance is less than or equal the distance, we'll reach the target
+                if *remaining_distance <= distance {
+                    let overflow: Option<f32> = if *remaining_distance != distance {
+                        Some(distance - *remaining_distance)
+                    } else {
+                        None
+                    };
+                    *self = Position::Stopped { node: *to };
+
+                    return overflow;
                 }
+
+                *remaining_distance -= distance;
+
+                None
+            }
+            _ => unreachable!(),
         }
     }
 
-#[allow(dead_code)]
-impl Position {
     /// Returns `true` if the position is exactly at a node (not traveling).
     pub fn is_at_node(&self) -> bool {
-        self.edge_progress.is_none()
+        matches!(self, Position::Stopped { .. })
     }
 
     /// Returns the `NodeId` of the current node (source of travel if moving).
     pub fn current_node(&self) -> NodeId {
-        self.node
-    }
-
-    /// Returns the `NodeId` of the destination node, if currently traveling.
-    pub fn target_node(&self) -> Option<NodeId> {
-        self.edge_progress.as_ref().map(|ep| ep.target_node)
-    }
-
-    /// Returns `true` if the entity is traveling between nodes.
-    pub fn is_moving(&self) -> bool {
-        self.edge_progress.is_some()
-    }
-}
-
-fn can_traverse(entity_type: EntityType, edge: Edge) -> bool {
-    let entity_flags = entity_type.traversal_flags();
-    edge.traversal_flags.contains(entity_flags)
-}
-
-pub fn movement_system(
-    map: Res<Map>,
-    delta_time: Res<DeltaTime>,
-    mut entities: Query<(&mut MovementState, &mut Movable, &mut Position, &EntityType)>,
-    mut errors: EventWriter<GameError>,
-) {
-    for (mut movement_state, mut movable, mut position, entity_type) in entities.iter_mut() {
-        let distance = movable.speed * 60.0 * delta_time.0;
-
-        match *movement_state {
-            MovementState::Stopped => {
-                // Check if we have a requested direction to start moving
-                if let Some(requested_direction) = movable.requested_direction {
-                    if let Some(edge) = map.graph.find_edge_in_direction(position.node, requested_direction) {
-                        if can_traverse(*entity_type, edge) {
-                            // Start moving in the requested direction
-                            let progress = if edge.distance > 0.0 {
-                                distance / edge.distance
-                            } else {
-                                // Zero-distance edge (tunnels) - immediately teleport
-                                tracing::debug!("Entity entering tunnel from node {} to node {}", position.node, edge.target);
-                                1.0
-                            };
-
-                            position.edge_progress = Some(EdgeProgress {
-                                target_node: edge.target,
-                                progress,
-                            });
-                            movable.current_direction = requested_direction;
-                            movable.requested_direction = None;
-                            *movement_state = MovementState::Moving {
-                                direction: requested_direction,
-                            };
-                        }
-                    } else {
-                        errors.write(
-                            EntityError::InvalidMovement(format!(
-                                "No edge found in direction {:?} from node {}",
-                                requested_direction, position.node
-                            ))
-                            .into(),
-                        );
-                    }
-                }
-            }
-            MovementState::Moving { direction } => {
-                // Continue moving or handle node transitions
-                let current_node = position.node;
-                if let Some(edge_progress) = &mut position.edge_progress {
-                    // Extract target node before mutable operations
-                    let target_node = edge_progress.target_node;
-
-                    // Get the current edge for distance calculation
-                    let edge = map.graph.find_edge(current_node, target_node);
-
-                    if let Some(edge) = edge {
-                        // Update progress along the edge
-                        if edge.distance > 0.0 {
-                            edge_progress.progress += distance / edge.distance;
-                        } else {
-                            // Zero-distance edge (tunnels) - immediately complete
-                            edge_progress.progress = 1.0;
-                        }
-
-                        if edge_progress.progress >= 1.0 {
-                            // Reached the target node
-                            let overflow = if edge.distance > 0.0 {
-                                (edge_progress.progress - 1.0) * edge.distance
-                            } else {
-                                // Zero-distance edge - use remaining distance for overflow
-                                distance
-                            };
-                            position.node = target_node;
-                            position.edge_progress = None;
-
-                            let mut continued_moving = false;
-
-                            // Try to use requested direction first
-                            if let Some(requested_direction) = movable.requested_direction {
-                                if let Some(next_edge) = map.graph.find_edge_in_direction(position.node, requested_direction) {
-                                    if can_traverse(*entity_type, next_edge) {
-                                        let next_progress = if next_edge.distance > 0.0 {
-                                            overflow / next_edge.distance
-                                        } else {
-                                            // Zero-distance edge - immediately complete
-                                            1.0
-                                        };
-
-                                        position.edge_progress = Some(EdgeProgress {
-                                            target_node: next_edge.target,
-                                            progress: next_progress,
-                                        });
-                                        movable.current_direction = requested_direction;
-                                        movable.requested_direction = None;
-                                        *movement_state = MovementState::Moving {
-                                            direction: requested_direction,
-                                        };
-                                        continued_moving = true;
-                                    }
-                                }
-                            }
-
-                            // If no requested direction or it failed, try to continue in current direction
-                            if !continued_moving {
-                                if let Some(next_edge) = map.graph.find_edge_in_direction(position.node, direction) {
-                                    if can_traverse(*entity_type, next_edge) {
-                                        let next_progress = if next_edge.distance > 0.0 {
-                                            overflow / next_edge.distance
-                                        } else {
-                                            // Zero-distance edge - immediately complete
-                                            1.0
-                                        };
-
-                                        position.edge_progress = Some(EdgeProgress {
-                                            target_node: next_edge.target,
-                                            progress: next_progress,
-                                        });
-                                        // Keep current direction and movement state
-                                        continued_moving = true;
-                                    }
-                                }
-                            }
-
-                            // If we couldn't continue moving, stop
-                            if !continued_moving {
-                                *movement_state = MovementState::Stopped;
-                                movable.requested_direction = None;
-                            }
-                        }
-                    } else {
-                        // Edge not found - this is an inconsistent state
-                        errors.write(
-                            EntityError::InvalidMovement(format!(
-                                "Inconsistent state: Moving on non-existent edge from {} to {}",
-                                current_node, target_node
-                            ))
-                            .into(),
-                        );
-                        *movement_state = MovementState::Stopped;
-                        position.edge_progress = None;
-                    }
-                } else {
-                    // Movement state says moving but no edge progress - this shouldn't happen
-                    errors.write(EntityError::InvalidMovement("Entity in Moving state but no edge progress".to_string()).into());
-                    *movement_state = MovementState::Stopped;
-                }
-            }
+        match self {
+            Position::Stopped { node } => *node,
+            Position::Moving { from, .. } => *from,
         }
     }
 }

src/systems/player.rs

@@ -0,0 +1,189 @@
+use bevy_ecs::{
+    entity::Entity,
+    event::{EventReader, EventWriter},
+    prelude::{Commands, ResMut},
+    query::With,
+    system::{Query, Res},
+};
+
+use crate::{
+    error::GameError,
+    events::{GameCommand, GameEvent},
+    map::builder::Map,
+    map::graph::Edge,
+    systems::{
+        components::{
+            AudioState, ControlState, DeltaTime, EntityType, Frozen, GhostCollider, GlobalState, MovementModifiers,
+            PlayerControlled, PlayerLifecycle, StartupSequence,
+        },
+        debug::DebugState,
+        movement::{BufferedDirection, Position, Velocity},
+    },
+};
+
+/// Processes player input commands and updates game state accordingly.
+///
+/// Handles keyboard-driven commands like movement direction changes, debug mode
+/// toggling, audio muting, and game exit requests. Movement commands are buffered
+/// to allow direction changes before reaching intersections, improving gameplay
+/// responsiveness. Non-movement commands immediately modify global game state.
+pub fn player_control_system(
+    mut events: EventReader<GameEvent>,
+    mut state: ResMut<GlobalState>,
+    mut debug_state: ResMut<DebugState>,
+    mut audio_state: ResMut<AudioState>,
+    mut players: Query<(&PlayerLifecycle, &ControlState, &mut BufferedDirection), With<PlayerControlled>>,
+    mut errors: EventWriter<GameError>,
+) {
+    // Get the player's movable component (ensuring there is only one player)
+    let (lifecycle, control, mut buffered_direction) = match players.single_mut() {
+        Ok(tuple) => tuple,
+        Err(e) => {
+            errors.write(GameError::InvalidState(format!(
+                "No/multiple entities queried for player system: {}",
+                e
+            )));
+            return;
+        }
+    };
+
+    // If the player is not interactive or input is locked, ignore movement commands
+    let allow_input = lifecycle.is_interactive() && matches!(control, ControlState::InputEnabled);
+
+    // Handle events
+    for event in events.read() {
+        if let GameEvent::Command(command) = event {
+            match command {
+                GameCommand::MovePlayer(direction) => {
+                    if allow_input {
+                        *buffered_direction = BufferedDirection::Some {
+                            direction: *direction,
+                            remaining_time: 0.25,
+                        };
+                    }
+                }
+                GameCommand::Exit => {
+                    state.exit = true;
+                }
+                GameCommand::ToggleDebug => {
+                    debug_state.enabled = !debug_state.enabled;
+                }
+                GameCommand::MuteAudio => {
+                    audio_state.muted = !audio_state.muted;
+                    tracing::info!("Audio {}", if audio_state.muted { "muted" } else { "unmuted" });
+                }
+                _ => {}
+            }
+        }
+    }
+}
+
+pub fn can_traverse(entity_type: EntityType, edge: Edge) -> bool {
+    let entity_flags = entity_type.traversal_flags();
+    edge.traversal_flags.contains(entity_flags)
+}
+
+/// Executes frame-by-frame movement for Pac-Man.
+///
+/// Handles movement logic including buffered direction changes, edge traversal validation, and continuous movement between nodes.
+/// When stopped, prioritizes buffered directions for responsive controls, falling back to current direction.
+/// Supports movement chaining within a single frame when traveling at high speeds.
+pub fn player_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut entities: Query<
+        (
+            &PlayerLifecycle,
+            &ControlState,
+            &MovementModifiers,
+            &mut Position,
+            &mut Velocity,
+            &mut BufferedDirection,
+        ),
+        With<PlayerControlled>,
+    >,
+    // mut errors: EventWriter<GameError>,
+) {
+    for (lifecycle, control, modifiers, mut position, mut velocity, mut buffered_direction) in entities.iter_mut() {
+        if !lifecycle.is_interactive() || !matches!(control, ControlState::InputEnabled) {
+            continue;
+        }
+
+        // Decrement the buffered direction remaining time
+        if let BufferedDirection::Some {
+            direction,
+            remaining_time,
+        } = *buffered_direction
+        {
+            if remaining_time <= 0.0 {
+                *buffered_direction = BufferedDirection::None;
+            } else {
+                *buffered_direction = BufferedDirection::Some {
+                    direction,
+                    remaining_time: remaining_time - delta_time.0,
+                };
+            }
+        }
+
+        let mut distance = velocity.speed * modifiers.speed_multiplier * 60.0 * delta_time.0;
+
+        loop {
+            match *position {
+                Position::Stopped { .. } => {
+                    // If there is a buffered direction, travel it's edge first if available.
+                    if let BufferedDirection::Some { direction, .. } = *buffered_direction {
+                        // If there's no edge in that direction, ignore the buffered direction.
+                        if let Some(edge) = map.graph.find_edge_in_direction(position.current_node(), direction) {
+                            // If there is an edge in that direction (and it's traversable), start moving towards it and consume the buffered direction.
+                            if can_traverse(EntityType::Player, edge) {
+                                velocity.direction = edge.direction;
+                                *position = Position::Moving {
+                                    from: position.current_node(),
+                                    to: edge.target,
+                                    remaining_distance: edge.distance,
+                                };
+                                *buffered_direction = BufferedDirection::None;
+                            }
+                        }
+                    }
+
+                    // If there is no buffered direction (or it's not yet valid), continue in the current direction.
+                    if let Some(edge) = map.graph.find_edge_in_direction(position.current_node(), velocity.direction) {
+                        if can_traverse(EntityType::Player, edge) {
+                            velocity.direction = edge.direction;
+                            *position = Position::Moving {
+                                from: position.current_node(),
+                                to: edge.target,
+                                remaining_distance: edge.distance,
+                            };
+                        }
+                    } else {
+                        // No edge in our current direction either, erase the buffered direction and stop.
+                        *buffered_direction = BufferedDirection::None;
+                        break;
+                    }
+                }
+                Position::Moving { .. } => {
+                    if let Some(overflow) = position.tick(distance) {
+                        distance = overflow;
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Applies tunnel slowdown based on the current node tile
+pub fn player_tunnel_slowdown_system(map: Res<Map>, mut q: Query<(&Position, &mut MovementModifiers), With<PlayerControlled>>) {
+    if let Ok((position, mut modifiers)) = q.single_mut() {
+        let node = position.current_node();
+        let in_tunnel = map
+            .tile_at_node(node)
+            .map(|t| t == crate::constants::MapTile::Tunnel)
+            .unwrap_or(false);
+        modifiers.tunnel_slowdown_active = in_tunnel;
+        modifiers.speed_multiplier = if in_tunnel { 0.6 } else { 1.0 };
+    }
+}

src/systems/profiling.rs

@@ -1,15 +1,169 @@
 use bevy_ecs::prelude::Resource;
 use bevy_ecs::system::{IntoSystem, System};
-use parking_lot::Mutex;
-use std::collections::HashMap;
+use circular_buffer::CircularBuffer;
+use micromap::Map;
+use parking_lot::{Mutex, RwLock};
+use smallvec::SmallVec;
+use std::fmt::Display;
 use std::time::Duration;
+use strum::EnumCount;
+use strum_macros::{EnumCount, IntoStaticStr};
+use thousands::Separable;
+
+use crate::systems::formatting;
+
+/// The maximum number of systems that can be profiled. Must not be exceeded, or it will panic.
+const MAX_SYSTEMS: usize = SystemId::COUNT;
+/// The number of durations to keep in the circular buffer.
+const TIMING_WINDOW_SIZE: usize = 30;
+
+#[derive(EnumCount, IntoStaticStr, Debug, PartialEq, Eq, Hash, Copy, Clone)]
+pub enum SystemId {
+    Input,
+    PlayerControls,
+    Ghost,
+    Movement,
+    Audio,
+    Blinking,
+    DirectionalRender,
+    DirtyRender,
+    HudRender,
+    Render,
+    DebugRender,
+    Present,
+    Collision,
+    Item,
+    PlayerMovement,
+    GhostCollision,
+    Stage,
+}
+
+impl Display for SystemId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", Into::<&'static str>::into(self).to_ascii_lowercase())
+    }
+}
 
 #[derive(Resource, Default, Debug)]
 pub struct SystemTimings {
-    pub timings: Mutex<HashMap<&'static str, Duration>>,
+    /// Map of system names to a queue of durations, using a circular buffer.
+    ///
+    /// Uses a RwLock to allow multiple readers for the HashMap, and a Mutex on the circular buffer for exclusive access.
+    /// This is probably overkill, but it's fun to play with.
+    ///
+    /// Also, we use a micromap::Map as the number of systems is generally quite small.
+    /// Just make sure to set the capacity appropriately, or it will panic.
+    pub timings: RwLock<Map<SystemId, Mutex<CircularBuffer<TIMING_WINDOW_SIZE, Duration>>, MAX_SYSTEMS>>,
 }
 
-pub fn profile<S, M>(name: &'static str, system: S) -> impl FnMut(&mut bevy_ecs::world::World)
+impl SystemTimings {
+    pub fn add_timing(&self, id: SystemId, duration: Duration) {
+        // acquire a upgradable read lock
+        let mut timings = self.timings.upgradable_read();
+
+        // happy path, the name is already in the map (no need to mutate the hashmap)
+        if timings.contains_key(&id) {
+            let queue = timings
+                .get(&id)
+                .expect("System name not found in map after contains_key check");
+            let mut queue = queue.lock();
+
+            queue.push_back(duration);
+            return;
+        }
+
+        // otherwise, acquire a write lock and insert a new queue
+        timings.with_upgraded(|timings| {
+            let queue = timings.entry(id).or_insert_with(|| Mutex::new(CircularBuffer::new()));
+            queue.lock().push_back(duration);
+        });
+    }
+
+    pub fn get_stats(&self) -> Map<SystemId, (Duration, Duration), MAX_SYSTEMS> {
+        let timings = self.timings.read();
+        let mut stats = Map::new();
+
+        for (id, queue) in timings.iter() {
+            if queue.lock().is_empty() {
+                continue;
+            }
+
+            let durations: Vec<f64> = queue.lock().iter().map(|d| d.as_secs_f64() * 1000.0).collect();
+            let count = durations.len() as f64;
+
+            let sum: f64 = durations.iter().sum();
+            let mean = sum / count;
+
+            let variance = durations.iter().map(|x| (x - mean).powi(2)).sum::<f64>() / count;
+            let std_dev = variance.sqrt();
+
+            stats.insert(
+                *id,
+                (
+                    Duration::from_secs_f64(mean / 1000.0),
+                    Duration::from_secs_f64(std_dev / 1000.0),
+                ),
+            );
+        }
+
+        stats
+    }
+
+    pub fn get_total_stats(&self) -> (Duration, Duration) {
+        let timings = self.timings.read();
+        let mut all_durations = Vec::new();
+
+        for queue in timings.values() {
+            all_durations.extend(queue.lock().iter().map(|d| d.as_secs_f64() * 1000.0));
+        }
+
+        if all_durations.is_empty() {
+            return (Duration::ZERO, Duration::ZERO);
+        }
+
+        let count = all_durations.len() as f64;
+        let sum: f64 = all_durations.iter().sum();
+        let mean = sum / count;
+
+        let variance = all_durations.iter().map(|x| (x - mean).powi(2)).sum::<f64>() / count;
+        let std_dev = variance.sqrt();
+
+        (
+            Duration::from_secs_f64(mean / 1000.0),
+            Duration::from_secs_f64(std_dev / 1000.0),
+        )
+    }
+
+    pub fn format_timing_display(&self) -> SmallVec<[String; SystemId::COUNT]> {
+        let stats = self.get_stats();
+        let (total_avg, total_std) = self.get_total_stats();
+
+        let effective_fps = match 1.0 / total_avg.as_secs_f64() {
+            f if f > 100.0 => (f as u32).separate_with_commas(),
+            f if f < 10.0 => format!("{:.1} FPS", f),
+            f => format!("{:.0} FPS", f),
+        };
+
+        // Collect timing data for formatting
+        let mut timing_data = Vec::new();
+
+        // Add total stats
+        timing_data.push((effective_fps, total_avg, total_std));
+
+        // Add top 5 most expensive systems
+        let mut sorted_stats: Vec<_> = stats.iter().collect();
+        sorted_stats.sort_by(|a, b| b.1 .0.cmp(&a.1 .0));
+
+        for (name, (avg, std_dev)) in sorted_stats.iter().take(5) {
+            timing_data.push((name.to_string(), *avg, *std_dev));
+        }
+
+        // Use the formatting module to format the data
+        formatting::format_timing_display(timing_data)
+    }
+}
+
+pub fn profile<S, M>(id: SystemId, system: S) -> impl FnMut(&mut bevy_ecs::world::World)
 where
     S: IntoSystem<(), (), M> + 'static,
 {
@@ -25,8 +179,8 @@ where
         system.run((), world);
         let duration = start.elapsed();
 
-        if let Some(mut timings) = world.get_resource_mut::<SystemTimings>() {
-            timings.timings.lock().insert(name, duration);
+        if let Some(timings) = world.get_resource::<SystemTimings>() {
+            timings.add_timing(id, duration);
         }
     }
 }

src/systems/render.rs

@@ -1,26 +1,48 @@
+use crate::constants::CANVAS_SIZE;
 use crate::error::{GameError, TextureError};
 use crate::map::builder::Map;
-use crate::systems::components::{DeltaTime, DirectionalAnimated, Renderable};
-use crate::systems::movement::{Movable, MovementState, Position};
+use crate::systems::blinking::Blinking;
+use crate::systems::components::{
+    DeltaTime, DirectionalAnimated, EntityType, GhostCollider, PlayerControlled, Renderable, ScoreResource, StartupSequence,
+};
+use crate::systems::movement::{Position, Velocity};
 use crate::texture::sprite::SpriteAtlas;
+use crate::texture::text::TextTexture;
 use bevy_ecs::entity::Entity;
 use bevy_ecs::event::EventWriter;
-use bevy_ecs::prelude::{Changed, Or, RemovedComponents};
-use bevy_ecs::system::{NonSendMut, Query, Res};
+use bevy_ecs::prelude::{Changed, Or, RemovedComponents, With, Without};
+use bevy_ecs::resource::Resource;
+use bevy_ecs::system::{NonSendMut, Query, Res, ResMut};
+use sdl2::pixels::Color;
+use sdl2::rect::{Point, Rect};
 use sdl2::render::{Canvas, Texture};
 use sdl2::video::Window;
 
+#[derive(Resource, Default)]
+pub struct RenderDirty(pub bool);
+
+#[allow(clippy::type_complexity)]
+pub fn dirty_render_system(
+    mut dirty: ResMut<RenderDirty>,
+    changed_renderables: Query<(), Or<(Changed<Renderable>, Changed<Position>)>>,
+    removed_renderables: RemovedComponents<Renderable>,
+) {
+    if !changed_renderables.is_empty() || !removed_renderables.is_empty() {
+        dirty.0 = true;
+    }
+}
+
 /// Updates the directional animated texture of an entity.
 ///
 /// This runs before the render system so it can update the sprite based on the current direction of travel, as well as whether the entity is moving.
 pub fn directional_render_system(
     dt: Res<DeltaTime>,
-    mut renderables: Query<(&MovementState, &Movable, &mut DirectionalAnimated, &mut Renderable)>,
+    mut renderables: Query<(&Position, &Velocity, &mut DirectionalAnimated, &mut Renderable)>,
     mut errors: EventWriter<GameError>,
 ) {
-    for (movement_state, movable, mut texture, mut renderable) in renderables.iter_mut() {
-        let stopped = matches!(movement_state, MovementState::Stopped);
-        let current_direction = movable.current_direction;
+    for (position, velocity, mut texture, mut renderable) in renderables.iter_mut() {
+        let stopped = matches!(position, Position::Stopped { .. });
+        let current_direction = velocity.direction;
 
         let texture = if stopped {
             texture.stopped_textures[current_direction.as_usize()].as_mut()
@@ -37,7 +59,7 @@ pub fn directional_render_system(
                 renderable.sprite = new_tile;
             }
         } else {
-            errors.write(TextureError::RenderFailed(format!("Entity has no texture")).into());
+            errors.write(TextureError::RenderFailed("Entity has no texture".to_string()).into());
             continue;
         }
     }
@@ -49,24 +71,124 @@ pub struct MapTextureResource(pub Texture<'static>);
 /// A non-send resource for the backbuffer texture. This just wraps the texture with a type so it can be differentiated when exposed as a resource.
 pub struct BackbufferResource(pub Texture<'static>);
 
+/// Updates entity visibility based on StartupSequence stages
+pub fn ready_visibility_system(
+    startup: Res<StartupSequence>,
+    mut player_query: Query<&mut Renderable, (With<PlayerControlled>, Without<GhostCollider>)>,
+    mut ghost_query: Query<&mut Renderable, (With<GhostCollider>, Without<PlayerControlled>)>,
+    mut energizer_query: Query<(&mut Blinking, &EntityType)>,
+) {
+    match *startup {
+        StartupSequence::TextOnly { .. } => {
+            // Hide player and ghosts, disable energizer blinking
+            if let Ok(mut renderable) = player_query.single_mut() {
+                renderable.visible = false;
+            }
+
+            for mut renderable in ghost_query.iter_mut() {
+                renderable.visible = false;
+            }
+
+            // Disable energizer blinking in text-only stage
+            for (mut blinking, entity_type) in energizer_query.iter_mut() {
+                if matches!(entity_type, EntityType::PowerPellet) {
+                    blinking.timer = 0.0; // Reset timer to prevent blinking
+                }
+            }
+        }
+        StartupSequence::CharactersVisible { .. } => {
+            // Show player and ghosts, enable energizer blinking
+            if let Ok(mut renderable) = player_query.single_mut() {
+                renderable.visible = true;
+            }
+
+            for mut renderable in ghost_query.iter_mut() {
+                renderable.visible = true;
+            }
+
+            // Energizer blinking is handled by the blinking system
+        }
+        StartupSequence::GameActive => {
+            // All entities are visible and blinking is normal
+            if let Ok(mut renderable) = player_query.single_mut() {
+                renderable.visible = true;
+            }
+
+            for mut renderable in ghost_query.iter_mut() {
+                renderable.visible = true;
+            }
+        }
+    }
+}
+
+/// Renders the HUD (score, lives, etc.) on top of the game.
+pub fn hud_render_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    mut atlas: NonSendMut<SpriteAtlas>,
+    score: Res<ScoreResource>,
+    startup: Res<StartupSequence>,
+    mut errors: EventWriter<GameError>,
+) {
+    let mut text_renderer = TextTexture::new(1.0);
+
+    // Render lives and high score text in white
+    let lives = 3; // TODO: Get from actual lives resource
+    let lives_text = format!("{lives}UP   HIGH SCORE   ");
+    let lives_position = glam::UVec2::new(4 + 8 * 3, 2); // x_offset + lives_offset * 8, y_offset
+
+    if let Err(e) = text_renderer.render(&mut canvas, &mut atlas, &lives_text, lives_position) {
+        errors.write(TextureError::RenderFailed(format!("Failed to render lives text: {}", e)).into());
+    }
+
+    // Render score text in yellow (Pac-Man's color)
+    let score_text = format!("{:02}", score.0);
+    let score_offset = 7 - (score_text.len() as i32);
+    let score_position = glam::UVec2::new(4 + 8 * score_offset as u32, 10); // x_offset + score_offset * 8, 8 + y_offset
+
+    if let Err(e) = text_renderer.render(&mut canvas, &mut atlas, &score_text, score_position) {
+        errors.write(TextureError::RenderFailed(format!("Failed to render score text: {}", e)).into());
+    }
+
+    // Render text based on StartupSequence stage
+    if matches!(
+        *startup,
+        StartupSequence::TextOnly { .. } | StartupSequence::CharactersVisible { .. }
+    ) {
+        let ready_text = "READY!";
+        let ready_width = text_renderer.text_width(ready_text);
+        let ready_position = glam::UVec2::new((CANVAS_SIZE.x - ready_width) / 2, 160);
+        if let Err(e) = text_renderer.render_with_color(&mut canvas, &mut atlas, ready_text, ready_position, Color::YELLOW) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render READY text: {}", e)).into());
+        }
+
+        if matches!(*startup, StartupSequence::TextOnly { .. }) {
+            let player_one_text = "PLAYER ONE";
+            let player_one_width = text_renderer.text_width(player_one_text);
+            let player_one_position = glam::UVec2::new((CANVAS_SIZE.x - player_one_width) / 2, 113);
+
+            if let Err(e) =
+                text_renderer.render_with_color(&mut canvas, &mut atlas, player_one_text, player_one_position, Color::CYAN)
+            {
+                errors.write(TextureError::RenderFailed(format!("Failed to render PLAYER ONE text: {}", e)).into());
+            }
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
 pub fn render_system(
     mut canvas: NonSendMut<&mut Canvas<Window>>,
     map_texture: NonSendMut<MapTextureResource>,
     mut backbuffer: NonSendMut<BackbufferResource>,
     mut atlas: NonSendMut<SpriteAtlas>,
     map: Res<Map>,
+    dirty: Res<RenderDirty>,
     renderables: Query<(Entity, &Renderable, &Position)>,
-    changed_renderables: Query<(), Or<(Changed<Renderable>, Changed<Position>)>>,
-    removed_renderables: RemovedComponents<Renderable>,
     mut errors: EventWriter<GameError>,
 ) {
-    if changed_renderables.is_empty() && removed_renderables.is_empty() {
+    if !dirty.0 {
         return;
     }
-    // Clear the main canvas first
-    canvas.set_draw_color(sdl2::pixels::Color::BLACK);
-    canvas.clear();
-
     // Render to backbuffer
     canvas
         .with_texture_canvas(&mut backbuffer.0, |backbuffer_canvas| {
@@ -80,13 +202,22 @@ pub fn render_system(
             }
 
             // Render all entities to the backbuffer
-            for (_, renderable, position) in renderables.iter() {
-                let pos = position.get_pixel_pos(&map.graph);
+            for (_, renderable, position) in renderables
+                .iter()
+                .sort_by_key::<(Entity, &Renderable, &Position), _>(|(_, renderable, _)| renderable.layer)
+                .rev()
+            {
+                if !renderable.visible {
+                    continue;
+                }
+
+                let pos = position.get_pixel_position(&map.graph);
                 match pos {
                     Ok(pos) => {
-                        let dest = crate::helpers::centered_with_size(
-                            glam::IVec2::new(pos.x as i32, pos.y as i32),
-                            glam::UVec2::new(renderable.sprite.size.x as u32, renderable.sprite.size.y as u32),
+                        let dest = Rect::from_center(
+                            Point::from((pos.x as i32, pos.y as i32)),
+                            renderable.sprite.size.x as u32,
+                            renderable.sprite.size.y as u32,
                         );
 
                         renderable
@@ -96,7 +227,7 @@ pub fn render_system(
                             .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
                     }
                     Err(e) => {
-                        errors.write(e.into());
+                        errors.write(e);
                     }
                 }
             }
@@ -104,11 +235,5 @@ pub fn render_system(
         .err()
         .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
 
-    // Copy backbuffer to main canvas and present
-    canvas
-        .copy(&backbuffer.0, None, None)
-        .err()
-        .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
-
-    canvas.present();
+    canvas.copy(&backbuffer.0, None, None).unwrap();
 }

src/systems/stage.rs

@@ -0,0 +1,33 @@
+use bevy_ecs::{
+    prelude::{Commands, Entity, Query, With},
+    system::ResMut,
+};
+
+use crate::systems::components::{Frozen, GhostCollider, PlayerControlled, StartupSequence};
+
+/// Handles startup sequence transitions and component management
+pub fn startup_stage_system(
+    mut startup: ResMut<StartupSequence>,
+    mut commands: Commands,
+    mut player_query: Query<Entity, With<PlayerControlled>>,
+    mut ghost_query: Query<Entity, With<GhostCollider>>,
+) {
+    if let Some((from, to)) = startup.tick() {
+        match (from, to) {
+            (StartupSequence::TextOnly { .. }, StartupSequence::CharactersVisible { .. }) => {
+                // TODO: Add TextOnly tag component to hide entities
+                // TODO: Add CharactersVisible tag component to show entities
+                // TODO: Remove TextOnly tag component
+            }
+            (StartupSequence::CharactersVisible { .. }, StartupSequence::GameActive) => {
+                // Remove Frozen tag from all entities
+                for entity in player_query.iter_mut().chain(ghost_query.iter_mut()) {
+                    commands.entity(entity).remove::<Frozen>();
+                }
+                // TODO: Add GameActive tag component
+                // TODO: Remove CharactersVisible tag component
+            }
+            _ => {}
+        }
+    }
+}

src/texture/animated.rs

@@ -1,11 +1,19 @@
 use crate::error::{AnimatedTextureError, GameError, GameResult, TextureError};
 use crate::texture::sprite::AtlasTile;
 
+/// Frame-based animation system for cycling through multiple sprite tiles.
+///
+/// Manages automatic frame progression based on elapsed time.
+/// Uses a time banking system to ensure consistent animation speed regardless of frame rate variations.
 #[derive(Debug, Clone)]
 pub struct AnimatedTexture {
+    /// Sequence of sprite tiles that make up the animation frames
     tiles: Vec<AtlasTile>,
+    /// Duration each frame should be displayed (in seconds)
     frame_duration: f32,
+    /// Index of the currently active frame in the tiles vector
     current_frame: usize,
+    /// Accumulated time since the last frame change (for smooth timing)
     time_bank: f32,
 }
 
@@ -25,6 +33,16 @@ impl AnimatedTexture {
         })
     }
 
+    /// Advances the animation by the specified time delta with automatic frame cycling.
+    ///
+    /// Accumulates time in the time bank and progresses through frames when enough
+    /// time has elapsed. Supports frame rates independent of game frame rate by
+    /// potentially advancing multiple frames in a single call if `dt` is large.
+    /// Animation loops automatically when reaching the final frame.
+    ///
+    /// # Arguments
+    ///
+    /// * `dt` - Time elapsed since the last tick (typically frame delta time)
     pub fn tick(&mut self, dt: f32) {
         self.time_bank += dt;
         while self.time_bank >= self.frame_duration {

src/texture/sprite.rs

@@ -8,8 +8,10 @@ use std::collections::HashMap;
 
 use crate::error::TextureError;
 
+/// Atlas frame mapping data loaded from JSON metadata files.
 #[derive(Clone, Debug, Deserialize)]
 pub struct AtlasMapper {
+    /// Mapping from sprite name to frame bounds within the atlas texture
     pub frames: HashMap<String, MapperFrame>,
 }
 
@@ -72,10 +74,19 @@ impl AtlasTile {
     }
 }
 
+/// High-performance sprite atlas providing fast texture region lookups and rendering.
+///
+/// Combines a single large texture with metadata mapping to enable efficient
+/// sprite rendering without texture switching. Caches color modulation state
+/// to minimize redundant SDL2 calls and supports both named sprite lookups
+/// and optional default color modulation configuration.
 pub struct SpriteAtlas {
+    /// The combined texture containing all sprite frames
     texture: Texture<'static>,
+    /// Mapping from sprite names to their pixel coordinates within the texture
     tiles: HashMap<String, MapperFrame>,
     default_color: Option<Color>,
+    /// Cached color modulation state to avoid redundant SDL2 calls
     last_modulation: Option<Color>,
 }
 
@@ -89,6 +100,12 @@ impl SpriteAtlas {
         }
     }
 
+    /// Retrieves a sprite tile by name from the atlas with fast HashMap lookup.
+    ///
+    /// Returns an `AtlasTile` containing the texture coordinates and dimensions
+    /// for the named sprite, or `None` if the sprite name is not found in the
+    /// atlas. The returned tile can be used for immediate rendering or stored
+    /// for repeated use in animations and entity sprites.
     pub fn get_tile(&self, name: &str) -> Option<AtlasTile> {
         self.tiles.get(name).map(|frame| AtlasTile {
             pos: U16Vec2::new(frame.x, frame.y),

src/texture/text.rs

@@ -10,10 +10,20 @@
 //!
 //! ```rust
 //! use pacman::texture::text::TextTexture;
+//! use sdl2::pixels::Color;
 //!
 //! // Create a text texture with 1.0 scale (8x8 pixels per character)
 //! let mut text_renderer = TextTexture::new(1.0);
 //!
+//! // Set default color for all text
+//! text_renderer.set_color(Color::WHITE);
+//!
+//! // Render text with default color
+//! text_renderer.render(&mut canvas, &mut atlas, "Hello", position)?;
+//!
+//! // Render text with specific color
+//! text_renderer.render_with_color(&mut canvas, &mut atlas, "World", position, Color::YELLOW)?;
+//!
 //! // Set scale for larger text
 //! text_renderer.set_scale(2.0);
 //!
@@ -46,6 +56,7 @@
 use anyhow::Result;
 use glam::UVec2;
 
+use sdl2::pixels::Color;
 use sdl2::render::{Canvas, RenderTarget};
 use std::collections::HashMap;
 
@@ -79,6 +90,7 @@ fn char_to_tile_name(c: char) -> Option<String> {
 pub struct TextTexture {
     char_map: HashMap<char, AtlasTile>,
     scale: f32,
+    default_color: Option<Color>,
 }
 
 impl Default for TextTexture {
@@ -86,6 +98,7 @@ impl Default for TextTexture {
         Self {
             scale: 1.0,
             char_map: Default::default(),
+            default_color: None,
         }
     }
 }
@@ -119,13 +132,26 @@ impl TextTexture {
         }
     }
 
-    /// Renders a string of text at the given position.
+    /// Renders a string of text at the given position using the default color.
     pub fn render<C: RenderTarget>(
         &mut self,
         canvas: &mut Canvas<C>,
         atlas: &mut SpriteAtlas,
         text: &str,
         position: UVec2,
+    ) -> Result<()> {
+        let color = self.default_color.unwrap_or(Color::WHITE);
+        self.render_with_color(canvas, atlas, text, position, color)
+    }
+
+    /// Renders a string of text at the given position with a specific color.
+    pub fn render_with_color<C: RenderTarget>(
+        &mut self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut SpriteAtlas,
+        text: &str,
+        position: UVec2,
+        color: Color,
     ) -> Result<()> {
         let mut x_offset = 0;
         let char_width = (8.0 * self.scale) as u32;
@@ -134,9 +160,9 @@ impl TextTexture {
         for c in text.chars() {
             // Get the tile from the char_map, or insert it if it doesn't exist
             if let Some(tile) = self.get_tile(c, atlas)? {
-                // Render the tile if it exists
+                // Render the tile with the specified color
                 let dest = sdl2::rect::Rect::new((position.x + x_offset) as i32, position.y as i32, char_width, char_height);
-                tile.render(canvas, atlas, dest)?;
+                tile.render_with_color(canvas, atlas, dest, color)?;
             }
 
             // Always advance x_offset for all characters (including spaces)
@@ -146,6 +172,16 @@ impl TextTexture {
         Ok(())
     }
 
+    /// Sets the default color for text rendering.
+    pub fn set_color(&mut self, color: Color) {
+        self.default_color = Some(color);
+    }
+
+    /// Gets the current default color.
+    pub fn color(&self) -> Option<Color> {
+        self.default_color
+    }
+
     /// Sets the scale for text rendering.
     pub fn set_scale(&mut self, scale: f32) {
         self.scale = scale;

tests/asset.rs

@@ -1,14 +0,0 @@
-use pacman::asset::Asset;
-use std::path::Path;
-use strum::IntoEnumIterator;
-
-#[test]
-fn test_asset_paths_valid() {
-    let base_path = Path::new("assets/game/");
-
-    for asset in Asset::iter() {
-        let path = base_path.join(asset.path());
-        assert!(path.exists(), "Asset path does not exist: {:?}", path);
-        assert!(path.is_file(), "Asset path is not a file: {:?}", path);
-    }
-}

tests/collision.rs

@@ -0,0 +1,150 @@
+use bevy_ecs::{event::Events, prelude::*, system::RunSystemOnce, world::World};
+
+use pacman::{
+    error::GameError,
+    events::GameEvent,
+    map::builder::Map,
+    systems::{
+        collision::{check_collision, collision_system},
+        components::{Collider, EntityType, Ghost, GhostCollider, ItemCollider, PacmanCollider},
+        movement::Position,
+    },
+};
+
+fn create_test_world() -> World {
+    let mut world = World::new();
+
+    // Add required resources
+    world.insert_resource(Events::<GameEvent>::default());
+    world.insert_resource(Events::<GameError>::default());
+
+    // Add a minimal test map
+    world.insert_resource(create_test_map());
+
+    world
+}
+
+fn create_test_map() -> Map {
+    use pacman::constants::RAW_BOARD;
+    Map::new(RAW_BOARD).expect("Failed to create test map")
+}
+
+fn spawn_test_pacman(world: &mut World) -> Entity {
+    world
+        .spawn((Position::Stopped { node: 0 }, Collider { size: 10.0 }, PacmanCollider))
+        .id()
+}
+
+fn spawn_test_item(world: &mut World) -> Entity {
+    world
+        .spawn((
+            Position::Stopped { node: 0 },
+            Collider { size: 8.0 },
+            ItemCollider,
+            EntityType::Pellet,
+        ))
+        .id()
+}
+
+fn spawn_test_ghost(world: &mut World) -> Entity {
+    world
+        .spawn((
+            Position::Stopped { node: 0 },
+            Collider { size: 12.0 },
+            GhostCollider,
+            Ghost::Blinky,
+            EntityType::Ghost,
+        ))
+        .id()
+}
+
+fn spawn_test_ghost_at_node(world: &mut World, node: usize) -> Entity {
+    world
+        .spawn((
+            Position::Stopped { node },
+            Collider { size: 12.0 },
+            GhostCollider,
+            Ghost::Blinky,
+            EntityType::Ghost,
+        ))
+        .id()
+}
+
+#[test]
+fn test_collider_collision_detection() {
+    let collider1 = Collider { size: 10.0 };
+    let collider2 = Collider { size: 8.0 };
+
+    // Test collision detection
+    assert!(collider1.collides_with(collider2.size, 5.0)); // Should collide (distance < 9.0)
+    assert!(!collider1.collides_with(collider2.size, 15.0)); // Should not collide (distance > 9.0)
+}
+
+#[test]
+fn test_check_collision_helper() {
+    let map = create_test_map();
+    let pos1 = Position::Stopped { node: 0 };
+    let pos2 = Position::Stopped { node: 0 }; // Same position
+    let collider1 = Collider { size: 10.0 };
+    let collider2 = Collider { size: 8.0 };
+
+    // Test collision at same position
+    let result = check_collision(&pos1, &collider1, &pos2, &collider2, &map);
+    assert!(result.is_ok());
+    assert!(result.unwrap()); // Should collide at same position
+
+    // Test collision at different positions
+    let pos3 = Position::Stopped { node: 1 }; // Different position
+    let result = check_collision(&pos1, &collider1, &pos3, &collider2, &map);
+    assert!(result.is_ok());
+    // May or may not collide depending on actual node positions
+}
+
+#[test]
+fn test_collision_system_pacman_item() {
+    let mut world = create_test_world();
+    let _pacman = spawn_test_pacman(&mut world);
+    let _item = spawn_test_item(&mut world);
+
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
+}
+
+#[test]
+fn test_collision_system_pacman_ghost() {
+    let mut world = create_test_world();
+    let _pacman = spawn_test_pacman(&mut world);
+    let _ghost = spawn_test_ghost(&mut world);
+
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
+}
+
+#[test]
+fn test_collision_system_no_collision() {
+    let mut world = create_test_world();
+    let _pacman = spawn_test_pacman(&mut world);
+    let _ghost = spawn_test_ghost_at_node(&mut world, 1); // Different node
+
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
+}
+
+#[test]
+fn test_collision_system_multiple_entities() {
+    let mut world = create_test_world();
+    let _pacman = spawn_test_pacman(&mut world);
+    let _item = spawn_test_item(&mut world);
+    let _ghost = spawn_test_ghost(&mut world);
+
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
+}

tests/common/mod.rs

@@ -28,7 +28,7 @@ pub fn setup_sdl() -> Result<(Canvas<Window>, TextureCreator<WindowContext>, Sdl
 
 pub fn create_atlas(canvas: &mut sdl2::render::Canvas<sdl2::video::Window>) -> SpriteAtlas {
     let texture_creator = canvas.texture_creator();
-    let atlas_bytes = get_asset_bytes(Asset::Atlas).unwrap();
+    let atlas_bytes = get_asset_bytes(Asset::AtlasImage).unwrap();
 
     let texture = texture_creator.load_texture_bytes(&atlas_bytes).unwrap();
     let texture: Texture<'static> = unsafe { std::mem::transmute(texture) };

tests/constants.rs

@@ -2,27 +2,34 @@ use pacman::constants::*;
 
 #[test]
 fn test_raw_board_structure() {
+    // Test board dimensions match expected size
     assert_eq!(RAW_BOARD.len(), BOARD_CELL_SIZE.y as usize);
-
     for row in RAW_BOARD.iter() {
         assert_eq!(row.len(), BOARD_CELL_SIZE.x as usize);
     }
 
-    // Test boundaries
+    // Test boundaries are properly walled
     assert!(RAW_BOARD[0].chars().all(|c| c == '#'));
     assert!(RAW_BOARD[RAW_BOARD.len() - 1].chars().all(|c| c == '#'));
-
-    // Test tunnel row
-    let tunnel_row = RAW_BOARD[14];
-    assert_eq!(tunnel_row.chars().next().unwrap(), 'T');
-    assert_eq!(tunnel_row.chars().last().unwrap(), 'T');
 }
 
 #[test]
-fn test_raw_board_content() {
-    let power_pellet_count = RAW_BOARD.iter().flat_map(|row| row.chars()).filter(|&c| c == 'o').count();
-    assert_eq!(power_pellet_count, 4);
-
-    assert!(RAW_BOARD.iter().any(|row| row.contains('X')));
-    assert!(RAW_BOARD.iter().any(|row| row.contains("==")));
+fn test_raw_board_contains_required_elements() {
+    // Test that essential game elements are present
+    assert!(
+        RAW_BOARD.iter().any(|row| row.contains('X')),
+        "Board should contain Pac-Man start position"
+    );
+    assert!(
+        RAW_BOARD.iter().any(|row| row.contains("==")),
+        "Board should contain ghost house door"
+    );
+    assert!(
+        RAW_BOARD.iter().any(|row| row.chars().any(|c| c == 'T')),
+        "Board should contain tunnel entrances"
+    );
+    assert!(
+        RAW_BOARD.iter().any(|row| row.chars().any(|c| c == 'o')),
+        "Board should contain power pellets"
+    );
 }

tests/debug_rendering.rs

@@ -1,34 +0,0 @@
-use glam::Vec2;
-use pacman::entity::graph::{Graph, Node};
-use pacman::map::render::MapRenderer;
-
-#[test]
-fn test_find_nearest_node() {
-    let mut graph = Graph::new();
-
-    // Add some test nodes
-    let node1 = graph.add_node(Node {
-        position: Vec2::new(10.0, 10.0),
-    });
-    let node2 = graph.add_node(Node {
-        position: Vec2::new(50.0, 50.0),
-    });
-    let node3 = graph.add_node(Node {
-        position: Vec2::new(100.0, 100.0),
-    });
-
-    // Test cursor near node1
-    let cursor_pos = Vec2::new(12.0, 8.0);
-    let nearest = MapRenderer::find_nearest_node(&graph, cursor_pos);
-    assert_eq!(nearest, Some(node1));
-
-    // Test cursor near node2
-    let cursor_pos = Vec2::new(45.0, 55.0);
-    let nearest = MapRenderer::find_nearest_node(&graph, cursor_pos);
-    assert_eq!(nearest, Some(node2));
-
-    // Test cursor near node3
-    let cursor_pos = Vec2::new(98.0, 102.0);
-    let nearest = MapRenderer::find_nearest_node(&graph, cursor_pos);
-    assert_eq!(nearest, Some(node3));
-}

tests/direction.rs

@@ -1,5 +1,5 @@
 use glam::IVec2;
-use pacman::entity::direction::*;
+use pacman::map::direction::*;
 
 #[test]
 fn test_direction_opposite() {

tests/error.rs

@@ -0,0 +1,158 @@
+use pacman::error::{
+    AnimatedTextureError, AssetError, EntityError, GameError, GameResult, IntoGameError, MapError, OptionExt, ParseError,
+    ResultExt, TextureError,
+};
+use std::io;
+
+#[test]
+fn test_game_error_from_asset_error() {
+    let asset_error = AssetError::NotFound("test.png".to_string());
+    let game_error: GameError = asset_error.into();
+    assert!(matches!(game_error, GameError::Asset(_)));
+}
+
+#[test]
+fn test_game_error_from_parse_error() {
+    let parse_error = ParseError::UnknownCharacter('Z');
+    let game_error: GameError = parse_error.into();
+    assert!(matches!(game_error, GameError::MapParse(_)));
+}
+
+#[test]
+fn test_game_error_from_map_error() {
+    let map_error = MapError::NodeNotFound(42);
+    let game_error: GameError = map_error.into();
+    assert!(matches!(game_error, GameError::Map(_)));
+}
+
+#[test]
+fn test_game_error_from_texture_error() {
+    let texture_error = TextureError::LoadFailed("Failed to load".to_string());
+    let game_error: GameError = texture_error.into();
+    assert!(matches!(game_error, GameError::Texture(_)));
+}
+
+#[test]
+fn test_game_error_from_entity_error() {
+    let entity_error = EntityError::NodeNotFound(10);
+    let game_error: GameError = entity_error.into();
+    assert!(matches!(game_error, GameError::Entity(_)));
+}
+
+#[test]
+fn test_game_error_from_io_error() {
+    let io_error = io::Error::new(io::ErrorKind::NotFound, "File not found");
+    let game_error: GameError = io_error.into();
+    assert!(matches!(game_error, GameError::Io(_)));
+}
+
+#[test]
+fn test_texture_error_from_animated_error() {
+    let animated_error = AnimatedTextureError::InvalidFrameDuration(-1.0);
+    let texture_error: TextureError = animated_error.into();
+    assert!(matches!(texture_error, TextureError::Animated(_)));
+}
+
+#[test]
+fn test_asset_error_from_io_error() {
+    let io_error = io::Error::new(io::ErrorKind::PermissionDenied, "Permission denied");
+    let asset_error: AssetError = io_error.into();
+    assert!(matches!(asset_error, AssetError::Io(_)));
+}
+
+#[test]
+fn test_parse_error_display() {
+    let error = ParseError::UnknownCharacter('!');
+    assert_eq!(error.to_string(), "Unknown character in board: !");
+
+    let error = ParseError::InvalidHouseDoorCount(3);
+    assert_eq!(error.to_string(), "House door must have exactly 2 positions, found 3");
+}
+
+#[test]
+fn test_entity_error_display() {
+    let error = EntityError::NodeNotFound(42);
+    assert_eq!(error.to_string(), "Node not found in graph: 42");
+
+    let error = EntityError::EdgeNotFound { from: 1, to: 2 };
+    assert_eq!(error.to_string(), "Edge not found: from 1 to 2");
+}
+
+#[test]
+fn test_animated_texture_error_display() {
+    let error = AnimatedTextureError::InvalidFrameDuration(0.0);
+    assert_eq!(error.to_string(), "Frame duration must be positive, got 0");
+}
+
+#[test]
+fn test_into_game_error_trait() {
+    let result: Result<i32, io::Error> = Err(io::Error::new(io::ErrorKind::Other, "test error"));
+    let game_result: GameResult<i32> = result.into_game_error();
+
+    assert!(game_result.is_err());
+    if let Err(GameError::InvalidState(msg)) = game_result {
+        assert!(msg.contains("test error"));
+    } else {
+        panic!("Expected InvalidState error");
+    }
+}
+
+#[test]
+fn test_into_game_error_trait_success() {
+    let result: Result<i32, io::Error> = Ok(42);
+    let game_result: GameResult<i32> = result.into_game_error();
+
+    assert_eq!(game_result.unwrap(), 42);
+}
+
+#[test]
+fn test_option_ext_some() {
+    let option: Option<i32> = Some(42);
+    let result: GameResult<i32> = option.ok_or_game_error(|| GameError::InvalidState("Not found".to_string()));
+
+    assert_eq!(result.unwrap(), 42);
+}
+
+#[test]
+fn test_option_ext_none() {
+    let option: Option<i32> = None;
+    let result: GameResult<i32> = option.ok_or_game_error(|| GameError::InvalidState("Not found".to_string()));
+
+    assert!(result.is_err());
+    if let Err(GameError::InvalidState(msg)) = result {
+        assert_eq!(msg, "Not found");
+    } else {
+        panic!("Expected InvalidState error");
+    }
+}
+
+#[test]
+fn test_result_ext_success() {
+    let result: Result<i32, io::Error> = Ok(42);
+    let game_result: GameResult<i32> = result.with_context(|_| GameError::InvalidState("Context".to_string()));
+
+    assert_eq!(game_result.unwrap(), 42);
+}
+
+#[test]
+fn test_result_ext_error() {
+    let result: Result<i32, io::Error> = Err(io::Error::new(io::ErrorKind::Other, "original error"));
+    let game_result: GameResult<i32> = result.with_context(|_| GameError::InvalidState("Context error".to_string()));
+
+    assert!(game_result.is_err());
+    if let Err(GameError::InvalidState(msg)) = game_result {
+        assert_eq!(msg, "Context error");
+    } else {
+        panic!("Expected InvalidState error");
+    }
+}
+
+#[test]
+fn test_error_chain_conversions() {
+    // Test that we can convert through multiple levels
+    let animated_error = AnimatedTextureError::InvalidFrameDuration(-5.0);
+    let texture_error: TextureError = animated_error.into();
+    let game_error: GameError = texture_error.into();
+
+    assert!(matches!(game_error, GameError::Texture(TextureError::Animated(_))));
+}

tests/events.rs

@@ -0,0 +1,19 @@
+use pacman::events::{GameCommand, GameEvent};
+use pacman::map::direction::Direction;
+
+#[test]
+fn test_game_command_to_game_event_conversion_all_variants() {
+    let commands = vec![
+        GameCommand::Exit,
+        GameCommand::MovePlayer(Direction::Up),
+        GameCommand::ToggleDebug,
+        GameCommand::MuteAudio,
+        GameCommand::ResetLevel,
+        GameCommand::TogglePause,
+    ];
+
+    for command in commands {
+        let event: GameEvent = command.into();
+        assert_eq!(event, GameEvent::Command(command));
+    }
+}

tests/formatting.rs

@@ -0,0 +1,165 @@
+use pacman::systems::formatting::format_timing_display;
+use std::time::Duration;
+
+use pretty_assertions::assert_eq;
+
+fn get_timing_data() -> Vec<(String, Duration, Duration)> {
+    vec![
+        ("total".to_string(), Duration::from_micros(1234), Duration::from_micros(570)),
+        ("input".to_string(), Duration::from_micros(120), Duration::from_micros(45)),
+        ("player".to_string(), Duration::from_micros(456), Duration::from_micros(123)),
+        ("movement".to_string(), Duration::from_micros(789), Duration::from_micros(234)),
+        ("render".to_string(), Duration::from_micros(12), Duration::from_micros(3)),
+        ("debug".to_string(), Duration::from_nanos(460), Duration::from_nanos(557)),
+    ]
+}
+
+fn get_formatted_output() -> impl IntoIterator<Item = String> {
+    format_timing_display(get_timing_data())
+}
+
+#[test]
+fn test_complex_formatting_alignment() {
+    let mut colon_positions = vec![];
+    let mut first_decimal_positions = vec![];
+    let mut second_decimal_positions = vec![];
+    let mut first_unit_positions = vec![];
+    let mut second_unit_positions = vec![];
+
+    get_formatted_output().into_iter().for_each(|line| {
+        let (mut got_decimal, mut got_unit) = (false, false);
+        for (i, char) in line.chars().enumerate() {
+            match char {
+                ':' => colon_positions.push(i),
+                '.' => {
+                    if got_decimal {
+                        second_decimal_positions.push(i);
+                    } else {
+                        first_decimal_positions.push(i);
+                    }
+                    got_decimal = true;
+                }
+                's' => {
+                    if got_unit {
+                        first_unit_positions.push(i);
+                    } else {
+                        second_unit_positions.push(i);
+                        got_unit = true;
+                    }
+                }
+                _ => {}
+            }
+        }
+    });
+
+    // Assert that all positions were found
+    assert_eq!(
+        [
+            &colon_positions,
+            &first_decimal_positions,
+            &second_decimal_positions,
+            &first_unit_positions,
+            &second_unit_positions
+        ]
+        .iter()
+        .all(|p| p.len() == 6),
+        true
+    );
+
+    // Assert that all positions are the same
+    assert!(
+        colon_positions.iter().all(|&p| p == colon_positions[0]),
+        "colon positions are not the same {:?}",
+        colon_positions
+    );
+    assert!(
+        first_decimal_positions.iter().all(|&p| p == first_decimal_positions[0]),
+        "first decimal positions are not the same {:?}",
+        first_decimal_positions
+    );
+    assert!(
+        second_decimal_positions.iter().all(|&p| p == second_decimal_positions[0]),
+        "second decimal positions are not the same {:?}",
+        second_decimal_positions
+    );
+    assert!(
+        first_unit_positions.iter().all(|&p| p == first_unit_positions[0]),
+        "first unit positions are not the same {:?}",
+        first_unit_positions
+    );
+    assert!(
+        second_unit_positions.iter().all(|&p| p == second_unit_positions[0]),
+        "second unit positions are not the same {:?}",
+        second_unit_positions
+    );
+}
+
+#[test]
+fn test_format_timing_display_basic() {
+    let timing_data = vec![
+        ("render".to_string(), Duration::from_micros(1500), Duration::from_micros(200)),
+        ("input".to_string(), Duration::from_micros(300), Duration::from_micros(50)),
+        ("physics".to_string(), Duration::from_nanos(750), Duration::from_nanos(100)),
+    ];
+
+    let formatted = format_timing_display(timing_data);
+
+    // Should have 3 lines (one for each system)
+    assert_eq!(formatted.len(), 3);
+
+    // Each line should contain the system name
+    assert!(formatted.iter().any(|line| line.contains("render")));
+    assert!(formatted.iter().any(|line| line.contains("input")));
+    assert!(formatted.iter().any(|line| line.contains("physics")));
+
+    // Each line should contain timing information with proper units
+    for line in formatted.iter() {
+        assert!(line.contains(":"), "Line should contain colon separator: {}", line);
+        assert!(line.contains("±"), "Line should contain ± symbol: {}", line);
+    }
+}
+
+#[test]
+fn test_format_timing_display_units() {
+    let timing_data = vec![
+        ("seconds".to_string(), Duration::from_secs(2), Duration::from_millis(100)),
+        ("millis".to_string(), Duration::from_millis(15), Duration::from_micros(200)),
+        ("micros".to_string(), Duration::from_micros(500), Duration::from_nanos(50)),
+        ("nanos".to_string(), Duration::from_nanos(250), Duration::from_nanos(25)),
+    ];
+
+    let formatted = format_timing_display(timing_data);
+
+    // Check that appropriate units are used
+    let all_lines = formatted.join(" ");
+    assert!(all_lines.contains("s"), "Should contain seconds unit");
+    assert!(all_lines.contains("ms"), "Should contain milliseconds unit");
+    assert!(all_lines.contains("µs"), "Should contain microseconds unit");
+    assert!(all_lines.contains("ns"), "Should contain nanoseconds unit");
+}
+
+#[test]
+fn test_format_timing_display_alignment() {
+    let timing_data = vec![
+        ("short".to_string(), Duration::from_micros(100), Duration::from_micros(10)),
+        (
+            "very_long_name".to_string(),
+            Duration::from_micros(200),
+            Duration::from_micros(20),
+        ),
+    ];
+
+    let formatted = format_timing_display(timing_data);
+
+    // Find colon positions - they should be aligned
+    let colon_positions: Vec<usize> = formatted.iter().map(|line| line.find(':').unwrap_or(0)).collect();
+
+    // All colons should be at the same position (aligned)
+    if colon_positions.len() > 1 {
+        let first_pos = colon_positions[0];
+        assert!(
+            colon_positions.iter().all(|&pos| pos == first_pos),
+            "Colons should be aligned at the same position"
+        );
+    }
+}

tests/game.rs

@@ -1,12 +0,0 @@
-use pacman::constants::RAW_BOARD;
-use pacman::map::builder::Map;
-
-mod item;
-
-#[test]
-fn test_game_map_creation() {
-    let map = Map::new(RAW_BOARD).unwrap();
-
-    assert!(map.graph.node_count() > 0);
-    assert!(!map.grid_to_node.is_empty());
-}

tests/graph.rs

@@ -1,5 +1,5 @@
-use pacman::entity::direction::Direction;
-use pacman::entity::graph::{Graph, Node, TraversalFlags};
+use pacman::map::direction::Direction;
+use pacman::map::graph::{Graph, Node, TraversalFlags};
 
 fn create_test_graph() -> Graph {
     let mut graph = Graph::new();
@@ -29,7 +29,7 @@ fn test_graph_basic_operations() {
         position: glam::Vec2::new(16.0, 0.0),
     });
 
-    assert_eq!(graph.node_count(), 2);
+    assert_eq!(graph.nodes().count(), 2);
     assert!(graph.get_node(node1).is_some());
     assert!(graph.get_node(node2).is_some());
     assert!(graph.get_node(999).is_none());
@@ -102,7 +102,7 @@ fn should_add_connected_node() {
         )
         .unwrap();
 
-    assert_eq!(graph.node_count(), 2);
+    assert_eq!(graph.nodes().count(), 2);
     let edge = graph.find_edge(node1, node2);
     assert!(edge.is_some());
     assert_eq!(edge.unwrap().direction, Direction::Right);

tests/helpers.rs

@@ -1,19 +0,0 @@
-use glam::{IVec2, UVec2};
-use pacman::helpers::centered_with_size;
-
-#[test]
-fn test_centered_with_size() {
-    let test_cases = [
-        ((100, 100), (50, 30), (75, 85)),
-        ((50, 50), (51, 31), (25, 35)),
-        ((0, 0), (100, 100), (-50, -50)),
-        ((-100, -50), (80, 40), (-140, -70)),
-        ((1000, 1000), (1000, 1000), (500, 500)),
-    ];
-
-    for ((pos_x, pos_y), (size_x, size_y), (expected_x, expected_y)) in test_cases {
-        let rect = centered_with_size(IVec2::new(pos_x, pos_y), UVec2::new(size_x, size_y));
-        assert_eq!(rect.origin(), (expected_x, expected_y));
-        assert_eq!(rect.size(), (size_x, size_y));
-    }
-}

tests/hud.rs

@@ -0,0 +1,26 @@
+use bevy_ecs::{event::Events, world::World};
+
+use pacman::{error::GameError, systems::components::ScoreResource};
+
+fn create_test_world() -> World {
+    let mut world = World::new();
+
+    // Add required resources
+    world.insert_resource(Events::<GameError>::default());
+    world.insert_resource(ScoreResource(1230)); // Test score
+
+    world
+}
+
+#[test]
+fn test_hud_render_system_runs_without_error() {
+    let world = create_test_world();
+
+    // The HUD render system requires SDL2 resources that aren't available in tests,
+    // but we can at least verify it doesn't panic when called
+    // In a real test environment, we'd need to mock the SDL2 canvas and atlas
+
+    // For now, just verify the score resource is accessible
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, 1230);
+}

tests/input.rs

@@ -0,0 +1,38 @@
+use pacman::events::{GameCommand, GameEvent};
+use pacman::map::direction::Direction;
+use pacman::systems::input::{process_simple_key_events, Bindings, SimpleKeyEvent};
+use sdl2::keyboard::Keycode;
+
+#[test]
+fn resumes_previous_direction_when_secondary_key_released() {
+    let mut bindings = Bindings::default();
+
+    // Frame 1: Press W (Up) => emits Move Up
+    let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::W)]);
+    assert!(events.contains(&GameEvent::Command(GameCommand::MovePlayer(Direction::Up))));
+
+    // Frame 2: Press D (Right) => emits Move Right
+    let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::D)]);
+    assert!(events.contains(&GameEvent::Command(GameCommand::MovePlayer(Direction::Right))));
+
+    // Frame 3: Release D, no new key this frame => should continue previous key W (Up)
+    let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyUp(Keycode::D)]);
+    assert!(events.contains(&GameEvent::Command(GameCommand::MovePlayer(Direction::Up))));
+}
+
+#[test]
+fn holds_last_pressed_key_across_frames_when_no_new_input() {
+    let mut bindings = Bindings::default();
+
+    // Frame 1: Press Left
+    let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::Left)]);
+    assert!(events.contains(&GameEvent::Command(GameCommand::MovePlayer(Direction::Left))));
+
+    // Frame 2: No input => continues Left
+    let events = process_simple_key_events(&mut bindings, &[]);
+    assert!(events.contains(&GameEvent::Command(GameCommand::MovePlayer(Direction::Left))));
+
+    // Frame 3: Release Left, no input remains => nothing emitted
+    let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyUp(Keycode::Left)]);
+    assert!(events.is_empty());
+}

tests/item.rs

@@ -1,46 +1,255 @@
-// use glam::U16Vec2;
-// use pacman::texture::sprite::{AtlasTile, Sprite};
+use bevy_ecs::{event::Events, prelude::*, system::RunSystemOnce, world::World};
 
-// #[test]
-// fn test_item_type_get_score() {
-//     assert_eq!(ItemType::Pellet.get_score(), 10);
-//     assert_eq!(ItemType::Energizer.get_score(), 50);
+use pacman::{
+    events::GameEvent,
+    map::builder::Map,
+    systems::{
+        audio::AudioEvent,
+        components::{AudioState, EntityType, ItemCollider, PacmanCollider, ScoreResource},
+        item::{is_valid_item_collision, item_system},
+        movement::Position,
+    },
+};
 
-//     let fruit = ItemType::Fruit { kind: FruitKind::Apple };
-//     assert_eq!(fruit.get_score(), 100);
-// }
+#[test]
+fn test_calculate_score_for_item() {
+    assert!(EntityType::Pellet.score_value() < EntityType::PowerPellet.score_value());
+    assert!(EntityType::Pellet.score_value().is_some());
+    assert!(EntityType::PowerPellet.score_value().is_some());
+    assert!(EntityType::Player.score_value().is_none());
+    assert!(EntityType::Ghost.score_value().is_none());
+}
 
-// #[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);
+#[test]
+fn test_is_collectible_item() {
+    // Collectible
+    assert!(EntityType::Pellet.is_collectible());
+    assert!(EntityType::PowerPellet.is_collectible());
 
-//     assert_eq!(kinds.len(), FruitKind::COUNT);
+    // Non-collectible
+    assert!(!EntityType::Player.is_collectible());
+    assert!(!EntityType::Ghost.is_collectible());
+}
 
-//     // 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_is_valid_item_collision() {
+    // Player-item collisions should be valid
+    assert!(is_valid_item_collision(EntityType::Player, EntityType::Pellet));
+    assert!(is_valid_item_collision(EntityType::Player, EntityType::PowerPellet));
+    assert!(is_valid_item_collision(EntityType::Pellet, EntityType::Player));
+    assert!(is_valid_item_collision(EntityType::PowerPellet, EntityType::Player));
 
-// #[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);
+    // Non-player-item collisions should be invalid
+    assert!(!is_valid_item_collision(EntityType::Player, EntityType::Ghost));
+    assert!(!is_valid_item_collision(EntityType::Ghost, EntityType::Pellet));
+    assert!(!is_valid_item_collision(EntityType::Pellet, EntityType::PowerPellet));
+    assert!(!is_valid_item_collision(EntityType::Player, EntityType::Player));
+}
 
-//     assert!(!item.is_collected());
-//     assert_eq!(item.get_score(), 10);
-//     assert_eq!(item.position().from_node_id(), 0);
+fn create_test_world() -> World {
+    let mut world = World::new();
 
-//     item.collect();
-//     assert!(item.is_collected());
-// }
+    // Add required resources
+    world.insert_resource(ScoreResource(0));
+    world.insert_resource(AudioState::default());
+    world.insert_resource(Events::<GameEvent>::default());
+    world.insert_resource(Events::<AudioEvent>::default());
+    world.insert_resource(Events::<pacman::error::GameError>::default());
+
+    // Add a minimal test map
+    world.insert_resource(create_test_map());
+
+    world
+}
+
+fn create_test_map() -> Map {
+    use pacman::constants::RAW_BOARD;
+    Map::new(RAW_BOARD).expect("Failed to create test map")
+}
+
+fn spawn_test_pacman(world: &mut World) -> Entity {
+    world
+        .spawn((Position::Stopped { node: 0 }, EntityType::Player, PacmanCollider))
+        .id()
+}
+
+fn spawn_test_item(world: &mut World, item_type: EntityType) -> Entity {
+    world.spawn((Position::Stopped { node: 1 }, item_type, ItemCollider)).id()
+}
+
+fn send_collision_event(world: &mut World, entity1: Entity, entity2: Entity) {
+    let mut events = world.resource_mut::<Events<GameEvent>>();
+    events.send(GameEvent::Collision(entity1, entity2));
+}
+
+#[test]
+fn test_item_system_pellet_collection() {
+    let mut world = create_test_world();
+    let pacman = spawn_test_pacman(&mut world);
+    let pellet = spawn_test_item(&mut world, EntityType::Pellet);
+
+    // Send collision event
+    send_collision_event(&mut world, pacman, pellet);
+
+    // Run the item system
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check that score was updated
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, 10);
+
+    // Check that the pellet was despawned (query should return empty)
+    let item_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Pellet))
+        .count();
+    assert_eq!(item_count, 0);
+}
+
+#[test]
+fn test_item_system_power_pellet_collection() {
+    let mut world = create_test_world();
+    let pacman = spawn_test_pacman(&mut world);
+    let power_pellet = spawn_test_item(&mut world, EntityType::PowerPellet);
+
+    send_collision_event(&mut world, pacman, power_pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check that score was updated with power pellet value
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, 50);
+
+    // Check that the power pellet was despawned (query should return empty)
+    let item_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::PowerPellet))
+        .count();
+    assert_eq!(item_count, 0);
+}
+
+#[test]
+fn test_item_system_multiple_collections() {
+    let mut world = create_test_world();
+    let pacman = spawn_test_pacman(&mut world);
+    let pellet1 = spawn_test_item(&mut world, EntityType::Pellet);
+    let pellet2 = spawn_test_item(&mut world, EntityType::Pellet);
+    let power_pellet = spawn_test_item(&mut world, EntityType::PowerPellet);
+
+    // Send multiple collision events
+    send_collision_event(&mut world, pacman, pellet1);
+    send_collision_event(&mut world, pacman, pellet2);
+    send_collision_event(&mut world, pacman, power_pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check final score: 2 pellets (20) + 1 power pellet (50) = 70
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, 70);
+
+    // Check that all items were despawned
+    let pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Pellet))
+        .count();
+    let power_pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::PowerPellet))
+        .count();
+    assert_eq!(pellet_count, 0);
+    assert_eq!(power_pellet_count, 0);
+}
+
+#[test]
+fn test_item_system_ignores_non_item_collisions() {
+    let mut world = create_test_world();
+    let pacman = spawn_test_pacman(&mut world);
+
+    // Create a ghost entity (not an item)
+    let ghost = world.spawn((Position::Stopped { node: 2 }, EntityType::Ghost)).id();
+
+    // Initial score
+    let initial_score = world.resource::<ScoreResource>().0;
+
+    // Send collision event between pacman and ghost
+    send_collision_event(&mut world, pacman, ghost);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Score should remain unchanged
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, initial_score);
+
+    // Ghost should still exist (not despawned)
+    let ghost_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Ghost))
+        .count();
+    assert_eq!(ghost_count, 1);
+}
+
+#[test]
+fn test_item_system_no_collision_events() {
+    let mut world = create_test_world();
+    let _pacman = spawn_test_pacman(&mut world);
+    let _pellet = spawn_test_item(&mut world, EntityType::Pellet);
+
+    let initial_score = world.resource::<ScoreResource>().0;
+
+    // Run system without any collision events
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Nothing should change
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, initial_score);
+    let pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Pellet))
+        .count();
+    assert_eq!(pellet_count, 1);
+}
+
+#[test]
+fn test_item_system_collision_with_missing_entity() {
+    let mut world = create_test_world();
+    let pacman = spawn_test_pacman(&mut world);
+
+    // Create a fake entity ID that doesn't exist
+    let fake_entity = Entity::from_raw(999);
+
+    send_collision_event(&mut world, pacman, fake_entity);
+
+    // System should handle gracefully and not crash
+    world
+        .run_system_once(item_system)
+        .expect("System should handle missing entities gracefully");
+
+    // Score should remain unchanged
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, 0);
+}
+
+#[test]
+fn test_item_system_preserves_existing_score() {
+    let mut world = create_test_world();
+
+    // Set initial score
+    world.insert_resource(ScoreResource(100));
+
+    let pacman = spawn_test_pacman(&mut world);
+    let pellet = spawn_test_item(&mut world, EntityType::Pellet);
+
+    send_collision_event(&mut world, pacman, pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Score should be initial + pellet value
+    let score = world.resource::<ScoreResource>();
+    assert_eq!(score.0, 110);
+}

tests/map_builder.rs

@@ -6,7 +6,7 @@ use pacman::map::builder::Map;
 fn test_map_creation() {
     let map = Map::new(RAW_BOARD).unwrap();
 
-    assert!(map.graph.node_count() > 0);
+    assert!(map.graph.nodes().count() > 0);
     assert!(!map.grid_to_node.is_empty());
 
     // Check that some connections were made

tests/movement.rs

@@ -0,0 +1,195 @@
+use glam::Vec2;
+use pacman::map::direction::Direction;
+use pacman::map::graph::{Graph, Node};
+use pacman::systems::movement::{BufferedDirection, Position, Velocity};
+
+fn create_test_graph() -> Graph {
+    let mut graph = Graph::new();
+
+    // Add a few test nodes
+    let node0 = graph.add_node(Node {
+        position: Vec2::new(0.0, 0.0),
+    });
+    let node1 = graph.add_node(Node {
+        position: Vec2::new(16.0, 0.0),
+    });
+    let node2 = graph.add_node(Node {
+        position: Vec2::new(0.0, 16.0),
+    });
+
+    // Connect them
+    graph.connect(node0, node1, false, None, Direction::Right).unwrap();
+    graph.connect(node0, node2, false, None, Direction::Down).unwrap();
+
+    graph
+}
+
+#[test]
+fn test_position_is_at_node() {
+    let stopped_pos = Position::Stopped { node: 0 };
+    let moving_pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 8.0,
+    };
+
+    assert!(stopped_pos.is_at_node());
+    assert!(!moving_pos.is_at_node());
+}
+
+#[test]
+fn test_position_current_node() {
+    let stopped_pos = Position::Stopped { node: 5 };
+    let moving_pos = Position::Moving {
+        from: 3,
+        to: 7,
+        remaining_distance: 12.0,
+    };
+
+    assert_eq!(stopped_pos.current_node(), 5);
+    assert_eq!(moving_pos.current_node(), 3);
+}
+
+#[test]
+fn test_position_tick_no_movement_when_stopped() {
+    let mut pos = Position::Stopped { node: 0 };
+    let result = pos.tick(5.0);
+
+    assert!(result.is_none());
+    assert_eq!(pos, Position::Stopped { node: 0 });
+}
+
+#[test]
+fn test_position_tick_no_movement_when_zero_distance() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 10.0,
+    };
+    let result = pos.tick(0.0);
+
+    assert!(result.is_none());
+    assert_eq!(
+        pos,
+        Position::Moving {
+            from: 0,
+            to: 1,
+            remaining_distance: 10.0,
+        }
+    );
+}
+
+#[test]
+fn test_position_tick_partial_movement() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 10.0,
+    };
+    let result = pos.tick(3.0);
+
+    assert!(result.is_none());
+    assert_eq!(
+        pos,
+        Position::Moving {
+            from: 0,
+            to: 1,
+            remaining_distance: 7.0,
+        }
+    );
+}
+
+#[test]
+fn test_position_tick_exact_arrival() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 5.0,
+    };
+    let result = pos.tick(5.0);
+
+    assert!(result.is_none());
+    assert_eq!(pos, Position::Stopped { node: 1 });
+}
+
+#[test]
+fn test_position_tick_overshoot_with_overflow() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 3.0,
+    };
+    let result = pos.tick(8.0);
+
+    assert_eq!(result, Some(5.0));
+    assert_eq!(pos, Position::Stopped { node: 1 });
+}
+
+#[test]
+fn test_position_get_pixel_position_stopped() {
+    let graph = create_test_graph();
+    let pos = Position::Stopped { node: 0 };
+
+    let pixel_pos = pos.get_pixel_position(&graph).unwrap();
+    let expected = Vec2::new(
+        0.0 + pacman::constants::BOARD_PIXEL_OFFSET.x as f32,
+        0.0 + pacman::constants::BOARD_PIXEL_OFFSET.y as f32,
+    );
+
+    assert_eq!(pixel_pos, expected);
+}
+
+#[test]
+fn test_position_get_pixel_position_moving() {
+    let graph = create_test_graph();
+    let pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 8.0, // Halfway through a 16-unit edge
+    };
+
+    let pixel_pos = pos.get_pixel_position(&graph).unwrap();
+    // Should be halfway between (0,0) and (16,0), so at (8,0) plus offset
+    let expected = Vec2::new(
+        8.0 + pacman::constants::BOARD_PIXEL_OFFSET.x as f32,
+        0.0 + pacman::constants::BOARD_PIXEL_OFFSET.y as f32,
+    );
+
+    assert_eq!(pixel_pos, expected);
+}
+
+#[test]
+fn test_velocity_basic_properties() {
+    let velocity = Velocity {
+        speed: 2.5,
+        direction: Direction::Up,
+    };
+
+    assert_eq!(velocity.speed, 2.5);
+    assert_eq!(velocity.direction, Direction::Up);
+}
+
+#[test]
+fn test_buffered_direction_none() {
+    let buffered = BufferedDirection::None;
+    assert_eq!(buffered, BufferedDirection::None);
+}
+
+#[test]
+fn test_buffered_direction_some() {
+    let buffered = BufferedDirection::Some {
+        direction: Direction::Left,
+        remaining_time: 0.5,
+    };
+
+    if let BufferedDirection::Some {
+        direction,
+        remaining_time,
+    } = buffered
+    {
+        assert_eq!(direction, Direction::Left);
+        assert_eq!(remaining_time, 0.5);
+    } else {
+        panic!("Expected BufferedDirection::Some");
+    }
+}

tests/player.rs

@@ -0,0 +1,576 @@
+use bevy_ecs::{event::Events, prelude::*, system::RunSystemOnce, world::World};
+
+use pacman::{
+    events::{GameCommand, GameEvent},
+    map::{
+        builder::Map,
+        direction::Direction,
+        graph::{Edge, TraversalFlags},
+    },
+    systems::{
+        components::{AudioState, DeltaTime, EntityType, GlobalState, PlayerControlled},
+        debug::DebugState,
+        movement::{BufferedDirection, Position, Velocity},
+        player::{can_traverse, player_control_system, player_movement_system},
+    },
+};
+
+// Test helper functions for ECS setup
+fn create_test_world() -> World {
+    let mut world = World::new();
+
+    // Add resources
+    world.insert_resource(GlobalState { exit: false });
+    world.insert_resource(DebugState::default());
+    world.insert_resource(AudioState::default());
+    world.insert_resource(DeltaTime(1.0 / 60.0)); // 60 FPS
+    world.insert_resource(Events::<GameEvent>::default());
+    world.insert_resource(Events::<pacman::error::GameError>::default());
+
+    // Create a simple test map with nodes and edges
+    let test_map = create_test_map();
+    world.insert_resource(test_map);
+
+    world
+}
+
+fn create_test_map() -> Map {
+    // Use the actual RAW_BOARD from constants.rs
+    use pacman::constants::RAW_BOARD;
+    Map::new(RAW_BOARD).expect("Failed to create test map")
+}
+
+fn spawn_test_player(world: &mut World) -> Entity {
+    world
+        .spawn((
+            PlayerControlled,
+            Position::Stopped { node: 0 },
+            Velocity {
+                speed: 1.0,
+                direction: Direction::Right,
+            },
+            BufferedDirection::None,
+            EntityType::Player,
+        ))
+        .id()
+}
+
+fn send_game_event(world: &mut World, command: GameCommand) {
+    let mut events = world.resource_mut::<Events<GameEvent>>();
+    events.send(GameEvent::Command(command));
+}
+
+#[test]
+fn test_can_traverse_player_on_all_edges() {
+    let edge = Edge {
+        target: 1,
+        distance: 10.0,
+        direction: Direction::Up,
+        traversal_flags: TraversalFlags::ALL,
+    };
+
+    assert!(can_traverse(EntityType::Player, edge));
+}
+
+#[test]
+fn test_can_traverse_player_on_pacman_only_edges() {
+    let edge = Edge {
+        target: 1,
+        distance: 10.0,
+        direction: Direction::Right,
+        traversal_flags: TraversalFlags::PACMAN,
+    };
+
+    assert!(can_traverse(EntityType::Player, edge));
+}
+
+#[test]
+fn test_can_traverse_player_blocked_on_ghost_only_edges() {
+    let edge = Edge {
+        target: 1,
+        distance: 10.0,
+        direction: Direction::Left,
+        traversal_flags: TraversalFlags::GHOST,
+    };
+
+    assert!(!can_traverse(EntityType::Player, edge));
+}
+
+#[test]
+fn test_can_traverse_ghost_on_all_edges() {
+    let edge = Edge {
+        target: 2,
+        distance: 15.0,
+        direction: Direction::Down,
+        traversal_flags: TraversalFlags::ALL,
+    };
+
+    assert!(can_traverse(EntityType::Ghost, edge));
+}
+
+#[test]
+fn test_can_traverse_ghost_on_ghost_only_edges() {
+    let edge = Edge {
+        target: 2,
+        distance: 15.0,
+        direction: Direction::Up,
+        traversal_flags: TraversalFlags::GHOST,
+    };
+
+    assert!(can_traverse(EntityType::Ghost, edge));
+}
+
+#[test]
+fn test_can_traverse_ghost_blocked_on_pacman_only_edges() {
+    let edge = Edge {
+        target: 2,
+        distance: 15.0,
+        direction: Direction::Right,
+        traversal_flags: TraversalFlags::PACMAN,
+    };
+
+    assert!(!can_traverse(EntityType::Ghost, edge));
+}
+
+#[test]
+fn test_can_traverse_static_entities_flags() {
+    let edge = Edge {
+        target: 3,
+        distance: 8.0,
+        direction: Direction::Left,
+        traversal_flags: TraversalFlags::ALL,
+    };
+
+    // Static entities have empty traversal flags but can still "traverse"
+    // in the sense that empty flags are contained in any flag set
+    // This is the expected behavior since empty ⊆ any set
+    assert!(can_traverse(EntityType::Pellet, edge));
+    assert!(can_traverse(EntityType::PowerPellet, edge));
+}
+
+#[test]
+fn test_entity_type_traversal_flags() {
+    assert_eq!(EntityType::Player.traversal_flags(), TraversalFlags::PACMAN);
+    assert_eq!(EntityType::Ghost.traversal_flags(), TraversalFlags::GHOST);
+    assert_eq!(EntityType::Pellet.traversal_flags(), TraversalFlags::empty());
+    assert_eq!(EntityType::PowerPellet.traversal_flags(), TraversalFlags::empty());
+}
+
+// ============================================================================
+// ECS System Tests
+// ============================================================================
+
+#[test]
+fn test_player_control_system_move_command() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send move command
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Up));
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that buffered direction was updated
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+
+    match *buffered_direction {
+        BufferedDirection::Some {
+            direction,
+            remaining_time,
+        } => {
+            assert_eq!(direction, Direction::Up);
+            assert_eq!(remaining_time, 0.25);
+        }
+        BufferedDirection::None => panic!("Expected buffered direction to be set"),
+    }
+}
+
+#[test]
+fn test_player_control_system_exit_command() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send exit command
+    send_game_event(&mut world, GameCommand::Exit);
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that exit flag was set
+    let state = world.resource::<GlobalState>();
+    assert!(state.exit);
+}
+
+#[test]
+fn test_player_control_system_toggle_debug() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send toggle debug command
+    send_game_event(&mut world, GameCommand::ToggleDebug);
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that debug state changed
+    let debug_state = world.resource::<DebugState>();
+    assert!(debug_state.enabled);
+}
+
+#[test]
+fn test_player_control_system_mute_audio() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send mute audio command
+    send_game_event(&mut world, GameCommand::MuteAudio);
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that audio was muted
+    let audio_state = world.resource::<AudioState>();
+    assert!(audio_state.muted);
+
+    // Send mute audio command again to unmute - need fresh events
+    world.resource_mut::<Events<GameEvent>>().clear(); // Clear previous events
+    send_game_event(&mut world, GameCommand::MuteAudio);
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that audio was unmuted
+    let audio_state = world.resource::<AudioState>();
+    assert!(!audio_state.muted, "Audio should be unmuted after second toggle");
+}
+
+#[test]
+fn test_player_control_system_no_player_entity() {
+    let mut world = create_test_world();
+    // Don't spawn a player entity
+
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Up));
+
+    // Run the system - should write an error
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that an error was written (we can't easily check Events without manual management,
+    // so for this test we just verify the system ran without panicking)
+    // In a real implementation, you might expose error checking through the ECS world
+}
+
+#[test]
+fn test_player_movement_system_buffered_direction_expires() {
+    let mut world = create_test_world();
+    let player = spawn_test_player(&mut world);
+
+    // Set a buffered direction with short time
+    world.entity_mut(player).insert(BufferedDirection::Some {
+        direction: Direction::Up,
+        remaining_time: 0.01, // Very short time
+    });
+
+    // Set delta time to expire the buffered direction
+    world.insert_resource(DeltaTime(0.02));
+
+    // Run the system
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that buffered direction expired or remaining time decreased significantly
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+    match *buffered_direction {
+        BufferedDirection::None => {} // Expected - fully expired
+        BufferedDirection::Some { remaining_time, .. } => {
+            assert!(
+                remaining_time <= 0.0,
+                "Buffered direction should be expired or have non-positive time"
+            );
+        }
+    }
+}
+
+#[test]
+fn test_player_movement_system_start_moving_from_stopped() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Player starts at node 0, facing right (towards node 1)
+    // Should start moving when system runs
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that player started moving
+    let mut query = world.query::<&Position>();
+    let position = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { from, .. } => {
+            assert_eq!(from, 0, "Player should start from node 0");
+            // Don't assert exact target node since the real map has different connectivity
+        }
+        Position::Stopped { .. } => {} // May stay stopped if no valid edge in current direction
+    }
+}
+
+#[test]
+fn test_player_movement_system_buffered_direction_change() {
+    let mut world = create_test_world();
+    let player = spawn_test_player(&mut world);
+
+    // Set a buffered direction to go down (towards node 2)
+    world.entity_mut(player).insert(BufferedDirection::Some {
+        direction: Direction::Down,
+        remaining_time: 1.0,
+    });
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that player started moving down instead of right
+    let mut query = world.query::<(&Position, &Velocity, &BufferedDirection)>();
+    let (position, _velocity, _buffered_direction) = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { from, to, .. } => {
+            assert_eq!(from, 0);
+            assert_eq!(to, 2); // Should be moving to node 2 (down)
+        }
+        Position::Stopped { .. } => panic!("Player should have started moving"),
+    }
+
+    // Check if the movement actually happened based on the real map connectivity
+    // The buffered direction might not be consumed if there's no valid edge in that direction
+}
+
+#[test]
+fn test_player_movement_system_no_valid_edge() {
+    let mut world = create_test_world();
+    let player = spawn_test_player(&mut world);
+
+    // Set velocity to direction with no edge
+    world.entity_mut(player).insert(Velocity {
+        speed: 1.0,
+        direction: Direction::Up, // No edge up from node 0
+    });
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Player should remain stopped
+    let mut query = world.query::<&Position>();
+    let position = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Stopped { node } => assert_eq!(node, 0),
+        Position::Moving { .. } => panic!("Player shouldn't be able to move without valid edge"),
+    }
+}
+
+#[test]
+fn test_player_movement_system_continue_moving() {
+    let mut world = create_test_world();
+    let player = spawn_test_player(&mut world);
+
+    // Set player to already be moving
+    world.entity_mut(player).insert(Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 50.0,
+    });
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that player continued moving and distance decreased
+    let mut query = world.query::<&Position>();
+    let position = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { remaining_distance, .. } => {
+            assert!(remaining_distance < 50.0); // Should have moved
+        }
+        Position::Stopped { .. } => {
+            // If player reached destination, that's also valid
+        }
+    }
+}
+
+// ============================================================================
+// Integration Tests
+// ============================================================================
+
+#[test]
+fn test_full_player_input_to_movement_flow() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send move command
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Down));
+
+    // Run control system to process input
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Run movement system to execute movement
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check final state - player should be moving down
+    let mut query = world.query::<(&Position, &Velocity, &BufferedDirection)>();
+    let (position, _velocity, _buffered_direction) = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { from, to, .. } => {
+            assert_eq!(from, 0);
+            assert_eq!(to, 2); // Moving to node 2 (down)
+        }
+        Position::Stopped { .. } => panic!("Player should be moving"),
+    }
+
+    // Check that player moved in the buffered direction if possible
+    // In the real map, the buffered direction may not be consumable if there's no valid edge
+}
+
+#[test]
+fn test_buffered_direction_timing() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send move command
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Up));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Run movement system multiple times with small delta times
+    world.insert_resource(DeltaTime(0.1)); // 0.1 seconds
+
+    // First run - buffered direction should still be active
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+
+    match *buffered_direction {
+        BufferedDirection::Some { remaining_time, .. } => {
+            assert!(remaining_time > 0.0);
+            assert!(remaining_time < 0.25);
+        }
+        BufferedDirection::None => panic!("Buffered direction should still be active"),
+    }
+
+    // Run again to fully expire the buffered direction
+    world.insert_resource(DeltaTime(0.2)); // Total 0.3 seconds, should expire
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    let buffered_direction = query.single(&world).expect("Player should exist");
+    assert_eq!(*buffered_direction, BufferedDirection::None);
+}
+
+#[test]
+fn test_multiple_rapid_direction_changes() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Send multiple rapid direction changes
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Up));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Down));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Left));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Only the last direction should be buffered
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+
+    match *buffered_direction {
+        BufferedDirection::Some { direction, .. } => {
+            assert_eq!(direction, Direction::Left);
+        }
+        BufferedDirection::None => panic!("Expected buffered direction"),
+    }
+}
+
+#[test]
+fn test_player_state_persistence_across_systems() {
+    let mut world = create_test_world();
+    let _player = spawn_test_player(&mut world);
+
+    // Test that multiple commands can be processed - but need to handle events properly
+    // Clear any existing events first
+    world.resource_mut::<Events<GameEvent>>().clear();
+
+    // Toggle debug mode
+    send_game_event(&mut world, GameCommand::ToggleDebug);
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+    let debug_state_after_toggle = *world.resource::<DebugState>();
+
+    // Clear events and mute audio
+    world.resource_mut::<Events<GameEvent>>().clear();
+    send_game_event(&mut world, GameCommand::MuteAudio);
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+    let audio_muted_after_toggle = world.resource::<AudioState>().muted;
+
+    // Clear events and move player
+    world.resource_mut::<Events<GameEvent>>().clear();
+    send_game_event(&mut world, GameCommand::MovePlayer(Direction::Down));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that all state changes persisted
+    // Variables already captured above during individual tests
+    let mut query = world.query::<&Position>();
+    let position = *query.single(&world).expect("Player should exist");
+
+    // Check that the state changes persisted individually
+    assert!(debug_state_after_toggle.enabled, "Debug state should have toggled");
+    assert!(audio_muted_after_toggle, "Audio should be muted");
+
+    // Player position depends on actual map connectivity
+    match position {
+        Position::Moving { .. } => {}  // Good - player is moving
+        Position::Stopped { .. } => {} // Also ok - might not have valid edge in that direction
+    }
+}

tests/profiling.rs

@@ -0,0 +1,40 @@
+use pacman::systems::profiling::{SystemId, SystemTimings};
+use std::time::Duration;
+
+#[test]
+fn test_timing_statistics() {
+    let timings = SystemTimings::default();
+
+    // Add some test data
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(10));
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(12));
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(8));
+
+    let stats = timings.get_stats();
+    let (avg, std_dev) = stats.get(&SystemId::PlayerControls).unwrap();
+
+    // Average should be 10ms, standard deviation should be small
+    assert!((avg.as_millis() as f64 - 10.0).abs() < 1.0);
+    assert!(std_dev.as_millis() > 0);
+
+    let (total_avg, total_std) = timings.get_total_stats();
+    assert!((total_avg.as_millis() as f64 - 10.0).abs() < 1.0);
+    assert!(total_std.as_millis() > 0);
+}
+
+// #[test]
+// fn test_window_size_limit() {
+//     let timings = SystemTimings::default();
+
+//     // Add more than 90 timings to test window size limit
+//     for i in 0..100 {
+//         timings.add_timing("test_system", Duration::from_millis(i));
+//     }
+
+//     let stats = timings.get_stats();
+//     let (avg, _) = stats.get("test_system").unwrap();
+
+//     // Should only keep the last 90 values, so average should be around 55ms
+//     // (average of 10-99)
+//     assert!((avg.as_millis() as f64 - 55.0).abs() < 5.0);
+// }

tests/text.rs

@@ -107,3 +107,23 @@ fn test_text_scale() -> Result<(), String> {
 
     Ok(())
 }
+
+#[test]
+fn test_text_color() -> Result<(), String> {
+    let mut text_texture = TextTexture::new(1.0);
+
+    // Test default color (should be None initially)
+    assert_eq!(text_texture.color(), None);
+
+    // Test setting color
+    let test_color = sdl2::pixels::Color::YELLOW;
+    text_texture.set_color(test_color);
+    assert_eq!(text_texture.color(), Some(test_color));
+
+    // Test changing color
+    let new_color = sdl2::pixels::Color::RED;
+    text_texture.set_color(new_color);
+    assert_eq!(text_texture.color(), Some(new_color));
+
+    Ok(())
+}

web.build.ts

@@ -1,7 +1,7 @@
 import { $ } from "bun";
 import { existsSync, promises as fs } from "fs";
 import { platform } from "os";
-import { dirname, join, relative, resolve } from "path";
+import { basename, dirname, join, relative, resolve } from "path";
 import { match, P } from "ts-pattern";
 import { configure, getConsoleSink, getLogger } from "@logtape/logtape";
 
@@ -79,16 +79,19 @@ async function build(release: boolean, env: Record<string, string> | null) {
 
   // The files to copy into 'dist'
   const files = [
-    ...["index.html", "favicon.ico", "build.css", "TerminalVector.ttf"].map(
-      (file) => ({
-        src: join(siteFolder, file),
-        dest: join(dist, file),
+    ...[
+      "index.html",
+      "favicon.ico",
+      "build.css",
+      "../game/TerminalVector.ttf",
+    ].map((file) => ({
+      src: resolve(join(siteFolder, file)),
+      dest: join(dist, basename(file)),
       optional: false,
-      })
-    ),
+    })),
     ...["pacman.wasm", "pacman.js", "deps/pacman.data"].map((file) => ({
       src: join(outputFolder, file),
-      dest: join(dist, file.split("/").pop() || file),
+      dest: join(dist, basename(file)),
       optional: false,
     })),
     {