feat: add cursor-based node highlighting for debug

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

@@ -5,14 +5,12 @@ 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;
 
 pub struct App {
     pub game: Game,
@@ -110,17 +108,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/entity/graph.rs

@@ -223,6 +223,19 @@ impl Graph {
         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.
     pub fn find_edge(&self, from: NodeId, to: NodeId) -> Option<Edge> {
         self.adjacency_list.get(from)?.edges().find(|edge| edge.target == to)

src/game/mod.rs

@@ -8,23 +8,35 @@ 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::movement::{BufferedDirection, Position, Velocity};
+use crate::systems::player::player_movement_system;
+use crate::systems::profiling::SystemId;
 use crate::systems::{
+    audio::{audio_system, AudioEvent, AudioResource},
     blinking::blinking_system,
     collision::collision_system,
     components::{
-        Collider, CollisionLayer, DeltaTime, DirectionalAnimated, EntityType, GlobalState, ItemBundle, ItemCollider,
-        PacmanCollider, PlayerBundle, PlayerControlled, Renderable, Score, ScoreResource,
+        AudioState, Collider, DeltaTime, DirectionalAnimated, EntityType, Ghost, GhostBundle, GhostCollider, GlobalState,
+        ItemBundle, ItemCollider, PacmanCollider, PlayerBundle, PlayerControlled, RenderDirty, Renderable, ScoreResource,
     },
-    control::player_system,
+    debug::{debug_render_system, DebugState, DebugTextureResource},
+    ghost::ghost_movement_system,
     input::input_system,
-    movement::movement_system,
+    item::item_system,
+    player::player_control_system,
     profiling::{profile, SystemTimings},
-    render::{directional_render_system, render_system, BackbufferResource, MapTextureResource},
+    render::{directional_render_system, dirty_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 bevy_ecs::system::NonSendMut;
+use bevy_ecs::{
+    event::EventRegistry,
+    observer::Trigger,
+    schedule::Schedule,
+    system::{Res, ResMut},
+    world::World,
+};
 use sdl2::image::LoadTexture;
 use sdl2::render::{Canvas, ScaleMode, TextureCreator};
 use sdl2::video::{Window, WindowContext};
@@ -35,7 +47,7 @@ use crate::{
     constants,
     events::GameCommand,
     map::render::MapRenderer,
-    systems::input::Bindings,
+    systems::{debug::CursorPosition, input::Bindings},
     texture::sprite::{AtlasMapper, SpriteAtlas},
 };
 
@@ -61,6 +73,7 @@ impl Game {
 
         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)
@@ -72,6 +85,16 @@ impl Game {
             .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);
+
+        // Initialize audio system
+        let audio = crate::audio::Audio::new();
+
         // 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| {
@@ -100,7 +123,7 @@ impl Game {
         // Render map to texture
         canvas
             .with_texture_canvas(&mut map_texture, |map_canvas| {
-                MapRenderer::render_map(map_canvas, &mut atlas, &mut map_tiles);
+                MapRenderer::render_map(map_canvas, &mut atlas, &map_tiles);
             })
             .map_err(|e| GameError::Sdl(e.to_string()))?;
 
@@ -135,16 +158,12 @@ impl Game {
 
         let player = PlayerBundle {
             player: PlayerControlled,
-            position: Position {
-                node: pacman_start_node,
-                edge_progress: None,
-            },
-            movement_state: MovementState::Stopped,
-            movable: Movable {
+            position: Position::Stopped { node: pacman_start_node },
+            velocity: Velocity {
                 speed: 1.15,
-                current_direction: Direction::Left,
-                requested_direction: Some(Direction::Left), // Start moving left immediately
+                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())))?,
@@ -157,8 +176,7 @@ impl Game {
             },
             entity_type: EntityType::Player,
             collider: Collider {
-                size: constants::CELL_SIZE as f32 * 1.25,
-                layer: CollisionLayer::PACMAN,
+                size: constants::CELL_SIZE as f32 * 1.375,
             },
             pacman_collider: PacmanCollider,
         };
@@ -168,6 +186,8 @@ impl Game {
         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(AudioResource(audio));
 
         world.insert_resource(map);
         world.insert_resource(GlobalState { exit: false });
@@ -175,28 +195,49 @@ impl Game {
         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.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) => {}
+            |event: Trigger<GameEvent>, mut state: ResMut<GlobalState>, _score: ResMut<ScoreResource>| {
+                if matches!(*event, GameEvent::Command(GameCommand::Exit)) {
+                    state.exit = true;
+                }
             },
         );
-
         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),
-                profile("render", render_system),
+                profile(SystemId::Input, input_system),
+                profile(SystemId::PlayerControls, player_control_system),
+                profile(SystemId::PlayerMovement, player_movement_system),
+                profile(SystemId::Ghost, ghost_movement_system),
+                profile(SystemId::Collision, collision_system),
+                profile(SystemId::Item, item_system),
+                profile(SystemId::Audio, audio_system),
+                profile(SystemId::Blinking, blinking_system),
+                profile(SystemId::DirectionalRender, directional_render_system),
+                profile(SystemId::DirtyRender, dirty_render_system),
+                profile(SystemId::Render, render_system),
+                profile(SystemId::DebugRender, debug_render_system),
+                profile(
+                    SystemId::Present,
+                    |mut canvas: NonSendMut<&mut Canvas<Window>>,
+                     backbuffer: NonSendMut<BackbufferResource>,
+                     debug_state: Res<DebugState>,
+                     mut dirty: ResMut<RenderDirty>| {
+                        if dirty.0 || *debug_state != DebugState::Off {
+                            // Only copy backbuffer to main canvas if debug rendering is off
+                            // (debug rendering draws directly to main canvas)
+                            if *debug_state == DebugState::Off {
+                                canvas.copy(&backbuffer.0, None, None).unwrap();
+                            }
+                            dirty.0 = false;
+                            canvas.present();
+                        }
+                    },
+                ),
             )
                 .chain(),
         );
@@ -204,6 +245,9 @@ impl Game {
         // Spawn player
         world.spawn(player);
 
+        // 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())))?;
@@ -213,33 +257,23 @@ impl Game {
         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,
-                ),
+            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 {
-                    node: node_id,
-                    edge_progress: None,
-                },
+                position: Position::Stopped { node: node_id },
                 sprite: Renderable {
                     sprite,
                     layer: 1,
                     visible: true,
                 },
                 entity_type: item_type,
-                score: Score(score),
-                collider: Collider {
-                    size,
-                    layer: CollisionLayer::ITEM,
-                },
+                collider: Collider { size },
                 item_collider: ItemCollider,
             });
 
@@ -254,77 +288,110 @@ impl Game {
         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 => {}
-    //     }
-    // }
+    /// Spawns all four ghosts at their starting positions with appropriate textures.
+    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),
+            ]
+        };
 
-    // fn process_events(&mut self) {
-    //     while let Some(event) = self.state.event_queue.pop_front() {
-    //         match event {
-    //             GameEvent::Command(command) => self.handle_command(command),
-    //         }
-    // }
+        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>();
 
-    // /// 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)?;
+                // Create directional animated textures for the ghost
+                let mut textures = [None, None, None, None];
+                let mut stopped_textures = [None, None, None, None];
 
-    //     // Reset items
-    //     self.state.items = self.state.map.generate_items(&self.state.atlas)?;
+                for direction in Direction::DIRECTIONS {
+                    let moving_prefix = match direction {
+                        Direction::Up => "up",
+                        Direction::Down => "down",
+                        Direction::Left => "left",
+                        Direction::Right => "right",
+                    };
 
-    //     // Randomize ghost positions
-    //     let ghost_types = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde];
-    //     let mut rng = SmallRng::from_os_rng();
+                    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"
+                                )))
+                            })?,
+                    ];
 
-    //     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)?;
-    //     }
+                    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"
+                        )))
+                    })?];
 
-    //     // Reset collision system
-    //     self.state.collision_system = CollisionSystem::default();
+                    textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.2)?);
+                    stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
+                }
 
-    //     // Re-register Pac-Man
-    //     self.state.pacman_id = self.state.collision_system.register_entity(self.state.pacman.position());
+                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,
+                }
+            };
 
-    //     // 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);
-    //     }
+            world.spawn(ghost);
+        }
 
-    //     // 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(())
-    // }
+        Ok(())
+    }
 
     /// Ticks the game state.
     ///
@@ -340,52 +407,9 @@ impl Game {
             .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();
+        state.exit
     }
 
-    // /// 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

src/map/render.rs

@@ -19,7 +19,7 @@ impl MapRenderer {
     ///
     /// This function draws the static map texture to the screen at the correct
     /// position and scale.
-    pub fn render_map<T: RenderTarget>(canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, map_tiles: &mut [AtlasTile]) {
+    pub fn render_map<T: RenderTarget>(canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, map_tiles: &[AtlasTile]) {
         for (y, row) in TILE_MAP.iter().enumerate() {
             for (x, &tile_index) in row.iter().enumerate() {
                 let mut tile = map_tiles[tile_index];

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

@@ -19,7 +19,10 @@ pub fn collision_system(
     // 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)) {
+            match (
+                pacman_pos.get_pixel_position(&map.graph),
+                item_pos.get_pixel_position(&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);

src/systems/components.rs

@@ -3,7 +3,7 @@ use bitflags::bitflags;
 
 use crate::{
     entity::graph::TraversalFlags,
-    systems::movement::{Movable, MovementState, Position},
+    systems::movement::{BufferedDirection, Position, Velocity},
     texture::{animated::AnimatedTexture, sprite::AtlasTile},
 };
 
@@ -11,6 +11,46 @@ 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.
+    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 {
@@ -60,7 +100,6 @@ bitflags! {
 #[derive(Component)]
 pub struct Collider {
     pub size: f32,
-    pub layer: CollisionLayer,
 }
 
 /// Marker components for collision filtering optimization
@@ -73,15 +112,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 +130,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 +156,15 @@ pub struct ScoreResource(pub u32);
 
 #[derive(Resource)]
 pub struct DeltaTime(pub f32);
+
+#[derive(Resource, Default)]
+pub struct RenderDirty(pub bool);
+
+/// 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,
+}

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,267 @@
+//! 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::movement::Position;
+use crate::systems::profiling::SystemTimings;
+use crate::systems::render::BackbufferResource;
+use bevy_ecs::prelude::*;
+use glam::Vec2;
+use sdl2::pixels::Color;
+use sdl2::rect::Rect;
+use sdl2::render::{Canvas, Texture, TextureCreator};
+use sdl2::video::{Window, WindowContext};
+
+#[derive(Resource, Default, Debug, Copy, Clone)]
+pub struct CursorPosition(pub Vec2);
+
+#[derive(Resource, Default, Debug, Copy, Clone, PartialEq)]
+pub enum DebugState {
+    #[default]
+    Off,
+    Graph,
+    Collision,
+}
+
+impl DebugState {
+    pub fn next(&self) -> Self {
+        match self {
+            DebugState::Off => DebugState::Graph,
+            DebugState::Graph => DebugState::Collision,
+            DebugState::Collision => DebugState::Off,
+        }
+    }
+}
+
+/// Resource to hold the debug texture for persistent rendering
+pub struct DebugTextureResource(pub Texture<'static>);
+
+/// Transforms a position from logical canvas coordinates to output canvas coordinates
+fn transform_position(pos: (f32, f32), output_size: (u32, u32), logical_size: (u32, u32)) -> (i32, i32) {
+    let scale_x = output_size.0 as f32 / logical_size.0 as f32;
+    let scale_y = output_size.1 as f32 / logical_size.1 as f32;
+    let scale = scale_x.min(scale_y);
+
+    let offset_x = (output_size.0 as f32 - logical_size.0 as f32 * scale) / 2.0;
+    let offset_y = (output_size.1 as f32 - logical_size.1 as f32 * scale) / 2.0;
+
+    let x = (pos.0 * scale + offset_x) as i32;
+    let y = (pos.1 * scale + offset_y) as i32;
+    (x, y)
+}
+
+/// Transforms a position from logical canvas coordinates to output canvas coordinates (with board offset)
+fn transform_position_with_offset(pos: (f32, f32), output_size: (u32, u32), logical_size: (u32, u32)) -> (i32, i32) {
+    let scale_x = output_size.0 as f32 / logical_size.0 as f32;
+    let scale_y = output_size.1 as f32 / logical_size.1 as f32;
+    let scale = scale_x.min(scale_y);
+
+    let offset_x = (output_size.0 as f32 - logical_size.0 as f32 * scale) / 2.0;
+    let offset_y = (output_size.1 as f32 - logical_size.1 as f32 * scale) / 2.0;
+
+    let x = ((pos.0 + BOARD_PIXEL_OFFSET.x as f32) * scale + offset_x) as i32;
+    let y = ((pos.1 + BOARD_PIXEL_OFFSET.y as f32) * scale + offset_y) as i32;
+    (x, y)
+}
+
+/// Transforms a size from logical canvas coordinates to output canvas coordinates
+fn transform_size(size: f32, output_size: (u32, u32), logical_size: (u32, u32)) -> u32 {
+    let scale_x = output_size.0 as f32 / logical_size.0 as f32;
+    let scale_y = output_size.1 as f32 / logical_size.1 as f32;
+    let scale = scale_x.min(scale_y); // Use the smaller scale to maintain aspect ratio
+
+    (size * scale) as u32
+}
+
+/// 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,
+) {
+    // Get TTF context
+    let ttf_context = sdl2::ttf::init().unwrap();
+
+    // Load font
+    let font = ttf_context.load_font("assets/site/TerminalVector.ttf", 12).unwrap();
+
+    // 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();
+    }
+}
+
+pub fn debug_render_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    backbuffer: NonSendMut<BackbufferResource>,
+    mut debug_texture: NonSendMut<DebugTextureResource>,
+    debug_state: Res<DebugState>,
+    timings: Res<SystemTimings>,
+    map: Res<Map>,
+    colliders: Query<(&Collider, &Position)>,
+    cursor: Res<CursorPosition>,
+) {
+    if *debug_state == DebugState::Off {
+        return;
+    }
+
+    // Get canvas sizes for coordinate transformation
+    let output_size = canvas.output_size().unwrap();
+    let logical_size = canvas.logical_size();
+
+    // 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 cursor_world_pos = cursor.0 - BOARD_PIXEL_OFFSET.as_vec2();
+
+    // Draw debug info on the high-resolution debug texture
+    canvas
+        .with_texture_canvas(&mut debug_texture.0, |debug_canvas| {
+            match *debug_state {
+                DebugState::Graph => {
+                    // Find the closest node to the cursor
+
+                    let closest_node = 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);
+
+                    debug_canvas.set_draw_color(Color::RED);
+                    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_x, start_y) = transform_position_with_offset(
+                            (start_node_model.position.x, start_node_model.position.y),
+                            output_size,
+                            logical_size,
+                        );
+                        let (end_x, end_y) = transform_position_with_offset((end_node.x, end_node.y), output_size, logical_size);
+
+                        debug_canvas.draw_line((start_x, start_y), (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
+                        if Some(id) == closest_node {
+                            debug_canvas.set_draw_color(Color::YELLOW);
+                        } else {
+                            debug_canvas.set_draw_color(Color::BLUE);
+                        }
+
+                        // Transform position using common method
+                        let (x, y) = transform_position_with_offset((pos.x, pos.y), output_size, logical_size);
+                        let size = transform_size(4.0, output_size, logical_size);
+
+                        debug_canvas
+                            .fill_rect(Rect::new(x - (size as i32 / 2), y - (size as i32 / 2), size, size))
+                            .unwrap();
+                    }
+                }
+                DebugState::Collision => {
+                    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 (x, y) = transform_position((pos.x, pos.y), output_size, logical_size);
+                        let size = transform_size(collider.size, output_size, logical_size);
+
+                        // Center the collision box on the entity
+                        let rect = Rect::new(x - (size as i32 / 2), y - (size as i32 / 2), size, size);
+                        debug_canvas.draw_rect(rect).unwrap();
+                    }
+                }
+                _ => {}
+            }
+
+            // Render node ID if a node is highlighted
+            if let DebugState::Graph = *debug_state {
+                if let Some(closest_node_id) = 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)
+                {
+                    let node = map.graph.get_node(closest_node_id).unwrap();
+                    let (x, y) = transform_position_with_offset((node.position.x, node.position.y), output_size, logical_size);
+
+                    let ttf_context = sdl2::ttf::init().unwrap();
+                    let font = ttf_context.load_font("assets/site/TerminalVector.ttf", 12).unwrap();
+                    let surface = font.render(&closest_node_id.to_string()).blended(Color::WHITE).unwrap();
+                    let texture = texture_creator.create_texture_from_surface(&surface).unwrap();
+                    let dest = Rect::new(x + 10, 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);
+        })
+        .unwrap();
+
+    // Draw the debug texture directly onto the main canvas at full resolution
+    canvas.copy(&debug_texture.0, None, None).unwrap();
+}

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,69 @@
+use bevy_ecs::system::{Query, Res};
+use rand::prelude::*;
+use smallvec::SmallVec;
+
+use crate::{
+    entity::{direction::Direction, graph::Edge},
+    map::builder::Map,
+    systems::{
+        components::{DeltaTime, Ghost},
+        movement::{Position, Velocity},
+    },
+};
+
+/// Ghost AI system that handles randomized movement decisions.
+///
+/// This system runs on all ghosts and makes periodic decisions about
+/// which direction to move in when they reach intersections.
+pub fn ghost_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut ghosts: Query<(&Ghost, &mut Velocity, &mut Position)>,
+) {
+    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(crate::entity::graph::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;
+                    }
+                }
+            }
+        }
+    }
+}

src/systems/input.rs

@@ -1,8 +1,14 @@
-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, ResMut},
+};
+use glam::Vec2;
 use sdl2::{event::Event, keyboard::Keycode, EventPump};
 
+use crate::systems::debug::CursorPosition;
 use crate::{
     entity::direction::Direction,
     events::{GameCommand, GameEvent},
@@ -11,6 +17,8 @@ use crate::{
 #[derive(Debug, Clone, Resource)]
 pub struct Bindings {
     key_bindings: HashMap<Keycode, GameCommand>,
+    movement_keys: HashSet<Keycode>,
+    last_movement_key: Option<Keycode>,
 }
 
 impl Default for Bindings {
@@ -35,24 +43,78 @@ 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,
+            last_movement_key: None,
+        }
     }
 }
 
-pub fn input_system(bindings: Res<Bindings>, mut writer: EventWriter<GameEvent>, mut pump: NonSendMut<&'static mut EventPump>) {
+pub fn input_system(
+    mut bindings: ResMut<Bindings>,
+    mut writer: EventWriter<GameEvent>,
+    mut pump: NonSendMut<&'static mut EventPump>,
+    mut cursor: ResMut<CursorPosition>,
+) {
+    let mut movement_key_pressed = false;
+
     for event in pump.poll_iter() {
         match event {
             Event::Quit { .. } => {
                 writer.write(GameEvent::Command(GameCommand::Exit));
             }
-            Event::KeyDown { keycode: Some(key), .. } => {
+            Event::MouseMotion { x, y, .. } => {
+                cursor.0 = Vec2::new(x as f32, y as f32);
+            }
+            Event::KeyUp {
+                repeat: false,
+                keycode: Some(key),
+                ..
+            } => {
+                // If the last movement key was released, then forget it.
+                if let Some(last_movement_key) = bindings.last_movement_key {
+                    if last_movement_key == key {
+                        bindings.last_movement_key = None;
+                    }
+                }
+            }
+            Event::KeyDown {
+                keycode: Some(key),
+                repeat: false,
+                ..
+            } => {
                 let command = bindings.key_bindings.get(&key).copied();
                 if let Some(command) = command {
-                    tracing::info!("triggering command: {:?}", command);
                     writer.write(GameEvent::Command(command));
                 }
+
+                if bindings.movement_keys.contains(&key) {
+                    movement_key_pressed = true;
+                    bindings.last_movement_key = Some(key);
+                }
             }
             _ => {}
         }
     }
+
+    if let Some(last_movement_key) = bindings.last_movement_key {
+        if !movement_key_pressed {
+            let command = bindings.key_bindings.get(&last_movement_key).copied();
+            if let Some(command) = command {
+                writer.write(GameEvent::Command(command));
+            }
+        }
+    }
 }

src/systems/item.rs

@@ -0,0 +1,49 @@
+use bevy_ecs::{event::EventReader, prelude::*, query::With, system::Query};
+
+use crate::{
+    events::GameEvent,
+    systems::{
+        audio::AudioEvent,
+        components::{EntityType, ItemCollider, PacmanCollider, ScoreResource},
+    },
+};
+
+pub fn item_system(
+    mut commands: Commands,
+    mut collision_events: EventReader<GameEvent>,
+    mut score: ResMut<ScoreResource>,
+    pacman_query: Query<Entity, With<PacmanCollider>>,
+    item_query: Query<(Entity, &EntityType), With<ItemCollider>>,
+    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 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) {
+                match entity_type {
+                    EntityType::Pellet => {
+                        score.0 += 10;
+                    }
+                    EntityType::PowerPellet => {
+                        score.0 += 50;
+                    }
+                    _ => continue,
+                }
+
+                // Remove the collected item
+                commands.entity(item_ent).despawn();
+
+                events.write(AudioEvent::PlayEat);
+            }
+        }
+    }
+}

src/systems/mod.rs

@@ -3,11 +3,16 @@
 //! 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;

src/systems/movement.rs

@@ -1,46 +1,40 @@
+use crate::entity::direction::Direction;
 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 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.
 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,
+/// 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 Velocity {
+    pub speed: f32,
+    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 },
 }
 
 /// Pure spatial position component - works for both static and dynamic entities.
 #[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 speed: f32,
-    pub current_direction: Direction,
-    pub requested_direction: Option<Direction>,
+pub enum Position {
+    Stopped {
+        node: NodeId,
+    },
+    Moving {
+        from: NodeId,
+        to: NodeId,
+        remaining_distance: f32,
+    },
 }
 
 impl Position {
@@ -52,26 +46,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 +81,205 @@ impl Position {
             pos.y + crate::constants::BOARD_PIXEL_OFFSET.y as f32,
         ))
     }
-}
 
-impl Default for Position {
-    fn default() -> Self {
-        Position {
-            node: 0,
-            edge_progress: None,
+    /// Moves the position by a given distance towards it's current target node.
+    ///
+    /// Returns the overflow distance, if any.
+    pub fn tick(&mut self, distance: f32) -> Option<f32> {
+        if distance <= 0.0 || self.is_at_node() {
+            return 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,
         }
     }
 }
+
+// pub fn movement_system(
+//     map: Res<Map>,
+//     delta_time: Res<DeltaTime>,
+//     mut entities: Query<(&mut Position, &mut Movable, &EntityType)>,
+//     mut errors: EventWriter<GameError>,
+// ) {
+//     for (mut position, mut movable, entity_type) in entities.iter_mut() {
+//         let distance = movable.speed * 60.0 * delta_time.0;
+
+//         match *position {
+//             Position::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.current_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.current_node(),
+//                                     edge.target
+//                                 );
+//                                 1.0
+//                             };
+
+//                             *position = Position::Moving {
+//                                 from: position.current_node(),
+//                                 to: edge.target,
+//                                 remaining_distance: progress,
+//                             };
+//                             movable.current_direction = requested_direction;
+//                             movable.requested_direction = None;
+//                         }
+//                     } else {
+//                         errors.write(
+//                             EntityError::InvalidMovement(format!(
+//                                 "No edge found in direction {:?} from node {}",
+//                                 requested_direction,
+//                                 position.current_node()
+//                             ))
+//                             .into(),
+//                         );
+//                     }
+//                 }
+//             }
+//             Position::Moving {
+//                 from,
+//                 to,
+//                 remaining_distance,
+//             } => {
+//                 // Continue moving or handle node transitions
+//                 let current_node = *from;
+//                 if let Some(edge) = map.graph.find_edge(current_node, *to) {
+//                     // Extract target node before mutable operations
+//                     let target_node = *to;
+
+//                     // 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 {
+//                             *remaining_distance += distance / edge.distance;
+//                         } else {
+//                             // Zero-distance edge (tunnels) - immediately complete
+//                             *remaining_distance = 1.0;
+//                         }
+
+//                         if *remaining_distance >= 1.0 {
+//                             // Reached the target node
+//                             let overflow = if edge.distance > 0.0 {
+//                                 (*remaining_distance - 1.0) * edge.distance
+//                             } else {
+//                                 // Zero-distance edge - use remaining distance for overflow
+//                                 distance
+//                             };
+//                             *position = Position::Stopped { node: target_node };
+
+//                             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 = Position::Moving {
+//                                             from: position.current_node(),
+//                                             to: next_edge.target,
+//                                             remaining_distance: next_progress,
+//                                         };
+//                                         movable.current_direction = requested_direction;
+//                                         movable.requested_direction = None;
+//                                         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 = Position::Moving {
+//                                             from: position.current_node(),
+//                                             to: next_edge.target,
+//                                             remaining_distance: 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;
+//                 }
+//             }
+//         }
+//     }
+// }

src/systems/player.rs

@@ -0,0 +1,143 @@
+use bevy_ecs::{
+    event::{EventReader, EventWriter},
+    prelude::ResMut,
+    query::With,
+    system::{Query, Res},
+};
+
+use crate::{
+    entity::graph::Edge,
+    error::GameError,
+    events::{GameCommand, GameEvent},
+    map::builder::Map,
+    systems::{
+        components::{AudioState, DeltaTime, EntityType, GlobalState, PlayerControlled},
+        debug::DebugState,
+        movement::{BufferedDirection, Position, Velocity},
+    },
+};
+
+// Handles player input and control
+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<&mut BufferedDirection, With<PlayerControlled>>,
+    mut errors: EventWriter<GameError>,
+) {
+    // Get the player's movable component (ensuring there is only one player)
+    let mut buffered_direction = match players.single_mut() {
+        Ok(buffered_direction) => buffered_direction,
+        Err(e) => {
+            errors.write(GameError::InvalidState(format!(
+                "No/multiple entities queried for player system: {}",
+                e
+            )));
+            return;
+        }
+    };
+
+    // Handle events
+    for event in events.read() {
+        if let GameEvent::Command(command) = event {
+            match command {
+                GameCommand::MovePlayer(direction) => {
+                    *buffered_direction = BufferedDirection::Some {
+                        direction: *direction,
+                        remaining_time: 0.25,
+                    };
+                }
+                GameCommand::Exit => {
+                    state.exit = true;
+                }
+                GameCommand::ToggleDebug => {
+                    *debug_state = debug_state.next();
+                }
+                GameCommand::MuteAudio => {
+                    audio_state.muted = !audio_state.muted;
+                    tracing::info!("Audio {}", if audio_state.muted { "muted" } else { "unmuted" });
+                }
+                _ => {}
+            }
+        }
+    }
+}
+
+fn can_traverse(entity_type: EntityType, edge: Edge) -> bool {
+    let entity_flags = entity_type.traversal_flags();
+    edge.traversal_flags.contains(entity_flags)
+}
+
+pub fn player_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut entities: Query<(&mut Position, &mut Velocity, &mut BufferedDirection), With<PlayerControlled>>,
+    // mut errors: EventWriter<GameError>,
+) {
+    for (mut position, mut velocity, mut buffered_direction) in entities.iter_mut() {
+        // 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 * 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;
+                    }
+                }
+            }
+        }
+    }
+}

src/systems/profiling.rs

@@ -1,15 +1,166 @@
 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,
+    Render,
+    DebugRender,
+    Present,
+    Collision,
+    Item,
+    PlayerMovement,
+}
+
+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 +176,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,25 +1,37 @@
 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::components::{DeltaTime, DirectionalAnimated, RenderDirty, Renderable};
+use crate::systems::movement::{Position, Velocity};
 use crate::texture::sprite::SpriteAtlas;
 use bevy_ecs::entity::Entity;
 use bevy_ecs::event::EventWriter;
-use bevy_ecs::system::{NonSendMut, Query, Res};
+use bevy_ecs::prelude::{Changed, Or, RemovedComponents};
+use bevy_ecs::system::{NonSendMut, Query, Res, ResMut};
 use sdl2::render::{Canvas, Texture};
 use sdl2::video::Window;
 
+#[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()
@@ -31,9 +43,12 @@ pub fn directional_render_system(
             if !stopped {
                 texture.tick(dt.0);
             }
-            renderable.sprite = *texture.current_tile();
+            let new_tile = *texture.current_tile();
+            if renderable.sprite != new_tile {
+                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;
         }
     }
@@ -45,19 +60,20 @@ 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>);
 
+#[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>,
-    renderables: Query<(Entity, &mut Renderable, &Position)>,
+    dirty: Res<RenderDirty>,
+    renderables: Query<(Entity, &Renderable, &Position)>,
     mut errors: EventWriter<GameError>,
 ) {
-    // Clear the main canvas first
-    canvas.set_draw_color(sdl2::pixels::Color::BLACK);
-    canvas.clear();
-
+    if !dirty.0 {
+        return;
+    }
     // Render to backbuffer
     canvas
         .with_texture_canvas(&mut backbuffer.0, |backbuffer_canvas| {
@@ -66,18 +82,21 @@ pub fn render_system(
             backbuffer_canvas.clear();
 
             // Copy the pre-rendered map texture to the backbuffer
-            backbuffer_canvas
-                .copy(&map_texture.0, None, None)
-                .err()
-                .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+            if let Err(e) = backbuffer_canvas.copy(&map_texture.0, None, None) {
+                errors.write(TextureError::RenderFailed(e.to_string()).into());
+            }
 
             // Render all entities to the backbuffer
-            for (_, mut renderable, position) in renderables
-            // .iter_mut()
-            // .sort_by_key::<&mut Renderable, _, _>(|(renderable, renderable, renderable)| renderable.layer)
-            // .collect()
+            for (_, renderable, position) in renderables
+                .iter()
+                .sort_by_key::<(Entity, &Renderable, &Position), _>(|(_, renderable, _)| renderable.layer)
+                .rev()
             {
-                let pos = position.get_pixel_pos(&map.graph);
+                if !renderable.visible {
+                    continue;
+                }
+
+                let pos = position.get_pixel_position(&map.graph);
                 match pos {
                     Ok(pos) => {
                         let dest = crate::helpers::centered_with_size(
@@ -92,19 +111,11 @@ pub fn render_system(
                             .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
                     }
                     Err(e) => {
-                        errors.write(e.into());
+                        errors.write(e);
                     }
                 }
             }
         })
         .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();
 }

src/texture/sprite.rs

@@ -21,7 +21,7 @@ pub struct MapperFrame {
     pub height: u16,
 }
 
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, PartialEq)]
 pub struct AtlasTile {
     pub pos: U16Vec2,
     pub size: U16Vec2,
@@ -30,7 +30,7 @@ pub struct AtlasTile {
 
 impl AtlasTile {
     pub fn render<C: RenderTarget>(
-        &mut self,
+        &self,
         canvas: &mut Canvas<C>,
         atlas: &mut SpriteAtlas,
         dest: Rect,
@@ -41,7 +41,7 @@ impl AtlasTile {
     }
 
     pub fn render_with_color<C: RenderTarget>(
-        &mut self,
+        &self,
         canvas: &mut Canvas<C>,
         atlas: &mut SpriteAtlas,
         dest: Rect,

src/texture/text.rs

@@ -103,9 +103,9 @@ impl TextTexture {
         &self.char_map
     }
 
-    pub fn get_tile(&mut self, c: char, atlas: &mut SpriteAtlas) -> Result<Option<&mut AtlasTile>> {
+    pub fn get_tile(&mut self, c: char, atlas: &mut SpriteAtlas) -> Result<Option<&AtlasTile>> {
         if self.char_map.contains_key(&c) {
-            return Ok(self.char_map.get_mut(&c));
+            return Ok(self.char_map.get(&c));
         }
 
         if let Some(tile_name) = char_to_tile_name(c) {
@@ -113,7 +113,7 @@ impl TextTexture {
                 .get_tile(&tile_name)
                 .ok_or(GameError::Texture(TextureError::AtlasTileNotFound(tile_name)))?;
             self.char_map.insert(c, tile);
-            Ok(self.char_map.get_mut(&c))
+            Ok(self.char_map.get(&c))
         } else {
             Ok(None)
         }

tests/formatting.rs

@@ -0,0 +1,95 @@
+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_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
+    );
+}

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);
+// }