refactor: create workspace, move 'pacman' into pacman/ subfolder as workspace member

pacman/src/app.rs

@@ -0,0 +1,163 @@
+use std::collections::HashMap;
+use std::time::{Duration, Instant};
+
+use crate::error::{GameError, GameResult};
+
+use crate::constants::{CANVAS_SIZE, LOOP_TIME, SCALE};
+use crate::formatter;
+use crate::game::Game;
+use crate::platform;
+use sdl2::pixels::PixelFormatEnum;
+use sdl2::render::RendererInfo;
+use sdl2::{AudioSubsystem, Sdl};
+use tracing::{debug, info, trace};
+
+/// Main application wrapper that manages SDL initialization, window lifecycle, and the game loop.
+pub struct App {
+    pub game: Game,
+    last_tick: Instant,
+    focused: bool,
+    // Keep SDL alive for the app lifetime so subsystems (audio) are not shut down
+    _sdl_context: Sdl,
+    _audio_subsystem: AudioSubsystem,
+}
+
+impl App {
+    /// Initializes SDL subsystems, creates the game window, and sets up the game state.
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError::Sdl` if any SDL initialization step fails, or propagates
+    /// errors from `Game::new()` during game state setup.
+    pub fn new() -> GameResult<Self> {
+        info!("Initializing SDL2 application");
+        let sdl_context = sdl2::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+        debug!("Initializing SDL2 subsystems");
+        let ttf_context = sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let video_subsystem = sdl_context.video().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let audio_subsystem = sdl_context.audio().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let event_pump = sdl_context.event_pump().map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        trace!(
+            width = (CANVAS_SIZE.x as f32 * SCALE).round() as u32,
+            height = (CANVAS_SIZE.y as f32 * SCALE).round() as u32,
+            scale = SCALE,
+            "Creating game window"
+        );
+        let window = video_subsystem
+            .window(
+                "Pac-Man",
+                (CANVAS_SIZE.x as f32 * SCALE).round() as u32,
+                (CANVAS_SIZE.y as f32 * SCALE).round() as u32,
+            )
+            .resizable()
+            .position_centered()
+            .build()
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        #[derive(Debug)]
+        struct DriverDetail {
+            info: RendererInfo,
+            index: usize,
+        }
+
+        let drivers: HashMap<&'static str, DriverDetail> = sdl2::render::drivers()
+            .enumerate()
+            .map(|(index, d)| (d.name, DriverDetail { info: d, index }))
+            .collect::<HashMap<_, _>>();
+
+        let get_driver =
+            |name: &'static str| -> Option<u32> { drivers.get(name.to_lowercase().as_str()).map(|d| d.index as u32) };
+
+        {
+            let mut names = drivers.keys().collect::<Vec<_>>();
+            names.sort_by_key(|k| get_driver(k));
+            trace!("Drivers: {names:?}")
+        }
+
+        // Count the number of times each pixel format is supported by each driver
+        let pixel_format_counts: HashMap<PixelFormatEnum, usize> = drivers
+            .values()
+            .flat_map(|d| d.info.texture_formats.iter())
+            .fold(HashMap::new(), |mut counts, format| {
+                *counts.entry(*format).or_insert(0) += 1;
+                counts
+            });
+
+        trace!(pixel_format_counts = ?pixel_format_counts, "Available pixel formats per driver");
+
+        let index = get_driver("direct3d");
+        trace!(driver_index = ?index, "Selected graphics driver");
+
+        trace!("Creating hardware-accelerated canvas");
+        let mut canvas = window
+            .into_canvas()
+            .accelerated()
+            // .index(index)
+            .build()
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        trace!(
+            logical_width = CANVAS_SIZE.x,
+            logical_height = CANVAS_SIZE.y,
+            "Setting canvas logical size"
+        );
+        canvas
+            .set_logical_size(CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        debug!(renderer_info = ?canvas.info(), "Canvas renderer initialized");
+
+        trace!("Creating texture factory");
+        let texture_creator = canvas.texture_creator();
+
+        info!("Starting game initialization");
+        let game = Game::new(canvas, ttf_context, texture_creator, event_pump)?;
+
+        info!("Application initialization completed successfully");
+        Ok(App {
+            game,
+            focused: true,
+            last_tick: Instant::now(),
+            _sdl_context: sdl_context,
+            _audio_subsystem: audio_subsystem,
+        })
+    }
+
+    /// Executes a single frame of the game loop with consistent timing and optional sleep.
+    ///
+    /// Calculates delta time since the last frame, runs game logic via `game.tick()`,
+    /// and implements frame rate limiting by sleeping for remaining time if the frame
+    /// completed faster than the target `LOOP_TIME`. Sleep behavior varies based on
+    /// window focus to conserve CPU when the game is not active.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the game should continue running, `false` if the game requested exit.
+    pub fn run(&mut self) -> bool {
+        {
+            let start = Instant::now();
+
+            let dt = self.last_tick.elapsed().as_secs_f32();
+            self.last_tick = start;
+
+            // Increment the global tick counter for tracing
+            formatter::increment_tick();
+
+            let exit = self.game.tick(dt);
+
+            if exit {
+                return false;
+            }
+
+            // Sleep if we still have time left
+            if start.elapsed() < LOOP_TIME {
+                let time = LOOP_TIME.saturating_sub(start.elapsed());
+                if time != Duration::ZERO {
+                    platform::sleep(time, self.focused);
+                }
+            }
+
+            true
+        }
+    }
+}

pacman/src/asset.rs

@@ -0,0 +1,137 @@
+//! Cross-platform asset loading abstraction.
+//! On desktop, assets are embedded using include_bytes!; on Emscripten, assets are loaded from the filesystem.
+
+use std::borrow::Cow;
+use std::iter;
+
+use crate::audio::Sound;
+use crate::error::AssetError;
+
+/// Enumeration of all game assets with cross-platform loading support.
+///
+/// Each variant corresponds to a specific file that can be loaded either from
+/// binary-embedded data or embedded filesystem (Emscripten).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Asset {
+    /// Main sprite atlas containing all game graphics (atlas.png)
+    AtlasImage,
+    /// Terminal Vector font for text rendering (TerminalVector.ttf)
+    Font,
+    /// Sound file assets
+    SoundFile(Sound),
+}
+
+use strum::IntoEnumIterator;
+
+impl Asset {
+    #[allow(dead_code)]
+    pub fn into_iter() -> AssetIter {
+        AssetIter {
+            sound_iter: None,
+            state: 0,
+        }
+    }
+}
+
+#[allow(clippy::type_complexity)]
+pub struct AssetIter {
+    sound_iter: Option<iter::Map<<Sound as IntoEnumIterator>::Iterator, fn(Sound) -> Asset>>,
+    state: u8,
+}
+
+impl Iterator for AssetIter {
+    type Item = Asset;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.state {
+            0 => {
+                self.state = 1;
+                Some(Asset::AtlasImage)
+            }
+            1 => {
+                self.state = 2;
+                Some(Asset::Font)
+            }
+            2 => self
+                .sound_iter
+                .get_or_insert_with(|| Sound::iter().map(Asset::SoundFile))
+                .next(),
+            _ => None,
+        }
+    }
+}
+
+impl Asset {
+    /// Returns the relative file path for this asset within the game's asset directory.
+    ///
+    /// Paths are consistent across platforms and used by the Emscripten backend
+    /// for filesystem loading. Desktop builds embed assets directly and don't
+    /// use these paths at runtime.
+    pub fn path(&self) -> &str {
+        use Asset::*;
+        match self {
+            SoundFile(Sound::Waka(0)) => "sound/pacman/waka/1.ogg",
+            SoundFile(Sound::Waka(1)) => "sound/pacman/waka/2.ogg",
+            SoundFile(Sound::Waka(2)) => "sound/pacman/waka/3.ogg",
+            SoundFile(Sound::Waka(3..=u8::MAX)) => "sound/pacman/waka/4.ogg",
+            SoundFile(Sound::PacmanDeath) => "sound/pacman/death.ogg",
+            SoundFile(Sound::ExtraLife) => "sound/pacman/extra_life.ogg",
+            SoundFile(Sound::Fruit) => "sound/pacman/fruit.ogg",
+            SoundFile(Sound::Ghost) => "sound/pacman/ghost.ogg",
+            SoundFile(Sound::Beginning) => "sound/begin.ogg",
+            SoundFile(Sound::Intermission) => "sound/intermission.ogg",
+            AtlasImage => "atlas.png",
+            Font => "TerminalVector.ttf",
+        }
+    }
+
+    /// Loads asset bytes using the appropriate platform-specific method.
+    ///
+    /// On desktop platforms, returns embedded compile-time data via `rust-embed`.
+    /// On Emscripten, loads from the filesystem using the asset's path. The returned
+    /// `Cow` allows zero-copy access to embedded data while supporting owned data
+    /// when loaded from disk.
+    ///
+    /// # Errors
+    ///
+    /// Returns `AssetError::NotFound` if the asset file cannot be located,
+    /// or `AssetError::Io` for filesystem I/O failures.
+    pub fn get_bytes(&self) -> Result<Cow<'static, [u8]>, AssetError> {
+        use tracing::trace;
+        trace!(asset = ?self, "Loading game asset");
+        let result = self.get_bytes_platform();
+        match &result {
+            Ok(bytes) => trace!(asset = ?self, size_bytes = bytes.len(), "Asset loaded successfully"),
+            Err(e) => trace!(asset = ?self, error = ?e, "Asset loading failed"),
+        }
+        result
+    }
+
+    #[cfg(not(target_os = "emscripten"))]
+    fn get_bytes_platform(&self) -> Result<Cow<'static, [u8]>, AssetError> {
+        #[derive(rust_embed::Embed)]
+        #[folder = "assets/game/"]
+        struct EmbeddedAssets;
+
+        let path = self.path();
+        EmbeddedAssets::get(path)
+            .map(|file| file.data)
+            .ok_or_else(|| AssetError::NotFound(path.to_string()))
+    }
+
+    #[cfg(target_os = "emscripten")]
+    fn get_bytes_platform(&self) -> Result<Cow<'static, [u8]>, AssetError> {
+        use sdl2::rwops::RWops;
+        use std::io::{self, Read};
+
+        let path = format!("assets/game/{}", self.path());
+        let mut rwops = RWops::from_file(&path, "rb").map_err(|_| AssetError::NotFound(self.path().to_string()))?;
+
+        let len = rwops.len().ok_or_else(|| AssetError::NotFound(self.path().to_string()))?;
+
+        let mut buf = vec![0u8; len];
+        rwops.read_exact(&mut buf).map_err(|e| AssetError::Io(io::Error::other(e)))?;
+
+        Ok(Cow::Owned(buf))
+    }
+}

pacman/src/audio.rs

@@ -0,0 +1,251 @@
+//! This module handles the audio playback for the game.
+use std::collections::HashMap;
+
+use crate::asset::Asset;
+use anyhow::{anyhow, Result};
+use sdl2::{
+    mixer::{self, Chunk, InitFlag, LoaderRWops, AUDIO_S16LSB},
+    rwops::RWops,
+};
+use strum::IntoEnumIterator;
+
+const AUDIO_FREQUENCY: i32 = 16_000;
+const AUDIO_CHANNELS: i32 = 4;
+const DEFAULT_VOLUME: u8 = 32;
+const WAKA_SOUND_COUNT: u8 = 4;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Sound {
+    Waka(u8),
+    PacmanDeath,
+    ExtraLife,
+    Fruit,
+    Ghost,
+    Beginning,
+    Intermission,
+}
+
+impl IntoEnumIterator for Sound {
+    type Iterator = std::vec::IntoIter<Sound>;
+
+    fn iter() -> Self::Iterator {
+        let mut sounds = vec![
+            Sound::PacmanDeath,
+            Sound::ExtraLife,
+            Sound::Fruit,
+            Sound::Ghost,
+            Sound::Beginning,
+            Sound::Intermission,
+        ];
+        sounds.extend((0..WAKA_SOUND_COUNT).map(Sound::Waka));
+        sounds.into_iter()
+    }
+}
+
+/// The audio system for the game.
+///
+/// This struct is responsible for initializing the audio device, loading sounds,
+/// and playing them. If audio fails to initialize, it will be disabled and all
+/// functions will silently do nothing.
+pub struct Audio {
+    _mixer_context: Option<mixer::Sdl2MixerContext>,
+    sounds: HashMap<Sound, Chunk>,
+    next_waka_index: u8,
+    state: AudioState,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum AudioState {
+    Enabled { volume: u8 },
+    Muted { previous_volume: u8 },
+    Disabled,
+}
+
+impl Default for Audio {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Audio {
+    /// Creates a new `Audio` instance.
+    ///
+    /// If audio fails to initialize, the audio system will be disabled and
+    /// all functions will silently do nothing.
+    pub fn new() -> Self {
+        match Self::try_new() {
+            Ok(audio) => audio,
+            Err(e) => {
+                tracing::warn!("Failed to initialize audio: {}. Audio will be disabled.", e);
+                Self {
+                    _mixer_context: None,
+                    sounds: HashMap::new(),
+                    next_waka_index: 0,
+                    state: AudioState::Disabled,
+                }
+            }
+        }
+    }
+
+    fn try_new() -> Result<Self> {
+        let format = AUDIO_S16LSB;
+        let chunk_size = {
+            // 256 is the minimum for Emscripten, but in practice 1024 is much more reliable
+            #[cfg(target_os = "emscripten")]
+            {
+                1024
+            }
+
+            // Otherwise, 256 is plenty safe.
+            #[cfg(not(target_os = "emscripten"))]
+            {
+                256
+            }
+        };
+
+        // Try to open audio, but don't panic if it fails
+        mixer::open_audio(AUDIO_FREQUENCY, format, AUDIO_CHANNELS, chunk_size)
+            .map_err(|e| anyhow!("Failed to open audio: {}", e))?;
+
+        mixer::allocate_channels(AUDIO_CHANNELS);
+
+        // set channel volume
+        for i in 0..AUDIO_CHANNELS {
+            mixer::Channel(i).set_volume(DEFAULT_VOLUME as i32);
+        }
+
+        // Try to initialize mixer, but don't panic if it fails
+        let mixer_context = mixer::init(InitFlag::OGG).map_err(|e| anyhow!("Failed to initialize SDL2_mixer: {}", e))?;
+
+        // Try to load sounds, but don't panic if any fail
+        let sounds: HashMap<Sound, Chunk> = Sound::iter()
+            .filter_map(|sound_type| match Self::load_sound(sound_type) {
+                Ok(chunk) => Some((sound_type, chunk)),
+                Err(e) => {
+                    tracing::warn!("Failed to load sound {:?}: {}", sound_type, e);
+                    None
+                }
+            })
+            .collect();
+
+        // If no sounds loaded successfully, disable audio
+        if sounds.is_empty() {
+            return Err(anyhow!("No sounds loaded successfully"));
+        }
+
+        Ok(Audio {
+            _mixer_context: Some(mixer_context),
+            sounds,
+            next_waka_index: 0u8,
+            state: AudioState::Enabled { volume: DEFAULT_VOLUME },
+        })
+    }
+
+    fn load_sound(sound_type: Sound) -> Result<Chunk> {
+        let asset = Asset::SoundFile(sound_type);
+        let data = asset
+            .get_bytes()
+            .map_err(|e| anyhow!("Failed to get bytes for {:?}: {}", sound_type, e))?;
+        let rwops = RWops::from_bytes(&data).map_err(|e| anyhow!("Failed to create RWops for {:?}: {}", sound_type, e))?;
+        rwops
+            .load_wav()
+            .map_err(|e| anyhow!("Failed to load wav for {:?}: {}", sound_type, e))
+    }
+
+    /// Plays the next waka eating sound in the cycle of four variants.
+    ///
+    /// Automatically rotates through the four eating sound assets. The sound plays on channel 0 and the internal sound index
+    /// advances to the next variant. Silently returns if audio is disabled, muted,
+    /// or no sounds were loaded successfully.
+    pub fn waka(&mut self) {
+        if !matches!(self.state, AudioState::Enabled { .. }) {
+            return;
+        }
+
+        if let Some(chunk) = self.sounds.get(&Sound::Waka(self.next_waka_index)) {
+            match mixer::Channel::all().play(chunk, 0) {
+                Ok(channel) => {
+                    tracing::trace!("Playing sound #{} on channel {:?}", self.next_waka_index + 1, channel);
+                }
+                Err(e) => {
+                    tracing::warn!("Could not play sound #{}: {}", self.next_waka_index + 1, e);
+                }
+            }
+        }
+        self.next_waka_index = (self.next_waka_index + 1) % WAKA_SOUND_COUNT;
+    }
+
+    /// Plays the provided sound effect once.
+    pub fn play(&mut self, sound: Sound) {
+        if !matches!(self.state, AudioState::Enabled { .. }) {
+            return;
+        }
+
+        if let Some(chunk) = self.sounds.get(&sound) {
+            let _ = mixer::Channel::all().play(chunk, 0);
+        }
+    }
+
+    /// Halts all currently playing audio channels.
+    pub fn stop_all(&mut self) {
+        if self.state != AudioState::Disabled {
+            mixer::Channel::all().halt();
+        }
+    }
+
+    /// Pauses all currently playing audio channels.
+    pub fn pause_all(&mut self) {
+        if self.state != AudioState::Disabled {
+            mixer::Channel::all().pause();
+        }
+    }
+
+    /// Resumes all currently playing audio channels.
+    pub fn resume_all(&mut self) {
+        if self.state != AudioState::Disabled {
+            mixer::Channel::all().resume();
+        }
+    }
+
+    /// Instantly mutes or unmutes all audio channels by adjusting their volume.
+    ///
+    /// Sets all 4 mixer channels to zero volume when muting, or restores them to
+    /// their default volume (32) when unmuting. The mute state is tracked internally
+    /// regardless of whether audio is disabled, allowing the state to be preserved.
+    pub fn set_mute(&mut self, mute: bool) {
+        match (mute, self.state) {
+            // Mute
+            (true, AudioState::Enabled { volume }) => {
+                self.state = AudioState::Muted { previous_volume: volume };
+                for i in 0..AUDIO_CHANNELS {
+                    mixer::Channel(i).set_volume(0);
+                }
+            }
+            // Unmute
+            (false, AudioState::Muted { previous_volume }) => {
+                self.state = AudioState::Enabled { volume: previous_volume };
+                for i in 0..AUDIO_CHANNELS {
+                    mixer::Channel(i).set_volume(previous_volume as i32);
+                }
+            }
+            _ => {}
+        }
+    }
+
+    /// Returns the current mute state regardless of whether audio is functional.
+    ///
+    /// This tracks the user's mute preference and will return `true` if muted
+    /// even when the audio system is disabled due to initialization failures.
+    pub fn is_muted(&self) -> bool {
+        matches!(self.state, AudioState::Muted { .. })
+    }
+
+    /// Returns whether the audio system failed to initialize and is non-functional.
+    ///
+    /// Audio can be disabled due to SDL2_mixer initialization failures, missing
+    /// audio device, or failure to load any sound assets. When disabled, all
+    /// audio operations become no-ops.
+    pub fn is_disabled(&self) -> bool {
+        matches!(self.state, AudioState::Disabled)
+    }
+}

pacman/src/bin/aspect_demo.rs

@@ -0,0 +1,133 @@
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+#![cfg_attr(coverage_nightly, coverage(off))]
+
+use std::time::{Duration, Instant};
+
+use sdl2::event::Event;
+use sdl2::keyboard::Keycode;
+use sdl2::pixels::Color;
+use sdl2::rect::Rect;
+
+// A self-contained SDL2 demo showing how to keep a consistent aspect ratio
+// with letterboxing/pillarboxing in a resizable window.
+//
+// This uses SDL2's logical size feature, which automatically sets a viewport
+// to preserve the target aspect ratio and adds black bars as needed.
+// We also clear the full window to black and then clear the logical viewport
+// to a content color, so bars remain visibly black.
+
+const LOGICAL_WIDTH: u32 = 320; // target content width
+const LOGICAL_HEIGHT: u32 = 180; // target content height (16:9)
+
+fn main() -> Result<(), String> {
+    // Initialize SDL2
+    let sdl = sdl2::init()?;
+    let video = sdl.video()?;
+
+    // Create a resizable window
+    let window = video
+        .window("SDL2 Aspect Ratio Demo", 960, 540)
+        .resizable()
+        .position_centered()
+        .build()
+        .map_err(|e| e.to_string())?;
+
+    let mut canvas = window.into_canvas().build().map_err(|e| e.to_string())?;
+
+    // Set the desired logical (virtual) resolution. SDL will letterbox/pillarbox
+    // as needed to preserve this aspect ratio when the window is resized.
+    canvas
+        .set_logical_size(LOGICAL_WIDTH, LOGICAL_HEIGHT)
+        .map_err(|e| e.to_string())?;
+    // Optional: uncomment to enforce integer scaling only (more retro look)
+    // canvas.set_integer_scale(true)?;
+
+    let mut events = sdl.event_pump()?;
+
+    let mut running = true;
+    let start = Instant::now();
+    let mut last_log = Instant::now();
+
+    while running {
+        for event in events.poll_iter() {
+            match event {
+                Event::Quit { .. }
+                | Event::KeyDown {
+                    keycode: Some(Keycode::Escape),
+                    ..
+                } => {
+                    running = false;
+                }
+                Event::Window { win_event, .. } => {
+                    // Periodically log window size and the computed viewport
+                    // to demonstrate how letterboxing/pillarboxing behaves.
+                    use sdl2::event::WindowEvent;
+                    match win_event {
+                        WindowEvent::Resized(_, _)
+                        | WindowEvent::SizeChanged(_, _)
+                        | WindowEvent::Maximized
+                        | WindowEvent::Restored => {
+                            if last_log.elapsed() > Duration::from_millis(250) {
+                                let out_size = canvas.output_size()?;
+                                let viewport = canvas.viewport();
+                                println!(
+                                    "window={}x{}, viewport x={}, y={}, w={}, h={}",
+                                    out_size.0,
+                                    out_size.1,
+                                    viewport.x(),
+                                    viewport.y(),
+                                    viewport.width(),
+                                    viewport.height()
+                                );
+                                last_log = Instant::now();
+                            }
+                        }
+                        _ => {}
+                    }
+                }
+                _ => {}
+            }
+        }
+
+        // 1) Clear the entire window to black (no viewport) so the bars are black
+        canvas.set_viewport(None);
+        canvas.set_draw_color(Color::RGB(0, 0, 0));
+        canvas.clear();
+
+        // 2) Re-apply logical size so SDL sets a viewport that preserves aspect
+        //    ratio. Clearing now only affects the letterboxed content area.
+        canvas
+            .set_logical_size(LOGICAL_WIDTH, LOGICAL_HEIGHT)
+            .map_err(|e| e.to_string())?;
+
+        // Fill the content area with a background color to differentiate from bars
+        canvas.set_draw_color(Color::RGB(30, 30, 40));
+        canvas.clear();
+
+        // Draw a simple grid to visualize scaling clearly
+        canvas.set_draw_color(Color::RGB(60, 60, 90));
+        let step = 20i32;
+        for x in (0..=LOGICAL_WIDTH as i32).step_by(step as usize) {
+            let _ = canvas.draw_line(sdl2::rect::Point::new(x, 0), sdl2::rect::Point::new(x, LOGICAL_HEIGHT as i32));
+        }
+        for y in (0..=LOGICAL_HEIGHT as i32).step_by(step as usize) {
+            let _ = canvas.draw_line(sdl2::rect::Point::new(0, y), sdl2::rect::Point::new(LOGICAL_WIDTH as i32, y));
+        }
+
+        // Draw a border around the logical content area
+        canvas.set_draw_color(Color::RGB(200, 200, 220));
+        let border = Rect::new(0, 0, LOGICAL_WIDTH, LOGICAL_HEIGHT);
+        canvas.draw_rect(border)?;
+
+        // Draw a moving box to demonstrate dynamic content staying within aspect
+        let elapsed_ms = start.elapsed().as_millis() as i32;
+        let t = (elapsed_ms / 8) % LOGICAL_WIDTH as i32;
+        let box_rect = Rect::new(t - 10, (LOGICAL_HEIGHT as i32 / 2) - 10, 20, 20);
+        canvas.set_draw_color(Color::RGB(255, 140, 0));
+        canvas.fill_rect(box_rect).ok();
+
+        canvas.present();
+    }
+
+    Ok(())
+}

pacman/src/bin/timing_demo.rs

@@ -0,0 +1,94 @@
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+#![cfg_attr(coverage_nightly, coverage(off))]
+
+use circular_buffer::CircularBuffer;
+use pacman::constants::CANVAS_SIZE;
+use sdl2::event::Event;
+use sdl2::keyboard::Keycode;
+use sdl2::pixels::Color;
+use std::time::{Duration, Instant};
+
+fn main() -> Result<(), String> {
+    let sdl_context = sdl2::init()?;
+    let video_subsystem = sdl_context.video()?;
+
+    let window = video_subsystem
+        .window("SDL2 Timing Demo", CANVAS_SIZE.x, CANVAS_SIZE.y)
+        .opengl()
+        .position_centered()
+        .build()
+        .map_err(|e| e.to_string())?;
+
+    let mut canvas = window.into_canvas().accelerated().build().map_err(|e| e.to_string())?;
+    canvas
+        .set_logical_size(CANVAS_SIZE.x, CANVAS_SIZE.y)
+        .map_err(|e| e.to_string())?;
+
+    let mut event_pump = sdl_context.event_pump()?;
+
+    // Store frame timings in milliseconds
+    let mut frame_timings = CircularBuffer::<20_000, f64>::new();
+    let mut last_report_time = Instant::now();
+    let report_interval = Duration::from_millis(500);
+
+    'running: loop {
+        let frame_start_time = Instant::now();
+
+        for event in event_pump.poll_iter() {
+            match event {
+                Event::Quit { .. }
+                | Event::KeyDown {
+                    keycode: Some(Keycode::Escape),
+                    ..
+                } => {
+                    break 'running;
+                }
+                _ => {}
+            }
+        }
+
+        // Clear the screen
+        canvas.set_draw_color(Color::RGB(0, 0, 0));
+        canvas.clear();
+        canvas.present();
+
+        // Record timing
+        let frame_duration = frame_start_time.elapsed();
+        frame_timings.push_back(frame_duration.as_secs_f64());
+
+        // Report stats every `report_interval`
+        let elapsed = last_report_time.elapsed();
+        if elapsed >= report_interval {
+            if !frame_timings.is_empty() {
+                let count = frame_timings.len() as f64;
+                let sum: f64 = frame_timings.iter().sum();
+                let mean = sum / count;
+
+                let variance = frame_timings
+                    .iter()
+                    .map(|value| {
+                        let diff = mean - value;
+                        diff * diff
+                    })
+                    .sum::<f64>()
+                    / count;
+                let std_dev = variance.sqrt();
+
+                println!(
+                    "Rendered {count} frames at {fps:.1} fps (last {elapsed:.2?}): mean={mean:.3?}, std_dev={std_dev:.3?}",
+                    count = frame_timings.len(),
+                    fps = count / elapsed.as_secs_f64(),
+                    elapsed = elapsed,
+                    mean = Duration::from_secs_f64(mean),
+                    std_dev = Duration::from_secs_f64(std_dev),
+                );
+            }
+
+            // Reset for next interval
+            frame_timings.clear();
+            last_report_time = Instant::now();
+        }
+    }
+
+    Ok(())
+}

pacman/src/constants.rs

@@ -0,0 +1,160 @@
+//! This module contains all the constants used in the game.
+
+use std::time::Duration;
+
+use glam::UVec2;
+
+/// Target frame duration for 60 FPS game loop timing.
+///
+/// Calculated as 1/60th of a second (≈16.67ms).
+///
+/// Uses integer arithmetic to avoid floating-point precision loss.
+pub const LOOP_TIME: Duration = Duration::from_nanos(1_000_000_000 / 60);
+
+/// The size of each cell, in pixels.
+pub const CELL_SIZE: u32 = 8;
+/// The size of the game board, in cells.
+pub const BOARD_CELL_SIZE: UVec2 = UVec2::new(28, 31);
+
+/// The scale factor for the window (integer zoom)
+pub const SCALE: f32 = 2.6;
+
+/// Game board offset from window origin to reserve space for HUD elements.
+///
+/// The 3-cell vertical offset (24 pixels) provides space at the top of the
+/// screen for score display, player lives, and other UI elements.
+pub const BOARD_CELL_OFFSET: UVec2 = UVec2::new(0, 3);
+
+/// Bottom HUD row offset to reserve space below the game board.
+///
+/// The 2-cell vertical offset (16 pixels) provides space at the bottom of the
+/// screen for displaying Pac-Man's lives (left) and fruit symbols (right).
+pub const BOARD_BOTTOM_CELL_OFFSET: UVec2 = UVec2::new(0, 2);
+
+/// Pixel-space equivalent of `BOARD_CELL_OFFSET` for rendering calculations.
+///
+/// Automatically calculated from the cell offset to maintain consistency
+/// when the cell size changes. Used for positioning sprites and debug overlays.
+pub const BOARD_PIXEL_OFFSET: UVec2 = UVec2::new(BOARD_CELL_OFFSET.x * CELL_SIZE, BOARD_CELL_OFFSET.y * CELL_SIZE);
+
+/// Pixel-space equivalent of `BOARD_BOTTOM_CELL_OFFSET` for rendering calculations.
+///
+/// Automatically calculated from the cell offset to maintain consistency
+/// when the cell size changes. Used for positioning bottom HUD elements.
+pub const BOARD_BOTTOM_PIXEL_OFFSET: UVec2 =
+    UVec2::new(BOARD_BOTTOM_CELL_OFFSET.x * CELL_SIZE, BOARD_BOTTOM_CELL_OFFSET.y * CELL_SIZE);
+
+/// Animation timing constants for ghost state management
+pub mod animation {
+    /// Normal ghost movement animation speed (ticks per frame at 60 ticks/sec)
+    pub const GHOST_NORMAL_SPEED: u16 = 12;
+    /// Eaten ghost (eyes) animation speed (ticks per frame at 60 ticks/sec)
+    pub const GHOST_EATEN_SPEED: u16 = 6;
+    /// Frightened ghost animation speed (ticks per frame at 60 ticks/sec)
+    pub const GHOST_FRIGHTENED_SPEED: u16 = 12;
+    /// Time in ticks for frightened ghosts to return to normal
+    pub const GHOST_FRIGHTENED_TICKS: u32 = 5 * 60;
+    /// Time in ticks when frightened ghosts start flashing
+    pub const GHOST_FRIGHTENED_FLASH_START_TICKS: u32 = GHOST_FRIGHTENED_TICKS - 2 * 60;
+}
+
+/// The size of the canvas, in pixels.
+pub const CANVAS_SIZE: UVec2 = UVec2::new(
+    (BOARD_CELL_SIZE.x + BOARD_CELL_OFFSET.x + BOARD_BOTTOM_CELL_OFFSET.x) * CELL_SIZE,
+    (BOARD_CELL_SIZE.y + BOARD_CELL_OFFSET.y + BOARD_BOTTOM_CELL_OFFSET.y) * CELL_SIZE,
+);
+
+pub const LARGE_SCALE: f32 = 2.6;
+
+pub const LARGE_CANVAS_SIZE: UVec2 = UVec2::new(
+    (((BOARD_CELL_SIZE.x + BOARD_CELL_OFFSET.x + BOARD_BOTTOM_CELL_OFFSET.x) * CELL_SIZE) as f32 * LARGE_SCALE) as u32,
+    (((BOARD_CELL_SIZE.y + BOARD_CELL_OFFSET.y + BOARD_BOTTOM_CELL_OFFSET.y) * CELL_SIZE) as f32 * LARGE_SCALE) as u32,
+);
+
+/// Collider size constants for different entity types
+pub mod collider {
+    use super::CELL_SIZE;
+
+    /// Collider size for player and ghosts
+    pub const PLAYER_SIZE: f32 = CELL_SIZE as f32 * 1.385;
+    /// Collider size for ghosts
+    pub const GHOST_SIZE: f32 = CELL_SIZE as f32 * 1.55;
+    /// Collider size for pellets
+    pub const PELLET_SIZE: f32 = CELL_SIZE as f32 * 0.4;
+    /// Collider size for power pellets/energizers
+    pub const POWER_PELLET_SIZE: f32 = CELL_SIZE as f32 * 0.95;
+    /// Collider size for fruits
+    pub const FRUIT_SIZE: f32 = CELL_SIZE as f32 * 1.375;
+}
+
+/// UI and rendering constants
+pub mod ui {
+    /// Debug font size in points
+    pub const DEBUG_FONT_SIZE: u16 = 12;
+    /// Power pellet blink rate in ticks (at 60 FPS, 12 ticks = 0.2 seconds)
+    pub const POWER_PELLET_BLINK_RATE: u32 = 12;
+}
+
+/// Map tile types that define gameplay behavior and collision properties.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum MapTile {
+    /// Traversable space with no collectible items
+    Empty,
+    Wall,
+    /// Small collectible. Implicitly a traversable tile.
+    Pellet,
+    /// Large collectible. Implicitly a traversable tile.
+    PowerPellet,
+    /// Special traversable tile that connects to tunnel portals.
+    Tunnel,
+}
+
+/// ASCII art representation of the classic Pac-Man maze layout.
+///
+/// Uses character symbols to define the game world. This layout is parsed by `MapTileParser`
+/// to generate the navigable graph and collision geometry.
+pub const RAW_BOARD: [&str; BOARD_CELL_SIZE.y as usize] = [
+    "############################",
+    "#............##............#",
+    "#.####.#####.##.#####.####.#",
+    "#o####.#####.##.#####.####o#",
+    "#.####.#####.##.#####.####.#",
+    "#..........................#",
+    "#.####.##.########.##.####.#",
+    "#.####.##.########.##.####.#",
+    "#......##....##....##......#",
+    "######.##### ## #####.######",
+    "     #.##### ## #####.#     ",
+    "     #.##    ==    ##.#     ",
+    "     #.## ######## ##.#     ",
+    "######.## ######## ##.######",
+    "T     .   ########   .     T",
+    "######.## ######## ##.######",
+    "     #.## ######## ##.#     ",
+    "     #.##          ##.#     ",
+    "     #.## ######## ##.#     ",
+    "######.## ######## ##.######",
+    "#............##............#",
+    "#.####.#####.##.#####.####.#",
+    "#.####.#####.##.#####.####.#",
+    "#o..##.......X .......##..o#",
+    "###.##.##.########.##.##.###",
+    "###.##.##.########.##.##.###",
+    "#......##....##....##......#",
+    "#.##########.##.##########.#",
+    "#.##########.##.##########.#",
+    "#..........................#",
+    "############################",
+];
+
+/// Game initialization constants
+pub mod startup {
+    /// Number of frames for the startup sequence (3 seconds at 60 FPS)
+    pub const STARTUP_FRAMES: u32 = 60 * 4;
+}
+
+/// Game mechanics constants
+pub mod mechanics {
+    /// Player movement speed multiplier
+    pub const PLAYER_SPEED: f32 = 1.15;
+}

pacman/src/error.rs

@@ -0,0 +1,108 @@
+//! Centralized error types for the Pac-Man game.
+//!
+//! This module defines all error types used throughout the application,
+//! providing a consistent error handling approach.
+
+use std::io;
+
+use bevy_ecs::event::Event;
+
+/// Main error type for the Pac-Man game.
+///
+/// This is the primary error type that should be used in public APIs.
+/// It can represent any error that can occur during game operation.
+#[derive(thiserror::Error, Debug, Event)]
+pub enum GameError {
+    #[error("Asset error: {0}")]
+    Asset(#[from] AssetError),
+
+    #[error("Platform error: {0}")]
+    Platform(#[from] PlatformError),
+
+    #[error("Map parsing error: {0}")]
+    MapParse(#[from] ParseError),
+
+    #[error("Map error: {0}")]
+    Map(#[from] MapError),
+
+    #[error("Texture error: {0}")]
+    Texture(#[from] TextureError),
+
+    #[error("Entity error: {0}")]
+    Entity(#[from] EntityError),
+
+    #[error("SDL error: {0}")]
+    Sdl(String),
+
+    #[error("IO error: {0}")]
+    Io(#[from] io::Error),
+
+    #[error("Invalid state: {0}")]
+    InvalidState(String),
+}
+
+#[derive(thiserror::Error, Debug)]
+pub enum AssetError {
+    #[error("IO error: {0}")]
+    Io(#[from] io::Error),
+
+    #[error("Asset not found: {0}")]
+    NotFound(String),
+}
+
+/// Platform-specific errors.
+#[derive(thiserror::Error, Debug)]
+pub enum PlatformError {
+    #[error("Console initialization failed: {0}")]
+    ConsoleInit(String),
+}
+
+/// Error type for map parsing operations.
+#[derive(thiserror::Error, Debug)]
+pub enum ParseError {
+    #[error("Unknown character in board: {0}")]
+    UnknownCharacter(char),
+    #[error("House door must have exactly 2 positions, found {0}")]
+    InvalidHouseDoorCount(usize),
+    #[error("Map parsing failed: {0}")]
+    ParseFailed(String),
+}
+
+/// Errors related to texture operations.
+#[derive(thiserror::Error, Debug)]
+pub enum TextureError {
+    #[error("Failed to load texture: {0}")]
+    LoadFailed(String),
+
+    #[error("Texture not found in atlas: {0}")]
+    AtlasTileNotFound(String),
+
+    #[error("Invalid texture format: {0}")]
+    InvalidFormat(String),
+
+    #[error("Rendering failed: {0}")]
+    RenderFailed(String),
+}
+
+/// Errors related to entity operations.
+#[derive(thiserror::Error, Debug)]
+pub enum EntityError {
+    #[error("Node not found in graph: {0}")]
+    NodeNotFound(usize),
+
+    #[error("Edge not found: from {from} to {to}")]
+    EdgeNotFound { from: usize, to: usize },
+}
+
+/// Errors related to map operations.
+#[derive(thiserror::Error, Debug)]
+pub enum MapError {
+    #[error("Node not found: {0}")]
+    NodeNotFound(usize),
+
+    #[error("Invalid map configuration: {0}")]
+    InvalidConfig(String),
+}
+
+/// Result type for game operations.
+pub type GameResult<T> = Result<T, GameError>;

pacman/src/events.rs

@@ -0,0 +1,63 @@
+use bevy_ecs::{entity::Entity, event::Event};
+
+use crate::{map::direction::Direction, systems::Ghost};
+
+/// Player input commands that trigger specific game actions.
+///
+/// Commands are generated by the input system in response to keyboard events
+/// and processed by appropriate game systems to modify state or behavior.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GameCommand {
+    /// Request immediate game shutdown
+    Exit,
+    /// Set Pac-Man's movement direction
+    MovePlayer(Direction),
+    /// Cycle through debug visualization modes
+    ToggleDebug,
+    /// Toggle audio mute state
+    MuteAudio,
+    /// Restart the current level with fresh entity positions and items
+    ResetLevel,
+    /// Pause or resume game ticking logic
+    /// TODO: Display pause state, fix debug rendering pause distress
+    TogglePause,
+    /// Toggle fullscreen mode (desktop only)
+    #[cfg(not(target_os = "emscripten"))]
+    ToggleFullscreen,
+    SingleTick,
+}
+
+/// Global events that flow through the ECS event system to coordinate game behavior.
+///
+/// Events enable loose coupling between systems - input generates commands and
+/// various systems respond appropriately without direct dependencies.
+#[derive(Event, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum GameEvent {
+    /// Player input command to be processed by relevant game systems
+    Command(GameCommand),
+}
+
+impl From<GameCommand> for GameEvent {
+    fn from(command: GameCommand) -> Self {
+        GameEvent::Command(command)
+    }
+}
+
+/// Data for requesting stage transitions; processed centrally in stage_system
+#[derive(Event, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StageTransition {
+    GhostEatenPause { ghost_entity: Entity, ghost_type: Ghost },
+}
+
+/// Collision triggers for immediate collision handling via observers
+#[derive(Event, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CollisionTrigger {
+    /// Pac-Man collided with a ghost
+    GhostCollision {
+        pacman: Entity,
+        ghost: Entity,
+        ghost_type: Ghost,
+    },
+    /// Pac-Man collided with an item
+    ItemCollision { item: Entity },
+}

pacman/src/formatter.rs

@@ -0,0 +1,152 @@
+//! Custom tracing formatter with tick counter integration
+
+use std::fmt;
+use std::sync::atomic::{AtomicU64, Ordering};
+use time::macros::format_description;
+use time::{format_description::FormatItem, OffsetDateTime};
+use tracing::{Event, Level, Subscriber};
+use tracing_subscriber::fmt::format::Writer;
+use tracing_subscriber::fmt::{FmtContext, FormatEvent, FormatFields, FormattedFields};
+use tracing_subscriber::registry::LookupSpan;
+
+/// Global atomic counter for tracking game ticks
+static TICK_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// Maximum value for tick counter display (16-bit hex)
+const TICK_DISPLAY_MASK: u64 = 0xFFFF;
+
+/// Cached format description for timestamps
+/// Uses 3 subsecond digits on Emscripten, 5 otherwise for better performance
+#[cfg(target_os = "emscripten")]
+const TIMESTAMP_FORMAT: &[FormatItem<'static>] = format_description!("[hour]:[minute]:[second].[subsecond digits:3]");
+
+#[cfg(not(target_os = "emscripten"))]
+const TIMESTAMP_FORMAT: &[FormatItem<'static>] = format_description!("[hour]:[minute]:[second].[subsecond digits:5]");
+
+/// A custom formatter that includes both timestamp and tick counter in hexadecimal
+///
+/// Re-implementation of the Full formatter to add a tick counter and timestamp.
+pub struct CustomFormatter;
+
+impl<S, N> FormatEvent<S, N> for CustomFormatter
+where
+    S: Subscriber + for<'a> LookupSpan<'a>,
+    N: for<'a> FormatFields<'a> + 'static,
+{
+    fn format_event(&self, ctx: &FmtContext<'_, S, N>, mut writer: Writer<'_>, event: &Event<'_>) -> fmt::Result {
+        let meta = event.metadata();
+
+        // 1) Timestamp (dimmed when ANSI)
+        let now = OffsetDateTime::now_utc();
+        let formatted_time = now.format(&TIMESTAMP_FORMAT).map_err(|e| {
+            eprintln!("Failed to format timestamp: {}", e);
+            fmt::Error
+        })?;
+        write_dimmed(&mut writer, formatted_time)?;
+        writer.write_char(' ')?;
+
+        // 2) Tick counter, dim when ANSI
+        let tick_count = get_tick_count() & TICK_DISPLAY_MASK;
+        if writer.has_ansi_escapes() {
+            write!(writer, "\x1b[2m0x{:04X}\x1b[0m ", tick_count)?;
+        } else {
+            write!(writer, "0x{:04X} ", tick_count)?;
+        }
+
+        // 3) Colored 5-char level like Full
+        write_colored_level(&mut writer, meta.level())?;
+        writer.write_char(' ')?;
+
+        // 4) Span scope chain (bold names, fields in braces, dimmed ':')
+        if let Some(scope) = ctx.event_scope() {
+            let mut saw_any = false;
+            for span in scope.from_root() {
+                write_bold(&mut writer, span.metadata().name())?;
+                saw_any = true;
+                let ext = span.extensions();
+                if let Some(fields) = &ext.get::<FormattedFields<N>>() {
+                    if !fields.is_empty() {
+                        write_bold(&mut writer, "{")?;
+                        write!(writer, "{}", fields)?;
+                        write_bold(&mut writer, "}")?;
+                    }
+                }
+                if writer.has_ansi_escapes() {
+                    write!(writer, "\x1b[2m:\x1b[0m")?;
+                } else {
+                    writer.write_char(':')?;
+                }
+            }
+            if saw_any {
+                writer.write_char(' ')?;
+            }
+        }
+
+        // 5) Target (dimmed), then a space
+        if writer.has_ansi_escapes() {
+            write!(writer, "\x1b[2m{}\x1b[0m\x1b[2m:\x1b[0m ", meta.target())?;
+        } else {
+            write!(writer, "{}: ", meta.target())?;
+        }
+
+        // 6) Event fields
+        ctx.format_fields(writer.by_ref(), event)?;
+
+        // 7) Newline
+        writeln!(writer)
+    }
+}
+
+/// Write the verbosity level with the same coloring/alignment as the Full formatter.
+fn write_colored_level(writer: &mut Writer<'_>, level: &Level) -> fmt::Result {
+    if writer.has_ansi_escapes() {
+        // Basic ANSI color sequences; reset with \x1b[0m
+        let (color, text) = match *level {
+            Level::TRACE => ("\x1b[35m", "TRACE"), // purple
+            Level::DEBUG => ("\x1b[34m", "DEBUG"), // blue
+            Level::INFO => ("\x1b[32m", " INFO"),  // green, note leading space
+            Level::WARN => ("\x1b[33m", " WARN"),  // yellow, note leading space
+            Level::ERROR => ("\x1b[31m", "ERROR"), // red
+        };
+        write!(writer, "{}{}\x1b[0m", color, text)
+    } else {
+        // Right-pad to width 5 like Full's non-ANSI mode
+        match *level {
+            Level::TRACE => write!(writer, "{:>5}", "TRACE"),
+            Level::DEBUG => write!(writer, "{:>5}", "DEBUG"),
+            Level::INFO => write!(writer, "{:>5}", " INFO"),
+            Level::WARN => write!(writer, "{:>5}", " WARN"),
+            Level::ERROR => write!(writer, "{:>5}", "ERROR"),
+        }
+    }
+}
+
+fn write_dimmed(writer: &mut Writer<'_>, s: impl fmt::Display) -> fmt::Result {
+    if writer.has_ansi_escapes() {
+        write!(writer, "\x1b[2m{}\x1b[0m", s)
+    } else {
+        write!(writer, "{}", s)
+    }
+}
+
+fn write_bold(writer: &mut Writer<'_>, s: impl fmt::Display) -> fmt::Result {
+    if writer.has_ansi_escapes() {
+        write!(writer, "\x1b[1m{}\x1b[0m", s)
+    } else {
+        write!(writer, "{}", s)
+    }
+}
+
+/// Increment the global tick counter by 1
+///
+/// This should be called once per game tick/frame from the main game loop
+pub fn increment_tick() {
+    TICK_COUNTER.fetch_add(1, Ordering::Relaxed);
+}
+
+/// Get the current tick count
+///
+/// Returns the current value of the global tick counter
+pub fn get_tick_count() -> u64 {
+    TICK_COUNTER.load(Ordering::Relaxed)
+}

pacman/src/game.rs

@@ -0,0 +1,786 @@
+//! This module contains the main game logic and state.
+
+include!(concat!(env!("OUT_DIR"), "/atlas_data.rs"));
+
+use std::collections::HashMap;
+use std::ops::Not;
+use tracing::{debug, info, trace, warn};
+
+use crate::constants::{self, animation, MapTile, CANVAS_SIZE};
+use crate::error::{GameError, GameResult};
+use crate::events::{CollisionTrigger, GameEvent, StageTransition};
+use crate::map::builder::Map;
+use crate::map::direction::Direction;
+use crate::systems::item::PelletCount;
+use crate::systems::state::{IntroPlayed, PauseState};
+use crate::systems::{
+    self, audio_system, blinking_system, collision_system, combined_render_system, directional_render_system,
+    dirty_render_system, eaten_ghost_system, fruit_sprite_system, ghost_collision_observer, ghost_movement_system,
+    ghost_state_system, hud_render_system, item_collision_observer, linear_render_system, player_life_sprite_system,
+    present_system, profile, time_to_live_system, touch_ui_render_system, AudioEvent, AudioResource, AudioState,
+    BackbufferResource, Blinking, BufferedDirection, Collider, DebugState, DebugTextureResource, DeltaTime, DirectionalAnimation,
+    EntityType, Frozen, FruitSprites, GameStage, Ghost, GhostAnimation, GhostAnimations, GhostBundle, GhostCollider, GhostState,
+    GlobalState, ItemBundle, ItemCollider, LastAnimationState, LinearAnimation, MapTextureResource, MovementModifiers, NodeId,
+    PacmanCollider, PlayerAnimation, PlayerBundle, PlayerControlled, PlayerDeathAnimation, PlayerLives, Position, RenderDirty,
+    Renderable, ScoreResource, StartupSequence, SystemId, SystemTimings, Timing, TouchState, Velocity, Visibility,
+};
+
+use crate::texture::animated::{DirectionalTiles, TileSequence};
+use crate::texture::sprite::AtlasTile;
+use crate::texture::sprites::{FrightenedColor, GameSprite, GhostSprite, MazeSprite, PacmanSprite};
+use bevy_ecs::change_detection::DetectChanges;
+use bevy_ecs::event::EventRegistry;
+use bevy_ecs::observer::Trigger;
+use bevy_ecs::schedule::{IntoScheduleConfigs, Schedule, SystemSet};
+use bevy_ecs::system::{Local, Res, ResMut};
+use bevy_ecs::world::World;
+use sdl2::event::EventType;
+use sdl2::image::LoadTexture;
+use sdl2::render::{BlendMode, Canvas, ScaleMode, TextureCreator};
+use sdl2::rwops::RWops;
+use sdl2::video::{Window, WindowContext};
+use sdl2::EventPump;
+
+use crate::{
+    asset::Asset,
+    events::GameCommand,
+    map::render::MapRenderer,
+    systems::{BatchedLinesResource, Bindings, CursorPosition, TtfAtlasResource},
+    texture::sprite::{AtlasMapper, SpriteAtlas},
+};
+
+/// System set for all gameplay systems to ensure they run after input processing
+#[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
+enum GameplaySet {
+    /// Gameplay systems that process inputs
+    Input,
+    /// Gameplay systems that update the game state
+    Update,
+    /// Gameplay systems that respond to events
+    Respond,
+}
+
+/// System set for all rendering systems to ensure they run after gameplay logic
+#[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
+enum RenderSet {
+    Animation,
+    Draw,
+    Present,
+}
+
+/// Core game state manager built on the Bevy ECS architecture.
+///
+/// Orchestrates all game systems through a centralized `World` containing entities,
+/// components, and resources, while a `Schedule` defines system execution order.
+/// Handles initialization of graphics resources, entity spawning, and per-frame
+/// game logic coordination. SDL2 resources are stored as `NonSend` to respect
+/// thread safety requirements while integrating with the ECS.
+pub struct Game {
+    pub world: World,
+    pub schedule: Schedule,
+}
+
+impl Game {
+    /// Initializes the complete game state including ECS world, graphics, and entity spawning.
+    ///
+    /// Performs extensive setup: creates render targets and debug textures, loads and parses
+    /// the sprite atlas, renders the static map to a cached texture, builds the navigation
+    /// graph from the board layout, spawns Pac-Man with directional animations, creates
+    /// all four ghosts with their AI behavior, and places collectible items throughout
+    /// the maze. Registers event types and configures the system execution schedule.
+    ///
+    /// # Arguments
+    ///
+    /// * `canvas` - SDL2 rendering context with static lifetime for ECS storage
+    /// * `texture_creator` - SDL2 texture factory for creating render targets
+    /// * `event_pump` - SDL2 event polling interface for input handling
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError` for SDL2 failures, asset loading problems, atlas parsing
+    /// errors, or entity initialization issues.
+    pub fn new(
+        mut canvas: Canvas<Window>,
+        ttf_context: sdl2::ttf::Sdl2TtfContext,
+        texture_creator: TextureCreator<WindowContext>,
+        mut event_pump: EventPump,
+    ) -> GameResult<Game> {
+        info!("Starting game initialization");
+
+        debug!("Disabling unnecessary SDL events");
+        Self::disable_sdl_events(&mut event_pump);
+
+        debug!("Setting up textures and fonts");
+        let (backbuffer, mut map_texture, debug_texture, ttf_atlas) =
+            Self::setup_textures_and_fonts(&mut canvas, &texture_creator, ttf_context)?;
+
+        debug!("Initializing audio subsystem");
+        let audio = crate::audio::Audio::new();
+
+        debug!("Loading sprite atlas and map tiles");
+        let (mut atlas, map_tiles) = Self::load_atlas_and_map_tiles(&texture_creator)?;
+        debug!("Rendering static map to texture cache");
+        canvas
+            .with_texture_canvas(&mut map_texture, |map_canvas| {
+                MapRenderer::render_map(map_canvas, &mut atlas, &map_tiles);
+            })
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        debug!("Building navigation graph from map layout");
+        let map = Map::new(constants::RAW_BOARD)?;
+
+        debug!("Creating player animations and bundle");
+        let (player_animation, player_start_sprite) = Self::create_player_animations(&atlas)?;
+        let player_bundle = Self::create_player_bundle(&map, player_animation, player_start_sprite);
+
+        debug!("Creating death animation sequence");
+        let death_animation = Self::create_death_animation(&atlas)?;
+
+        debug!("Initializing ECS world and system schedule");
+        let mut world = World::default();
+        let mut schedule = Schedule::default();
+
+        debug!("Setting up ECS event registry and observers");
+        Self::setup_ecs(&mut world);
+
+        world.add_observer(systems::spawn_fruit_observer);
+
+        debug!("Inserting resources into ECS world");
+        Self::insert_resources(
+            &mut world,
+            map,
+            audio,
+            atlas,
+            event_pump,
+            canvas,
+            backbuffer,
+            map_texture,
+            debug_texture,
+            ttf_atlas,
+            death_animation,
+        )?;
+
+        debug!("Configuring system execution schedule");
+        Self::configure_schedule(&mut schedule);
+
+        debug!("Spawning player entity");
+        world.spawn(player_bundle).insert((Frozen, Visibility::hidden()));
+
+        info!("Spawning game entities");
+        Self::spawn_ghosts(&mut world)?;
+        Self::spawn_items(&mut world)?;
+
+        info!("Game initialization completed successfully");
+        Ok(Game { world, schedule })
+    }
+
+    fn disable_sdl_events(event_pump: &mut EventPump) {
+        for event_type in [
+            EventType::JoyAxisMotion,
+            EventType::JoyBallMotion,
+            EventType::JoyHatMotion,
+            EventType::JoyButtonDown,
+            EventType::JoyButtonUp,
+            EventType::JoyDeviceAdded,
+            EventType::JoyDeviceRemoved,
+            EventType::ControllerAxisMotion,
+            EventType::ControllerButtonDown,
+            EventType::ControllerButtonUp,
+            EventType::ControllerDeviceAdded,
+            EventType::ControllerDeviceRemoved,
+            EventType::ControllerDeviceRemapped,
+            EventType::ControllerTouchpadDown,
+            EventType::ControllerTouchpadMotion,
+            EventType::ControllerTouchpadUp,
+            EventType::DollarGesture,
+            EventType::DollarRecord,
+            EventType::MultiGesture,
+            EventType::ClipboardUpdate,
+            EventType::DropFile,
+            EventType::DropText,
+            EventType::DropBegin,
+            EventType::DropComplete,
+            EventType::AudioDeviceAdded,
+            EventType::AudioDeviceRemoved,
+            EventType::RenderTargetsReset,
+            EventType::RenderDeviceReset,
+            EventType::LocaleChanged,
+            EventType::TextInput,
+            EventType::TextEditing,
+            EventType::Display,
+            EventType::MouseWheel,
+            EventType::AppDidEnterBackground,
+            EventType::AppWillEnterForeground,
+            EventType::AppWillEnterBackground,
+            EventType::AppDidEnterForeground,
+            EventType::AppLowMemory,
+            EventType::AppTerminating,
+            EventType::User,
+            EventType::Last,
+        ] {
+            event_pump.disable_event(event_type);
+        }
+    }
+
+    fn setup_textures_and_fonts(
+        canvas: &mut Canvas<Window>,
+        texture_creator: &TextureCreator<WindowContext>,
+        ttf_context: sdl2::ttf::Sdl2TtfContext,
+    ) -> GameResult<(
+        sdl2::render::Texture,
+        sdl2::render::Texture,
+        sdl2::render::Texture,
+        crate::texture::ttf::TtfAtlas,
+    )> {
+        let mut backbuffer = texture_creator
+            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        backbuffer.set_scale_mode(ScaleMode::Nearest);
+
+        let mut map_texture = texture_creator
+            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        map_texture.set_scale_mode(ScaleMode::Nearest);
+
+        let output_size = constants::LARGE_CANVAS_SIZE;
+        let mut debug_texture = texture_creator
+            .create_texture_target(Some(sdl2::pixels::PixelFormatEnum::ARGB8888), output_size.x, output_size.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        debug_texture.set_blend_mode(BlendMode::Blend);
+        debug_texture.set_scale_mode(ScaleMode::Nearest);
+
+        let font_data: &'static [u8] = Asset::Font.get_bytes()?.to_vec().leak();
+        let font_asset = RWops::from_bytes(font_data).map_err(|_| GameError::Sdl("Failed to load font".to_string()))?;
+        let debug_font = ttf_context
+            .load_font_from_rwops(font_asset, constants::ui::DEBUG_FONT_SIZE)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        let mut ttf_atlas = crate::texture::ttf::TtfAtlas::new(texture_creator, &debug_font)?;
+        ttf_atlas.populate_atlas(canvas, texture_creator, &debug_font)?;
+
+        Ok((backbuffer, map_texture, debug_texture, ttf_atlas))
+    }
+
+    fn load_atlas_and_map_tiles(texture_creator: &TextureCreator<WindowContext>) -> GameResult<(SpriteAtlas, Vec<AtlasTile>)> {
+        trace!("Loading atlas image from embedded assets");
+        let atlas_bytes = Asset::AtlasImage.get_bytes()?;
+        let atlas_texture = texture_creator.load_texture_bytes(&atlas_bytes).map_err(|e| {
+            if e.to_string().contains("format") || e.to_string().contains("unsupported") {
+                GameError::Texture(crate::error::TextureError::InvalidFormat(format!(
+                    "Unsupported texture format: {e}"
+                )))
+            } else {
+                GameError::Texture(crate::error::TextureError::LoadFailed(e.to_string()))
+            }
+        })?;
+
+        debug!(frame_count = ATLAS_FRAMES.len(), "Creating sprite atlas from texture");
+        let atlas_mapper = AtlasMapper {
+            frames: ATLAS_FRAMES.into_iter().map(|(k, v)| (k.to_string(), *v)).collect(),
+        };
+        let atlas = SpriteAtlas::new(atlas_texture, atlas_mapper);
+
+        trace!("Extracting map tile sprites from atlas");
+        let mut map_tiles = Vec::with_capacity(35);
+        for i in 0..35 {
+            let tile_name = GameSprite::Maze(MazeSprite::Tile(i)).to_path();
+            let tile = atlas.get_tile(&tile_name)?;
+            map_tiles.push(tile);
+        }
+
+        Ok((atlas, map_tiles))
+    }
+
+    fn create_player_animations(atlas: &SpriteAtlas) -> GameResult<(DirectionalAnimation, AtlasTile)> {
+        let up_moving_tiles = [
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Up, 0)).to_path())?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Up, 1)).to_path())?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Full).to_path())?,
+        ];
+        let down_moving_tiles = [
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Down, 0)).to_path())?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Down, 1)).to_path())?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Full).to_path())?,
+        ];
+        let left_moving_tiles = [
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Left, 0)).to_path())?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Left, 1)).to_path())?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Full).to_path())?,
+        ];
+        let right_moving_tiles = [
+            SpriteAtlas::get_tile(
+                atlas,
+                &GameSprite::Pacman(PacmanSprite::Moving(Direction::Right, 0)).to_path(),
+            )?,
+            SpriteAtlas::get_tile(
+                atlas,
+                &GameSprite::Pacman(PacmanSprite::Moving(Direction::Right, 1)).to_path(),
+            )?,
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Full).to_path())?,
+        ];
+
+        let moving_tiles = DirectionalTiles::new(
+            TileSequence::new(&up_moving_tiles),
+            TileSequence::new(&down_moving_tiles),
+            TileSequence::new(&left_moving_tiles),
+            TileSequence::new(&right_moving_tiles),
+        );
+
+        let up_stopped_tile =
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Up, 1)).to_path())?;
+        let down_stopped_tile =
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Down, 1)).to_path())?;
+        let left_stopped_tile =
+            SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Moving(Direction::Left, 1)).to_path())?;
+        let right_stopped_tile = SpriteAtlas::get_tile(
+            atlas,
+            &GameSprite::Pacman(PacmanSprite::Moving(Direction::Right, 1)).to_path(),
+        )?;
+
+        let stopped_tiles = DirectionalTiles::new(
+            TileSequence::new(&[up_stopped_tile]),
+            TileSequence::new(&[down_stopped_tile]),
+            TileSequence::new(&[left_stopped_tile]),
+            TileSequence::new(&[right_stopped_tile]),
+        );
+
+        let player_animation = DirectionalAnimation::new(moving_tiles, stopped_tiles, 5);
+        let player_start_sprite = SpriteAtlas::get_tile(atlas, &GameSprite::Pacman(PacmanSprite::Full).to_path())?;
+
+        Ok((player_animation, player_start_sprite))
+    }
+
+    fn create_death_animation(atlas: &SpriteAtlas) -> GameResult<LinearAnimation> {
+        let mut death_tiles = Vec::new();
+        for i in 0..=10 {
+            // Assuming death animation has 11 frames named pacman/die_0, pacman/die_1, etc.
+            let tile = atlas.get_tile(&GameSprite::Pacman(PacmanSprite::Dying(i)).to_path())?;
+            death_tiles.push(tile);
+        }
+
+        let tile_sequence = TileSequence::new(&death_tiles);
+        Ok(LinearAnimation::new(tile_sequence, 8)) // 8 ticks per frame, non-looping
+    }
+
+    fn create_player_bundle(map: &Map, player_animation: DirectionalAnimation, player_start_sprite: AtlasTile) -> PlayerBundle {
+        PlayerBundle {
+            player: PlayerControlled,
+            position: Position::Stopped {
+                node: map.start_positions.pacman,
+            },
+            velocity: Velocity {
+                speed: constants::mechanics::PLAYER_SPEED,
+                direction: Direction::Left,
+            },
+            movement_modifiers: MovementModifiers::default(),
+            buffered_direction: BufferedDirection::None,
+            sprite: Renderable {
+                sprite: player_start_sprite,
+                layer: 0,
+            },
+            directional_animation: player_animation,
+            entity_type: EntityType::Player,
+            collider: Collider {
+                size: constants::collider::PLAYER_SIZE,
+            },
+            pacman_collider: PacmanCollider,
+        }
+    }
+
+    fn setup_ecs(world: &mut World) {
+        EventRegistry::register_event::<GameError>(world);
+        EventRegistry::register_event::<GameEvent>(world);
+        EventRegistry::register_event::<AudioEvent>(world);
+        EventRegistry::register_event::<StageTransition>(world);
+        EventRegistry::register_event::<CollisionTrigger>(world);
+
+        world.add_observer(
+            |event: Trigger<GameEvent>, mut state: ResMut<GlobalState>, _score: ResMut<ScoreResource>| {
+                if matches!(*event, GameEvent::Command(GameCommand::Exit)) {
+                    state.exit = true;
+                }
+            },
+        );
+
+        world.add_observer(ghost_collision_observer);
+        world.add_observer(item_collision_observer);
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn insert_resources(
+        world: &mut World,
+        map: Map,
+        audio: crate::audio::Audio,
+        atlas: SpriteAtlas,
+        event_pump: EventPump,
+        canvas: Canvas<Window>,
+        backbuffer: sdl2::render::Texture,
+        map_texture: sdl2::render::Texture,
+        debug_texture: sdl2::render::Texture,
+        ttf_atlas: crate::texture::ttf::TtfAtlas,
+        death_animation: LinearAnimation,
+    ) -> GameResult<()> {
+        world.insert_non_send_resource(atlas);
+        world.insert_resource(Self::create_ghost_animations(world.non_send_resource::<SpriteAtlas>())?);
+        let player_animation = Self::create_player_animations(world.non_send_resource::<SpriteAtlas>())?.0;
+        world.insert_resource(PlayerAnimation(player_animation));
+        world.insert_resource(PlayerDeathAnimation(death_animation));
+
+        world.insert_resource(FruitSprites::default());
+        world.insert_resource(BatchedLinesResource::new(&map, constants::LARGE_SCALE));
+        world.insert_resource(map);
+        world.insert_resource(GlobalState { exit: false });
+        world.insert_resource(PlayerLives::default());
+        world.insert_resource(ScoreResource(0));
+        world.insert_resource(PelletCount(0));
+        world.insert_resource(SystemTimings::default());
+        world.insert_resource(Timing::default());
+        world.insert_resource(Bindings::default());
+        world.insert_resource(DeltaTime { seconds: 0.0, ticks: 0 });
+        world.insert_resource(RenderDirty::default());
+        world.insert_resource(DebugState::default());
+        world.insert_resource(AudioState::default());
+        world.insert_resource(IntroPlayed::default());
+        world.insert_resource(CursorPosition::default());
+        world.insert_resource(TouchState::default());
+        world.insert_resource(GameStage::Starting(StartupSequence::TextOnly {
+            remaining_ticks: constants::startup::STARTUP_FRAMES,
+        }));
+        world.insert_resource(PauseState::default());
+
+        world.insert_non_send_resource(event_pump);
+        world.insert_non_send_resource::<&mut Canvas<Window>>(Box::leak(Box::new(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(TtfAtlasResource(ttf_atlas));
+        world.insert_non_send_resource(AudioResource(audio));
+        Ok(())
+    }
+
+    fn configure_schedule(schedule: &mut Schedule) {
+        let stage_system = profile(SystemId::Stage, systems::stage_system);
+        let input_system = profile(SystemId::Input, systems::input::input_system);
+        let pause_system = profile(SystemId::Input, systems::handle_pause_command);
+        let player_control_system = profile(SystemId::PlayerControls, systems::player_control_system);
+        let player_movement_system = profile(SystemId::PlayerMovement, systems::player_movement_system);
+        let player_tunnel_slowdown_system = profile(SystemId::PlayerMovement, systems::player::player_tunnel_slowdown_system);
+        let ghost_movement_system = profile(SystemId::Ghost, ghost_movement_system);
+        let collision_system = profile(SystemId::Collision, collision_system);
+        let audio_system = profile(SystemId::Audio, audio_system);
+        let blinking_system = profile(SystemId::Blinking, blinking_system);
+        let directional_render_system = profile(SystemId::DirectionalRender, directional_render_system);
+        let linear_render_system = profile(SystemId::LinearRender, linear_render_system);
+        let dirty_render_system = profile(SystemId::DirtyRender, dirty_render_system);
+        let hud_render_system = profile(SystemId::HudRender, hud_render_system);
+        let player_life_sprite_system = profile(SystemId::HudRender, player_life_sprite_system);
+        let fruit_sprite_system = profile(SystemId::HudRender, fruit_sprite_system);
+        let present_system = profile(SystemId::Present, present_system);
+        let unified_ghost_state_system = profile(SystemId::GhostStateAnimation, ghost_state_system);
+        let eaten_ghost_system = profile(SystemId::EatenGhost, eaten_ghost_system);
+        let time_to_live_system = profile(SystemId::TimeToLive, time_to_live_system);
+        let manage_pause_state_system = profile(SystemId::PauseManager, systems::state::manage_pause_state_system);
+
+        // Input system should always run to prevent SDL event pump from blocking
+        let input_systems = (
+            input_system.run_if(|mut local: Local<u8>| {
+                *local = local.wrapping_add(1u8);
+                // run every nth frame
+                *local % 2 == 0
+            }),
+            player_control_system,
+            pause_system,
+            #[cfg(not(target_os = "emscripten"))]
+            profile(SystemId::Input, systems::handle_fullscreen_command),
+        )
+            .chain();
+
+        // .run_if(|game_state: Res<GameStage>| matches!(*game_state, GameStage::Playing));
+
+        schedule
+            .add_systems((
+                input_systems.in_set(GameplaySet::Input),
+                time_to_live_system.before(GameplaySet::Update),
+                (
+                    player_movement_system,
+                    player_tunnel_slowdown_system,
+                    ghost_movement_system,
+                    eaten_ghost_system,
+                    collision_system,
+                    unified_ghost_state_system,
+                )
+                    .in_set(GameplaySet::Update),
+                (
+                    blinking_system,
+                    directional_render_system,
+                    linear_render_system,
+                    player_life_sprite_system,
+                    fruit_sprite_system,
+                )
+                    .in_set(RenderSet::Animation),
+                stage_system.in_set(GameplaySet::Respond),
+                (
+                    (|mut dirty: ResMut<RenderDirty>, score: Res<ScoreResource>, stage: Res<GameStage>| {
+                        dirty.0 = score.is_changed() || stage.is_changed();
+                    }),
+                    dirty_render_system.run_if(|dirty: Res<RenderDirty>| dirty.0.not()),
+                    combined_render_system,
+                    hud_render_system,
+                    touch_ui_render_system,
+                )
+                    .chain()
+                    .in_set(RenderSet::Draw),
+                (present_system, audio_system).chain().in_set(RenderSet::Present),
+                manage_pause_state_system.after(GameplaySet::Update),
+            ))
+            .configure_sets((
+                GameplaySet::Input,
+                GameplaySet::Update.run_if(|paused: Res<PauseState>| paused.active()),
+                GameplaySet::Respond.run_if(|paused: Res<PauseState>| paused.active()),
+                RenderSet::Animation.run_if(|paused: Res<PauseState>| paused.active()),
+                RenderSet::Draw,
+                RenderSet::Present,
+            ));
+    }
+
+    fn spawn_items(world: &mut World) -> GameResult<()> {
+        trace!("Loading item sprites from atlas");
+        let pellet_sprite = SpriteAtlas::get_tile(
+            world.non_send_resource::<SpriteAtlas>(),
+            &GameSprite::Maze(MazeSprite::Pellet).to_path(),
+        )?;
+        let energizer_sprite = SpriteAtlas::get_tile(
+            world.non_send_resource::<SpriteAtlas>(),
+            &GameSprite::Maze(MazeSprite::Energizer).to_path(),
+        )?;
+
+        let nodes: Vec<(NodeId, EntityType, AtlasTile, f32)> = world
+            .resource::<Map>()
+            .iter_nodes()
+            .filter_map(|(id, tile)| match tile {
+                MapTile::Pellet => Some((*id, EntityType::Pellet, pellet_sprite, constants::collider::PELLET_SIZE)),
+                MapTile::PowerPellet => Some((
+                    *id,
+                    EntityType::PowerPellet,
+                    energizer_sprite,
+                    constants::collider::POWER_PELLET_SIZE,
+                )),
+                _ => None,
+            })
+            .collect();
+
+        info!(
+            pellet_count = nodes.iter().filter(|(_, t, _, _)| *t == EntityType::Pellet).count(),
+            power_pellet_count = nodes.iter().filter(|(_, t, _, _)| *t == EntityType::PowerPellet).count(),
+            "Spawning collectible items"
+        );
+
+        for (id, item_type, sprite, size) in nodes {
+            let mut item = world.spawn(ItemBundle {
+                position: Position::Stopped { node: id },
+                sprite: Renderable { sprite, layer: 1 },
+                entity_type: item_type,
+                collider: Collider { size },
+                item_collider: ItemCollider,
+            });
+
+            if item_type == EntityType::PowerPellet {
+                item.insert((Frozen, Blinking::new(constants::ui::POWER_PELLET_BLINK_RATE)));
+            }
+        }
+        Ok(())
+    }
+
+    /// Creates and spawns all four ghosts with unique AI personalities and directional animations.
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError::Texture` if any ghost sprite cannot be found in the atlas,
+    /// typically indicating missing or misnamed sprite files.
+    fn spawn_ghosts(world: &mut World) -> GameResult<()> {
+        trace!("Spawning ghost entities with AI personalities");
+        // Extract the data we need first to avoid borrow conflicts
+        let ghost_start_positions = {
+            let map = world.resource::<Map>();
+            [
+                (Ghost::Blinky, map.start_positions.blinky),
+                (Ghost::Pinky, map.start_positions.pinky),
+                (Ghost::Inky, map.start_positions.inky),
+                (Ghost::Clyde, map.start_positions.clyde),
+            ]
+        };
+
+        for (ghost_type, start_node) in ghost_start_positions {
+            // Create the ghost bundle in a separate scope to manage borrows
+            let ghost = {
+                let animations = world.resource::<GhostAnimations>().get_normal(&ghost_type).unwrap().clone();
+                let atlas = world.non_send_resource::<SpriteAtlas>();
+                let sprite_path = GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Left, 0)).to_path();
+
+                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, &sprite_path)?,
+                        layer: 0,
+                    },
+                    directional_animation: animations,
+                    entity_type: EntityType::Ghost,
+                    collider: Collider {
+                        size: constants::collider::GHOST_SIZE,
+                    },
+                    ghost_collider: GhostCollider,
+                    ghost_state: GhostState::Normal,
+                    last_animation_state: LastAnimationState(GhostAnimation::Normal),
+                }
+            };
+
+            let entity = world.spawn(ghost).insert((Frozen, Visibility::hidden())).id();
+            trace!(ghost = ?ghost_type, entity = ?entity, start_node, "Spawned ghost entity");
+        }
+
+        info!("All ghost entities spawned successfully");
+        Ok(())
+    }
+
+    fn create_ghost_animations(atlas: &SpriteAtlas) -> GameResult<GhostAnimations> {
+        // Eaten (eyes) animations - single tile per direction
+        let up_eye = atlas.get_tile(&GameSprite::Ghost(GhostSprite::Eyes(Direction::Up)).to_path())?;
+        let down_eye = atlas.get_tile(&GameSprite::Ghost(GhostSprite::Eyes(Direction::Down)).to_path())?;
+        let left_eye = atlas.get_tile(&GameSprite::Ghost(GhostSprite::Eyes(Direction::Left)).to_path())?;
+        let right_eye = atlas.get_tile(&GameSprite::Ghost(GhostSprite::Eyes(Direction::Right)).to_path())?;
+
+        let eyes_tiles = DirectionalTiles::new(
+            TileSequence::new(&[up_eye]),
+            TileSequence::new(&[down_eye]),
+            TileSequence::new(&[left_eye]),
+            TileSequence::new(&[right_eye]),
+        );
+        let eyes = DirectionalAnimation::new(eyes_tiles.clone(), eyes_tiles, animation::GHOST_EATEN_SPEED);
+
+        let mut animations = HashMap::new();
+
+        for ghost_type in [Ghost::Blinky, Ghost::Pinky, Ghost::Inky, Ghost::Clyde] {
+            // Normal animations - create directional tiles for each direction
+            let up_tiles = [
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Up, 0)).to_path())?,
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Up, 1)).to_path())?,
+            ];
+            let down_tiles = [
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Down, 0)).to_path())?,
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Down, 1)).to_path())?,
+            ];
+            let left_tiles = [
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Left, 0)).to_path())?,
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Left, 1)).to_path())?,
+            ];
+            let right_tiles = [
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Right, 0)).to_path())?,
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Normal(ghost_type, Direction::Right, 1)).to_path())?,
+            ];
+
+            let normal_moving = DirectionalTiles::new(
+                TileSequence::new(&up_tiles),
+                TileSequence::new(&down_tiles),
+                TileSequence::new(&left_tiles),
+                TileSequence::new(&right_tiles),
+            );
+            let normal = DirectionalAnimation::new(normal_moving.clone(), normal_moving, animation::GHOST_NORMAL_SPEED);
+
+            animations.insert(ghost_type, normal);
+        }
+
+        let (frightened, frightened_flashing) = {
+            // Load frightened animation tiles (same for all ghosts)
+            let frightened_blue_a =
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Frightened(FrightenedColor::Blue, 0)).to_path())?;
+            let frightened_blue_b =
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Frightened(FrightenedColor::Blue, 1)).to_path())?;
+            let frightened_white_a =
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Frightened(FrightenedColor::White, 0)).to_path())?;
+            let frightened_white_b =
+                atlas.get_tile(&GameSprite::Ghost(GhostSprite::Frightened(FrightenedColor::White, 1)).to_path())?;
+
+            (
+                LinearAnimation::new(
+                    TileSequence::new(&[frightened_blue_a, frightened_blue_b]),
+                    animation::GHOST_NORMAL_SPEED,
+                ),
+                LinearAnimation::new(
+                    TileSequence::new(&[frightened_blue_a, frightened_white_a, frightened_blue_b, frightened_white_b]),
+                    animation::GHOST_FRIGHTENED_SPEED,
+                ),
+            )
+        };
+
+        Ok(GhostAnimations::new(animations, eyes, frightened, frightened_flashing))
+    }
+
+    /// Executes one frame of game logic by running all scheduled ECS systems.
+    ///
+    /// Updates the world's delta time resource and runs the complete system pipeline:
+    /// input processing, entity movement, collision detection, item collection,
+    /// audio playback, animation updates, and rendering. Each system operates on
+    /// relevant entities and modifies world state, with the schedule ensuring
+    /// proper execution order and data dependencies.
+    ///
+    /// # Arguments
+    ///
+    /// * `dt` - Frame delta time in seconds for time-based animations and movement
+    ///
+    /// # Returns
+    ///
+    /// `true` if the game should terminate (exit command received), `false` to continue
+    pub fn tick(&mut self, dt: f32) -> bool {
+        self.world.insert_resource(DeltaTime { seconds: dt, ticks: 1 });
+
+        // Note: We don't need to read the current tick here since we increment it after running systems
+
+        // Measure total frame time including all systems
+        let start = std::time::Instant::now();
+        self.schedule.run(&mut self.world);
+        let total_duration = start.elapsed();
+
+        // Increment tick counter and record the total timing
+        if let (Some(timings), Some(timing)) = (
+            self.world.get_resource::<systems::profiling::SystemTimings>(),
+            self.world.get_resource::<Timing>(),
+        ) {
+            let new_tick = timing.increment_tick();
+            timings.add_total_timing(total_duration, new_tick);
+
+            // Log performance warnings for slow frames
+            if total_duration.as_millis() > 17 {
+                // Warn if frame takes too long
+                let slowest_systems = timings.get_slowest_systems();
+                let systems_context = if slowest_systems.is_empty() {
+                    "No specific systems identified".to_string()
+                } else {
+                    slowest_systems
+                        .iter()
+                        .map(|(id, duration)| format!("{} ({:.2?})", id, duration))
+                        .collect::<Vec<String>>()
+                        .join(", ")
+                };
+
+                warn!(
+                    total = format!("{:.3?}", total_duration),
+                    tick = new_tick,
+                    systems = systems_context,
+                    "Frame took longer than expected"
+                );
+            }
+        }
+
+        let state = self
+            .world
+            .get_resource::<GlobalState>()
+            .expect("GlobalState could not be acquired");
+
+        state.exit
+    }
+}

pacman/src/lib.rs

@@ -0,0 +1,22 @@
+//! Pac-Man game library crate.
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod app;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod audio;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod error;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod events;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod formatter;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod platform;
+
+pub mod asset;
+pub mod constants;
+pub mod game;
+pub mod map;
+pub mod systems;
+pub mod texture;

pacman/src/main.rs

@@ -0,0 +1,53 @@
+#![cfg_attr(all(not(use_console), target_os = "windows"), windows_subsystem = "windows")]
+#![cfg_attr(all(use_console, target_os = "windows"), windows_subsystem = "console")]
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+#![cfg_attr(coverage_nightly, coverage(off))]
+
+use std::env;
+
+use crate::{app::App, constants::LOOP_TIME};
+use tracing::info;
+
+// These modules are excluded from coverage.
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod app;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod audio;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod error;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod events;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod formatter;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod platform;
+
+mod asset;
+mod constants;
+mod game;
+mod map;
+mod systems;
+mod texture;
+
+/// The main entry point of the application.
+///
+/// This function initializes SDL, the window, the game state, and then enters
+/// the main game loop.
+pub fn main() {
+    // Parse command line arguments
+    let args: Vec<String> = env::args().collect();
+    let force_console = args.iter().any(|arg| arg == "--console" || arg == "-c");
+
+    // On Emscripten, this connects the subscriber to the browser console
+    platform::init_console(force_console).expect("Could not initialize console");
+
+    let mut app = App::new().expect("Could not create app");
+
+    info!(loop_time = ?LOOP_TIME, "Starting game loop");
+
+    loop {
+        if !app.run() {
+            break;
+        }
+    }
+}

pacman/src/map/builder.rs

@@ -0,0 +1,428 @@
+//! Map construction and building functionality.
+use crate::constants::{MapTile, BOARD_CELL_SIZE, CELL_SIZE};
+use crate::map::direction::Direction;
+use crate::map::graph::{Graph, Node, TraversalFlags};
+use crate::map::parser::MapTileParser;
+use crate::systems::{NodeId, Position};
+use bevy_ecs::resource::Resource;
+use glam::{I8Vec2, IVec2, Vec2};
+use std::collections::{HashMap, VecDeque};
+use tracing::debug;
+
+use crate::error::{GameResult, MapError};
+
+/// Predefined spawn locations for all game entities within the navigation graph.
+///
+/// These positions are determined during map parsing and graph construction.
+pub struct NodePositions {
+    /// Pac-Man's starting position in the lower section of the maze
+    pub pacman: NodeId,
+    /// Blinky starts at the ghost house entrance
+    pub blinky: NodeId,
+    /// Pinky starts in the left area of the ghost house
+    pub pinky: NodeId,
+    /// Inky starts in the right area of the ghost house
+    pub inky: NodeId,
+    /// Clyde starts in the center of the ghost house
+    pub clyde: NodeId,
+    /// Fruit spawn location directly below the ghost house
+    pub fruit_spawn: Position,
+}
+
+/// Complete maze representation combining visual layout with navigation pathfinding.
+///
+/// Transforms the ASCII board layout into a fully connected navigation graph
+/// while preserving tile-based collision and rendering data. The graph enables
+/// smooth entity movement with proper pathfinding, while the grid mapping allows
+/// efficient spatial queries and debug visualization.
+#[derive(Resource)]
+pub struct Map {
+    /// Connected graph of navigable positions.
+    pub graph: Graph,
+    /// Bidirectional mapping between 2D grid coordinates and graph node indices.
+    pub grid_to_node: HashMap<I8Vec2, NodeId>,
+    /// Predetermined spawn locations for all game entities
+    pub start_positions: NodePositions,
+    /// 2D array of tile types for collision detection and rendering
+    tiles: [[MapTile; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize],
+}
+
+impl Map {
+    /// Creates a new `Map` instance from a raw board layout.
+    ///
+    /// This constructor initializes the map tiles based on the provided character layout
+    /// and then generates a navigation graph from the walkable areas.
+    ///
+    /// # Panics
+    ///
+    /// This function will panic if the board layout contains unknown characters or if
+    /// the house door is not defined by exactly two '=' characters.
+    pub fn new(raw_board: [&str; BOARD_CELL_SIZE.y as usize]) -> GameResult<Map> {
+        debug!("Starting map construction from character layout");
+        let parsed_map = MapTileParser::parse_board(raw_board)?;
+
+        let map = parsed_map.tiles;
+        let house_door = parsed_map.house_door;
+        let tunnel_ends = parsed_map.tunnel_ends;
+        debug!(
+            house_door_count = house_door.len(),
+            tunnel_ends_count = tunnel_ends.len(),
+            "Parsed map special locations"
+        );
+
+        let mut graph = Graph::new();
+        let mut grid_to_node = HashMap::new();
+
+        let cell_offset = Vec2::splat(CELL_SIZE as f32 / 2.0);
+
+        // Find a starting point for the graph generation, preferably Pac-Man's position.
+        let start_pos = parsed_map
+            .pacman_start
+            .ok_or_else(|| MapError::InvalidConfig("Pac-Man's starting position not found".to_string()))?;
+
+        // Add the starting position to the graph/queue
+        let mut queue = VecDeque::new();
+        queue.push_back(start_pos);
+        let pos = Vec2::new(
+            (start_pos.x as i32 * CELL_SIZE as i32) as f32,
+            (start_pos.y as i32 * CELL_SIZE as i32) as f32,
+        ) + cell_offset;
+        let node_id = graph.add_node(Node { position: pos });
+        grid_to_node.insert(start_pos, node_id);
+
+        // Iterate over the queue, adding nodes to the graph and connecting them to their neighbors
+        while let Some(source_position) = queue.pop_front() {
+            for dir in Direction::DIRECTIONS {
+                let new_position = source_position + dir.as_ivec2();
+
+                // Skip if the new position is out of bounds
+                if new_position.x < 0
+                    || new_position.x as i32 >= BOARD_CELL_SIZE.x as i32
+                    || new_position.y < 0
+                    || new_position.y as i32 >= BOARD_CELL_SIZE.y as i32
+                {
+                    continue;
+                }
+
+                // Skip if the new position is already in the graph
+                if grid_to_node.contains_key(&new_position) {
+                    continue;
+                }
+
+                // Skip if the new position is not a walkable tile
+                if matches!(
+                    map[new_position.x as usize][new_position.y as usize],
+                    MapTile::Pellet | MapTile::PowerPellet | MapTile::Empty | MapTile::Tunnel
+                ) {
+                    // Add the new position to the graph/queue
+                    let pos = Vec2::new(
+                        (new_position.x as i32 * CELL_SIZE as i32) as f32,
+                        (new_position.y as i32 * CELL_SIZE as i32) as f32,
+                    ) + cell_offset;
+                    let new_node_id = graph.add_node(Node { position: pos });
+                    grid_to_node.insert(new_position, new_node_id);
+                    queue.push_back(new_position);
+
+                    // Connect the new node to the source node
+                    let source_node_id = grid_to_node
+                        .get(&source_position)
+                        .unwrap_or_else(|| panic!("Source node not found for {source_position}"));
+
+                    // Connect the new node to the source node
+                    graph
+                        .connect(*source_node_id, new_node_id, false, None, dir)
+                        .map_err(|e| MapError::InvalidConfig(format!("Failed to add edge: {e}")))?;
+                }
+            }
+        }
+
+        // While most nodes are already connected to their neighbors, some may not be, so we need to connect them
+        for (grid_pos, &node_id) in &grid_to_node {
+            for dir in Direction::DIRECTIONS {
+                // If the node doesn't have an edge in this direction, look for a neighbor in that direction
+                if graph.adjacency_list[node_id as usize].get(dir).is_none() {
+                    let neighbor = grid_pos + dir.as_ivec2();
+                    // If the neighbor exists, connect the node to it
+                    if let Some(&neighbor_id) = grid_to_node.get(&neighbor) {
+                        graph
+                            .connect(node_id, neighbor_id, false, None, dir)
+                            .map_err(|e| MapError::InvalidConfig(format!("Failed to add edge: {e}")))?;
+                    }
+                }
+            }
+        }
+
+        // Build house structure
+        let (house_entrance_node_id, left_center_node_id, center_center_node_id, right_center_node_id) =
+            Self::build_house(&mut graph, &grid_to_node, &house_door)?;
+
+        // Find fruit spawn location (directly below ghost house)
+        let left_node_position = I8Vec2::new(13, 17);
+        let left_node_id = grid_to_node.get(&left_node_position).unwrap();
+        let right_node_position = I8Vec2::new(14, 17);
+        let right_node_id = grid_to_node.get(&right_node_position).unwrap();
+
+        let distance = graph
+            .get_node(*right_node_id)
+            .unwrap()
+            .position
+            .distance(graph.get_node(*left_node_id).unwrap().position);
+
+        // interpolate between the two nodes
+        let fruit_spawn_position: Position = Position::Moving {
+            from: *left_node_id,
+            to: *right_node_id,
+            remaining_distance: distance / 2.0,
+        };
+
+        let start_positions = NodePositions {
+            pacman: grid_to_node[&start_pos],
+            blinky: house_entrance_node_id,
+            pinky: left_center_node_id,
+            inky: right_center_node_id,
+            clyde: center_center_node_id,
+            fruit_spawn: fruit_spawn_position,
+        };
+
+        // Build tunnel connections
+        debug!("Building tunnel connections");
+        Self::build_tunnels(&mut graph, &grid_to_node, &tunnel_ends)?;
+
+        debug!(node_count = graph.nodes().count(), "Map construction completed successfully");
+        Ok(Map {
+            graph,
+            grid_to_node,
+            start_positions,
+            tiles: map,
+        })
+    }
+
+    pub fn iter_nodes(&self) -> impl Iterator<Item = (&NodeId, &MapTile)> {
+        self.grid_to_node.iter().map(move |(pos, node_id)| {
+            let tile = &self.tiles[pos.x as usize][pos.y as usize];
+            (node_id, tile)
+        })
+    }
+
+    /// Returns the `MapTile` at a given node id.
+    pub fn tile_at_node(&self, node_id: NodeId) -> Option<MapTile> {
+        // reverse lookup: node -> grid
+        for (grid_pos, id) in &self.grid_to_node {
+            if *id == node_id {
+                return Some(self.tiles[grid_pos.x as usize][grid_pos.y as usize]);
+            }
+        }
+        None
+    }
+
+    /// Constructs the ghost house area with restricted access and internal navigation.
+    ///
+    /// Creates a multi-level ghost house with entrance control, internal movement
+    /// areas, and starting positions for each ghost. The house entrance uses
+    /// ghost-only traversal flags to prevent Pac-Man from entering while allowing
+    /// ghosts to exit. Internal nodes are arranged in vertical lines to provide
+    /// distinct starting areas for each ghost character.
+    ///
+    /// # Returns
+    ///
+    /// Tuple of node IDs: (house_entrance, left_center, center_center, right_center)
+    /// representing the four key positions within the ghost house structure.
+    fn build_house(
+        graph: &mut Graph,
+        grid_to_node: &HashMap<I8Vec2, NodeId>,
+        house_door: &[Option<I8Vec2>; 2],
+    ) -> GameResult<(NodeId, NodeId, NodeId, NodeId)> {
+        // Calculate the position of the house entrance node
+        let (house_entrance_node_id, house_entrance_node_position) = {
+            // Translate the grid positions to the actual node ids
+            let left_node = grid_to_node
+                .get(
+                    &(house_door[0]
+                        .ok_or_else(|| MapError::InvalidConfig("First house door position not acquired".to_string()))?
+                        + Direction::Left.as_ivec2()),
+                )
+                .ok_or_else(|| MapError::InvalidConfig("Left house door node not found".to_string()))?;
+            let right_node = grid_to_node
+                .get(
+                    &(house_door[1]
+                        .ok_or_else(|| MapError::InvalidConfig("Second house door position not acquired".to_string()))?
+                        + Direction::Right.as_ivec2()),
+                )
+                .ok_or_else(|| MapError::InvalidConfig("Right house door node not found".to_string()))?;
+
+            // Calculate the position of the house node
+            let (node_id, node_position) = {
+                let left_pos = graph
+                    .get_node(*left_node)
+                    .ok_or(MapError::NodeNotFound(*left_node as usize))?
+                    .position;
+                let right_pos = graph
+                    .get_node(*right_node)
+                    .ok_or(MapError::NodeNotFound(*right_node as usize))?
+                    .position;
+                let house_node = graph.add_node(Node {
+                    position: left_pos.lerp(right_pos, 0.5),
+                });
+                (house_node, left_pos.lerp(right_pos, 0.5))
+            };
+
+            // Connect the house door to the left and right nodes
+            graph
+                .connect(node_id, *left_node, true, None, Direction::Left)
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house door to left node: {e}")))?;
+            graph
+                .connect(node_id, *right_node, true, None, Direction::Right)
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house door to right node: {e}")))?;
+
+            (node_id, node_position)
+        };
+
+        // A helper function to help create the various 'lines' of nodes within the house
+        let create_house_line = |graph: &mut Graph, center_pos: Vec2| -> GameResult<(NodeId, NodeId)> {
+            // Place the nodes at, above, and below the center position
+            let center_node_id = graph.add_node(Node { position: center_pos });
+            let top_node_id = graph.add_node(Node {
+                position: center_pos + IVec2::from(Direction::Up.as_ivec2()).as_vec2() * (CELL_SIZE as f32 / 2.0),
+            });
+            let bottom_node_id = graph.add_node(Node {
+                position: center_pos + IVec2::from(Direction::Down.as_ivec2()).as_vec2() * (CELL_SIZE as f32 / 2.0),
+            });
+
+            // Connect the center node to the top and bottom nodes
+            graph
+                .connect(center_node_id, top_node_id, false, None, Direction::Up)
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house line to top node: {e}")))?;
+            graph
+                .connect(center_node_id, bottom_node_id, false, None, Direction::Down)
+                .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house line to bottom node: {e}")))?;
+
+            Ok((center_node_id, top_node_id))
+        };
+
+        // Calculate the position of the center line's center node
+        let center_line_center_position =
+            house_entrance_node_position + IVec2::from(Direction::Down.as_ivec2()).as_vec2() * (3.0 * CELL_SIZE as f32);
+
+        // Create the center line
+        let (center_center_node_id, center_top_node_id) = create_house_line(graph, center_line_center_position)?;
+
+        // Create a ghost-only, two-way connection for the house door.
+        // This prevents Pac-Man from entering or exiting through the door.
+        graph
+            .add_edge(
+                house_entrance_node_id,
+                center_top_node_id,
+                false,
+                None,
+                Direction::Down,
+                TraversalFlags::GHOST,
+            )
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to create ghost-only entrance to house: {e}")))?;
+
+        graph
+            .add_edge(
+                center_top_node_id,
+                house_entrance_node_id,
+                false,
+                None,
+                Direction::Up,
+                TraversalFlags::GHOST,
+            )
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to create ghost-only exit from house: {e}")))?;
+
+        // Create the left line
+        let (left_center_node_id, _) = create_house_line(
+            graph,
+            center_line_center_position + IVec2::from(Direction::Left.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
+        )?;
+
+        // Create the right line
+        let (right_center_node_id, _) = create_house_line(
+            graph,
+            center_line_center_position + IVec2::from(Direction::Right.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
+        )?;
+
+        debug!("Left center node id: {left_center_node_id}");
+
+        // Connect the center line to the left and right lines
+        graph
+            .connect(center_center_node_id, left_center_node_id, false, None, Direction::Left)
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house entrance to left top line: {e}")))?;
+
+        graph
+            .connect(center_center_node_id, right_center_node_id, false, None, Direction::Right)
+            .map_err(|e| MapError::InvalidConfig(format!("Failed to connect house entrance to right top line: {e}")))?;
+
+        debug!("House entrance node id: {house_entrance_node_id}");
+
+        Ok((
+            house_entrance_node_id,
+            left_center_node_id,
+            center_center_node_id,
+            right_center_node_id,
+        ))
+    }
+
+    /// Creates horizontal tunnel portals for instant teleportation across the maze.
+    ///
+    /// Establishes the tunnel system that allows entities to instantly travel from the left edge of the maze to the right edge.
+    /// Creates hidden intermediate nodes beyond the visible tunnel entrances and connects them with zero-distance edges for instantaneous traversal.
+    fn build_tunnels(
+        graph: &mut Graph,
+        grid_to_node: &HashMap<I8Vec2, NodeId>,
+        tunnel_ends: &[Option<I8Vec2>; 2],
+    ) -> GameResult<()> {
+        // Create the hidden tunnel nodes
+        let left_tunnel_hidden_node_id = {
+            let left_tunnel_entrance_node_id =
+                grid_to_node[&tunnel_ends[0].ok_or_else(|| MapError::InvalidConfig("Left tunnel end not found".to_string()))?];
+            let left_tunnel_entrance_node = graph
+                .get_node(left_tunnel_entrance_node_id)
+                .ok_or_else(|| MapError::InvalidConfig("Left tunnel entrance node not found".to_string()))?;
+
+            graph
+                .add_connected(
+                    left_tunnel_entrance_node_id,
+                    Direction::Left,
+                    Node {
+                        position: left_tunnel_entrance_node.position
+                            + IVec2::from(Direction::Left.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
+                    },
+                )
+                .expect("Failed to connect left tunnel entrance to left tunnel hidden node")
+        };
+
+        // Create the right tunnel nodes
+        let right_tunnel_hidden_node_id = {
+            let right_tunnel_entrance_node_id =
+                grid_to_node[&tunnel_ends[1].ok_or_else(|| MapError::InvalidConfig("Right tunnel end not found".to_string()))?];
+            let right_tunnel_entrance_node = graph
+                .get_node(right_tunnel_entrance_node_id)
+                .ok_or_else(|| MapError::InvalidConfig("Right tunnel entrance node not found".to_string()))?;
+
+            graph
+                .add_connected(
+                    right_tunnel_entrance_node_id,
+                    Direction::Right,
+                    Node {
+                        position: right_tunnel_entrance_node.position
+                            + IVec2::from(Direction::Right.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
+                    },
+                )
+                .expect("Failed to connect right tunnel entrance to right tunnel hidden node")
+        };
+
+        // Connect the left tunnel hidden node to the right tunnel hidden node
+        graph
+            .connect(
+                left_tunnel_hidden_node_id,
+                right_tunnel_hidden_node_id,
+                false,
+                Some(0.0),
+                Direction::Left,
+            )
+            .expect("Failed to connect left tunnel hidden node to right tunnel hidden node");
+
+        Ok(())
+    }
+}

pacman/src/map/direction.rs

@@ -0,0 +1,57 @@
+use glam::I8Vec2;
+use strum_macros::AsRefStr;
+
+/// The four cardinal directions.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, AsRefStr)]
+#[repr(usize)]
+#[strum(serialize_all = "lowercase")]
+pub enum Direction {
+    Up,
+    Down,
+    Left,
+    #[default]
+    Right,
+}
+
+impl Direction {
+    /// The four cardinal directions.
+    /// This is just a convenience constant for iterating over the directions.
+    pub const DIRECTIONS: [Direction; 4] = [Direction::Up, Direction::Down, Direction::Left, Direction::Right];
+
+    /// Returns the opposite direction. Constant time.
+    pub const fn opposite(self) -> Direction {
+        match self {
+            Direction::Up => Direction::Down,
+            Direction::Down => Direction::Up,
+            Direction::Left => Direction::Right,
+            Direction::Right => Direction::Left,
+        }
+    }
+
+    /// Returns the direction as an I8Vec2.
+    pub fn as_ivec2(self) -> I8Vec2 {
+        self.into()
+    }
+
+    /// Returns the direction as a usize (0-3). Constant time.
+    /// This is useful for indexing into arrays.
+    pub const fn as_usize(self) -> usize {
+        match self {
+            Direction::Up => 0,
+            Direction::Down => 1,
+            Direction::Left => 2,
+            Direction::Right => 3,
+        }
+    }
+}
+
+impl From<Direction> for I8Vec2 {
+    fn from(dir: Direction) -> Self {
+        match dir {
+            Direction::Up => -I8Vec2::Y,
+            Direction::Down => I8Vec2::Y,
+            Direction::Left => -I8Vec2::X,
+            Direction::Right => I8Vec2::X,
+        }
+    }
+}

pacman/src/map/graph.rs

@@ -0,0 +1,250 @@
+use glam::Vec2;
+
+use crate::systems::NodeId;
+
+use super::direction::Direction;
+
+use bitflags::bitflags;
+
+bitflags! {
+    /// Defines who can traverse a given edge using flags for fast checking.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+    pub struct TraversalFlags: u8 {
+        const PACMAN = 1 << 0;
+        const GHOST = 1 << 1;
+
+        /// Convenience flag for edges that all entities can use
+        const ALL = Self::PACMAN.bits() | Self::GHOST.bits();
+    }
+}
+
+/// Represents a directed edge from one node to another with a given weight (e.g., distance).
+#[derive(Debug, Clone, Copy)]
+pub struct Edge {
+    /// The destination node of this edge.
+    pub target: NodeId,
+    /// The length of the edge.
+    pub distance: f32,
+    /// The cardinal direction of this edge.
+    pub direction: Direction,
+    /// Defines who is allowed to traverse this edge.
+    pub traversal_flags: TraversalFlags,
+}
+
+/// Represents a node in the graph, defined by its position.
+#[derive(Debug)]
+pub struct Node {
+    /// The 2D coordinates of the node.
+    pub position: Vec2,
+}
+
+/// Represents the four possible directions from a node in the graph.
+///
+/// Each field contains an optional edge leading in that direction.
+/// This structure is used to represent the adjacency list for each node,
+/// providing O(1) access to edges in any cardinal direction.
+#[derive(Debug, Default)]
+pub struct Intersection {
+    /// Edge leading upward from this node, if it exists.
+    pub up: Option<Edge>,
+    /// Edge leading downward from this node, if it exists.
+    pub down: Option<Edge>,
+    /// Edge leading leftward from this node, if it exists.
+    pub left: Option<Edge>,
+    /// Edge leading rightward from this node, if it exists.
+    pub right: Option<Edge>,
+}
+
+impl Intersection {
+    /// Returns an iterator over all edges from this intersection.
+    ///
+    /// This iterator yields only the edges that exist (non-None values).
+    pub fn edges(&self) -> impl Iterator<Item = Edge> {
+        [self.up, self.down, self.left, self.right].into_iter().flatten()
+    }
+
+    /// Retrieves the edge in the specified direction, if it exists.
+    pub fn get(&self, direction: Direction) -> Option<Edge> {
+        match direction {
+            Direction::Up => self.up,
+            Direction::Down => self.down,
+            Direction::Left => self.left,
+            Direction::Right => self.right,
+        }
+    }
+
+    /// Sets the edge in the specified direction.
+    ///
+    /// This will overwrite any existing edge in that direction.
+    pub fn set(&mut self, direction: Direction, edge: Edge) {
+        match direction {
+            Direction::Up => self.up = Some(edge),
+            Direction::Down => self.down = Some(edge),
+            Direction::Left => self.left = Some(edge),
+            Direction::Right => self.right = Some(edge),
+        }
+    }
+}
+
+/// A directed graph structure using an adjacency list representation.
+///
+/// Nodes are stored in a vector, and their indices serve as their `NodeId`.
+/// This design provides fast, O(1) lookups for node data. Edges are stored
+/// in an adjacency list, where each node has a list of outgoing edges.
+pub struct Graph {
+    nodes: Vec<Node>,
+    pub adjacency_list: Vec<Intersection>,
+}
+
+impl Graph {
+    /// Creates a new, empty graph.
+    pub fn new() -> Self {
+        Graph {
+            nodes: Vec::new(),
+            adjacency_list: Vec::new(),
+        }
+    }
+
+    /// Adds a new node with the given data to the graph and returns its ID.
+    pub fn add_node(&mut self, data: Node) -> NodeId {
+        let id = self.nodes.len() as NodeId;
+        self.nodes.push(data);
+        self.adjacency_list.push(Intersection::default());
+        id
+    }
+
+    /// Connects a new node to the graph and adds an edge between the existing node and the new node.
+    pub fn add_connected(&mut self, from: NodeId, direction: Direction, new_node: Node) -> Result<NodeId, &'static str> {
+        let to = self.add_node(new_node);
+        self.connect(from, to, false, None, direction)?;
+        Ok(to)
+    }
+
+    /// Connects two existing nodes with an edge.
+    pub fn connect(
+        &mut self,
+        from: NodeId,
+        to: NodeId,
+        replace: bool,
+        distance: Option<f32>,
+        direction: Direction,
+    ) -> Result<(), &'static str> {
+        if from as usize >= self.adjacency_list.len() {
+            return Err("From node does not exist.");
+        }
+        if to as usize >= self.adjacency_list.len() {
+            return Err("To node does not exist.");
+        }
+
+        let edge_a = self.add_edge(from, to, replace, distance, direction, TraversalFlags::ALL);
+        let edge_b = self.add_edge(to, from, replace, distance, direction.opposite(), TraversalFlags::ALL);
+
+        if edge_a.is_err() && edge_b.is_err() {
+            return Err("Failed to connect nodes in both directions.");
+        }
+
+        Ok(())
+    }
+
+    /// Adds a directed edge between two nodes.
+    ///
+    /// If `distance` is `None`, it will be calculated automatically based on the
+    /// Euclidean distance between the two nodes.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The `from` node does not exist
+    /// - An edge already exists in the specified direction
+    /// - An edge already exists to the target node
+    /// - The provided distance is not positive
+    pub fn add_edge(
+        &mut self,
+        from: NodeId,
+        to: NodeId,
+        replace: bool,
+        distance: Option<f32>,
+        direction: Direction,
+        traversal_flags: TraversalFlags,
+    ) -> Result<(), &'static str> {
+        let edge = Edge {
+            target: to,
+            distance: match distance {
+                Some(distance) => {
+                    if distance < 0.0 {
+                        return Err("Edge distance must be on-negative.");
+                    }
+                    distance
+                }
+                None => {
+                    // If no distance is provided, calculate it based on the positions of the nodes
+                    let from_pos = self.nodes[from as usize].position;
+                    let to_pos = self.nodes[to as usize].position;
+                    from_pos.distance(to_pos)
+                }
+            },
+            direction,
+            traversal_flags,
+        };
+
+        if from as usize >= self.adjacency_list.len() {
+            return Err("From node does not exist.");
+        }
+
+        let adjacency_list = &mut self.adjacency_list[from as usize];
+
+        // Check if the edge already exists in this direction or to the same target
+        if let Some(err) = adjacency_list.edges().find_map(|e| {
+            if !replace {
+                // If we're not replacing the edge, we don't want to replace an edge that already exists in this direction
+                if e.direction == direction {
+                    return Some(Err("Edge already exists in this direction."));
+                } else if e.target == to {
+                    return Some(Err("Edge already exists."));
+                }
+            }
+            None
+        }) {
+            return err;
+        }
+
+        adjacency_list.set(direction, edge);
+
+        Ok(())
+    }
+
+    /// Retrieves an immutable reference to a node's data.
+    pub fn get_node(&self, id: NodeId) -> Option<&Node> {
+        self.nodes.get(id as usize)
+    }
+
+    /// 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 as NodeId, 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 as usize)?.edges().find(|edge| edge.target == to)
+    }
+
+    /// Finds an edge originating from a given node that follows a specific direction.
+    pub fn find_edge_in_direction(&self, from: NodeId, direction: Direction) -> Option<Edge> {
+        self.adjacency_list.get(from as usize)?.get(direction)
+    }
+}
+
+// Default implementation for creating an empty graph.
+impl Default for Graph {
+    fn default() -> Self {
+        Self::new()
+    }
+}

pacman/src/map/layout.rs

@@ -0,0 +1,95 @@
+pub const TILE_MAP: [[usize; 28]; 31] = [
+    [
+        0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 4,
+    ],
+    [
+        5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 9,
+    ],
+    [
+        5, 6, 10, 11, 11, 12, 6, 10, 11, 11, 11, 12, 6, 7, 8, 6, 10, 11, 11, 11, 12, 6, 10, 11, 11, 12, 6, 9,
+    ],
+    [
+        5, 6, 7, 6, 6, 8, 6, 7, 6, 6, 6, 8, 6, 7, 8, 6, 7, 6, 6, 6, 8, 6, 7, 6, 6, 8, 6, 9,
+    ],
+    [
+        5, 6, 13, 14, 14, 15, 6, 13, 14, 14, 14, 15, 6, 13, 15, 6, 13, 14, 14, 14, 15, 6, 13, 14, 14, 15, 6, 9,
+    ],
+    [
+        5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 9,
+    ],
+    [
+        5, 6, 10, 11, 11, 12, 6, 10, 12, 6, 10, 11, 11, 11, 11, 11, 11, 12, 6, 10, 12, 6, 10, 11, 11, 12, 6, 9,
+    ],
+    [
+        5, 6, 13, 14, 14, 15, 6, 7, 8, 6, 13, 14, 14, 16, 17, 14, 14, 15, 6, 7, 8, 6, 13, 14, 14, 15, 6, 9,
+    ],
+    [
+        5, 6, 6, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 6, 6, 9,
+    ],
+    [
+        18, 19, 19, 19, 19, 12, 6, 7, 20, 11, 11, 12, 6, 7, 8, 6, 10, 11, 11, 21, 8, 6, 10, 19, 19, 19, 19, 22,
+    ],
+    [
+        6, 6, 6, 6, 6, 5, 6, 7, 17, 14, 14, 15, 6, 13, 15, 6, 13, 14, 14, 16, 8, 6, 9, 6, 6, 6, 6, 6,
+    ],
+    [
+        6, 6, 6, 6, 6, 5, 6, 7, 8, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 8, 6, 9, 6, 6, 6, 6, 6,
+    ],
+    [
+        6, 6, 6, 6, 6, 5, 6, 7, 8, 6, 23, 19, 24, 25, 25, 26, 19, 27, 6, 7, 8, 6, 9, 6, 6, 6, 6, 6,
+    ],
+    [
+        1, 1, 1, 1, 1, 15, 6, 13, 15, 6, 9, 6, 6, 6, 6, 6, 6, 5, 6, 13, 15, 6, 13, 1, 1, 1, 1, 1,
+    ],
+    [
+        6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 9, 6, 6, 6, 6, 6, 6, 5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6,
+    ],
+    [
+        19, 19, 19, 19, 19, 12, 6, 10, 12, 6, 9, 6, 6, 6, 6, 6, 6, 5, 6, 10, 12, 6, 10, 19, 19, 19, 19, 19,
+    ],
+    [
+        6, 6, 6, 6, 6, 5, 6, 7, 8, 6, 28, 1, 1, 1, 1, 1, 1, 29, 6, 7, 8, 6, 9, 6, 6, 6, 6, 6,
+    ],
+    [
+        6, 6, 6, 6, 6, 5, 6, 7, 8, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 8, 6, 9, 6, 6, 6, 6, 6,
+    ],
+    [
+        6, 6, 6, 6, 6, 5, 6, 7, 8, 6, 10, 11, 11, 11, 11, 11, 11, 12, 6, 7, 8, 6, 9, 6, 6, 6, 6, 6,
+    ],
+    [
+        0, 1, 1, 1, 1, 15, 6, 13, 15, 6, 13, 14, 14, 16, 17, 14, 14, 15, 6, 13, 15, 6, 13, 1, 1, 1, 1, 4,
+    ],
+    [
+        5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 9,
+    ],
+    [
+        5, 6, 10, 11, 11, 12, 6, 10, 11, 11, 11, 12, 6, 7, 8, 6, 10, 11, 11, 11, 12, 6, 30, 11, 11, 12, 6, 9,
+    ],
+    [
+        5, 6, 13, 14, 16, 8, 6, 13, 14, 14, 14, 15, 6, 13, 15, 6, 13, 14, 14, 14, 15, 6, 7, 17, 14, 15, 6, 9,
+    ],
+    [
+        5, 6, 6, 6, 7, 8, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 8, 6, 6, 6, 9,
+    ],
+    [
+        31, 11, 12, 6, 7, 8, 6, 10, 12, 6, 10, 11, 11, 11, 11, 11, 11, 12, 6, 10, 12, 6, 7, 8, 6, 10, 11, 32,
+    ],
+    [
+        33, 14, 15, 6, 13, 15, 6, 7, 8, 6, 13, 14, 14, 16, 17, 14, 14, 15, 6, 7, 8, 6, 13, 15, 6, 13, 14, 34,
+    ],
+    [
+        5, 6, 6, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 7, 8, 6, 6, 6, 6, 6, 6, 9,
+    ],
+    [
+        5, 6, 10, 11, 11, 11, 11, 21, 20, 11, 11, 12, 6, 7, 8, 6, 10, 11, 11, 21, 20, 11, 11, 11, 11, 12, 6, 9,
+    ],
+    [
+        5, 6, 13, 14, 14, 14, 14, 14, 14, 14, 14, 15, 6, 13, 15, 6, 13, 14, 14, 14, 14, 14, 14, 14, 14, 15, 6, 9,
+    ],
+    [
+        5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 9,
+    ],
+    [
+        18, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 22,
+    ],
+];

pacman/src/map/mod.rs

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

pacman/src/map/parser.rs

@@ -0,0 +1,138 @@
+//! Map parsing functionality for converting raw board layouts into structured data.
+
+use crate::constants::{MapTile, BOARD_CELL_SIZE};
+use crate::error::ParseError;
+use glam::I8Vec2;
+
+/// Structured representation of parsed ASCII board layout with extracted special positions.
+///
+/// Contains the complete board state after character-to-tile conversion, along with
+/// the locations of special gameplay elements that require additional processing
+/// during graph construction. Special positions are extracted during parsing to
+/// enable proper map builder initialization.
+#[derive(Debug)]
+pub struct ParsedMap {
+    /// 2D array of tiles converted from ASCII characters
+    pub tiles: [[MapTile; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize],
+    /// Two positions marking the ghost house entrance (represented by '=' characters)
+    pub house_door: [Option<I8Vec2>; 2],
+    /// Two positions marking tunnel portals for wraparound teleportation ('T' characters)
+    pub tunnel_ends: [Option<I8Vec2>; 2],
+    /// Starting position for Pac-Man (marked by 'X' character in the layout)
+    pub pacman_start: Option<I8Vec2>,
+}
+
+/// Parser for converting raw board layouts into structured map data.
+pub struct MapTileParser;
+
+impl MapTileParser {
+    /// Converts ASCII characters from the board layout into corresponding tile types.
+    ///
+    /// Interprets the character-based maze representation: walls (`#`), collectible
+    /// pellets (`.` and `o`), traversable spaces (` `), tunnel entrances (`T`),
+    /// ghost house doors (`=`), and entity spawn markers (`X`). Special characters
+    /// that don't represent tiles in the final map (like spawn markers) are
+    /// converted to `Empty` tiles while their positions are tracked separately.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ParseError::UnknownCharacter` for any character not defined
+    /// in the game's ASCII art vocabulary.
+    pub fn parse_character(c: char) -> Result<MapTile, ParseError> {
+        match c {
+            '#' => Ok(MapTile::Wall),
+            '.' => Ok(MapTile::Pellet),
+            'o' => Ok(MapTile::PowerPellet),
+            ' ' => Ok(MapTile::Empty),
+            'T' => Ok(MapTile::Tunnel),
+            'X' => Ok(MapTile::Empty), // Pac-Man's starting position, treated as empty
+            '=' => Ok(MapTile::Wall),  // House door is represented as a wall tile
+            _ => Err(ParseError::UnknownCharacter(c)),
+        }
+    }
+
+    /// Parses a raw board layout into structured map data.
+    ///
+    /// # Arguments
+    ///
+    /// * `raw_board` - The raw board layout as an array of strings
+    ///
+    /// # Returns
+    ///
+    /// The parsed map data, or an error if parsing fails.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the board contains unknown characters or if the house door
+    /// is not properly defined by exactly two '=' characters.
+    pub fn parse_board(raw_board: [&str; BOARD_CELL_SIZE.y as usize]) -> Result<ParsedMap, ParseError> {
+        // Validate board dimensions
+        if raw_board.len() != BOARD_CELL_SIZE.y as usize {
+            return Err(ParseError::ParseFailed(format!(
+                "Invalid board height: expected {}, got {}",
+                BOARD_CELL_SIZE.y,
+                raw_board.len()
+            )));
+        }
+
+        for (i, line) in raw_board.iter().enumerate() {
+            if line.len() != BOARD_CELL_SIZE.x as usize {
+                return Err(ParseError::ParseFailed(format!(
+                    "Invalid board width at line {}: expected {}, got {}",
+                    i,
+                    BOARD_CELL_SIZE.x,
+                    line.len()
+                )));
+            }
+        }
+        let mut tiles = [[MapTile::Empty; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize];
+        let mut house_door = [None; 2];
+        let mut tunnel_ends = [None; 2];
+        let mut pacman_start: Option<I8Vec2> = None;
+
+        for (y, line) in raw_board.iter().enumerate().take(BOARD_CELL_SIZE.y as usize) {
+            for (x, character) in line.chars().enumerate().take(BOARD_CELL_SIZE.x as usize) {
+                let tile = Self::parse_character(character)?;
+
+                // Track special positions
+                match tile {
+                    MapTile::Tunnel => {
+                        if tunnel_ends[0].is_none() {
+                            tunnel_ends[0] = Some(I8Vec2::new(x as i8, y as i8));
+                        } else {
+                            tunnel_ends[1] = Some(I8Vec2::new(x as i8, y as i8));
+                        }
+                    }
+                    MapTile::Wall if character == '=' => {
+                        if house_door[0].is_none() {
+                            house_door[0] = Some(I8Vec2::new(x as i8, y as i8));
+                        } else {
+                            house_door[1] = Some(I8Vec2::new(x as i8, y as i8));
+                        }
+                    }
+                    _ => {}
+                }
+
+                // Track Pac-Man's starting position
+                if character == 'X' {
+                    pacman_start = Some(I8Vec2::new(x as i8, y as i8));
+                }
+
+                tiles[x][y] = tile;
+            }
+        }
+
+        // Validate house door configuration
+        let house_door_count = house_door.iter().filter(|x| x.is_some()).count();
+        if house_door_count != 2 {
+            return Err(ParseError::InvalidHouseDoorCount(house_door_count));
+        }
+
+        Ok(ParsedMap {
+            tiles,
+            house_door,
+            tunnel_ends,
+            pacman_start,
+        })
+    }
+}

pacman/src/map/render.rs

@@ -0,0 +1,36 @@
+//! Map rendering functionality.
+
+use crate::constants::{BOARD_CELL_OFFSET, CELL_SIZE};
+use crate::map::layout::TILE_MAP;
+use crate::texture::sprite::{AtlasTile, SpriteAtlas};
+use sdl2::pixels::Color;
+use sdl2::rect::Rect;
+use sdl2::render::{Canvas, RenderTarget};
+
+/// Handles rendering operations for the map.
+pub struct MapRenderer;
+
+impl MapRenderer {
+    /// Renders the map to the given canvas.
+    ///
+    /// 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: &[AtlasTile]) {
+        for (y, row) in TILE_MAP.iter().enumerate() {
+            for (x, &tile_index) in row.iter().enumerate() {
+                let mut tile = map_tiles[tile_index];
+                tile.color = Some(Color::RGB(0x20, 0x20, 0xf9));
+                let dest = Rect::new(
+                    (BOARD_CELL_OFFSET.x as usize * CELL_SIZE as usize + x * CELL_SIZE as usize) as i32,
+                    (BOARD_CELL_OFFSET.y as usize * CELL_SIZE as usize + y * CELL_SIZE as usize) as i32,
+                    CELL_SIZE,
+                    CELL_SIZE,
+                );
+
+                if let Err(e) = tile.render(canvas, atlas, dest) {
+                    tracing::error!("Failed to render map tile: {}", e);
+                }
+            }
+        }
+    }
+}

pacman/src/platform/desktop.rs

@@ -0,0 +1,209 @@
+//! Desktop platform implementation.
+
+use std::time::Duration;
+
+use rand::rngs::ThreadRng;
+use rust_embed::Embed;
+
+use crate::error::PlatformError;
+
+#[derive(Embed)]
+#[folder = "assets/game/"]
+struct EmbeddedAssets;
+
+/// Desktop platform implementation.
+pub fn sleep(duration: Duration, focused: bool) {
+    if focused {
+        spin_sleep::sleep(duration);
+    } else {
+        std::thread::sleep(duration);
+    }
+}
+
+#[allow(unused_variables)]
+pub fn init_console(force_console: bool) -> Result<(), PlatformError> {
+    use crate::formatter::CustomFormatter;
+    use tracing::Level;
+    use tracing_error::ErrorLayer;
+    use tracing_subscriber::{fmt, layer::SubscriberExt, util::SubscriberInitExt, Layer};
+
+    // Create a file layer
+    let log_file = std::fs::File::create("pacman.log")
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to create log file: {}", e)))?;
+    let file_layer = fmt::layer()
+        .with_ansi(false)
+        .with_writer(log_file)
+        .event_format(CustomFormatter)
+        .with_filter(tracing_subscriber::filter::LevelFilter::from_level(Level::DEBUG))
+        .boxed();
+
+    #[cfg(windows)]
+    {
+        // If using windows subsystem, and force_console is true, allocate a new console window
+        if force_console && cfg!(not(use_console)) {
+            use crate::platform::tracing_buffer::{SwitchableMakeWriter, SwitchableWriter};
+
+            // Setup deferred tracing subscriber that will buffer logs until console is ready
+            let switchable_writer = SwitchableWriter::default();
+            let make_writer = SwitchableMakeWriter::new(switchable_writer.clone());
+            let console_layer = fmt::layer()
+                .with_ansi(true)
+                .with_writer(make_writer)
+                .event_format(CustomFormatter)
+                .with_filter(tracing_subscriber::filter::LevelFilter::from_level(Level::DEBUG))
+                .boxed();
+
+            tracing_subscriber::registry()
+                .with(console_layer)
+                .with(file_layer)
+                .with(ErrorLayer::default())
+                .init();
+
+            // Enable virtual terminal processing for ANSI colors
+            allocate_console()?;
+            enable_ansi_support()?;
+
+            switchable_writer
+                .switch_to_direct_mode()
+                .map_err(|e| PlatformError::ConsoleInit(format!("Failed to switch to direct mode: {}", e)))?;
+        } else {
+            // Set up tracing subscriber with ANSI colors enabled
+            let console_layer = fmt::layer()
+                .with_ansi(true)
+                .with_writer(std::io::stdout)
+                .event_format(CustomFormatter)
+                .with_filter(tracing_subscriber::filter::LevelFilter::from_level(Level::DEBUG))
+                .boxed();
+
+            tracing_subscriber::registry()
+                .with(console_layer)
+                .with(file_layer)
+                .with(ErrorLayer::default())
+                .init();
+        }
+    }
+
+    #[cfg(not(windows))]
+    {
+        // Set up tracing subscriber with ANSI colors enabled
+        let console_layer = fmt::layer()
+            .with_ansi(true)
+            .with_writer(std::io::stdout)
+            .event_format(CustomFormatter)
+            .with_filter(tracing_subscriber::filter::LevelFilter::from_level(Level::DEBUG))
+            .boxed();
+
+        tracing_subscriber::registry()
+            .with(console_layer)
+            .with(file_layer)
+            .with(ErrorLayer::default())
+            .init();
+    }
+
+    Ok(())
+}
+
+pub fn rng() -> ThreadRng {
+    rand::rng()
+}
+
+/// Enable ANSI escape sequence support in the Windows console
+/// Windows-only
+#[cfg(windows)]
+fn enable_ansi_support() -> Result<(), PlatformError> {
+    use windows::Win32::System::Console::{
+        GetConsoleMode, GetStdHandle, SetConsoleMode, CONSOLE_MODE, ENABLE_VIRTUAL_TERMINAL_PROCESSING, STD_ERROR_HANDLE,
+        STD_OUTPUT_HANDLE,
+    };
+
+    // Enable ANSI processing for stdout
+    unsafe {
+        let stdout_handle = GetStdHandle(STD_OUTPUT_HANDLE)
+            .map_err(|e| PlatformError::ConsoleInit(format!("Failed to get stdout handle: {:?}", e)))?;
+
+        let mut console_mode = CONSOLE_MODE(0);
+        GetConsoleMode(stdout_handle, &mut console_mode)
+            .map_err(|e| PlatformError::ConsoleInit(format!("Failed to get console mode: {:?}", e)))?;
+
+        console_mode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
+        SetConsoleMode(stdout_handle, console_mode)
+            .map_err(|e| PlatformError::ConsoleInit(format!("Failed to enable ANSI for stdout: {:?}", e)))?;
+    }
+
+    // Enable ANSI processing for stderr
+    unsafe {
+        let stderr_handle = GetStdHandle(STD_ERROR_HANDLE)
+            .map_err(|e| PlatformError::ConsoleInit(format!("Failed to get stderr handle: {:?}", e)))?;
+
+        let mut console_mode = CONSOLE_MODE(0);
+        GetConsoleMode(stderr_handle, &mut console_mode)
+            .map_err(|e| PlatformError::ConsoleInit(format!("Failed to get console mode: {:?}", e)))?;
+
+        console_mode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
+        SetConsoleMode(stderr_handle, console_mode)
+            .map_err(|e| PlatformError::ConsoleInit(format!("Failed to enable ANSI for stderr: {:?}", e)))?;
+    }
+
+    Ok(())
+}
+
+/// Allocate a new console window for the process
+/// Windows-only
+#[cfg(windows)]
+fn allocate_console() -> Result<(), PlatformError> {
+    use windows::{
+        core::PCSTR,
+        Win32::{
+            Foundation::{GENERIC_READ, GENERIC_WRITE},
+            Storage::FileSystem::{CreateFileA, FILE_FLAGS_AND_ATTRIBUTES, FILE_SHARE_READ, FILE_SHARE_WRITE, OPEN_EXISTING},
+            System::Console::{AllocConsole, SetStdHandle, STD_ERROR_HANDLE, STD_INPUT_HANDLE, STD_OUTPUT_HANDLE},
+        },
+    };
+
+    // Allocate a new console for this process
+    unsafe { AllocConsole() }.map_err(|e| PlatformError::ConsoleInit(format!("Failed to allocate console: {:?}", e)))?;
+
+    // Note: SetConsoleTitle is not available in the imported modules, skipping title setting
+
+    // Redirect stdout
+    let stdout_handle = unsafe {
+        let pcstr = PCSTR::from_raw(c"CONOUT$".as_ptr() as *const u8);
+        CreateFileA::<PCSTR>(
+            pcstr,
+            (GENERIC_READ | GENERIC_WRITE).0,
+            FILE_SHARE_READ | FILE_SHARE_WRITE,
+            None,
+            OPEN_EXISTING,
+            FILE_FLAGS_AND_ATTRIBUTES(0),
+            None,
+        )
+    }
+    .map_err(|e| PlatformError::ConsoleInit(format!("Failed to create stdout handle: {:?}", e)))?;
+
+    // Redirect stdin
+    let stdin_handle = unsafe {
+        let pcstr = PCSTR::from_raw(c"CONIN$".as_ptr() as *const u8);
+        CreateFileA::<PCSTR>(
+            pcstr,
+            (GENERIC_READ | GENERIC_WRITE).0,
+            FILE_SHARE_READ | FILE_SHARE_WRITE,
+            None,
+            OPEN_EXISTING,
+            FILE_FLAGS_AND_ATTRIBUTES(0),
+            None,
+        )
+    }
+    .map_err(|e| PlatformError::ConsoleInit(format!("Failed to create stdin handle: {:?}", e)))?;
+
+    // Set the standard handles
+    unsafe { SetStdHandle(STD_OUTPUT_HANDLE, stdout_handle) }
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set stdout handle: {:?}", e)))?;
+
+    unsafe { SetStdHandle(STD_ERROR_HANDLE, stdout_handle) }
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set stderr handle: {:?}", e)))?;
+
+    unsafe { SetStdHandle(STD_INPUT_HANDLE, stdin_handle) }
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set stdin handle: {:?}", e)))?;
+
+    Ok(())
+}

pacman/src/platform/emscripten.rs

@@ -0,0 +1,64 @@
+//! Emscripten platform implementation.
+
+use crate::error::PlatformError;
+use crate::formatter::CustomFormatter;
+use rand::{rngs::SmallRng, SeedableRng};
+use std::ffi::CString;
+use std::io::{self, Write};
+use std::time::Duration;
+
+// Emscripten FFI functions
+extern "C" {
+    fn emscripten_sleep(ms: u32);
+    fn printf(format: *const u8, ...) -> i32;
+}
+
+pub fn sleep(duration: Duration, _focused: bool) {
+    unsafe {
+        emscripten_sleep(duration.as_millis() as u32);
+    }
+}
+
+pub fn init_console(_force_console: bool) -> Result<(), PlatformError> {
+    use tracing_subscriber::{fmt, layer::SubscriberExt, EnvFilter};
+
+    // Set up a custom tracing subscriber that writes directly to emscripten console
+    let subscriber = tracing_subscriber::registry()
+        .with(
+            fmt::layer()
+                .with_writer(|| EmscriptenConsoleWriter)
+                .with_ansi(false)
+                .event_format(CustomFormatter),
+        )
+        .with(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("debug")));
+
+    tracing::subscriber::set_global_default(subscriber)
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set tracing subscriber: {}", e)))?;
+
+    Ok(())
+}
+
+/// A writer that outputs to the browser console via printf (redirected by emscripten)
+struct EmscriptenConsoleWriter;
+
+impl Write for EmscriptenConsoleWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        if let Ok(s) = std::str::from_utf8(buf) {
+            if let Ok(cstr) = CString::new(s.trim_end_matches('\n')) {
+                let format_str = CString::new("%s\n").unwrap();
+                unsafe {
+                    printf(format_str.as_ptr().cast(), cstr.as_ptr());
+                }
+            }
+        }
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+pub fn rng() -> SmallRng {
+    SmallRng::from_os_rng()
+}

pacman/src/platform/mod.rs

@@ -0,0 +1,15 @@
+//! Platform abstraction layer for cross-platform functionality.
+
+#[cfg(not(target_os = "emscripten"))]
+mod desktop;
+#[cfg(not(target_os = "emscripten"))]
+pub use desktop::*;
+
+/// Tracing buffer is only used on Windows.
+#[cfg(windows)]
+pub mod tracing_buffer;
+
+#[cfg(target_os = "emscripten")]
+pub use emscripten::*;
+#[cfg(target_os = "emscripten")]
+mod emscripten;

pacman/src/platform/tracing_buffer.rs

@@ -0,0 +1,129 @@
+//! Buffered tracing setup for handling logs before console attachment.
+
+use parking_lot::Mutex;
+use std::io;
+use std::io::Write;
+use std::sync::Arc;
+use tracing::debug;
+use tracing_subscriber::fmt::MakeWriter;
+
+/// A thread-safe buffered writer that stores logs in memory until flushed.
+#[derive(Clone)]
+pub struct BufferedWriter {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+impl BufferedWriter {
+    /// Creates a new buffered writer.
+    pub fn new() -> Self {
+        Self {
+            buffer: Arc::new(Mutex::new(Vec::new())),
+        }
+    }
+
+    /// Flushes all buffered content to the provided writer and clears the buffer.
+    pub fn flush_to<W: Write>(&self, mut writer: W) -> io::Result<()> {
+        let mut buffer = self.buffer.lock();
+        if !buffer.is_empty() {
+            writer.write_all(&buffer)?;
+            writer.flush()?;
+            buffer.clear();
+        }
+        Ok(())
+    }
+
+    /// Returns the current buffer size in bytes.
+    pub fn buffer_size(&self) -> usize {
+        self.buffer.lock().len()
+    }
+}
+
+impl Write for BufferedWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        let mut buffer = self.buffer.lock();
+        buffer.extend_from_slice(buf);
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        // For buffered writer, flush is a no-op since we're storing in memory
+        Ok(())
+    }
+}
+
+impl Default for BufferedWriter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// A writer that can switch between buffering and direct output.
+#[derive(Clone, Default)]
+pub struct SwitchableWriter {
+    buffered_writer: BufferedWriter,
+    direct_mode: std::sync::Arc<parking_lot::Mutex<bool>>,
+}
+
+impl SwitchableWriter {
+    pub fn switch_to_direct_mode(&self) -> io::Result<()> {
+        let buffer_size = {
+            // Acquire the lock
+            let mut mode = self.direct_mode.lock();
+
+            // Get buffer size before flushing for debug logging
+            let buffer_size = self.buffered_writer.buffer_size();
+
+            // Flush any buffered content to stdout only
+            self.buffered_writer.flush_to(io::stdout())?;
+
+            // Switch to direct mode (and drop the lock)
+            *mode = true;
+
+            buffer_size
+        };
+
+        // Log how much was buffered (this will now go directly to stdout)
+        debug!("Flushed {buffer_size:?} bytes of buffered logs to console");
+
+        Ok(())
+    }
+}
+
+impl io::Write for SwitchableWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        if *self.direct_mode.lock() {
+            io::stdout().write(buf)
+        } else {
+            self.buffered_writer.clone().write(buf)
+        }
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        if *self.direct_mode.lock() {
+            io::stdout().flush()
+        } else {
+            // For buffered mode, flush is a no-op
+            Ok(())
+        }
+    }
+}
+
+/// A make writer that uses the switchable writer.
+#[derive(Clone)]
+pub struct SwitchableMakeWriter {
+    writer: SwitchableWriter,
+}
+
+impl SwitchableMakeWriter {
+    pub fn new(writer: SwitchableWriter) -> Self {
+        Self { writer }
+    }
+}
+
+impl<'a> MakeWriter<'a> for SwitchableMakeWriter {
+    type Writer = SwitchableWriter;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        self.writer.clone()
+    }
+}

pacman/src/systems/animation/blinking.rs

@@ -0,0 +1,66 @@
+use bevy_ecs::{
+    component::Component,
+    query::{Has, With},
+    system::{Query, Res},
+};
+
+use crate::systems::{DeltaTime, Frozen, Renderable, Visibility};
+
+#[derive(Component, Debug)]
+pub struct Blinking {
+    pub tick_timer: u32,
+    pub interval_ticks: u32,
+}
+
+impl Blinking {
+    pub fn new(interval_ticks: u32) -> Self {
+        Self {
+            tick_timer: 0,
+            interval_ticks,
+        }
+    }
+}
+
+/// Updates blinking entities by toggling their visibility at regular intervals.
+///
+/// This system manages entities that have both `Blinking` and `Renderable` components,
+/// accumulating ticks and toggling visibility when the specified interval is reached.
+/// Uses integer arithmetic for deterministic behavior.
+#[allow(clippy::type_complexity)]
+pub fn blinking_system(time: Res<DeltaTime>, mut query: Query<(&mut Blinking, &mut Visibility, Has<Frozen>), With<Renderable>>) {
+    for (mut blinking, mut visibility, frozen) in query.iter_mut() {
+        // If the entity is frozen, blinking is disabled and the entity is made visible
+        if frozen {
+            visibility.show();
+            continue;
+        }
+
+        // Increase the timer by the delta ticks
+        blinking.tick_timer += time.ticks;
+
+        // Handle zero interval case (immediate toggling)
+        if blinking.interval_ticks == 0 {
+            if time.ticks > 0 {
+                visibility.toggle();
+            }
+            continue;
+        }
+
+        // Calculate how many complete intervals have passed
+        let complete_intervals = blinking.tick_timer / blinking.interval_ticks;
+
+        // If no complete intervals have passed, there's nothing to do yet
+        if complete_intervals == 0 {
+            continue;
+        }
+
+        // Update the timer to the remainder after complete intervals
+        blinking.tick_timer %= blinking.interval_ticks;
+
+        // Toggle the visibility for each complete interval
+        // Since toggling twice is a no-op, we only need to toggle if the count is odd
+        if complete_intervals % 2 == 1 {
+            visibility.toggle();
+        }
+    }
+}

pacman/src/systems/animation/directional.rs

@@ -0,0 +1,104 @@
+use bevy_ecs::{
+    component::Component,
+    query::{Has, Or, With, Without},
+    system::{Query, Res},
+};
+
+use crate::{
+    systems::{DeltaTime, Dying, Frozen, LinearAnimation, Looping, Position, Renderable, Velocity},
+    texture::animated::DirectionalTiles,
+};
+
+/// Directional animation component with shared timing across all directions
+#[derive(Component, Clone)]
+pub struct DirectionalAnimation {
+    pub moving_tiles: DirectionalTiles,
+    pub stopped_tiles: DirectionalTiles,
+    pub current_frame: usize,
+    pub time_bank: u16,
+    pub frame_duration: u16,
+}
+
+impl DirectionalAnimation {
+    /// Creates a new directional animation with the given tiles and frame duration
+    pub fn new(moving_tiles: DirectionalTiles, stopped_tiles: DirectionalTiles, frame_duration: u16) -> Self {
+        Self {
+            moving_tiles,
+            stopped_tiles,
+            current_frame: 0,
+            time_bank: 0,
+            frame_duration,
+        }
+    }
+}
+
+/// Updates directional animated entities with synchronized timing across directions.
+///
+/// This runs before the render system to update sprites based on current direction and movement state.
+/// All directions share the same frame timing to ensure perfect synchronization.
+pub fn directional_render_system(
+    dt: Res<DeltaTime>,
+    mut query: Query<(&Position, &Velocity, &mut DirectionalAnimation, &mut Renderable, Has<Frozen>)>,
+) {
+    let ticks = (dt.seconds * 60.0).round() as u16; // Convert from seconds to ticks at 60 ticks/sec
+
+    for (position, velocity, mut anim, mut renderable, frozen) in query.iter_mut() {
+        let stopped = matches!(position, Position::Stopped { .. });
+
+        // Only tick animation when moving to preserve stopped frame
+        if !stopped && !frozen {
+            // Tick shared animation state
+            anim.time_bank += ticks;
+            while anim.time_bank >= anim.frame_duration {
+                anim.time_bank -= anim.frame_duration;
+                anim.current_frame += 1;
+            }
+        }
+
+        // Get tiles for current direction and movement state
+        let tiles = if stopped {
+            anim.stopped_tiles.get(velocity.direction)
+        } else {
+            anim.moving_tiles.get(velocity.direction)
+        };
+
+        if !tiles.is_empty() {
+            let new_tile = tiles.get_tile(anim.current_frame);
+            if renderable.sprite != new_tile {
+                renderable.sprite = new_tile;
+            }
+        }
+    }
+}
+
+/// System that updates `Renderable` sprites for entities with `LinearAnimation`.
+#[allow(clippy::type_complexity)]
+pub fn linear_render_system(
+    dt: Res<DeltaTime>,
+    mut query: Query<(&mut LinearAnimation, &mut Renderable, Has<Looping>), Or<(Without<Frozen>, With<Dying>)>>,
+) {
+    for (mut anim, mut renderable, looping) in query.iter_mut() {
+        if anim.finished {
+            continue;
+        }
+
+        anim.time_bank += dt.ticks as u16;
+        let frames_to_advance = (anim.time_bank / anim.frame_duration) as usize;
+
+        if frames_to_advance == 0 {
+            continue;
+        }
+
+        let total_frames = anim.tiles.len();
+
+        if !looping && anim.current_frame + frames_to_advance >= total_frames {
+            anim.finished = true;
+            anim.current_frame = total_frames - 1;
+        } else {
+            anim.current_frame += frames_to_advance;
+        }
+
+        anim.time_bank %= anim.frame_duration;
+        renderable.sprite = anim.tiles.get_tile(anim.current_frame);
+    }
+}

pacman/src/systems/animation/linear.rs

@@ -0,0 +1,30 @@
+use crate::texture::animated::TileSequence;
+use bevy_ecs::component::Component;
+use bevy_ecs::resource::Resource;
+
+/// Tag component to mark animations that should loop when they reach the end
+#[derive(Component, Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Looping;
+
+/// Linear animation component for non-directional animations (frightened ghosts)
+#[derive(Component, Resource, Clone)]
+pub struct LinearAnimation {
+    pub tiles: TileSequence,
+    pub current_frame: usize,
+    pub time_bank: u16,
+    pub frame_duration: u16,
+    pub finished: bool,
+}
+
+impl LinearAnimation {
+    /// Creates a new linear animation with the given tiles and frame duration
+    pub fn new(tiles: TileSequence, frame_duration: u16) -> Self {
+        Self {
+            tiles,
+            current_frame: 0,
+            time_bank: 0,
+            frame_duration,
+            finished: false,
+        }
+    }
+}

pacman/src/systems/animation/mod.rs

@@ -0,0 +1,7 @@
+mod blinking;
+mod directional;
+mod linear;
+
+pub use self::blinking::*;
+pub use self::directional::*;
+pub use self::linear::*;

pacman/src/systems/audio.rs

@@ -0,0 +1,112 @@
+//! 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},
+    resource::Resource,
+    system::{NonSendMut, ResMut},
+};
+use tracing::{debug, trace};
+
+use crate::{audio::Audio, audio::Sound};
+
+/// 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,
+}
+
+/// Events for triggering audio playback
+#[derive(Event, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AudioEvent {
+    /// Play a specific sound effect
+    PlaySound(Sound),
+    /// Play the cycling waka sound variant
+    Waka,
+    /// Stop all currently playing sounds
+    StopAll,
+    /// Pause all sounds
+    Pause,
+    /// Resume all sounds
+    Resume,
+}
+
+/// 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 state: ResMut<AudioState>, mut events: EventReader<AudioEvent>) {
+    // Set mute state if it has changed
+    if audio.0.is_muted() != state.muted {
+        debug!(muted = state.muted, "Audio mute state changed");
+        audio.0.set_mute(state.muted);
+    }
+
+    // Process audio events
+    for event in events.read() {
+        match event {
+            AudioEvent::Waka => {
+                if !audio.0.is_disabled() && !state.muted {
+                    trace!(sound_index = state.sound_index, "Playing eat sound");
+                    audio.0.waka();
+                    // Update the sound index for cycling through sounds
+                    state.sound_index = (state.sound_index + 1) % 4;
+                    // 4 eat sounds available
+                } else {
+                    debug!(
+                        disabled = audio.0.is_disabled(),
+                        muted = state.muted,
+                        "Skipping eat sound due to audio state"
+                    );
+                }
+            }
+            AudioEvent::PlaySound(sound) => {
+                if !audio.0.is_disabled() && !state.muted {
+                    trace!(?sound, "Playing sound");
+                    audio.0.play(*sound);
+                } else {
+                    debug!(
+                        disabled = audio.0.is_disabled(),
+                        muted = state.muted,
+                        "Skipping sound due to audio state"
+                    );
+                }
+            }
+            AudioEvent::StopAll => {
+                if !audio.0.is_disabled() {
+                    debug!("Stopping all audio");
+                    audio.0.stop_all();
+                } else {
+                    debug!("Audio disabled, ignoring stop all request");
+                }
+            }
+            AudioEvent::Pause => {
+                if !audio.0.is_disabled() {
+                    debug!("Pausing all audio");
+                    audio.0.pause_all();
+                } else {
+                    debug!("Audio disabled, ignoring pause all request");
+                }
+            }
+            AudioEvent::Resume => {
+                if !audio.0.is_disabled() {
+                    debug!("Resuming all audio");
+                    audio.0.resume_all();
+                } else {
+                    debug!("Audio disabled, ignoring resume all request");
+                }
+            }
+        }
+    }
+}

pacman/src/systems/collision.rs

@@ -0,0 +1,263 @@
+use bevy_ecs::{
+    component::Component,
+    entity::Entity,
+    event::EventWriter,
+    observer::Trigger,
+    query::With,
+    system::{Commands, Query, Res, ResMut},
+};
+use tracing::{debug, trace, warn};
+
+use crate::audio::Sound;
+use crate::{
+    constants,
+    systems::{movement::Position, AudioEvent, DyingSequence, FruitSprites, GameStage, Ghost, ScoreResource, SpawnTrigger},
+};
+use crate::{error::GameError, systems::GhostState};
+use crate::{
+    events::{CollisionTrigger, StageTransition},
+    systems::PelletCount,
+};
+use crate::{map::builder::Map, systems::EntityType};
+
+/// A component for defining the collision area of an entity.
+#[derive(Component)]
+pub struct Collider {
+    pub size: f32,
+}
+
+impl Collider {
+    /// Checks if this collider collides with another collider at the given distance.
+    pub fn collides_with(&self, other_size: f32, distance: f32) -> bool {
+        let collision_distance = (self.size + other_size) / 2.0;
+        distance < collision_distance
+    }
+}
+
+/// Marker components for collision filtering optimization
+#[derive(Component)]
+pub struct PacmanCollider;
+
+#[derive(Component)]
+pub struct GhostCollider;
+
+#[derive(Component)]
+pub struct ItemCollider;
+
+/// Helper function to check collision between two entities with colliders.
+pub fn check_collision(
+    pos1: &Position,
+    collider1: &Collider,
+    pos2: &Position,
+    collider2: &Collider,
+    map: &Map,
+) -> Result<bool, GameError> {
+    let pixel1 = pos1
+        .get_pixel_position(&map.graph)
+        .map_err(|e| GameError::InvalidState(format!("Failed to get pixel position for entity 1: {}", e)))?;
+    let pixel2 = pos2
+        .get_pixel_position(&map.graph)
+        .map_err(|e| GameError::InvalidState(format!("Failed to get pixel position for entity 2: {}", e)))?;
+
+    let distance = pixel1.distance(pixel2);
+    Ok(collider1.collides_with(collider2.size, distance))
+}
+
+/// Detects overlapping entities and triggers collision observers immediately.
+///
+/// Performs distance-based collision detection between Pac-Man and collectible items
+/// using each entity's position and collision radius. When entities overlap, triggers
+/// collision observers for immediate handling without race conditions.
+/// Collision detection accounts for both entities being in motion and supports
+/// circular collision boundaries for accurate gameplay feel.
+///
+/// Also detects collisions between Pac-Man and ghosts for gameplay mechanics like
+/// power pellet effects, ghost eating, and player death.
+#[allow(clippy::too_many_arguments)]
+pub fn collision_system(
+    map: Res<Map>,
+    pacman_query: Query<(Entity, &Position, &Collider), With<PacmanCollider>>,
+    item_query: Query<(Entity, &Position, &Collider), With<ItemCollider>>,
+    ghost_query: Query<(Entity, &Position, &Collider, &Ghost, &GhostState), With<GhostCollider>>,
+    mut commands: Commands,
+    mut errors: EventWriter<GameError>,
+) {
+    // Check PACMAN × ITEM collisions
+    for (pacman_entity, pacman_pos, pacman_collider) in pacman_query.iter() {
+        for (item_entity, item_pos, item_collider) in item_query.iter() {
+            match check_collision(pacman_pos, pacman_collider, item_pos, item_collider, &map) {
+                Ok(colliding) => {
+                    if colliding {
+                        trace!("Item collision detected");
+                        commands.trigger(CollisionTrigger::ItemCollision { item: item_entity });
+                    }
+                }
+                Err(e) => {
+                    errors.write(GameError::InvalidState(format!(
+                        "Collision system failed to check collision between entities {:?} and {:?}: {}",
+                        pacman_entity, item_entity, e
+                    )));
+                }
+            }
+        }
+
+        // Check PACMAN × GHOST collisions
+        for (ghost_entity, ghost_pos, ghost_collider, ghost, ghost_state) in ghost_query.iter() {
+            match check_collision(pacman_pos, pacman_collider, ghost_pos, ghost_collider, &map) {
+                Ok(colliding) => {
+                    if !colliding || matches!(*ghost_state, GhostState::Eyes) {
+                        continue;
+                    }
+
+                    trace!(ghost = ?ghost, "Ghost collision detected");
+                    commands.trigger(CollisionTrigger::GhostCollision {
+                        pacman: pacman_entity,
+                        ghost: ghost_entity,
+                        ghost_type: *ghost,
+                    });
+                }
+                Err(e) => {
+                    errors.write(GameError::InvalidState(format!(
+                        "Collision system failed to check collision between entities {:?} and {:?}: {}",
+                        pacman_entity, ghost_entity, e
+                    )));
+                }
+            }
+        }
+    }
+}
+
+/// Observer for handling ghost collisions immediately when they occur
+#[allow(clippy::too_many_arguments)]
+pub fn ghost_collision_observer(
+    trigger: Trigger<CollisionTrigger>,
+    mut stage_events: EventWriter<StageTransition>,
+    mut score: ResMut<ScoreResource>,
+    mut game_state: ResMut<GameStage>,
+    mut ghost_state_query: Query<&mut GhostState>,
+    mut events: EventWriter<AudioEvent>,
+) {
+    if let CollisionTrigger::GhostCollision {
+        pacman: _pacman,
+        ghost,
+        ghost_type,
+    } = *trigger
+    {
+        // Check if Pac-Man is already dying
+        if matches!(*game_state, GameStage::PlayerDying(_)) {
+            return;
+        }
+
+        // Check if the ghost is frightened
+        if let Ok(mut ghost_state) = ghost_state_query.get_mut(ghost) {
+            // Check if ghost is in frightened state
+            if matches!(*ghost_state, GhostState::Frightened { .. }) {
+                // Pac-Man eats the ghost
+                // Add score (200 points per ghost eaten)
+                debug!(ghost = ?ghost_type, score_added = 200, new_score = score.0 + 200, "Pacman ate frightened ghost");
+                score.0 += 200;
+
+                *ghost_state = GhostState::Eyes;
+
+                // Enter short pause to show bonus points, hide ghost, then set Eyes after pause
+                // Request transition via event so stage_system can process it
+                stage_events.write(StageTransition::GhostEatenPause {
+                    ghost_entity: ghost,
+                    ghost_type,
+                });
+
+                // Play ghost eaten sound
+                events.write(AudioEvent::PlaySound(Sound::Ghost));
+            } else if matches!(*ghost_state, GhostState::Normal) {
+                // Pac-Man dies
+                warn!(ghost = ?ghost_type, "Pacman hit by normal ghost, player dies");
+                *game_state = GameStage::PlayerDying(DyingSequence::Frozen { remaining_ticks: 60 });
+                events.write(AudioEvent::StopAll);
+            } else {
+                trace!(ghost_state = ?*ghost_state, "Ghost collision ignored due to state");
+            }
+        }
+    }
+}
+
+/// Observer for handling item collisions immediately when they occur
+#[allow(clippy::too_many_arguments)]
+pub fn item_collision_observer(
+    trigger: Trigger<CollisionTrigger>,
+    mut commands: Commands,
+    mut score: ResMut<ScoreResource>,
+    mut pellet_count: ResMut<PelletCount>,
+    item_query: Query<(Entity, &EntityType, &Position), With<ItemCollider>>,
+    mut ghost_query: Query<&mut GhostState, With<GhostCollider>>,
+    mut fruit_sprites: ResMut<FruitSprites>,
+    mut events: EventWriter<AudioEvent>,
+) {
+    if let CollisionTrigger::ItemCollision { item } = *trigger {
+        // Get the item type and update score
+        if let Ok((item_ent, entity_type, position)) = item_query.get(item) {
+            if let Some(score_value) = entity_type.score_value() {
+                trace!(item_entity = ?item_ent, item_type = ?entity_type, score_value, new_score = score.0 + score_value, "Item collected by player");
+                score.0 += score_value;
+
+                // Remove the collected item
+                commands.entity(item_ent).despawn();
+
+                // Track pellet consumption for fruit spawning
+                if *entity_type == EntityType::Pellet {
+                    pellet_count.0 += 1;
+                    trace!(pellet_count = pellet_count.0, "Pellet consumed");
+
+                    // Check if we should spawn a fruit
+                    if pellet_count.0 == 5 || pellet_count.0 == 170 {
+                        debug!(pellet_count = pellet_count.0, "Fruit spawn milestone reached");
+                        commands.trigger(SpawnTrigger::Fruit);
+                    }
+                }
+
+                // Trigger bonus points effect if a fruit is collected
+                if let EntityType::Fruit(fruit) = *entity_type {
+                    fruit_sprites.0.push(fruit);
+
+                    commands.trigger(SpawnTrigger::Bonus {
+                        position: *position,
+                        value: entity_type.score_value().unwrap(),
+                        ttl: 60 * 2,
+                    });
+                }
+
+                // Trigger audio if appropriate
+                if entity_type.is_collectible() {
+                    match *entity_type {
+                        EntityType::Fruit(_) => {
+                            events.write(AudioEvent::PlaySound(Sound::Fruit));
+                        }
+                        EntityType::Pellet | EntityType::PowerPellet => {
+                            events.write(AudioEvent::Waka);
+                        }
+                        _ => {}
+                    }
+                }
+
+                // Make non-eaten ghosts frightened when power pellet is collected
+                if matches!(*entity_type, EntityType::PowerPellet) {
+                    debug!(
+                        duration_ticks = constants::animation::GHOST_FRIGHTENED_TICKS,
+                        "Power pellet collected, frightening ghosts"
+                    );
+                    for mut ghost_state in ghost_query.iter_mut() {
+                        if matches!(*ghost_state, GhostState::Normal) {
+                            *ghost_state = GhostState::new_frightened(
+                                constants::animation::GHOST_FRIGHTENED_TICKS,
+                                constants::animation::GHOST_FRIGHTENED_FLASH_START_TICKS,
+                            );
+                        }
+                    }
+                    debug!(
+                        frightened_count = ghost_query.iter().count(),
+                        "Ghosts set to frightened state"
+                    );
+                }
+            }
+        }
+    }
+}

pacman/src/systems/common/bundles.rs

@@ -0,0 +1,43 @@
+use bevy_ecs::bundle::Bundle;
+
+use crate::systems::{
+    BufferedDirection, Collider, DirectionalAnimation, EntityType, Ghost, GhostCollider, GhostState, ItemCollider,
+    LastAnimationState, MovementModifiers, PacmanCollider, PlayerControlled, Position, Renderable, Velocity,
+};
+
+#[derive(Bundle)]
+pub struct PlayerBundle {
+    pub player: PlayerControlled,
+    pub position: Position,
+    pub velocity: Velocity,
+    pub buffered_direction: BufferedDirection,
+    pub sprite: Renderable,
+    pub directional_animation: DirectionalAnimation,
+    pub entity_type: EntityType,
+    pub collider: Collider,
+    pub movement_modifiers: MovementModifiers,
+    pub pacman_collider: PacmanCollider,
+}
+
+#[derive(Bundle)]
+pub struct ItemBundle {
+    pub position: Position,
+    pub sprite: Renderable,
+    pub entity_type: EntityType,
+    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_animation: DirectionalAnimation,
+    pub entity_type: EntityType,
+    pub collider: Collider,
+    pub ghost_collider: GhostCollider,
+    pub ghost_state: GhostState,
+    pub last_animation_state: LastAnimationState,
+}

pacman/src/systems/common/components.rs

@@ -0,0 +1,106 @@
+use bevy_ecs::{component::Component, resource::Resource};
+
+use crate::{map::graph::TraversalFlags, systems::FruitType};
+
+/// A tag component denoting the type of entity.
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum EntityType {
+    Player,
+    Ghost,
+    Pellet,
+    PowerPellet,
+    Fruit(FruitType),
+    Effect,
+}
+
+impl EntityType {
+    /// Returns the traversal flags for this entity type.
+    pub fn traversal_flags(&self) -> TraversalFlags {
+        match self {
+            EntityType::Player => TraversalFlags::PACMAN,
+            EntityType::Ghost => TraversalFlags::GHOST,
+            _ => TraversalFlags::empty(), // Static entities don't traverse
+        }
+    }
+    pub fn score_value(&self) -> Option<u32> {
+        match self {
+            EntityType::Pellet => Some(10),
+            EntityType::PowerPellet => Some(50),
+            EntityType::Fruit(fruit_type) => Some(fruit_type.score_value()),
+            _ => None,
+        }
+    }
+
+    pub fn is_collectible(&self) -> bool {
+        matches!(self, EntityType::Pellet | EntityType::PowerPellet | EntityType::Fruit(_))
+    }
+}
+
+#[derive(Resource)]
+pub struct GlobalState {
+    pub exit: bool,
+}
+
+#[derive(Resource)]
+pub struct ScoreResource(pub u32);
+
+#[derive(Resource)]
+pub struct DeltaTime {
+    /// Floating-point delta time in seconds
+    pub seconds: f32,
+    /// Integer tick delta (usually 1, but can be different for testing)
+    pub ticks: u32,
+}
+
+#[allow(dead_code)]
+impl DeltaTime {
+    /// Creates a new DeltaTime from a floating-point delta time in seconds
+    ///
+    /// While this method exists as a helper, it does not mean that seconds and ticks are interchangeable.
+    pub fn from_seconds(seconds: f32) -> Self {
+        Self {
+            seconds,
+            ticks: (seconds * 60.0).round() as u32,
+        }
+    }
+
+    /// Creates a new DeltaTime from an integer tick delta
+    ///
+    /// While this method exists as a helper, it does not mean that seconds and ticks are interchangeable.
+    pub fn from_ticks(ticks: u32) -> Self {
+        Self {
+            seconds: ticks as f32 / 60.0,
+            ticks,
+        }
+    }
+}
+
+/// Movement modifiers that can affect Pac-Man's speed or handling.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct MovementModifiers {
+    /// Multiplier applied to base speed (e.g., tunnels)
+    pub speed_multiplier: f32,
+    /// True when currently in a tunnel slowdown region
+    pub tunnel_slowdown_active: bool,
+}
+
+impl Default for MovementModifiers {
+    fn default() -> Self {
+        Self {
+            speed_multiplier: 1.0,
+            tunnel_slowdown_active: false,
+        }
+    }
+}
+
+/// Tag component for entities that should be frozen during startup
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Frozen;
+
+/// Component for HUD life sprite entities.
+/// Each life sprite entity has an index indicating its position from left to right (0, 1, 2, etc.).
+/// This mostly functions as a tag component for sprites.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct PlayerLife {
+    pub index: u32,
+}

pacman/src/systems/common/mod.rs

@@ -0,0 +1,5 @@
+pub mod bundles;
+pub mod components;
+
+pub use self::bundles::*;
+pub use self::components::*;

pacman/src/systems/debug.rs

@@ -0,0 +1,339 @@
+//! Debug rendering system
+use crate::constants::{self, BOARD_PIXEL_OFFSET};
+use crate::map::builder::Map;
+use crate::systems::{Collider, CursorPosition, NodeId, Position, SystemTimings};
+use crate::texture::ttf::{TtfAtlas, TtfRenderer};
+use bevy_ecs::resource::Resource;
+use bevy_ecs::system::{Query, Res};
+use glam::{IVec2, Vec2};
+use sdl2::pixels::Color;
+use sdl2::rect::{Point, Rect};
+use sdl2::render::{Canvas, Texture};
+use sdl2::video::Window;
+use smallvec::SmallVec;
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use tracing::warn;
+
+#[derive(Resource, Default, Debug, Copy, Clone)]
+pub struct DebugState {
+    pub enabled: bool,
+}
+
+fn f32_to_u8(value: f32) -> u8 {
+    (value * 255.0) as u8
+}
+
+/// Resource to hold the debug texture for persistent rendering
+pub struct DebugTextureResource(pub Texture);
+
+/// Resource to hold the TTF text atlas
+pub struct TtfAtlasResource(pub TtfAtlas);
+
+/// Resource to hold pre-computed batched line segments
+#[derive(Resource, Default, Debug, Clone)]
+pub struct BatchedLinesResource {
+    horizontal_lines: Vec<(i32, i32, i32)>, // (y, x_start, x_end)
+    vertical_lines: Vec<(i32, i32, i32)>,   // (x, y_start, y_end)
+}
+
+impl BatchedLinesResource {
+    /// Computes and caches batched line segments for the map graph
+    pub fn new(map: &Map, scale: f32) -> Self {
+        let mut horizontal_segments: HashMap<i32, Vec<(i32, i32)>> = HashMap::new();
+        let mut vertical_segments: HashMap<i32, Vec<(i32, i32)>> = HashMap::new();
+        let mut processed_edges: HashSet<(u16, u16)> = HashSet::new();
+
+        // Process all edges and group them by axis
+        for (start_node_id, edge) in map.graph.edges() {
+            // Acquire a stable key for the edge (from < to)
+            let edge_key = (start_node_id.min(edge.target), start_node_id.max(edge.target));
+
+            // Skip if we've already processed this edge in the reverse direction
+            if processed_edges.contains(&edge_key) {
+                continue;
+            }
+            processed_edges.insert(edge_key);
+
+            let start_pos = map.graph.get_node(start_node_id).unwrap().position;
+            let end_pos = map.graph.get_node(edge.target).unwrap().position;
+
+            let start = transform_position_with_offset(start_pos, scale);
+            let end = transform_position_with_offset(end_pos, scale);
+
+            // Determine if this is a horizontal or vertical line
+            if (start.y - end.y).abs() < 2 {
+                // Horizontal line (allowing for slight vertical variance)
+                let y = start.y;
+                let x_min = start.x.min(end.x);
+                let x_max = start.x.max(end.x);
+                horizontal_segments.entry(y).or_default().push((x_min, x_max));
+            } else if (start.x - end.x).abs() < 2 {
+                // Vertical line (allowing for slight horizontal variance)
+                let x = start.x;
+                let y_min = start.y.min(end.y);
+                let y_max = start.y.max(end.y);
+                vertical_segments.entry(x).or_default().push((y_min, y_max));
+            }
+        }
+
+        /// Merges overlapping or adjacent segments into continuous lines
+        fn merge_segments(segments: Vec<(i32, i32)>) -> Vec<(i32, i32)> {
+            if segments.is_empty() {
+                return Vec::new();
+            }
+
+            let mut merged = Vec::new();
+            let mut current_start = segments[0].0;
+            let mut current_end = segments[0].1;
+
+            for &(start, end) in segments.iter().skip(1) {
+                if start <= current_end + 1 {
+                    // Adjacent or overlapping
+                    current_end = current_end.max(end);
+                } else {
+                    merged.push((current_start, current_end));
+                    current_start = start;
+                    current_end = end;
+                }
+            }
+
+            merged.push((current_start, current_end));
+            merged
+        }
+
+        // Convert to flat vectors for fast iteration during rendering
+        let horizontal_lines = horizontal_segments
+            .into_iter()
+            .flat_map(|(y, mut segments)| {
+                segments.sort_unstable_by_key(|(start, _)| *start);
+                let merged = merge_segments(segments);
+                merged.into_iter().map(move |(x_start, x_end)| (y, x_start, x_end))
+            })
+            .collect::<Vec<_>>();
+
+        let vertical_lines = vertical_segments
+            .into_iter()
+            .flat_map(|(x, mut segments)| {
+                segments.sort_unstable_by_key(|(start, _)| *start);
+                let merged = merge_segments(segments);
+                merged.into_iter().map(move |(y_start, y_end)| (x, y_start, y_end))
+            })
+            .collect::<Vec<_>>();
+
+        Self {
+            horizontal_lines,
+            vertical_lines,
+        }
+    }
+
+    pub fn render(&self, canvas: &mut Canvas<Window>) {
+        // Render horizontal lines
+        for &(y, x_start, x_end) in &self.horizontal_lines {
+            let points = [Point::new(x_start, y), Point::new(x_end, y)];
+            let _ = canvas.draw_lines(&points[..]);
+        }
+
+        // Render vertical lines
+        for &(x, y_start, y_end) in &self.vertical_lines {
+            let points = [Point::new(x, y_start), Point::new(x, y_end)];
+            let _ = canvas.draw_lines(&points[..]);
+        }
+    }
+}
+
+/// Transforms a position from logical canvas coordinates to output canvas coordinates (with board offset)
+fn transform_position_with_offset(pos: Vec2, scale: f32) -> IVec2 {
+    ((pos + BOARD_PIXEL_OFFSET.as_vec2()) * scale).as_ivec2()
+}
+
+/// Renders timing information in the top-left corner of the screen using the debug text atlas
+#[cfg_attr(coverage_nightly, coverage(off))]
+fn render_timing_display(
+    canvas: &mut Canvas<Window>,
+    timings: &SystemTimings,
+    current_tick: u64,
+    text_renderer: &TtfRenderer,
+    atlas: &mut TtfAtlas,
+) {
+    // Format timing information using the formatting module
+    let lines = timings.format_timing_display(current_tick);
+    let line_height = text_renderer.text_height(atlas) as i32 + 2; // Add 2px line spacing
+    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| text_renderer.text_width(atlas, line))
+        .max()
+        .unwrap_or(0);
+
+    // Only draw background if there is text to display
+    let total_height = (lines.len() as u32) * line_height as u32;
+    if max_width > 0 && total_height > 0 {
+        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;
+        }
+
+        // Position each line below the previous one
+        let y_pos = padding + (i as i32 * line_height);
+        let position = Vec2::new(padding as f32, y_pos as f32);
+
+        // Render the line using the debug text renderer
+        text_renderer
+            .render_text(canvas, atlas, line, position, Color::RGBA(255, 255, 255, 200))
+            .unwrap();
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub fn debug_render_system(
+    canvas: &mut Canvas<Window>,
+    ttf_atlas: &mut TtfAtlasResource,
+    batched_lines: &Res<BatchedLinesResource>,
+    debug_state: &Res<DebugState>,
+    timings: &Res<SystemTimings>,
+    timing: &Res<crate::systems::profiling::Timing>,
+    map: &Res<Map>,
+    colliders: &Query<(&Collider, &Position)>,
+    cursor: &Res<CursorPosition>,
+) {
+    if !debug_state.enabled {
+        return;
+    }
+    // Create debug text renderer
+    let text_renderer = TtfRenderer::new(1.0);
+
+    let cursor_world_pos = match &**cursor {
+        CursorPosition::None => None,
+        CursorPosition::Some { position, .. } => Some(position - BOARD_PIXEL_OFFSET.as_vec2()),
+    };
+
+    // Clear the debug canvas
+    canvas.set_draw_color(Color::RGBA(0, 0, 0, 0));
+    canvas.clear();
+
+    // Find the closest node to the cursor
+    let closest_node = if let Some(cursor_world_pos) = cursor_world_pos {
+        map.graph
+            .nodes()
+            .map(|node| node.position.distance(cursor_world_pos))
+            .enumerate()
+            .min_by(|(_, a), (_, b)| a.partial_cmp(b).unwrap_or(Ordering::Less))
+            .map(|(id, _)| id)
+    } else {
+        None
+    };
+
+    canvas.set_draw_color(Color::GREEN);
+    {
+        let rects = colliders
+            .iter()
+            .map(|(collider, position)| {
+                let pos = position.get_pixel_position(&map.graph).unwrap();
+
+                // Transform position and size using common methods
+                let pos = (pos * constants::LARGE_SCALE).as_ivec2();
+                let size = (collider.size * constants::LARGE_SCALE) as u32;
+
+                Rect::from_center(Point::from((pos.x, pos.y)), size, size)
+            })
+            .collect::<SmallVec<[Rect; 100]>>();
+        if rects.len() > rects.capacity() {
+            warn!(
+                capacity = rects.capacity(),
+                count = rects.len(),
+                "Collider rects capacity exceeded"
+            );
+        }
+        canvas.draw_rects(&rects).unwrap();
+    }
+
+    canvas.set_draw_color(Color {
+        a: f32_to_u8(0.65),
+        ..Color::RED
+    });
+    canvas.set_blend_mode(sdl2::render::BlendMode::Blend);
+
+    // Use cached batched line segments
+    batched_lines.render(canvas);
+
+    {
+        let rects: Vec<_> = map
+            .graph
+            .nodes()
+            .enumerate()
+            .filter_map(|(id, node)| {
+                let pos = transform_position_with_offset(node.position, constants::LARGE_SCALE);
+                let size = (2.0 * constants::LARGE_SCALE) as u32;
+                let rect = Rect::new(pos.x - (size as i32 / 2), pos.y - (size as i32 / 2), size, size);
+
+                // If the node is the one closest to the cursor, draw it immediately
+                if closest_node == Some(id) {
+                    canvas.set_draw_color(Color::YELLOW);
+                    canvas.fill_rect(rect).unwrap();
+                    return None;
+                }
+
+                Some(rect)
+            })
+            .collect();
+
+        if rects.len() > rects.capacity() {
+            warn!(
+                capacity = rects.capacity(),
+                count = rects.len(),
+                "Node rects capacity exceeded"
+            );
+        }
+
+        // Draw the non-closest nodes all at once in blue
+        canvas.set_draw_color(Color::BLUE);
+        canvas.fill_rects(&rects).unwrap();
+    }
+
+    // Render node ID if a node is highlighted
+    if let Some(closest_node_id) = closest_node {
+        let node = map.graph.get_node(closest_node_id as NodeId).unwrap();
+        let pos = transform_position_with_offset(node.position, constants::LARGE_SCALE);
+
+        let node_id_text = closest_node_id.to_string();
+        let text_pos = Vec2::new((pos.x + 10) as f32, (pos.y - 5) as f32);
+
+        text_renderer
+            .render_text(
+                canvas,
+                &mut ttf_atlas.0,
+                &node_id_text,
+                text_pos,
+                Color {
+                    a: f32_to_u8(0.9),
+                    ..Color::WHITE
+                },
+            )
+            .unwrap();
+    }
+
+    // Render timing information in the top-left corner
+    // Use previous tick since current tick is incomplete (frame is still running)
+    let current_tick = timing.get_current_tick();
+    let previous_tick = current_tick.saturating_sub(1);
+    render_timing_display(canvas, timings, previous_tick, &text_renderer, &mut ttf_atlas.0);
+}

pacman/src/systems/ghost.rs

@@ -0,0 +1,402 @@
+use std::collections::HashMap;
+
+use crate::platform;
+use crate::systems::{DirectionalAnimation, Frozen, LinearAnimation, Looping};
+use crate::{
+    map::{
+        builder::Map,
+        direction::Direction,
+        graph::{Edge, TraversalFlags},
+    },
+    systems::{
+        components::DeltaTime,
+        movement::{Position, Velocity},
+    },
+};
+use bevy_ecs::component::Component;
+use bevy_ecs::resource::Resource;
+use tracing::{debug, trace, warn};
+
+use bevy_ecs::query::Without;
+use bevy_ecs::system::{Commands, Query, Res};
+use rand::seq::IndexedRandom;
+use smallvec::SmallVec;
+
+/// Tag component for Pac-Man during his death animation.
+/// This is mainly because the Frozen tag would stop both movement and animation, while the Dying tag can signal that the animation should continue despite being frozen.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct Dying;
+
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Hash)]
+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,
+        }
+    }
+}
+
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GhostState {
+    /// Normal ghost behavior - chasing Pac-Man
+    Normal,
+    /// Frightened state after power pellet - ghost can be eaten
+    Frightened {
+        remaining_ticks: u32,
+        flash: bool,
+        remaining_flash_ticks: u32,
+    },
+    /// Eyes state - ghost has been eaten and is returning to ghost house
+    Eyes,
+}
+
+impl GhostState {
+    /// Creates a new frightened state with the specified duration
+    pub fn new_frightened(total_ticks: u32, flash_start_ticks: u32) -> Self {
+        Self::Frightened {
+            remaining_ticks: total_ticks,
+            flash: false,
+            remaining_flash_ticks: flash_start_ticks, // Time until flashing starts
+        }
+    }
+
+    /// Ticks the ghost state, returning true if the state changed.
+    pub fn tick(&mut self) -> bool {
+        if let GhostState::Frightened {
+            remaining_ticks,
+            flash,
+            remaining_flash_ticks,
+        } = self
+        {
+            // Transition out of frightened state
+            if *remaining_ticks == 0 {
+                *self = GhostState::Normal;
+                return true;
+            }
+
+            *remaining_ticks -= 1;
+
+            if *remaining_flash_ticks > 0 {
+                *remaining_flash_ticks = remaining_flash_ticks.saturating_sub(1);
+                if *remaining_flash_ticks == 0 {
+                    *flash = true;
+                    true
+                } else {
+                    false
+                }
+            } else {
+                false
+            }
+        } else {
+            false
+        }
+    }
+
+    /// Returns the appropriate animation state for this ghost state
+    pub fn animation_state(&self) -> GhostAnimation {
+        match self {
+            GhostState::Normal => GhostAnimation::Normal,
+            GhostState::Eyes => GhostAnimation::Eyes,
+            GhostState::Frightened { flash: false, .. } => GhostAnimation::Frightened { flash: false },
+            GhostState::Frightened { flash: true, .. } => GhostAnimation::Frightened { flash: true },
+        }
+    }
+}
+
+/// Enumeration of different ghost animation states.
+/// Note that this is used in micromap which has a fixed size based on the number of variants,
+/// so extending this should be done with caution, and will require updating the micromap's capacity.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum GhostAnimation {
+    /// Normal ghost appearance with directional movement animations
+    Normal,
+    /// Blue ghost appearance when vulnerable (power pellet active)
+    Frightened { flash: bool },
+    /// Eyes-only animation when ghost has been consumed by Pac-Man (Eaten state)
+    Eyes,
+}
+
+/// Global resource containing pre-loaded animation sets for all ghost types.
+///
+/// This resource is initialized once during game startup and provides O(1) access
+/// to animation sets for each ghost type. The animation system uses this resource
+/// to efficiently switch between different ghost states without runtime asset loading.
+///
+/// The HashMap is keyed by `Ghost` enum variants (Blinky, Pinky, Inky, Clyde) and
+/// contains the normal directional animation for each ghost type.
+#[derive(Resource)]
+pub struct GhostAnimations {
+    pub normal: HashMap<Ghost, DirectionalAnimation>,
+    pub eyes: DirectionalAnimation,
+    pub frightened: LinearAnimation,
+    pub frightened_flashing: LinearAnimation,
+}
+
+impl GhostAnimations {
+    /// Creates a new GhostAnimations resource with the provided data.
+    pub fn new(
+        normal: HashMap<Ghost, DirectionalAnimation>,
+        eyes: DirectionalAnimation,
+        frightened: LinearAnimation,
+        frightened_flashing: LinearAnimation,
+    ) -> Self {
+        Self {
+            normal,
+            eyes,
+            frightened,
+            frightened_flashing,
+        }
+    }
+
+    /// Gets the normal directional animation for the specified ghost type.
+    pub fn get_normal(&self, ghost_type: &Ghost) -> Option<&DirectionalAnimation> {
+        self.normal.get(ghost_type)
+    }
+
+    /// Gets the eyes animation (shared across all ghosts).
+    pub fn eyes(&self) -> &DirectionalAnimation {
+        &self.eyes
+    }
+
+    /// Gets the frightened animations (shared across all ghosts).
+    pub fn frightened(&self, flash: bool) -> &LinearAnimation {
+        if flash {
+            &self.frightened_flashing
+        } else {
+            &self.frightened
+        }
+    }
+}
+
+/// Autonomous ghost AI system implementing randomized movement with backtracking avoidance.
+pub fn ghost_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut ghosts: Query<(&Ghost, &mut Velocity, &mut Position), Without<Frozen>>,
+) {
+    for (_ghost, mut velocity, mut position) in ghosts.iter_mut() {
+        let mut distance = velocity.speed * 60.0 * delta_time.seconds;
+        loop {
+            match *position {
+                Position::Stopped { node: current_node } => {
+                    let intersection = &map.graph.adjacency_list[current_node as usize];
+                    let opposite = velocity.direction.opposite();
+
+                    let mut non_opposite_options: SmallVec<[Edge; 3]> = SmallVec::new();
+
+                    // Collect all available directions that ghosts can traverse
+                    for edge in Direction::DIRECTIONS.iter().flat_map(|d| intersection.get(*d)) {
+                        if edge.traversal_flags.contains(TraversalFlags::GHOST) && edge.direction != opposite {
+                            non_opposite_options.push(edge);
+                        }
+                    }
+
+                    let new_edge: Edge = if non_opposite_options.is_empty() {
+                        if let Some(edge) = intersection.get(opposite) {
+                            trace!(node = current_node, ghost = ?_ghost, direction = ?opposite, "Ghost forced to reverse direction");
+                            edge
+                        } else {
+                            warn!(node = current_node, ghost = ?_ghost, "Ghost stuck with no available directions");
+                            break;
+                        }
+                    } else {
+                        *non_opposite_options.choose(&mut platform::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;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// System that handles eaten ghost behavior and respawn logic.
+///
+/// When a ghost is eaten by Pac-Man, it enters an "eaten" state where:
+/// 1. It displays eyes-only animation
+/// 2. It moves directly back to the ghost house at increased speed
+/// 3. Once it reaches the ghost house center, it respawns as a normal ghost
+///
+/// This system runs after the main movement system to override eaten ghost movement.
+pub fn eaten_ghost_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut eaten_ghosts: Query<(&Ghost, &mut Position, &mut Velocity, &mut GhostState), Without<Frozen>>,
+) {
+    for (ghost_type, mut position, mut velocity, mut ghost_state) in eaten_ghosts.iter_mut() {
+        // Only process ghosts that are in Eyes state
+        if !matches!(*ghost_state, GhostState::Eyes) {
+            continue;
+        }
+        // Set higher speed for eaten ghosts returning to ghost house
+        let original_speed = velocity.speed;
+        velocity.speed = ghost_type.base_speed() * 2.0; // Move twice as fast when eaten
+
+        // Calculate direction towards ghost house center (using Clyde's start position)
+        let ghost_house_center = map.start_positions.clyde;
+
+        match *position {
+            Position::Stopped { node: current_node } => {
+                // Find path to ghost house center and start moving
+                if let Some(direction) = find_direction_to_target(&map, current_node, ghost_house_center) {
+                    velocity.direction = direction;
+                    *position = Position::Moving {
+                        from: current_node,
+                        to: map.graph.adjacency_list[current_node as usize].get(direction).unwrap().target,
+                        remaining_distance: map.graph.adjacency_list[current_node as usize]
+                            .get(direction)
+                            .unwrap()
+                            .distance,
+                    };
+                }
+            }
+            Position::Moving { to, .. } => {
+                let distance = velocity.speed * 60.0 * delta_time.seconds;
+                if let Some(_overflow) = position.tick(distance) {
+                    // Reached target node, check if we're at ghost house center
+                    if to == ghost_house_center {
+                        // Respawn the ghost - set state back to normal
+                        debug!(ghost = ?ghost_type, "Eaten ghost reached ghost house, respawning as normal");
+                        *ghost_state = GhostState::Normal;
+                        // Reset to stopped at ghost house center
+                        *position = Position::Stopped {
+                            node: ghost_house_center,
+                        };
+                    } else {
+                        // Continue pathfinding to ghost house
+                        if let Some(next_direction) = find_direction_to_target(&map, to, ghost_house_center) {
+                            velocity.direction = next_direction;
+                            *position = Position::Moving {
+                                from: to,
+                                to: map.graph.adjacency_list[to as usize].get(next_direction).unwrap().target,
+                                remaining_distance: map.graph.adjacency_list[to as usize].get(next_direction).unwrap().distance,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+
+        // Restore original speed
+        velocity.speed = original_speed;
+    }
+}
+
+/// Helper function to find the direction from a node towards a target node.
+/// Uses simple greedy pathfinding - prefers straight lines when possible.
+fn find_direction_to_target(
+    map: &Map,
+    from_node: crate::systems::movement::NodeId,
+    target_node: crate::systems::movement::NodeId,
+) -> Option<Direction> {
+    let from_pos = map.graph.get_node(from_node).unwrap().position;
+    let target_pos = map.graph.get_node(target_node).unwrap().position;
+
+    let dx = target_pos.x as i32 - from_pos.x as i32;
+    let dy = target_pos.y as i32 - from_pos.y as i32;
+
+    // Prefer horizontal movement first, then vertical
+    let preferred_dirs = if dx.abs() > dy.abs() {
+        if dx > 0 {
+            [Direction::Right, Direction::Up, Direction::Down, Direction::Left]
+        } else {
+            [Direction::Left, Direction::Up, Direction::Down, Direction::Right]
+        }
+    } else if dy > 0 {
+        [Direction::Down, Direction::Left, Direction::Right, Direction::Up]
+    } else {
+        [Direction::Up, Direction::Left, Direction::Right, Direction::Down]
+    };
+
+    // Return first available direction towards target
+    for direction in preferred_dirs {
+        if let Some(edge) = map.graph.adjacency_list[from_node as usize].get(direction) {
+            if edge.traversal_flags.contains(TraversalFlags::GHOST) {
+                return Some(direction);
+            }
+        }
+    }
+
+    None
+}
+
+/// Component to track the last animation state for efficient change detection
+#[derive(Component, Debug, Clone, Copy, PartialEq)]
+pub struct LastAnimationState(pub GhostAnimation);
+
+/// Unified system that manages ghost state transitions and animations with component swapping
+pub fn ghost_state_system(
+    mut commands: Commands,
+    animations: Res<GhostAnimations>,
+    mut ghosts: Query<(bevy_ecs::entity::Entity, &Ghost, &mut GhostState, &mut LastAnimationState)>,
+) {
+    for (entity, ghost_type, mut ghost_state, mut last_animation_state) in ghosts.iter_mut() {
+        // Tick the ghost state to handle internal transitions (like flashing)
+        let _ = ghost_state.tick();
+
+        // Only update animation if the animation state actually changed
+        let current_animation_state = ghost_state.animation_state();
+        if last_animation_state.0 != current_animation_state {
+            trace!(ghost = ?ghost_type, old_state = ?last_animation_state.0, new_state = ?current_animation_state, "Ghost animation state changed");
+            match current_animation_state {
+                GhostAnimation::Frightened { flash } => {
+                    // Remove DirectionalAnimation, add LinearAnimation with Looping component
+                    commands
+                        .entity(entity)
+                        .remove::<DirectionalAnimation>()
+                        .insert(animations.frightened(flash).clone())
+                        .insert(Looping);
+                }
+                GhostAnimation::Normal => {
+                    // Remove LinearAnimation and Looping, add DirectionalAnimation
+                    commands
+                        .entity(entity)
+                        .remove::<(LinearAnimation, Looping)>()
+                        .insert(animations.get_normal(ghost_type).unwrap().clone());
+                }
+                GhostAnimation::Eyes => {
+                    // Remove LinearAnimation and Looping, add DirectionalAnimation (eyes animation)
+                    trace!(ghost = ?ghost_type, "Switching to eyes animation for eaten ghost");
+                    commands
+                        .entity(entity)
+                        .remove::<(LinearAnimation, Looping)>()
+                        .insert(animations.eyes().clone());
+                }
+            }
+            last_animation_state.0 = current_animation_state;
+        }
+    }
+}

pacman/src/systems/hud/fruits.rs

@@ -0,0 +1,79 @@
+use crate::systems::item::FruitType;
+use crate::texture::sprites::GameSprite;
+use bevy_ecs::component::Component;
+use bevy_ecs::resource::Resource;
+
+#[derive(Component)]
+pub struct FruitInHud {
+    pub index: u32,
+}
+
+#[derive(Resource, Default)]
+pub struct FruitSprites(pub Vec<FruitType>);
+
+use crate::constants::{BOARD_BOTTOM_PIXEL_OFFSET, CANVAS_SIZE, CELL_SIZE};
+use crate::error::GameError;
+use crate::systems::{PixelPosition, Renderable};
+use crate::texture::sprite::SpriteAtlas;
+use bevy_ecs::entity::Entity;
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::system::{Commands, NonSendMut, Query, Res};
+use glam::Vec2;
+
+/// Calculates the pixel position for a fruit sprite based on its index
+fn calculate_fruit_sprite_position(index: u32) -> Vec2 {
+    let start_x = CANVAS_SIZE.x - CELL_SIZE * 2; // 2 cells from right
+    let start_y = CANVAS_SIZE.y - BOARD_BOTTOM_PIXEL_OFFSET.y + (CELL_SIZE / 2) + 1; // In bottom area
+    let sprite_spacing = CELL_SIZE + CELL_SIZE / 2; // 1.5 cells between sprites
+
+    let x = start_x - ((index as f32) * (sprite_spacing as f32 * 1.5)).round() as u32;
+    let y = start_y - (1 + CELL_SIZE / 2);
+
+    Vec2::new((x - CELL_SIZE) as f32, (y + CELL_SIZE) as f32)
+}
+
+/// System that manages fruit sprite entities in the HUD.
+/// Spawns and despawns fruit sprite entities based on changes to FruitSprites resource.
+/// Displays up to 6 fruits, sorted by value.
+pub fn fruit_sprite_system(
+    mut commands: Commands,
+    atlas: NonSendMut<SpriteAtlas>,
+    current_fruit_sprites: Query<(Entity, &FruitInHud)>,
+    fruit_sprites: Res<FruitSprites>,
+    mut errors: EventWriter<GameError>,
+) {
+    // We only want to display the greatest 6 fruits
+    let fruits_to_display: Vec<_> = fruit_sprites.0.iter().rev().take(6).collect();
+
+    let mut current_sprites: Vec<_> = current_fruit_sprites.iter().collect();
+    current_sprites.sort_by_key(|(_, fruit)| fruit.index);
+
+    // Despawn all current sprites. We will respawn them.
+    // This is simpler than trying to match them up.
+    for (entity, _) in &current_sprites {
+        commands.entity(*entity).despawn();
+    }
+
+    for (i, fruit_type) in fruits_to_display.iter().enumerate() {
+        let fruit_sprite = match atlas.get_tile(&GameSprite::Fruit(**fruit_type).to_path()) {
+            Ok(sprite) => sprite,
+            Err(e) => {
+                errors.write(e.into());
+                continue;
+            }
+        };
+
+        let position = calculate_fruit_sprite_position(i as u32);
+
+        commands.spawn((
+            FruitInHud { index: i as u32 },
+            Renderable {
+                sprite: fruit_sprite,
+                layer: 255, // High layer to render on top
+            },
+            PixelPosition {
+                pixel_position: position,
+            },
+        ));
+    }
+}

pacman/src/systems/hud/lives.rs

@@ -0,0 +1,89 @@
+use std::cmp::Ordering;
+
+use crate::constants::{BOARD_BOTTOM_PIXEL_OFFSET, CANVAS_SIZE, CELL_SIZE};
+use crate::error::GameError;
+use crate::map::direction::Direction;
+use crate::systems::{PixelPosition, PlayerLife, PlayerLives, Renderable};
+use crate::texture::sprite::SpriteAtlas;
+use crate::texture::sprites::{GameSprite, PacmanSprite};
+use bevy_ecs::entity::Entity;
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::system::{Commands, NonSendMut, Query, Res};
+use glam::Vec2;
+
+/// Calculates the pixel position for a life sprite based on its index
+fn calculate_life_sprite_position(index: u32) -> Vec2 {
+    let start_x = CELL_SIZE * 2; // 2 cells from left
+    let start_y = CANVAS_SIZE.y - BOARD_BOTTOM_PIXEL_OFFSET.y + (CELL_SIZE / 2) + 1; // In bottom area
+    let sprite_spacing = CELL_SIZE + CELL_SIZE / 2; // 1.5 cells between sprites
+
+    let x = start_x + ((index as f32) * (sprite_spacing as f32 * 1.5)).round() as u32;
+    let y = start_y - CELL_SIZE / 2;
+
+    Vec2::new((x + CELL_SIZE) as f32, (y + CELL_SIZE) as f32)
+}
+
+/// System that manages player life sprite entities.
+/// Spawns and despawns life sprite entities based on changes to PlayerLives resource.
+/// Each life sprite is positioned based on its index (0, 1, 2, etc. from left to right).
+pub fn player_life_sprite_system(
+    mut commands: Commands,
+    atlas: NonSendMut<SpriteAtlas>,
+    current_life_sprites: Query<(Entity, &PlayerLife)>,
+    player_lives: Res<PlayerLives>,
+    mut errors: EventWriter<GameError>,
+) {
+    let displayed_lives = player_lives.0.saturating_sub(1);
+
+    // Get current life sprite entities, sorted by index
+    let mut current_sprites: Vec<_> = current_life_sprites.iter().collect();
+    current_sprites.sort_by_key(|(_, life)| life.index);
+    let current_count = current_sprites.len() as u8;
+
+    // Calculate the difference
+    let diff = (displayed_lives as i8) - (current_count as i8);
+
+    match diff.cmp(&0) {
+        // Ignore when the number of lives displayed is correct
+        Ordering::Equal => {}
+        // Spawn new life sprites
+        Ordering::Greater => {
+            let life_sprite = match atlas.get_tile(&GameSprite::Pacman(PacmanSprite::Moving(Direction::Left, 1)).to_path()) {
+                Ok(sprite) => sprite,
+                Err(e) => {
+                    errors.write(e.into());
+                    return;
+                }
+            };
+
+            for i in 0..diff {
+                let position = calculate_life_sprite_position(i as u32);
+
+                commands.spawn((
+                    PlayerLife { index: i as u32 },
+                    Renderable {
+                        sprite: life_sprite,
+                        layer: 255, // High layer to render on top
+                    },
+                    PixelPosition {
+                        pixel_position: position,
+                    },
+                ));
+            }
+        }
+        // Remove excess life sprites (highest indices first)
+        Ordering::Less => {
+            let to_remove = diff.unsigned_abs();
+            let sprites_to_remove: Vec<_> = current_sprites
+                .iter()
+                .rev() // Start from highest index
+                .take(to_remove as usize)
+                .map(|(entity, _)| *entity)
+                .collect();
+
+            for entity in sprites_to_remove {
+                commands.entity(entity).despawn();
+            }
+        }
+    }
+}

pacman/src/systems/hud/mod.rs

@@ -0,0 +1,9 @@
+pub mod fruits;
+pub mod lives;
+pub mod score;
+pub mod touch;
+
+pub use self::fruits::*;
+pub use self::lives::*;
+pub use self::score::*;
+pub use self::touch::*;

pacman/src/systems/hud/score.rs

@@ -0,0 +1,86 @@
+use crate::constants;
+use crate::error::{GameError, TextureError};
+use crate::systems::{BackbufferResource, GameStage, ScoreResource, StartupSequence};
+use crate::texture::sprite::SpriteAtlas;
+use crate::texture::text::TextTexture;
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::system::{NonSendMut, Res};
+use sdl2::pixels::Color;
+use sdl2::render::Canvas;
+use sdl2::video::Window;
+
+/// Renders the HUD (score, lives, etc.) on top of the game.
+#[allow(clippy::too_many_arguments)]
+pub fn hud_render_system(
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    mut atlas: NonSendMut<SpriteAtlas>,
+    score: Res<ScoreResource>,
+    stage: Res<GameStage>,
+    mut errors: EventWriter<GameError>,
+) {
+    let _ = canvas.with_texture_canvas(&mut backbuffer.0, |canvas| {
+        let mut text_renderer = TextTexture::new(1.0);
+
+        // Render lives and high score text in white
+        let lives_text = "1UP   HIGH SCORE   ";
+        let lives_position = glam::UVec2::new(4 + 8 * 3, 2); // x_offset + lives_offset * 8, y_offset
+
+        if let Err(e) = text_renderer.render(canvas, &mut atlas, lives_text, lives_position) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render lives text: {}", e)).into());
+        }
+
+        // Render score text
+        let score_text = format!("{:02}", score.0);
+        let score_offset = 7 - (score_text.len() as i32);
+        let score_position = glam::UVec2::new(4 + 8 * score_offset as u32, 10); // x_offset + score_offset * 8, 8 + y_offset
+
+        if let Err(e) = text_renderer.render(canvas, &mut atlas, &score_text, score_position) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render score text: {}", e)).into());
+        }
+
+        // Render high score text
+        let high_score_text = format!("{:02}", score.0);
+        let high_score_offset = 17 - (high_score_text.len() as i32);
+        let high_score_position = glam::UVec2::new(4 + 8 * high_score_offset as u32, 10); // x_offset + score_offset * 8, 8 + y_offset
+        if let Err(e) = text_renderer.render(canvas, &mut atlas, &high_score_text, high_score_position) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render high score text: {}", e)).into());
+        }
+
+        // Render GAME OVER text
+        if matches!(*stage, GameStage::GameOver) {
+            let game_over_text = "GAME  OVER";
+            let game_over_width = text_renderer.text_width(game_over_text);
+            let game_over_position = glam::UVec2::new((constants::CANVAS_SIZE.x - game_over_width) / 2, 160);
+            if let Err(e) = text_renderer.render_with_color(canvas, &mut atlas, game_over_text, game_over_position, Color::RED) {
+                errors.write(TextureError::RenderFailed(format!("Failed to render GAME OVER text: {}", e)).into());
+            }
+        }
+
+        // Render text based on StartupSequence stage
+        if matches!(
+            *stage,
+            GameStage::Starting(StartupSequence::TextOnly { .. })
+                | GameStage::Starting(StartupSequence::CharactersVisible { .. })
+        ) {
+            let ready_text = "READY!";
+            let ready_width = text_renderer.text_width(ready_text);
+            let ready_position = glam::UVec2::new((constants::CANVAS_SIZE.x - ready_width) / 2, 160);
+            if let Err(e) = text_renderer.render_with_color(canvas, &mut atlas, ready_text, ready_position, Color::YELLOW) {
+                errors.write(TextureError::RenderFailed(format!("Failed to render READY text: {}", e)).into());
+            }
+
+            if matches!(*stage, GameStage::Starting(StartupSequence::TextOnly { .. })) {
+                let player_one_text = "PLAYER ONE";
+                let player_one_width = text_renderer.text_width(player_one_text);
+                let player_one_position = glam::UVec2::new((constants::CANVAS_SIZE.x - player_one_width) / 2, 113);
+
+                if let Err(e) =
+                    text_renderer.render_with_color(canvas, &mut atlas, player_one_text, player_one_position, Color::CYAN)
+                {
+                    errors.write(TextureError::RenderFailed(format!("Failed to render PLAYER ONE text: {}", e)).into());
+                }
+            }
+        }
+    });
+}

pacman/src/systems/hud/touch.rs

@@ -0,0 +1,81 @@
+use crate::error::{GameError, TextureError};
+use crate::systems::{BackbufferResource, TouchState};
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::system::{NonSendMut, Res};
+use sdl2::pixels::Color;
+use sdl2::rect::Point;
+use sdl2::render::{BlendMode, Canvas};
+use sdl2::video::Window;
+
+/// Renders touch UI overlay for mobile/testing.
+pub fn touch_ui_render_system(
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    touch_state: Res<TouchState>,
+    mut errors: EventWriter<GameError>,
+) {
+    if let Some(ref touch_data) = touch_state.active_touch {
+        let _ = canvas.with_texture_canvas(&mut backbuffer.0, |canvas| {
+            // Set blend mode for transparency
+            canvas.set_blend_mode(BlendMode::Blend);
+
+            // Draw semi-transparent circle at touch start position
+            canvas.set_draw_color(Color::RGBA(255, 255, 255, 100));
+            let center = Point::new(touch_data.start_pos.x as i32, touch_data.start_pos.y as i32);
+
+            // Draw a simple circle by drawing filled rectangles (basic approach)
+            let radius = 30;
+            for dy in -radius..=radius {
+                for dx in -radius..=radius {
+                    if dx * dx + dy * dy <= radius * radius {
+                        let point = Point::new(center.x + dx, center.y + dy);
+                        if let Err(e) = canvas.draw_point(point) {
+                            errors.write(TextureError::RenderFailed(format!("Touch UI render error: {}", e)).into());
+                            return;
+                        }
+                    }
+                }
+            }
+
+            // Draw direction indicator if we have a direction
+            if let Some(direction) = touch_data.current_direction {
+                canvas.set_draw_color(Color::RGBA(0, 255, 0, 150));
+
+                // Draw arrow indicating direction
+                let arrow_length = 40;
+                let (dx, dy) = match direction {
+                    crate::map::direction::Direction::Up => (0, -arrow_length),
+                    crate::map::direction::Direction::Down => (0, arrow_length),
+                    crate::map::direction::Direction::Left => (-arrow_length, 0),
+                    crate::map::direction::Direction::Right => (arrow_length, 0),
+                };
+
+                let end_point = Point::new(center.x + dx, center.y + dy);
+                if let Err(e) = canvas.draw_line(center, end_point) {
+                    errors.write(TextureError::RenderFailed(format!("Touch arrow render error: {}", e)).into());
+                }
+
+                // Draw arrowhead (simple approach)
+                let arrow_size = 8;
+                match direction {
+                    crate::map::direction::Direction::Up => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y + arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y + arrow_size));
+                    }
+                    crate::map::direction::Direction::Down => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y - arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y - arrow_size));
+                    }
+                    crate::map::direction::Direction::Left => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y - arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y + arrow_size));
+                    }
+                    crate::map::direction::Direction::Right => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y - arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y + arrow_size));
+                    }
+                }
+            }
+        });
+    }
+}

pacman/src/systems/input.rs

@@ -0,0 +1,341 @@
+use std::collections::{HashMap, HashSet};
+
+use bevy_ecs::{
+    event::EventWriter,
+    resource::Resource,
+    system::{NonSendMut, Res, ResMut},
+};
+use glam::Vec2;
+use sdl2::{
+    event::{Event, WindowEvent},
+    keyboard::Keycode,
+    EventPump,
+};
+use smallvec::{smallvec, SmallVec};
+
+use crate::systems::DeltaTime;
+use crate::{
+    events::{GameCommand, GameEvent},
+    map::direction::Direction,
+};
+
+// Touch input constants
+pub const TOUCH_DIRECTION_THRESHOLD: f32 = 10.0;
+pub const TOUCH_EASING_DISTANCE_THRESHOLD: f32 = 1.0;
+pub const MAX_TOUCH_MOVEMENT_SPEED: f32 = 100.0;
+pub const TOUCH_EASING_FACTOR: f32 = 1.5;
+
+#[derive(Resource, Default, Debug, Copy, Clone)]
+pub enum CursorPosition {
+    #[default]
+    None,
+    Some {
+        position: Vec2,
+        remaining_time: f32,
+    },
+}
+
+#[derive(Resource, Default, Debug, Clone)]
+pub struct TouchState {
+    pub active_touch: Option<TouchData>,
+}
+
+#[derive(Debug, Clone)]
+pub struct TouchData {
+    pub finger_id: i64,
+    pub start_pos: Vec2,
+    pub current_pos: Vec2,
+    pub current_direction: Option<Direction>,
+}
+
+impl TouchData {
+    pub fn new(finger_id: i64, start_pos: Vec2) -> Self {
+        Self {
+            finger_id,
+            start_pos,
+            current_pos: start_pos,
+            current_direction: None,
+        }
+    }
+}
+
+#[derive(Resource, Debug, Clone)]
+pub struct Bindings {
+    key_bindings: HashMap<Keycode, GameCommand>,
+    movement_keys: HashSet<Keycode>,
+    pressed_movement_keys: Vec<Keycode>,
+}
+
+impl Default for Bindings {
+    fn default() -> Self {
+        let mut key_bindings = HashMap::new();
+
+        // Player movement
+        key_bindings.insert(Keycode::Up, GameCommand::MovePlayer(Direction::Up));
+        key_bindings.insert(Keycode::W, GameCommand::MovePlayer(Direction::Up));
+        key_bindings.insert(Keycode::Down, GameCommand::MovePlayer(Direction::Down));
+        key_bindings.insert(Keycode::S, GameCommand::MovePlayer(Direction::Down));
+        key_bindings.insert(Keycode::Left, GameCommand::MovePlayer(Direction::Left));
+        key_bindings.insert(Keycode::A, GameCommand::MovePlayer(Direction::Left));
+        key_bindings.insert(Keycode::Right, GameCommand::MovePlayer(Direction::Right));
+        key_bindings.insert(Keycode::D, GameCommand::MovePlayer(Direction::Right));
+
+        // Game actions
+        key_bindings.insert(Keycode::P, GameCommand::TogglePause);
+        key_bindings.insert(Keycode::Space, GameCommand::ToggleDebug);
+        key_bindings.insert(Keycode::M, GameCommand::MuteAudio);
+        key_bindings.insert(Keycode::R, GameCommand::ResetLevel);
+        key_bindings.insert(Keycode::T, GameCommand::SingleTick);
+
+        #[cfg(not(target_os = "emscripten"))]
+        {
+            key_bindings.insert(Keycode::Escape, GameCommand::Exit);
+            key_bindings.insert(Keycode::Q, GameCommand::Exit);
+            // Desktop-only fullscreen toggle
+            key_bindings.insert(Keycode::F, GameCommand::ToggleFullscreen);
+        }
+
+        let movement_keys = HashSet::from([
+            Keycode::W,
+            Keycode::A,
+            Keycode::S,
+            Keycode::D,
+            Keycode::Up,
+            Keycode::Down,
+            Keycode::Left,
+            Keycode::Right,
+        ]);
+
+        Self {
+            key_bindings,
+            movement_keys,
+            pressed_movement_keys: Vec::new(),
+        }
+    }
+}
+
+/// A simplified input event used for deterministic testing and logic reuse
+/// without depending on SDL's event pump.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SimpleKeyEvent {
+    KeyDown(Keycode),
+    KeyUp(Keycode),
+}
+
+/// Processes a frame's worth of simplified key events and returns the resulting
+/// `GameEvent`s that would be emitted by the input system for that frame.
+///
+/// This mirrors the behavior of `input_system` for keyboard-related logic:
+/// - KeyDown emits the bound command immediately (movement or otherwise)
+/// - Tracks pressed movement keys in order to continue movement on subsequent frames
+/// - KeyUp removes movement keys; if another movement key remains, it resumes
+pub fn process_simple_key_events(bindings: &mut Bindings, frame_events: &[SimpleKeyEvent]) -> Vec<GameEvent> {
+    let mut emitted_events = Vec::new();
+    let mut movement_key_pressed = false;
+
+    for event in frame_events {
+        match *event {
+            SimpleKeyEvent::KeyDown(key) => {
+                if let Some(command) = bindings.key_bindings.get(&key).copied() {
+                    emitted_events.push(GameEvent::Command(command));
+                }
+
+                if bindings.movement_keys.contains(&key) {
+                    movement_key_pressed = true;
+                    if !bindings.pressed_movement_keys.contains(&key) {
+                        bindings.pressed_movement_keys.push(key);
+                    }
+                }
+            }
+            SimpleKeyEvent::KeyUp(key) => {
+                if bindings.movement_keys.contains(&key) {
+                    bindings.pressed_movement_keys.retain(|&k| k != key);
+                }
+            }
+        }
+    }
+
+    if !movement_key_pressed {
+        if let Some(&last_movement_key) = bindings.pressed_movement_keys.last() {
+            if let Some(command) = bindings.key_bindings.get(&last_movement_key).copied() {
+                emitted_events.push(GameEvent::Command(command));
+            }
+        }
+    }
+
+    emitted_events
+}
+
+/// Calculates the primary direction from a 2D vector delta
+pub fn calculate_direction_from_delta(delta: Vec2) -> Direction {
+    if delta.x.abs() > delta.y.abs() {
+        if delta.x > 0.0 {
+            Direction::Right
+        } else {
+            Direction::Left
+        }
+    } else if delta.y > 0.0 {
+        Direction::Down
+    } else {
+        Direction::Up
+    }
+}
+
+/// Updates the touch reference position with easing
+///
+/// This slowly moves the start_pos towards the current_pos, with the speed
+/// decreasing as the distance gets smaller. The maximum movement speed is capped.
+/// Returns the delta vector and its length for reuse by the caller.
+pub fn update_touch_reference_position(touch_data: &mut TouchData, delta_time: f32) -> (Vec2, f32) {
+    // Calculate the vector from start to current position
+    let delta = touch_data.current_pos - touch_data.start_pos;
+    let distance = delta.length();
+
+    // If there's no significant distance, nothing to do
+    if distance < TOUCH_EASING_DISTANCE_THRESHOLD {
+        return (delta, distance);
+    }
+
+    // Calculate speed based on distance (slower as it gets closer)
+    // The easing function creates a curve where movement slows down as it approaches the target
+    let speed = (distance / TOUCH_EASING_FACTOR).min(MAX_TOUCH_MOVEMENT_SPEED);
+
+    // Calculate movement distance for this frame
+    let movement_amount = speed * delta_time;
+
+    // If the movement would overshoot, just set to target
+    if movement_amount >= distance {
+        touch_data.start_pos = touch_data.current_pos;
+    } else {
+        // Use direct vector scaling instead of normalization
+        let scale_factor = movement_amount / distance;
+        touch_data.start_pos += delta * scale_factor;
+    }
+
+    (delta, distance)
+}
+
+pub fn input_system(
+    delta_time: Res<DeltaTime>,
+    mut bindings: ResMut<Bindings>,
+    mut writer: EventWriter<GameEvent>,
+    mut pump: NonSendMut<EventPump>,
+    mut cursor: ResMut<CursorPosition>,
+    mut touch_state: ResMut<TouchState>,
+) {
+    let mut cursor_seen = false;
+    // Collect all events for this frame.
+    let frame_events: SmallVec<[Event; 3]> = pump.poll_iter().collect();
+
+    // Handle non-keyboard events inline and build a simplified keyboard event stream.
+    let mut simple_key_events: SmallVec<[SimpleKeyEvent; 3]> = smallvec![];
+    for event in &frame_events {
+        match *event {
+            Event::Quit { .. } => {
+                writer.write(GameEvent::Command(GameCommand::Exit));
+            }
+            Event::MouseMotion { x, y, .. } => {
+                *cursor = CursorPosition::Some {
+                    position: Vec2::new(x as f32, y as f32),
+                    remaining_time: 0.20,
+                };
+                cursor_seen = true;
+
+                // Handle mouse motion as touch motion for desktop testing
+                if let Some(ref mut touch_data) = touch_state.active_touch {
+                    touch_data.current_pos = Vec2::new(x as f32, y as f32);
+                }
+            }
+            // Handle mouse events as touch for desktop testing
+            Event::MouseButtonDown { x, y, .. } => {
+                let pos = Vec2::new(x as f32, y as f32);
+                touch_state.active_touch = Some(TouchData::new(0, pos)); // Use ID 0 for mouse
+            }
+            Event::MouseButtonUp { .. } => {
+                touch_state.active_touch = None;
+            }
+            // Handle actual touch events for mobile
+            Event::FingerDown { finger_id, x, y, .. } => {
+                // Convert normalized coordinates (0.0-1.0) to screen coordinates
+                let screen_x = x * crate::constants::CANVAS_SIZE.x as f32;
+                let screen_y = y * crate::constants::CANVAS_SIZE.y as f32;
+                let pos = Vec2::new(screen_x, screen_y);
+                touch_state.active_touch = Some(TouchData::new(finger_id, pos));
+            }
+            Event::FingerMotion { finger_id, x, y, .. } => {
+                if let Some(ref mut touch_data) = touch_state.active_touch {
+                    if touch_data.finger_id == finger_id {
+                        let screen_x = x * crate::constants::CANVAS_SIZE.x as f32;
+                        let screen_y = y * crate::constants::CANVAS_SIZE.y as f32;
+                        touch_data.current_pos = Vec2::new(screen_x, screen_y);
+                    }
+                }
+            }
+            Event::FingerUp { finger_id, .. } => {
+                if let Some(ref touch_data) = touch_state.active_touch {
+                    if touch_data.finger_id == finger_id {
+                        touch_state.active_touch = None;
+                    }
+                }
+            }
+            Event::KeyDown { keycode, repeat, .. } => {
+                if let Some(key) = keycode {
+                    if repeat {
+                        continue;
+                    }
+                    simple_key_events.push(SimpleKeyEvent::KeyDown(key));
+                }
+            }
+            Event::KeyUp { keycode, repeat, .. } => {
+                if let Some(key) = keycode {
+                    if repeat {
+                        continue;
+                    }
+                    simple_key_events.push(SimpleKeyEvent::KeyUp(key));
+                }
+            }
+            Event::Window { win_event, .. } => {
+                if let WindowEvent::Resized(w, h) = win_event {
+                    tracing::info!(width = w, height = h, event = ?win_event, "Window Resized");
+                }
+            }
+            // Despite disabling this event, it's still received, so we ignore it explicitly.
+            Event::RenderTargetsReset { .. } => {}
+            _ => {
+                tracing::warn!(event = ?event, "Unhandled Event");
+            }
+        }
+    }
+
+    // Delegate keyboard handling to shared logic used by tests and production.
+    let emitted = process_simple_key_events(&mut bindings, &simple_key_events);
+    for event in emitted {
+        writer.write(event);
+    }
+
+    // Update touch reference position with easing
+    if let Some(ref mut touch_data) = touch_state.active_touch {
+        // Apply easing to the reference position and get the delta for direction calculation
+        let (delta, distance) = update_touch_reference_position(touch_data, delta_time.seconds);
+
+        // Check for direction based on updated reference position
+        if distance >= TOUCH_DIRECTION_THRESHOLD {
+            let direction = calculate_direction_from_delta(delta);
+
+            // Only send command if direction has changed
+            if touch_data.current_direction != Some(direction) {
+                touch_data.current_direction = Some(direction);
+                writer.write(GameEvent::Command(GameCommand::MovePlayer(direction)));
+            }
+        } else if touch_data.current_direction.is_some() {
+            touch_data.current_direction = None;
+        }
+    }
+
+    if let (false, CursorPosition::Some { remaining_time, .. }) = (cursor_seen, &mut *cursor) {
+        *remaining_time -= delta_time.seconds;
+        if *remaining_time <= 0.0 {
+            *cursor = CursorPosition::None;
+        }
+    }
+}

pacman/src/systems/item.rs

@@ -0,0 +1,141 @@
+use bevy_ecs::{
+    event::Event,
+    observer::Trigger,
+    system::{Commands, NonSendMut, Res},
+};
+use rand::Rng;
+use strum_macros::IntoStaticStr;
+use tracing::debug;
+
+use crate::{
+    constants,
+    map::builder::Map,
+    platform::rng,
+    systems::{common::bundles::ItemBundle, Collider, Position, Renderable, TimeToLive},
+    texture::{
+        sprite::SpriteAtlas,
+        sprites::{EffectSprite, GameSprite},
+    },
+};
+
+use crate::{systems::common::components::EntityType, systems::ItemCollider};
+
+use std::cmp::Ordering;
+
+/// Tracks the number of pellets consumed by the player for fruit spawning mechanics.
+#[derive(bevy_ecs::resource::Resource, Debug, Default)]
+pub struct PelletCount(pub u32);
+
+/// Represents the different fruit sprites that can appear as bonus items.
+#[derive(IntoStaticStr, Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[strum(serialize_all = "snake_case")]
+pub enum FruitType {
+    Cherry,
+    Strawberry,
+    Orange,
+    Apple,
+    Melon,
+    Galaxian,
+    Bell,
+    Key,
+}
+
+impl PartialOrd for FruitType {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for FruitType {
+    fn cmp(&self, other: &Self) -> Ordering {
+        (self.score_value()).cmp(&other.score_value())
+    }
+}
+
+impl FruitType {
+    /// Returns the score value for this fruit type.
+    pub fn score_value(self) -> u32 {
+        match self {
+            FruitType::Cherry => 100,
+            FruitType::Strawberry => 300,
+            FruitType::Orange => 500,
+            FruitType::Apple => 700,
+            FruitType::Melon => 1000,
+            FruitType::Galaxian => 2000,
+            FruitType::Bell => 3000,
+            FruitType::Key => 5000,
+        }
+    }
+
+    pub fn from_index(index: u8) -> Self {
+        match index {
+            0 => FruitType::Cherry,
+            1 => FruitType::Strawberry,
+            2 => FruitType::Orange,
+            3 => FruitType::Apple,
+            4 => FruitType::Melon,
+            5 => FruitType::Galaxian,
+            6 => FruitType::Bell,
+            7 => FruitType::Key,
+            _ => panic!("Invalid fruit index: {}", index),
+        }
+    }
+}
+
+/// Trigger to spawn a fruit
+#[derive(Event, Clone, Copy, Debug)]
+pub enum SpawnTrigger {
+    Fruit,
+    Bonus { position: Position, value: u32, ttl: u32 },
+}
+
+pub fn spawn_fruit_observer(
+    trigger: Trigger<SpawnTrigger>,
+    mut commands: Commands,
+    atlas: NonSendMut<SpriteAtlas>,
+    map: Res<Map>,
+) {
+    let entity = match *trigger {
+        SpawnTrigger::Fruit => {
+            // Use cherry sprite as the default fruit (first fruit in original Pac-Man)
+            let sprite = &atlas
+                .get_tile(&GameSprite::Fruit(FruitType::from_index(0)).to_path())
+                .unwrap();
+            let bundle = ItemBundle {
+                position: map.start_positions.fruit_spawn,
+                sprite: Renderable {
+                    sprite: *sprite,
+                    layer: 1,
+                },
+                entity_type: EntityType::Fruit(FruitType::Cherry),
+                collider: Collider {
+                    size: constants::collider::FRUIT_SIZE,
+                },
+                item_collider: ItemCollider,
+            };
+
+            let lifetime_ticks = (rng().random_range(9f32..10f32) * 60f32).round() as u32;
+
+            commands.spawn((bundle, TimeToLive::new(lifetime_ticks)))
+        }
+        SpawnTrigger::Bonus { position, value, ttl } => {
+            let sprite = &atlas
+                .get_tile(&GameSprite::Effect(EffectSprite::Bonus(value)).to_path())
+                .unwrap();
+
+            let bundle = (
+                position,
+                TimeToLive::new(ttl),
+                Renderable {
+                    sprite: *sprite,
+                    layer: 1,
+                },
+                EntityType::Effect,
+            );
+
+            commands.spawn(bundle)
+        }
+    };
+
+    debug!(entity = ?entity.id(), "Entity spawned via trigger");
+}

pacman/src/systems/lifetime.rs

@@ -0,0 +1,33 @@
+use bevy_ecs::{
+    component::Component,
+    entity::Entity,
+    system::{Commands, Query, Res},
+};
+
+use crate::systems::DeltaTime;
+
+/// Component for entities that should be automatically deleted after a certain number of ticks
+#[derive(Component, Debug, Clone, Copy)]
+pub struct TimeToLive {
+    pub remaining_ticks: u32,
+}
+
+impl TimeToLive {
+    pub fn new(ticks: u32) -> Self {
+        Self { remaining_ticks: ticks }
+    }
+}
+
+/// System that manages entities with TimeToLive components, decrementing their remaining ticks
+/// and despawning them when they expire
+pub fn time_to_live_system(mut commands: Commands, dt: Res<DeltaTime>, mut query: Query<(Entity, &mut TimeToLive)>) {
+    for (entity, mut ttl) in query.iter_mut() {
+        if ttl.remaining_ticks <= dt.ticks {
+            // Entity has expired, despawn it
+            commands.entity(entity).despawn();
+        } else {
+            // Decrement remaining time
+            ttl.remaining_ticks = ttl.remaining_ticks.saturating_sub(dt.ticks);
+        }
+    }
+}

pacman/src/systems/mod.rs

@@ -0,0 +1,41 @@
+//! This module contains all the systems in the game.
+
+// These modules are excluded from coverage.
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod audio;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod debug;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod profiling;
+#[cfg_attr(coverage_nightly, coverage(off))]
+pub mod render;
+
+mod animation;
+mod collision;
+pub mod common;
+mod ghost;
+mod hud;
+pub mod input;
+pub mod item;
+pub mod lifetime;
+pub mod movement;
+pub mod player;
+pub mod state;
+
+// Re-export all the modules. Do not fine-tune the exports.
+
+pub use self::animation::*;
+pub use self::audio::*;
+pub use self::collision::*;
+pub use self::common::*;
+pub use self::debug::*;
+pub use self::ghost::*;
+pub use self::hud::*;
+pub use self::input::*;
+pub use self::item::*;
+pub use self::lifetime::*;
+pub use self::movement::*;
+pub use self::player::*;
+pub use self::profiling::*;
+pub use self::render::*;
+pub use self::state::*;

pacman/src/systems/movement.rs

@@ -0,0 +1,149 @@
+use crate::error::{EntityError, GameResult};
+use crate::map::direction::Direction;
+use crate::map::graph::Graph;
+use bevy_ecs::component::Component;
+use glam::Vec2;
+
+/// Zero-based index identifying a specific node in the navigation graph.
+///
+/// Nodes represent discrete movement targets in the maze. The index directly corresponds to the node's position in the
+/// graph's internal storage arrays.
+pub type NodeId = u16;
+
+/// 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 },
+}
+
+/// Entity position state that handles both stationary entities and moving entities.
+///
+/// Supports precise positioning during movement between discrete navigation nodes.
+/// When moving, entities smoothly interpolate along edges while tracking exact distance remaining to the target node.
+#[derive(Component, Debug, Copy, Clone, PartialEq)]
+pub enum Position {
+    /// Entity is stationary at a specific graph node.
+    Stopped { node: NodeId },
+    /// Entity is traveling between two nodes.
+    Moving {
+        from: NodeId,
+        to: NodeId,
+        /// Distance remaining to reach the target node.
+        remaining_distance: f32,
+    },
+}
+
+impl Position {
+    /// Calculates the current pixel position in the game world.
+    ///
+    /// Converts the graph position to screen coordinates, accounting for
+    /// the board offset and centering the sprite.
+    ///
+    /// # Errors
+    ///
+    /// Returns an `EntityError` if the node or edge is not found.
+    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(*node).ok_or(EntityError::NodeNotFound(*node as usize))?;
+                node.position
+            }
+            Position::Moving {
+                from,
+                to,
+                remaining_distance,
+            } => {
+                // Entity is traveling between nodes
+                let from_node = graph.get_node(*from).ok_or(EntityError::NodeNotFound(*from as usize))?;
+                let to_node = graph.get_node(*to).ok_or(EntityError::NodeNotFound(*to as usize))?;
+                let edge = graph.find_edge(*from, *to).ok_or(EntityError::EdgeNotFound {
+                    from: *from as usize,
+                    to: *to as usize,
+                })?;
+
+                // For zero-distance edges (tunnels), progress >= 1.0 means we're at the target
+                if edge.distance == 0.0 {
+                    to_node.position
+                } else {
+                    // Interpolate position based on progress
+                    let progress = 1.0 - (*remaining_distance / edge.distance);
+                    from_node.position.lerp(to_node.position, progress)
+                }
+            }
+        };
+
+        Ok(Vec2::new(
+            pos.x + crate::constants::BOARD_PIXEL_OFFSET.x as f32,
+            pos.y + crate::constants::BOARD_PIXEL_OFFSET.y as f32,
+        ))
+    }
+
+    /// Advances movement progress by the specified distance with overflow handling.
+    ///
+    /// For moving entities, decreases the remaining distance to the target node.
+    /// If the distance would overshoot the target, the entity transitions to
+    /// `Stopped` state and returns the excess distance for chaining movement
+    /// to the next edge in the same frame.
+    ///
+    /// # Arguments
+    ///
+    /// * `distance` - Distance to travel this frame (typically speed × delta_time)
+    ///
+    /// # Returns
+    ///
+    /// `Some(overflow)` if the target was reached with distance remaining,
+    /// `None` if still moving or already stopped.
+    pub fn tick(&mut self, distance: f32) -> Option<f32> {
+        if distance <= 0.0 || self.is_at_node() {
+            return None;
+        }
+
+        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!(),
+        }
+    }
+
+    /// Returns `true` if the position is exactly at a node (not traveling).
+    pub fn is_at_node(&self) -> bool {
+        matches!(self, Position::Stopped { .. })
+    }
+
+    /// Returns the `NodeId` of the current node (source of travel if moving).
+    pub fn current_node(&self) -> NodeId {
+        match self {
+            Position::Stopped { node } => *node,
+            Position::Moving { from, .. } => *from,
+        }
+    }
+}

pacman/src/systems/player.rs

@@ -0,0 +1,185 @@
+use bevy_ecs::{
+    component::Component,
+    event::EventReader,
+    query::{With, Without},
+    system::{Query, Res, ResMut, Single},
+};
+use tracing::trace;
+
+use crate::{
+    events::{GameCommand, GameEvent},
+    map::{builder::Map, graph::Edge},
+    systems::{
+        components::{DeltaTime, EntityType, Frozen, GlobalState, MovementModifiers},
+        debug::DebugState,
+        movement::{BufferedDirection, Position, Velocity},
+        AudioState,
+    },
+};
+
+/// A tag component for entities that are controlled by the player.
+#[derive(Default, Component)]
+pub struct PlayerControlled;
+
+pub fn can_traverse(entity_type: EntityType, edge: Edge) -> bool {
+    let entity_flags = entity_type.traversal_flags();
+    edge.traversal_flags.contains(entity_flags)
+}
+
+/// Processes player input commands and updates game state accordingly.
+///
+/// Handles keyboard-driven commands like movement direction changes, debug mode
+/// toggling, audio muting, and game exit requests. Movement commands are buffered
+/// to allow direction changes before reaching intersections, improving gameplay
+/// responsiveness. Non-movement commands immediately modify global game state.
+#[allow(clippy::type_complexity)]
+pub fn player_control_system(
+    mut events: EventReader<GameEvent>,
+    mut state: ResMut<GlobalState>,
+    mut debug_state: ResMut<DebugState>,
+    mut audio_state: ResMut<AudioState>,
+    mut player: Option<Single<&mut BufferedDirection, (With<PlayerControlled>, Without<Frozen>)>>,
+) {
+    // Handle events
+    for event in events.read() {
+        let GameEvent::Command(command) = event;
+
+        match command {
+            GameCommand::MovePlayer(direction) => {
+                // Only handle movement if there's an unfrozen player
+                if let Some(player_single) = player.as_mut() {
+                    trace!(direction = ?*direction, "Player direction buffered for movement");
+                    ***player_single = BufferedDirection::Some {
+                        direction: *direction,
+                        remaining_time: 0.25,
+                    };
+                }
+            }
+            GameCommand::Exit => {
+                state.exit = true;
+            }
+            GameCommand::ToggleDebug => {
+                debug_state.enabled = !debug_state.enabled;
+            }
+            GameCommand::MuteAudio => {
+                audio_state.muted = !audio_state.muted;
+                tracing::info!("Audio {}", if audio_state.muted { "muted" } else { "unmuted" });
+            }
+            _ => {}
+        }
+    }
+}
+
+/// Executes frame-by-frame movement for Pac-Man.
+///
+/// Handles movement logic including buffered direction changes, edge traversal validation, and continuous movement between nodes.
+/// When stopped, prioritizes buffered directions for responsive controls, falling back to current direction.
+/// Supports movement chaining within a single frame when traveling at high speeds.
+#[allow(clippy::type_complexity)]
+pub fn player_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut entities: Query<
+        (&MovementModifiers, &mut Position, &mut Velocity, &mut BufferedDirection),
+        (With<PlayerControlled>, Without<Frozen>),
+    >,
+    mut last_stopped_node: bevy_ecs::system::Local<Option<crate::systems::movement::NodeId>>,
+) {
+    for (modifiers, 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 {
+                trace!("Buffered direction expired");
+                *buffered_direction = BufferedDirection::None;
+            } else {
+                *buffered_direction = BufferedDirection::Some {
+                    direction,
+                    remaining_time: remaining_time - delta_time.seconds,
+                };
+            }
+        }
+
+        let mut distance = velocity.speed * modifiers.speed_multiplier * 60.0 * delta_time.seconds;
+
+        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) {
+                                trace!(from = position.current_node(), to = edge.target, direction = ?direction, "Player started moving using buffered direction");
+                                *last_stopped_node = None; // Reset stopped state when starting to move
+                                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) {
+                            trace!(from = position.current_node(), to = edge.target, direction = ?velocity.direction, "Player continued in current direction");
+                            *last_stopped_node = None; // Reset stopped state when starting to move
+                            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.
+                        let current_node = position.current_node();
+                        if *last_stopped_node != Some(current_node) {
+                            trace!(node = current_node, direction = ?velocity.direction, "Player stopped - no valid edge in current direction");
+                            *last_stopped_node = Some(current_node);
+                        }
+                        *buffered_direction = BufferedDirection::None;
+                        break;
+                    }
+                }
+                Position::Moving { .. } => {
+                    if let Some(overflow) = position.tick(distance) {
+                        distance = overflow;
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Applies tunnel slowdown based on the current node tile
+pub fn player_tunnel_slowdown_system(map: Res<Map>, player: Single<(&Position, &mut MovementModifiers), With<PlayerControlled>>) {
+    let (position, mut modifiers) = player.into_inner();
+    let node = position.current_node();
+    let in_tunnel = map
+        .tile_at_node(node)
+        .map(|t| t == crate::constants::MapTile::Tunnel)
+        .unwrap_or(false);
+
+    if modifiers.tunnel_slowdown_active != in_tunnel {
+        trace!(
+            node,
+            in_tunnel,
+            speed_multiplier = if in_tunnel { 0.6 } else { 1.0 },
+            "Player tunnel slowdown state changed"
+        );
+    }
+
+    modifiers.tunnel_slowdown_active = in_tunnel;
+    modifiers.speed_multiplier = if in_tunnel { 0.6 } else { 1.0 };
+}

pacman/src/systems/profiling.rs

@@ -0,0 +1,441 @@
+use bevy_ecs::system::IntoSystem;
+use bevy_ecs::{resource::Resource, system::System};
+use circular_buffer::CircularBuffer;
+use num_width::NumberWidth;
+use parking_lot::Mutex;
+use smallvec::SmallVec;
+use std::fmt::Display;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+use strum::{EnumCount, IntoEnumIterator};
+use strum_macros::{EnumCount, EnumIter, IntoStaticStr};
+use thousands::Separable;
+
+/// 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;
+
+/// A timing buffer that tracks durations and automatically inserts zero durations for skipped ticks.
+#[derive(Debug, Default)]
+pub struct TimingBuffer {
+    /// Circular buffer storing timing durations
+    buffer: CircularBuffer<TIMING_WINDOW_SIZE, Duration>,
+    /// The last tick when this buffer was updated
+    last_tick: u64,
+}
+
+impl TimingBuffer {
+    /// Adds a timing duration for the current tick.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `current_tick` is less than `last_tick`, indicating time went backwards.
+    pub fn add_timing(&mut self, duration: Duration, current_tick: u64) {
+        if current_tick < self.last_tick {
+            panic!(
+                "Time went backwards: current_tick ({}) < last_tick ({})",
+                current_tick, self.last_tick
+            );
+        }
+
+        // Insert zero durations for any skipped ticks (but not the current tick)
+        if current_tick > self.last_tick {
+            let skipped_ticks = current_tick - self.last_tick - 1;
+            for _ in 0..skipped_ticks {
+                self.buffer.push_back(Duration::ZERO);
+            }
+        }
+
+        // Add the actual timing
+        self.buffer.push_back(duration);
+        self.last_tick = current_tick;
+    }
+
+    /// Gets the most recent timing from the buffer.
+    pub fn get_most_recent_timing(&self) -> Duration {
+        self.buffer.back().copied().unwrap_or(Duration::ZERO)
+    }
+
+    /// Gets statistics for this timing buffer.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `current_tick` is less than `last_tick`, indicating time went backwards.
+    pub fn get_stats(&mut self, current_tick: u64) -> (Duration, Duration) {
+        // Insert zero durations for any skipped ticks since last update (but not the current tick)
+        if current_tick > self.last_tick {
+            let skipped_ticks = current_tick - self.last_tick - 1;
+            for _ in 0..skipped_ticks {
+                self.buffer.push_back(Duration::ZERO);
+            }
+            self.last_tick = current_tick;
+        }
+
+        // Calculate statistics using Welford's algorithm
+        let mut sample_count = 0u16;
+        let mut running_mean = 0.0;
+        let mut sum_squared_diff = 0.0;
+
+        let skip = self.last_tick.saturating_sub(current_tick);
+        for duration in self.buffer.iter().skip(skip as usize) {
+            let duration_secs = duration.as_secs_f32();
+            sample_count += 1;
+
+            let diff_from_mean = duration_secs - running_mean;
+            running_mean += diff_from_mean / sample_count as f32;
+
+            let diff_from_new_mean = duration_secs - running_mean;
+            sum_squared_diff += diff_from_mean * diff_from_new_mean;
+        }
+
+        if sample_count > 0 {
+            let variance = if sample_count > 1 {
+                sum_squared_diff / (sample_count - 1) as f32
+            } else {
+                0.0
+            };
+
+            (
+                Duration::from_secs_f32(running_mean),
+                Duration::from_secs_f32(variance.sqrt()),
+            )
+        } else {
+            (Duration::ZERO, Duration::ZERO)
+        }
+    }
+}
+
+/// A resource that tracks the current game tick using an atomic counter.
+/// This ensures thread-safe access to the tick counter across systems.
+#[derive(Resource, Debug)]
+pub struct Timing {
+    /// Atomic counter for the current game tick
+    current_tick: AtomicU64,
+}
+
+impl Timing {
+    /// Creates a new Timing resource starting at tick 0
+    pub fn new() -> Self {
+        Self {
+            current_tick: AtomicU64::new(0),
+        }
+    }
+
+    /// Gets the current tick value
+    pub fn get_current_tick(&self) -> u64 {
+        self.current_tick.load(Ordering::Relaxed)
+    }
+
+    /// Increments the tick counter and returns the new value
+    pub fn increment_tick(&self) -> u64 {
+        self.current_tick.fetch_add(1, Ordering::Relaxed) + 1
+    }
+}
+
+impl Default for Timing {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[derive(EnumCount, EnumIter, IntoStaticStr, Debug, PartialEq, Eq, Hash, Copy, Clone)]
+pub enum SystemId {
+    Total,
+    Input,
+    PlayerControls,
+    Ghost,
+    Movement,
+    Audio,
+    Blinking,
+    DirectionalRender,
+    LinearRender,
+    DirtyRender,
+    HudRender,
+    Render,
+    DebugRender,
+    Present,
+    Collision,
+    Item,
+    PlayerMovement,
+    GhostCollision,
+    Stage,
+    GhostStateAnimation,
+    EatenGhost,
+    TimeToLive,
+    PauseManager,
+}
+
+impl Display for SystemId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        // Use strum_macros::IntoStaticStr to get the static string
+        write!(f, "{}", Into::<&'static str>::into(self).to_ascii_lowercase())
+    }
+}
+
+#[derive(Resource, Debug)]
+pub struct SystemTimings {
+    /// Statically sized map of system names to timing buffers.
+    pub timings: micromap::Map<SystemId, Mutex<TimingBuffer>, MAX_SYSTEMS>,
+}
+
+impl Default for SystemTimings {
+    fn default() -> Self {
+        let mut timings = micromap::Map::new();
+
+        // Pre-populate with all SystemId variants to avoid runtime allocations
+        for id in SystemId::iter() {
+            timings.insert(id, Mutex::new(TimingBuffer::default()));
+        }
+
+        Self { timings }
+    }
+}
+
+impl SystemTimings {
+    pub fn add_timing(&self, id: SystemId, duration: Duration, current_tick: u64) {
+        // Since all SystemId variants are pre-populated, we can use a simple read lock
+        let buffer = self
+            .timings
+            .get(&id)
+            .expect("SystemId not found in pre-populated map - this is a bug");
+        buffer.lock().add_timing(duration, current_tick);
+    }
+
+    /// Add timing for the Total system (total frame time including scheduler.run)
+    pub fn add_total_timing(&self, duration: Duration, current_tick: u64) {
+        self.add_timing(SystemId::Total, duration, current_tick);
+    }
+
+    pub fn get_stats(&self, current_tick: u64) -> micromap::Map<SystemId, (Duration, Duration), MAX_SYSTEMS> {
+        let mut stats = micromap::Map::new();
+
+        // Iterate over all SystemId variants to ensure every system has an entry
+        for id in SystemId::iter() {
+            let buffer = self
+                .timings
+                .get(&id)
+                .expect("SystemId not found in pre-populated map - this is a bug");
+
+            let (average, standard_deviation) = buffer.lock().get_stats(current_tick);
+            stats.insert(id, (average, standard_deviation));
+        }
+
+        stats
+    }
+
+    pub fn format_timing_display(&self, current_tick: u64) -> SmallVec<[String; SystemId::COUNT]> {
+        let stats = self.get_stats(current_tick);
+
+        // Get the Total system metrics instead of averaging all systems
+        let (total_avg, total_std) = stats
+            .get(&SystemId::Total)
+            .copied()
+            .unwrap_or((Duration::ZERO, Duration::ZERO));
+
+        let effective_fps = match 1.0 / total_avg.as_secs_f64() {
+            f if f > 100.0 => format!("{:>5} FPS", (f as u32).separate_with_commas()),
+            f if f < 10.0 => format!("{:.1} FPS", f),
+            f => format!("{:5.0} FPS", f),
+        };
+
+        // Collect timing data for formatting
+        let mut timing_data = vec![(effective_fps, total_avg, total_std)];
+
+        // Sort the stats by average duration, excluding the Total system
+        let mut sorted_stats: Vec<_> = stats.iter().filter(|(id, _)| **id != SystemId::Total).collect();
+        sorted_stats.sort_by(|a, b| b.1 .0.cmp(&a.1 .0));
+
+        // Add the top 7 most expensive systems (excluding Total)
+        for (name, (avg, std_dev)) in sorted_stats.iter().take(9) {
+            timing_data.push((name.to_string(), *avg, *std_dev));
+        }
+
+        // Use the formatting module to format the data
+        format_timing_display(timing_data)
+    }
+
+    /// Returns a list of systems with their timings, likely responsible for slow frame timings.
+    ///
+    /// First, checks if any systems took longer than 2ms on the most recent tick.
+    /// If none exceed 2ms, accumulates systems until the top 30% of total timing
+    /// is reached, stopping at 5 systems maximum.
+    ///
+    /// Returns tuples of (SystemId, Duration) in a SmallVec capped at 5 items.
+    pub fn get_slowest_systems(&self) -> SmallVec<[(SystemId, Duration); 5]> {
+        let mut system_timings: Vec<(SystemId, Duration)> = Vec::new();
+        let mut total_duration = Duration::ZERO;
+
+        // Collect most recent timing for each system (excluding Total)
+        for id in SystemId::iter() {
+            if id == SystemId::Total {
+                continue;
+            }
+
+            if let Some(buffer) = self.timings.get(&id) {
+                let recent_timing = buffer.lock().get_most_recent_timing();
+                system_timings.push((id, recent_timing));
+                total_duration += recent_timing;
+            }
+        }
+
+        // Sort by duration (highest first)
+        system_timings.sort_by(|a, b| b.1.cmp(&a.1));
+
+        // Check for systems over 2ms threshold
+        let over_threshold: SmallVec<[(SystemId, Duration); 5]> = system_timings
+            .iter()
+            .filter(|(_, duration)| duration.as_millis() >= 2)
+            .copied()
+            .collect();
+
+        if !over_threshold.is_empty() {
+            return over_threshold;
+        }
+
+        // Accumulate top systems until 30% of total is reached (max 5 systems)
+        let threshold = total_duration.as_nanos() as f64 * 0.3;
+        let mut accumulated = 0u128;
+        let mut result = SmallVec::new();
+
+        for (id, duration) in system_timings.iter().take(5) {
+            result.push((*id, *duration));
+            accumulated += duration.as_nanos();
+
+            if accumulated as f64 >= threshold {
+                break;
+            }
+        }
+
+        result
+    }
+}
+
+pub fn profile<S, M>(id: SystemId, system: S) -> impl FnMut(&mut bevy_ecs::world::World)
+where
+    S: IntoSystem<(), (), M> + 'static,
+{
+    let mut system: S::System = IntoSystem::into_system(system);
+    let mut is_initialized = false;
+    move |world: &mut bevy_ecs::world::World| {
+        if !is_initialized {
+            system.initialize(world);
+            is_initialized = true;
+        }
+
+        let start = std::time::Instant::now();
+        system.run((), world);
+        let duration = start.elapsed();
+
+        if let (Some(timings), Some(timing)) = (world.get_resource::<SystemTimings>(), world.get_resource::<Timing>()) {
+            let current_tick = timing.get_current_tick();
+            timings.add_timing(id, duration, current_tick);
+        }
+    }
+}
+
+// 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_avg_int_width, max_avg_decimal_width, max_std_int_width, max_std_decimal_width) =
+        entries
+            .iter()
+            .fold((0, 3, 0, 3), |(avg_int_w, avg_dec_w, std_int_w, std_dec_w), e| {
+                (
+                    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),
+                )
+            });
+
+    let max_name_width = SystemId::iter()
+        .map(|id| id.to_string().len())
+        .max()
+        .expect("SystemId::iter() returned an empty iterator");
+
+    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]>>()
+}

pacman/src/systems/render.rs

@@ -0,0 +1,305 @@
+use crate::error::{GameError, TextureError};
+use crate::map::builder::Map;
+use crate::systems::{
+    debug_render_system, BatchedLinesResource, Collider, CursorPosition, DebugState, DebugTextureResource, Position, SystemId,
+    SystemTimings, TtfAtlasResource,
+};
+use crate::texture::sprite::{AtlasTile, SpriteAtlas};
+use bevy_ecs::component::Component;
+use bevy_ecs::entity::Entity;
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::query::{Changed, Or, With};
+use bevy_ecs::removal_detection::RemovedComponents;
+use bevy_ecs::resource::Resource;
+use bevy_ecs::system::{NonSendMut, Query, Res, ResMut};
+use glam::Vec2;
+use sdl2::rect::{Point, Rect};
+use sdl2::render::{BlendMode, Canvas, Texture};
+use sdl2::video::Window;
+use std::time::Instant;
+
+/// A component for entities that have a sprite, with a layer for ordering.
+///
+/// This is intended to be modified by other entities allowing animation.
+#[derive(Component)]
+pub struct Renderable {
+    pub sprite: AtlasTile,
+    pub layer: u8,
+}
+
+#[derive(Resource, Default)]
+pub struct RenderDirty(pub bool);
+
+#[derive(Component)]
+pub struct Hidden;
+
+/// A component that controls entity visibility in the render system.
+///
+/// Entities without this component are considered visible by default.
+/// This allows for efficient rendering where only entities that need
+/// visibility control have this component.
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Visibility(pub bool);
+
+impl Default for Visibility {
+    fn default() -> Self {
+        Self(true) // Default to visible
+    }
+}
+
+impl Visibility {
+    /// Creates a visible Visibility component
+    pub fn visible() -> Self {
+        Self(true)
+    }
+
+    /// Creates a hidden Visibility component
+    pub fn hidden() -> Self {
+        Self(false)
+    }
+
+    /// Returns true if the entity is visible
+    pub fn is_visible(&self) -> bool {
+        self.0
+    }
+
+    /// Returns true if the entity is hidden
+    #[allow(dead_code)] // Used in tests
+    pub fn is_hidden(&self) -> bool {
+        !self.0
+    }
+
+    /// Makes the entity visible
+    pub fn show(&mut self) {
+        self.0 = true;
+    }
+
+    /// Toggles the visibility state
+    pub fn toggle(&mut self) {
+        self.0 = !self.0;
+    }
+}
+
+/// Enum to identify which texture is being rendered to in the combined render system
+#[derive(Debug, Clone, Copy)]
+enum RenderTarget {
+    Backbuffer,
+    Debug,
+}
+
+#[allow(clippy::type_complexity)]
+pub fn dirty_render_system(
+    mut dirty: ResMut<RenderDirty>,
+    changed: Query<(), Or<(Changed<Renderable>, Changed<Position>, Changed<Visibility>)>>,
+    removed_renderables: RemovedComponents<Renderable>,
+) {
+    if changed.iter().count() > 0 || !removed_renderables.is_empty() {
+        dirty.0 = true;
+    }
+}
+
+/// Component for Renderables to store an exact pixel position
+#[derive(Component)]
+pub struct PixelPosition {
+    pub pixel_position: Vec2,
+}
+
+/// A non-send resource for the map texture. This just wraps the texture with a type so it can be differentiated when exposed as a resource.
+pub struct MapTextureResource(pub Texture);
+
+/// 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);
+
+#[allow(clippy::too_many_arguments)]
+#[allow(clippy::type_complexity)]
+pub fn render_system(
+    canvas: &mut Canvas<Window>,
+    map_texture: &NonSendMut<MapTextureResource>,
+    atlas: &mut SpriteAtlas,
+    map: &Res<Map>,
+    dirty: &Res<RenderDirty>,
+    renderables: &Query<
+        (
+            Entity,
+            &Renderable,
+            Option<&Position>,
+            Option<&PixelPosition>,
+            Option<&Visibility>,
+        ),
+        Or<(With<Position>, With<PixelPosition>)>,
+    >,
+    errors: &mut EventWriter<GameError>,
+) {
+    if !dirty.0 {
+        return;
+    }
+
+    // Clear the backbuffer
+    canvas.set_draw_color(sdl2::pixels::Color::BLACK);
+    canvas.clear();
+
+    // Copy the pre-rendered map texture to the backbuffer
+    if let Err(e) = canvas.copy(&map_texture.0, None, None) {
+        errors.write(TextureError::RenderFailed(e.to_string()).into());
+    }
+
+    // Collect and filter visible entities, then sort by layer
+    let mut visible_entities: Vec<_> = renderables
+        .iter()
+        .filter(|(_, _, _, _, visibility)| visibility.copied().unwrap_or_default().is_visible())
+        .collect();
+
+    visible_entities.sort_by_key(|(_, renderable, _, _, _)| renderable.layer);
+    visible_entities.reverse();
+
+    // Render all visible entities to the backbuffer
+    for (_entity, renderable, position, pixel_position, _visibility) in visible_entities {
+        let pos = if let Some(position) = position {
+            position.get_pixel_position(&map.graph)
+        } else {
+            Ok(pixel_position
+                .expect("Pixel position should be present via query filtering, but got None on both")
+                .pixel_position)
+        };
+
+        match pos {
+            Ok(pos) => {
+                let dest = Rect::from_center(
+                    Point::from((pos.x as i32, pos.y as i32)),
+                    renderable.sprite.size.x as u32,
+                    renderable.sprite.size.y as u32,
+                );
+
+                renderable
+                    .sprite
+                    .render(canvas, atlas, dest)
+                    .err()
+                    .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+            }
+            Err(e) => {
+                errors.write(e);
+            }
+        }
+    }
+}
+
+/// Combined render system that renders to both backbuffer and debug textures in a single
+/// with_multiple_texture_canvas call for reduced overhead
+#[allow(clippy::too_many_arguments)]
+#[allow(clippy::type_complexity)]
+pub fn combined_render_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    map_texture: NonSendMut<MapTextureResource>,
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut debug_texture: NonSendMut<DebugTextureResource>,
+    mut atlas: NonSendMut<SpriteAtlas>,
+    mut ttf_atlas: NonSendMut<TtfAtlasResource>,
+    batched_lines: Res<BatchedLinesResource>,
+    debug_state: Res<DebugState>,
+    timings: Res<SystemTimings>,
+    timing: Res<crate::systems::profiling::Timing>,
+    map: Res<Map>,
+    dirty: Res<RenderDirty>,
+    renderables: Query<
+        (
+            Entity,
+            &Renderable,
+            Option<&Position>,
+            Option<&PixelPosition>,
+            Option<&Visibility>,
+        ),
+        Or<(With<Position>, With<PixelPosition>)>,
+    >,
+    colliders: Query<(&Collider, &Position)>,
+    cursor: Res<CursorPosition>,
+    mut errors: EventWriter<GameError>,
+) {
+    if !dirty.0 {
+        return;
+    }
+
+    // Prepare textures and render targets
+    let textures = [
+        (&mut backbuffer.0, RenderTarget::Backbuffer),
+        (&mut debug_texture.0, RenderTarget::Debug),
+    ];
+
+    // Record timing for each system independently
+    let mut render_duration = None;
+    let mut debug_render_duration = None;
+
+    let result = canvas.with_multiple_texture_canvas(textures.iter(), |texture_canvas, render_target| match render_target {
+        RenderTarget::Backbuffer => {
+            let start_time = Instant::now();
+
+            render_system(
+                texture_canvas,
+                &map_texture,
+                &mut atlas,
+                &map,
+                &dirty,
+                &renderables,
+                &mut errors,
+            );
+
+            render_duration = Some(start_time.elapsed());
+        }
+        RenderTarget::Debug => {
+            if !debug_state.enabled {
+                return;
+            }
+
+            let start_time = Instant::now();
+
+            debug_render_system(
+                texture_canvas,
+                &mut ttf_atlas,
+                &batched_lines,
+                &debug_state,
+                &timings,
+                &timing,
+                &map,
+                &colliders,
+                &cursor,
+            );
+
+            debug_render_duration = Some(start_time.elapsed());
+        }
+    });
+
+    if let Err(e) = result {
+        errors.write(TextureError::RenderFailed(e.to_string()).into());
+    }
+
+    // Record timings for each system independently
+    let current_tick = timing.get_current_tick();
+
+    if let Some(duration) = render_duration {
+        timings.add_timing(SystemId::Render, duration, current_tick);
+    }
+    if let Some(duration) = debug_render_duration {
+        timings.add_timing(SystemId::DebugRender, duration, current_tick);
+    }
+}
+
+pub fn present_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    mut dirty: ResMut<RenderDirty>,
+    backbuffer: NonSendMut<BackbufferResource>,
+    debug_texture: NonSendMut<DebugTextureResource>,
+    debug_state: Res<DebugState>,
+) {
+    if dirty.0 {
+        // Copy the backbuffer to the main canvas
+        canvas.copy(&backbuffer.0, None, None).unwrap();
+
+        // Copy the debug texture to the canvas
+        if debug_state.enabled {
+            canvas.set_blend_mode(BlendMode::Blend);
+            canvas.copy(&debug_texture.0, None, None).unwrap();
+        }
+
+        canvas.present();
+        dirty.0 = false;
+    }
+}

pacman/src/systems/state.rs

@@ -0,0 +1,551 @@
+use std::mem::discriminant;
+use tracing::{debug, info};
+
+use crate::constants;
+use crate::events::StageTransition;
+use crate::map::direction::Direction;
+use crate::systems::{EntityType, ItemCollider, SpawnTrigger, Velocity};
+use crate::{
+    map::builder::Map,
+    systems::{
+        AudioEvent, Blinking, DirectionalAnimation, Dying, Frozen, Ghost, GhostCollider, GhostState, LinearAnimation, Looping,
+        NodeId, PlayerControlled, Position, Visibility,
+    },
+};
+use bevy_ecs::{
+    entity::Entity,
+    event::{EventReader, EventWriter},
+    query::{With, Without},
+    resource::Resource,
+    system::{Commands, Query, Res, ResMut, Single},
+};
+
+use crate::events::{GameCommand, GameEvent};
+#[cfg(not(target_os = "emscripten"))]
+use bevy_ecs::system::NonSendMut;
+#[cfg(not(target_os = "emscripten"))]
+use sdl2::render::Canvas;
+#[cfg(not(target_os = "emscripten"))]
+use sdl2::video::{FullscreenType, Window};
+
+#[derive(Resource, Clone)]
+pub struct PlayerAnimation(pub DirectionalAnimation);
+
+#[derive(Resource, Clone)]
+pub struct PlayerDeathAnimation(pub LinearAnimation);
+
+/// Tracks whether the beginning sound has been played for the current startup sequence
+#[derive(Resource, Debug, Default, Clone, Copy)]
+pub struct IntroPlayed(pub bool);
+
+/// A resource to track the overall stage of the game from a high-level perspective.
+#[derive(Resource, Debug, PartialEq, Eq, Clone, Copy)]
+pub enum GameStage {
+    Starting(StartupSequence),
+    /// The main gameplay loop is active.
+    Playing,
+    /// Short freeze after Pac-Man eats a ghost to display bonus score
+    GhostEatenPause {
+        remaining_ticks: u32,
+        ghost_entity: Entity,
+        ghost_type: Ghost,
+        node: NodeId,
+    },
+    /// The player has died and the death sequence is in progress. At the end, the player will return to the startup sequence or game over.
+    PlayerDying(DyingSequence),
+    /// The game has ended.
+    GameOver,
+}
+
+#[derive(Resource, Debug, PartialEq, Eq, Clone, Copy)]
+pub enum PauseState {
+    Inactive,
+    Active { remaining_ticks: Option<u32> },
+}
+
+impl Default for PauseState {
+    fn default() -> Self {
+        Self::Active { remaining_ticks: None }
+    }
+}
+
+impl PauseState {
+    pub fn active(&self) -> bool {
+        matches!(
+            self,
+            PauseState::Active { remaining_ticks: None }
+                | PauseState::Active {
+                    remaining_ticks: Some(1..=u32::MAX)
+                }
+        )
+    }
+
+    /// Ticks the pause state
+    /// # Returns
+    /// `true` if the state changed significantly (e.g. from active to inactive or vice versa)
+    pub fn tick(&mut self) -> bool {
+        match self {
+            // Permanent states
+            PauseState::Active { remaining_ticks: None } | PauseState::Inactive => false,
+            // Last tick of the active state
+            PauseState::Active {
+                remaining_ticks: Some(1),
+            } => {
+                *self = PauseState::Inactive;
+                true
+            }
+            // Active state with remaining ticks
+            PauseState::Active {
+                remaining_ticks: Some(ticks),
+            } => {
+                *self = PauseState::Active {
+                    remaining_ticks: Some(*ticks - 1),
+                };
+                false
+            }
+        }
+    }
+}
+
+pub fn handle_pause_command(
+    mut events: EventReader<GameEvent>,
+    mut pause_state: ResMut<PauseState>,
+    mut audio_events: EventWriter<AudioEvent>,
+) {
+    for event in events.read() {
+        match event {
+            GameEvent::Command(GameCommand::TogglePause) => {
+                *pause_state = match *pause_state {
+                    PauseState::Active { .. } => {
+                        info!("Game resumed");
+                        audio_events.write(AudioEvent::Resume);
+                        PauseState::Inactive
+                    }
+                    PauseState::Inactive => {
+                        info!("Game paused");
+                        audio_events.write(AudioEvent::Pause);
+                        PauseState::Active { remaining_ticks: None }
+                    }
+                }
+            }
+            GameEvent::Command(GameCommand::SingleTick) => {
+                // Single tick should not function while the game is playing
+                if matches!(*pause_state, PauseState::Active { remaining_ticks: None }) {
+                    return;
+                }
+
+                *pause_state = PauseState::Active {
+                    remaining_ticks: Some(1),
+                };
+                audio_events.write(AudioEvent::Resume);
+            }
+            _ => {}
+        }
+    }
+}
+
+pub fn manage_pause_state_system(mut pause_state: ResMut<PauseState>, mut audio_events: EventWriter<AudioEvent>) {
+    let changed = pause_state.tick();
+
+    // If the pause state changed, send the appropriate audio event
+    if changed {
+        // Since the pause state can never go from inactive to active, the only way to get here is if the game is now paused...
+        audio_events.write(AudioEvent::Pause);
+    }
+}
+
+#[cfg(not(target_os = "emscripten"))]
+pub fn handle_fullscreen_command(mut events: EventReader<GameEvent>, mut canvas: NonSendMut<&mut Canvas<Window>>) {
+    for event in events.read() {
+        if let GameEvent::Command(GameCommand::ToggleFullscreen) = event {
+            let window = canvas.window_mut();
+            let current = window.fullscreen_state();
+            let target = match current {
+                FullscreenType::Off => FullscreenType::Desktop,
+                _ => FullscreenType::Off,
+            };
+
+            if let Err(e) = window.set_fullscreen(target) {
+                tracing::warn!(error = ?e, "Failed to toggle fullscreen");
+            } else {
+                let on = matches!(target, FullscreenType::Desktop | FullscreenType::True);
+                info!(fullscreen = on, "Toggled fullscreen");
+            }
+        }
+    }
+}
+
+pub trait TooSimilar {
+    fn too_similar(&self, other: &Self) -> bool;
+}
+
+impl TooSimilar for GameStage {
+    fn too_similar(&self, other: &Self) -> bool {
+        discriminant(self) == discriminant(other) && {
+            // These states are very simple, so they're 'too similar' automatically
+            if matches!(self, GameStage::Playing | GameStage::GameOver) {
+                return true;
+            }
+
+            // Since the discriminant is the same but the values are different, it's the interior value that is somehow different
+            match (self, other) {
+                // These states are similar if their interior values are similar as well
+                (GameStage::Starting(startup), GameStage::Starting(other)) => startup.too_similar(other),
+                (GameStage::PlayerDying(dying), GameStage::PlayerDying(other)) => dying.too_similar(other),
+                (
+                    GameStage::GhostEatenPause {
+                        ghost_entity,
+                        ghost_type,
+                        node,
+                        ..
+                    },
+                    GameStage::GhostEatenPause {
+                        ghost_entity: other_ghost_entity,
+                        ghost_type: other_ghost_type,
+                        node: other_node,
+                        ..
+                    },
+                ) => ghost_entity == other_ghost_entity && ghost_type == other_ghost_type && node == other_node,
+                // Already handled, but kept to properly exhaust the match
+                (GameStage::Playing, _) | (GameStage::GameOver, _) => unreachable!(),
+                _ => unreachable!(),
+            }
+        }
+    }
+}
+
+/// A resource that manages the multi-stage startup sequence of the game.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum StartupSequence {
+    /// Stage 1: Text-only stage
+    /// - Player & ghosts are hidden
+    /// - READY! and PLAYER ONE text are shown
+    /// - Energizers do not blink
+    TextOnly {
+        /// Remaining ticks in this stage
+        remaining_ticks: u32,
+    },
+    /// Stage 2: Characters visible stage
+    /// - PLAYER ONE text is hidden, READY! text remains
+    /// - Ghosts and Pac-Man are now shown
+    CharactersVisible {
+        /// Remaining ticks in this stage
+        remaining_ticks: u32,
+    },
+}
+
+impl Default for GameStage {
+    fn default() -> Self {
+        Self::Playing
+    }
+}
+
+impl TooSimilar for StartupSequence {
+    fn too_similar(&self, other: &Self) -> bool {
+        discriminant(self) == discriminant(other)
+    }
+}
+
+/// The state machine for the multi-stage death sequence.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum DyingSequence {
+    /// Initial stage: entities are frozen, waiting for a delay.
+    Frozen { remaining_ticks: u32 },
+    /// Second stage: Pac-Man's death animation is playing.
+    Animating { remaining_ticks: u32 },
+    /// Third stage: Pac-Man is now gone, waiting a moment before the level restarts.
+    Hidden { remaining_ticks: u32 },
+}
+
+impl TooSimilar for DyingSequence {
+    fn too_similar(&self, other: &Self) -> bool {
+        discriminant(self) == discriminant(other)
+    }
+}
+
+/// A resource to store the number of player lives.
+#[derive(Resource, Debug)]
+pub struct PlayerLives(pub u8);
+
+impl Default for PlayerLives {
+    fn default() -> Self {
+        Self(3)
+    }
+}
+
+/// Handles startup sequence transitions and component management
+#[allow(clippy::too_many_arguments)]
+#[allow(clippy::type_complexity)]
+pub fn stage_system(
+    mut game_state: ResMut<GameStage>,
+    player_death_animation: Res<PlayerDeathAnimation>,
+    player_animation: Res<PlayerAnimation>,
+    mut player_lives: ResMut<PlayerLives>,
+    map: Res<Map>,
+    mut commands: Commands,
+    mut audio_events: EventWriter<AudioEvent>,
+    mut stage_event_reader: EventReader<StageTransition>,
+    mut blinking_query: Query<Entity, With<Blinking>>,
+    player: Single<(Entity, &mut Position), With<PlayerControlled>>,
+    mut item_query: Query<(Entity, &EntityType), With<ItemCollider>>,
+    mut ghost_query: Query<(Entity, &Ghost, &mut Position, &mut GhostState), (With<GhostCollider>, Without<PlayerControlled>)>,
+    mut intro_played: ResMut<IntroPlayed>,
+) {
+    let old_state = *game_state;
+    let mut new_state_opt: Option<GameStage> = None;
+
+    // Handle stage transition requests before normal ticking
+    for event in stage_event_reader.read() {
+        let StageTransition::GhostEatenPause {
+            ghost_entity,
+            ghost_type,
+        } = *event;
+        let pac_node = player.1.current_node();
+
+        debug!(ghost = ?ghost_type, node = pac_node, "Ghost eaten, entering pause state");
+        new_state_opt = Some(GameStage::GhostEatenPause {
+            remaining_ticks: 30,
+            ghost_entity,
+            ghost_type,
+            node: pac_node,
+        });
+    }
+
+    let new_state: GameStage = new_state_opt.unwrap_or_else(|| match *game_state {
+        GameStage::Playing => {
+            // This is the default state, do nothing
+            *game_state
+        }
+        GameStage::GhostEatenPause {
+            remaining_ticks,
+            ghost_entity,
+            ghost_type,
+            node,
+        } => {
+            if remaining_ticks > 0 {
+                GameStage::GhostEatenPause {
+                    remaining_ticks: remaining_ticks.saturating_sub(1),
+                    ghost_entity,
+                    ghost_type,
+                    node,
+                }
+            } else {
+                debug!("Ghost eaten pause ended, resuming gameplay");
+                GameStage::Playing
+            }
+        }
+        GameStage::Starting(sequence) => match sequence {
+            StartupSequence::TextOnly { remaining_ticks } => {
+                // Play the beginning sound once at the start of TextOnly stage
+                if !intro_played.0 {
+                    audio_events.write(AudioEvent::PlaySound(crate::audio::Sound::Beginning));
+                    intro_played.0 = true;
+                }
+                if remaining_ticks > 0 {
+                    GameStage::Starting(StartupSequence::TextOnly {
+                        remaining_ticks: remaining_ticks.saturating_sub(1),
+                    })
+                } else {
+                    GameStage::Starting(StartupSequence::CharactersVisible { remaining_ticks: 60 })
+                }
+            }
+            StartupSequence::CharactersVisible { remaining_ticks } => {
+                if remaining_ticks > 0 {
+                    GameStage::Starting(StartupSequence::CharactersVisible {
+                        remaining_ticks: remaining_ticks.saturating_sub(1),
+                    })
+                } else {
+                    info!("Startup sequence completed, beginning gameplay");
+                    GameStage::Playing
+                }
+            }
+        },
+        GameStage::PlayerDying(sequence) => match sequence {
+            DyingSequence::Frozen { remaining_ticks } => {
+                if remaining_ticks > 0 {
+                    GameStage::PlayerDying(DyingSequence::Frozen {
+                        remaining_ticks: remaining_ticks.saturating_sub(1),
+                    })
+                } else {
+                    let death_animation = &player_death_animation.0;
+                    let remaining_ticks = (death_animation.tiles.len() * death_animation.frame_duration as usize) as u32;
+                    debug!(animation_frames = remaining_ticks, "Starting player death animation");
+                    GameStage::PlayerDying(DyingSequence::Animating { remaining_ticks })
+                }
+            }
+            DyingSequence::Animating { remaining_ticks } => {
+                if remaining_ticks > 0 {
+                    GameStage::PlayerDying(DyingSequence::Animating {
+                        remaining_ticks: remaining_ticks.saturating_sub(1),
+                    })
+                } else {
+                    GameStage::PlayerDying(DyingSequence::Hidden { remaining_ticks: 60 })
+                }
+            }
+            DyingSequence::Hidden { remaining_ticks } => {
+                if remaining_ticks > 0 {
+                    GameStage::PlayerDying(DyingSequence::Hidden {
+                        remaining_ticks: remaining_ticks.saturating_sub(1),
+                    })
+                } else {
+                    player_lives.0 = player_lives.0.saturating_sub(1);
+
+                    if player_lives.0 > 0 {
+                        info!(remaining_lives = player_lives.0, "Player died, returning to startup sequence");
+                        GameStage::Starting(StartupSequence::CharactersVisible { remaining_ticks: 60 })
+                    } else {
+                        info!("All lives lost, game over");
+                        GameStage::GameOver
+                    }
+                }
+            }
+        },
+        GameStage::GameOver => *game_state,
+    });
+
+    if old_state == new_state {
+        return;
+    }
+
+    if !old_state.too_similar(&new_state) {
+        debug!(old_state = ?old_state, new_state = ?new_state, "Game stage transition");
+    }
+
+    match (old_state, new_state) {
+        (GameStage::Playing, GameStage::GhostEatenPause { ghost_entity, node, .. }) => {
+            // Freeze the player & non-eaten ghosts
+            commands.entity(player.0).insert(Frozen);
+            commands.entity(ghost_entity).insert(Frozen);
+            for (entity, _, _, state) in ghost_query.iter_mut() {
+                // Only freeze ghosts that are not currently eaten
+                if *state != GhostState::Eyes {
+                    debug!(ghost = ?entity, "Freezing ghost");
+                    commands.entity(entity).insert(Frozen);
+                }
+            }
+
+            // Hide the player & eaten ghost
+            commands.entity(player.0).insert(Visibility::hidden());
+            commands.entity(ghost_entity).insert(Visibility::hidden());
+
+            // Spawn bonus points entity at Pac-Man's position
+            commands.trigger(SpawnTrigger::Bonus {
+                position: Position::Stopped { node },
+                // TODO: Doubling score value for each consecutive ghost eaten
+                value: 200,
+                ttl: 30,
+            });
+        }
+        (GameStage::GhostEatenPause { ghost_entity, .. }, GameStage::Playing) => {
+            // Unfreeze and reveal the player & all ghosts
+            commands.entity(player.0).remove::<Frozen>().insert(Visibility::visible());
+            for (entity, _, _, _) in ghost_query.iter_mut() {
+                commands.entity(entity).remove::<Frozen>().insert(Visibility::visible());
+            }
+
+            // Reveal the eaten ghost and switch it to Eyes state
+            commands.entity(ghost_entity).insert(GhostState::Eyes);
+        }
+        (_, GameStage::PlayerDying(DyingSequence::Frozen { .. })) => {
+            // Freeze the player & ghosts
+            commands.entity(player.0).insert(Frozen);
+            for (entity, _, _, _) in ghost_query.iter_mut() {
+                commands.entity(entity).insert(Frozen);
+            }
+        }
+        (GameStage::PlayerDying(DyingSequence::Frozen { .. }), GameStage::PlayerDying(DyingSequence::Animating { .. })) => {
+            // Hide the ghosts
+            for (entity, _, _, _) in ghost_query.iter_mut() {
+                commands.entity(entity).insert(Visibility::hidden());
+            }
+
+            // Start Pac-Man's death animation
+            commands
+                .entity(player.0)
+                .remove::<DirectionalAnimation>()
+                .insert((Dying, player_death_animation.0.clone()));
+
+            // Play the death sound
+            audio_events.write(AudioEvent::PlaySound(crate::audio::Sound::PacmanDeath));
+        }
+        (_, GameStage::PlayerDying(DyingSequence::Hidden { .. })) => {
+            // Pac-Man's death animation is complete, so he should be hidden just like the ghosts.
+            // Then, we reset them all back to their original positions and states.
+
+            // Freeze the blinking power pellets, force them to be visible (if they were hidden by blinking)
+            for entity in blinking_query.iter_mut() {
+                commands.entity(entity).insert(Frozen).insert(Visibility::visible());
+            }
+
+            // Delete any fruit entities
+            for (entity, _) in item_query
+                .iter_mut()
+                .filter(|(_, entity_type)| matches!(entity_type, EntityType::Fruit(_)))
+            {
+                commands.entity(entity).despawn();
+            }
+
+            // Reset the player animation
+            commands
+                .entity(player.0)
+                .remove::<(Dying, LinearAnimation, Looping)>()
+                .insert((
+                    Velocity {
+                        speed: constants::mechanics::PLAYER_SPEED,
+                        direction: Direction::Left,
+                    },
+                    Position::Stopped {
+                        node: map.start_positions.pacman,
+                    },
+                    player_animation.0.clone(),
+                    Visibility::hidden(),
+                    Frozen,
+                ));
+
+            // Reset ghost positions and state
+            for (ghost_entity, ghost, _, _) in ghost_query.iter_mut() {
+                commands.entity(ghost_entity).insert((
+                    GhostState::Normal,
+                    Position::Stopped {
+                        node: match ghost {
+                            Ghost::Blinky => map.start_positions.blinky,
+                            Ghost::Pinky => map.start_positions.pinky,
+                            Ghost::Inky => map.start_positions.inky,
+                            Ghost::Clyde => map.start_positions.clyde,
+                        },
+                    },
+                    Frozen,
+                    Visibility::hidden(),
+                ));
+            }
+        }
+        (_, GameStage::Starting(StartupSequence::CharactersVisible { .. })) => {
+            // Unhide the player & ghosts
+            commands.entity(player.0).insert(Visibility::visible());
+            for (entity, _, _, _) in ghost_query.iter_mut() {
+                commands.entity(entity).insert(Visibility::visible());
+            }
+        }
+        (GameStage::Starting(StartupSequence::CharactersVisible { .. }), GameStage::Playing) => {
+            // Unfreeze the player & ghosts & blinking
+            commands.entity(player.0).remove::<Frozen>();
+            for (entity, _, _, _) in ghost_query.iter_mut() {
+                commands.entity(entity).remove::<Frozen>();
+            }
+            for entity in blinking_query.iter_mut() {
+                commands.entity(entity).remove::<Frozen>();
+            }
+            // Reset intro flag for the next round
+            intro_played.0 = false;
+        }
+        (_, GameStage::GameOver) => {
+            // Freeze blinking
+            for entity in blinking_query.iter_mut() {
+                commands.entity(entity).insert(Frozen);
+            }
+        }
+        _ => {}
+    }
+
+    *game_state = new_state;
+}

pacman/src/texture/animated.rs

@@ -0,0 +1,65 @@
+use glam::U16Vec2;
+
+use crate::{map::direction::Direction, texture::sprite::AtlasTile};
+
+/// A sequence of tiles for animation, backed by a vector.
+#[derive(Debug, Clone)]
+pub struct TileSequence {
+    tiles: Vec<AtlasTile>,
+}
+
+impl TileSequence {
+    /// Creates a new tile sequence from a slice of tiles.
+    pub fn new(tiles: &[AtlasTile]) -> Self {
+        Self { tiles: tiles.to_vec() }
+    }
+
+    /// Returns the tile at the given frame index, wrapping if necessary
+    pub fn get_tile(&self, frame: usize) -> AtlasTile {
+        if self.tiles.is_empty() {
+            // Return a default or handle the error appropriately
+            // For now, let's return a default tile, assuming it's a sensible default
+            return AtlasTile {
+                pos: U16Vec2::ZERO,
+                size: U16Vec2::ZERO,
+                color: None,
+            };
+        }
+        self.tiles[frame % self.tiles.len()]
+    }
+
+    pub fn len(&self) -> usize {
+        self.tiles.len()
+    }
+
+    /// Checks if the sequence contains any tiles.
+    pub fn is_empty(&self) -> bool {
+        self.tiles.is_empty()
+    }
+}
+
+/// A collection of tile sequences for each cardinal direction.
+#[derive(Debug, Clone)]
+pub struct DirectionalTiles {
+    pub up: TileSequence,
+    pub down: TileSequence,
+    pub left: TileSequence,
+    pub right: TileSequence,
+}
+
+impl DirectionalTiles {
+    /// Creates a new DirectionalTiles with different sequences per direction
+    pub fn new(up: TileSequence, down: TileSequence, left: TileSequence, right: TileSequence) -> Self {
+        Self { up, down, left, right }
+    }
+
+    /// Gets the tile sequence for the given direction
+    pub fn get(&self, direction: Direction) -> &TileSequence {
+        match direction {
+            Direction::Up => &self.up,
+            Direction::Down => &self.down,
+            Direction::Left => &self.left,
+            Direction::Right => &self.right,
+        }
+    }
+}

pacman/src/texture/mod.rs

@@ -0,0 +1,5 @@
+pub mod animated;
+pub mod sprite;
+pub mod sprites;
+pub mod text;
+pub mod ttf;

pacman/src/texture/sprite.rs

@@ -0,0 +1,110 @@
+use anyhow::Result;
+use glam::U16Vec2;
+use sdl2::pixels::Color;
+use sdl2::rect::Rect;
+use sdl2::render::{Canvas, RenderTarget, Texture};
+use std::collections::HashMap;
+use tracing::debug;
+
+use crate::error::TextureError;
+
+/// Atlas frame mapping data loaded from JSON metadata files.
+#[derive(Clone, Debug)]
+pub struct AtlasMapper {
+    /// Mapping from sprite name to frame bounds within the atlas texture
+    pub frames: HashMap<String, MapperFrame>,
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct MapperFrame {
+    pub pos: U16Vec2,
+    pub size: U16Vec2,
+}
+
+/// A single tile within a sprite atlas, defined by its position and size.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub struct AtlasTile {
+    pub pos: U16Vec2,
+    pub size: U16Vec2,
+    pub color: Option<Color>,
+}
+
+impl AtlasTile {
+    pub fn render<C: RenderTarget>(
+        &self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut SpriteAtlas,
+        dest: Rect,
+    ) -> Result<(), TextureError> {
+        let color = self.color.unwrap_or(atlas.default_color.unwrap_or(Color::WHITE));
+        self.render_with_color(canvas, atlas, dest, color)?;
+        Ok(())
+    }
+
+    pub fn render_with_color<C: RenderTarget>(
+        &self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut SpriteAtlas,
+        dest: Rect,
+        color: Color,
+    ) -> Result<(), TextureError> {
+        let src = Rect::new(self.pos.x as i32, self.pos.y as i32, self.size.x as u32, self.size.y as u32);
+
+        if atlas.last_modulation != Some(color) {
+            atlas.texture.set_color_mod(color.r, color.g, color.b);
+            atlas.last_modulation = Some(color);
+        }
+
+        canvas.copy(&atlas.texture, src, dest).map_err(TextureError::RenderFailed)?;
+        Ok(())
+    }
+}
+
+/// High-performance sprite atlas providing fast texture region lookups and rendering.
+///
+/// Combines a single large texture with metadata mapping to enable efficient
+/// sprite rendering without texture switching. Caches color modulation state
+/// to minimize redundant SDL2 calls and supports both named sprite lookups
+/// and optional default color modulation configuration.
+pub struct SpriteAtlas {
+    /// The combined texture containing all sprite frames
+    texture: Texture,
+    /// Mapping from sprite names to their pixel coordinates within the texture
+    tiles: HashMap<String, MapperFrame>,
+    default_color: Option<Color>,
+    /// Cached color modulation state to avoid redundant SDL2 calls
+    last_modulation: Option<Color>,
+}
+
+impl SpriteAtlas {
+    pub fn new(texture: Texture, mapper: AtlasMapper) -> Self {
+        let tile_count = mapper.frames.len();
+        let tiles = mapper.frames.into_iter().collect();
+
+        debug!(tile_count, "Created sprite atlas");
+        Self {
+            texture,
+            tiles,
+            default_color: None,
+            last_modulation: None,
+        }
+    }
+
+    /// Retrieves a sprite tile by name from the atlas with fast HashMap lookup.
+    ///
+    /// Returns an `AtlasTile` containing the texture coordinates and dimensions
+    /// for the named sprite, or `None` if the sprite name is not found in the
+    /// atlas. The returned tile can be used for immediate rendering or stored
+    /// for repeated use in animations and entity sprites.
+    pub fn get_tile(&self, name: &str) -> Result<AtlasTile, TextureError> {
+        let frame = self.tiles.get(name).ok_or_else(|| {
+            debug!(tile_name = name, "Atlas tile not found");
+            TextureError::AtlasTileNotFound(name.to_string())
+        })?;
+        Ok(AtlasTile {
+            pos: frame.pos,
+            size: frame.size,
+            color: self.default_color,
+        })
+    }
+}

pacman/src/texture/sprites.rs

@@ -0,0 +1,133 @@
+//! A structured representation of all sprite assets in the game.
+//!
+//! This module provides a set of enums to represent every sprite, allowing for
+//! type-safe access to asset paths and avoiding the use of raw strings.
+//! The `GameSprite` enum is the main entry point, and its `to_path` method
+//! generates the correct path for a given sprite in the texture atlas.
+
+use crate::{
+    map::direction::Direction,
+    systems::{FruitType, Ghost},
+};
+
+/// Represents the different sprites for Pac-Man.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum PacmanSprite {
+    /// A moving Pac-Man sprite for a given direction and animation frame.
+    Moving(Direction, u8),
+    /// The full, closed-mouth Pac-Man sprite.
+    Full,
+    /// A single frame of the dying animation.
+    Dying(u8),
+}
+
+/// Represents the color of a frightened ghost.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum FrightenedColor {
+    Blue,
+    White,
+}
+
+/// Represents the different sprites for ghosts.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum GhostSprite {
+    /// The normal appearance of a ghost for a given type, direction, and animation frame.
+    Normal(Ghost, Direction, u8),
+    /// The frightened appearance of a ghost, with a specific color and animation frame.
+    Frightened(FrightenedColor, u8),
+    /// The "eyes only" appearance of a ghost after being eaten.
+    Eyes(Direction),
+}
+
+/// Represents the different sprites for the maze and collectibles.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum MazeSprite {
+    /// A specific tile of the maze.
+    Tile(u8),
+    /// A standard pellet.
+    Pellet,
+    /// An energizer/power pellet.
+    Energizer,
+}
+
+/// Represents the different effect sprites that can appear as bonus items.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum EffectSprite {
+    Bonus(u32),
+}
+
+/// A top-level enum that encompasses all game sprites.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum GameSprite {
+    Pacman(PacmanSprite),
+    Ghost(GhostSprite),
+    Maze(MazeSprite),
+    Fruit(FruitType),
+    Effect(EffectSprite),
+}
+
+impl GameSprite {
+    /// Generates the asset path for the sprite.
+    ///
+    /// This path corresponds to the filename in the texture atlas JSON file.
+    pub fn to_path(self) -> String {
+        match self {
+            GameSprite::Pacman(PacmanSprite::Moving(dir, frame)) => format!(
+                "pacman/{}_{}.png",
+                dir.as_ref(),
+                match frame {
+                    0 => "a",
+                    1 => "b",
+                    _ => panic!("Invalid animation frame"),
+                }
+            ),
+            GameSprite::Pacman(PacmanSprite::Full) => "pacman/full.png".to_string(),
+            GameSprite::Pacman(PacmanSprite::Dying(frame)) => format!("pacman/death/{}.png", frame),
+
+            // Ghost sprites
+            GameSprite::Ghost(GhostSprite::Normal(ghost_type, dir, frame)) => {
+                let frame_char = match frame {
+                    0 => 'a',
+                    1 => 'b',
+                    _ => panic!("Invalid animation frame"),
+                };
+                format!(
+                    "ghost/{}/{}_{}.png",
+                    ghost_type.as_str(),
+                    dir.as_ref().to_lowercase(),
+                    frame_char
+                )
+            }
+            GameSprite::Ghost(GhostSprite::Frightened(color, frame)) => {
+                let frame_char = match frame {
+                    0 => 'a',
+                    1 => 'b',
+                    _ => panic!("Invalid animation frame"),
+                };
+                let color_str = match color {
+                    FrightenedColor::Blue => "blue",
+                    FrightenedColor::White => "white",
+                };
+                format!("ghost/frightened/{}_{}.png", color_str, frame_char)
+            }
+            GameSprite::Ghost(GhostSprite::Eyes(dir)) => format!("ghost/eyes/{}.png", dir.as_ref().to_lowercase()),
+
+            // Maze sprites
+            GameSprite::Maze(MazeSprite::Tile(index)) => format!("maze/tiles/{}.png", index),
+            GameSprite::Maze(MazeSprite::Pellet) => "maze/pellet.png".to_string(),
+            GameSprite::Maze(MazeSprite::Energizer) => "maze/energizer.png".to_string(),
+
+            // Fruit sprites
+            GameSprite::Fruit(fruit) => format!("edible/{}.png", Into::<&'static str>::into(fruit)),
+
+            // Effect sprites
+            GameSprite::Effect(EffectSprite::Bonus(value)) => match value {
+                100 | 200 | 300 | 400 | 700 | 800 | 1000 | 2000 | 3000 | 5000 => format!("effects/{}.png", value),
+                _ => {
+                    tracing::warn!("Invalid bonus value: {}", value);
+                    "effects/100.png".to_string()
+                }
+            },
+        }
+    }
+}

pacman/src/texture/text.rs

@@ -0,0 +1,187 @@
+//! This module provides text rendering using the texture atlas.
+//!
+//! The TextTexture system renders text from the atlas using character mapping.
+//! It supports a subset of characters with special handling for characters that
+//! can't be used in filenames.
+//!
+//! # Example Usage
+//!
+//! ```rust
+//! use pacman::texture::text::TextTexture;
+//! use sdl2::pixels::Color;
+//!
+//! // Create a text texture with 1.0 scale (8x8 pixels per character)
+//! let mut text_renderer = TextTexture::new(1.0);
+//!
+//! // Set default color for all text
+//! text_renderer.set_color(Color::WHITE);
+//!
+//! // Render text with default color
+//! text_renderer.render(&mut canvas, &mut atlas, "Hello", position)?;
+//!
+//! // Render text with specific color
+//! text_renderer.render_with_color(&mut canvas, &mut atlas, "World", position, Color::YELLOW)?;
+//!
+//! // Set scale for larger text
+//! text_renderer.set_scale(2.0);
+//!
+//! // Calculate text width for positioning
+//! let width = text_renderer.text_width("GAME OVER");
+//! let height = text_renderer.text_height();
+//! ```
+//!
+//! # Supported Characters
+//!
+//! - Letters: A-Z, a-z
+//! - Numbers: 0-9
+//! - Common symbols: ! ? . , : ; - _ ( ) [ ] { } < > = + * / \ | & @ # $ % ^ ~ ` ' "
+//! - Space character
+//!
+//! # Character Mapping
+//!
+//! Most characters use their literal name (e.g., "A.png", "1.png").
+//! Special characters use alternative names:
+//! - `"` → "text/_double_quote.png"
+//! - `'` → "text/_single_quote.png"
+//! - `\` → "text/\\backslash.png"
+//! - ` ` (space) → "text/space.png"
+//!
+//! # Memory Optimization
+//!
+//! The system caches character tiles in a HashMap to avoid repeated
+//! atlas lookups. Only tiles for used characters are stored in memory.
+
+use anyhow::Result;
+use glam::UVec2;
+
+use sdl2::pixels::Color;
+use sdl2::render::{Canvas, RenderTarget};
+use std::collections::HashMap;
+
+use crate::texture::sprite::{AtlasTile, SpriteAtlas};
+
+/// Converts a character to its tile name in the atlas.
+fn char_to_tile_name(c: char) -> Option<String> {
+    let name = match c {
+        // Letters A-Z
+        'A'..='Z' | '0'..='9' => format!("text/{c}.png"),
+        // Special characters
+        '!' => "text/!.png".to_string(),
+        '-' => "text/-.png".to_string(),
+        '"' => "text/_double_quote.png".to_string(),
+        '/' => "text/_forward_slash.png".to_string(),
+        // Skip spaces for now - they don't have a tile
+        ' ' => return None,
+
+        // Unsupported character
+        _ => return None,
+    };
+
+    Some(name)
+}
+
+/// A text texture that renders characters from the atlas.
+#[derive(Debug)]
+pub struct TextTexture {
+    char_map: HashMap<char, AtlasTile>,
+    scale: f32,
+    default_color: Option<Color>,
+}
+
+impl Default for TextTexture {
+    fn default() -> Self {
+        Self {
+            scale: 1.0,
+            char_map: Default::default(),
+            default_color: None,
+        }
+    }
+}
+
+impl TextTexture {
+    /// Creates a new text texture with the given scale.
+    pub fn new(scale: f32) -> Self {
+        Self {
+            scale,
+            ..Default::default()
+        }
+    }
+
+    #[allow(dead_code)]
+    pub fn get_char_map(&self) -> &HashMap<char, AtlasTile> {
+        &self.char_map
+    }
+
+    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(&c));
+        }
+
+        if let Some(tile_name) = char_to_tile_name(c) {
+            let tile = atlas.get_tile(&tile_name)?;
+            self.char_map.insert(c, tile);
+            Ok(self.char_map.get(&c))
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Renders a string of text at the given position using the default color.
+    pub fn render<C: RenderTarget>(
+        &mut self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut SpriteAtlas,
+        text: &str,
+        position: UVec2,
+    ) -> Result<()> {
+        let color = self.default_color.unwrap_or(Color::WHITE);
+        self.render_with_color(canvas, atlas, text, position, color)
+    }
+
+    /// Renders a string of text at the given position with a specific color.
+    pub fn render_with_color<C: RenderTarget>(
+        &mut self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut SpriteAtlas,
+        text: &str,
+        position: UVec2,
+        color: Color,
+    ) -> Result<()> {
+        let mut x_offset = 0;
+        let char_width = (8.0 * self.scale) as u32;
+        let char_height = self.text_height();
+
+        for c in text.chars() {
+            // Get the tile from the char_map, or insert it if it doesn't exist
+            if let Some(tile) = self.get_tile(c, atlas)? {
+                // Render the tile with the specified color
+                let dest = sdl2::rect::Rect::new((position.x + x_offset) as i32, position.y as i32, char_width, char_height);
+                tile.render_with_color(canvas, atlas, dest, color)?;
+            }
+
+            // Always advance x_offset for all characters (including spaces)
+            x_offset += char_width;
+        }
+
+        Ok(())
+    }
+
+    /// Calculates the width of a string in pixels at the current scale.
+    pub fn text_width(&self, text: &str) -> u32 {
+        let char_width = (8.0 * self.scale) as u32;
+        let mut width = 0;
+
+        for c in text.chars() {
+            if char_to_tile_name(c).is_some() || c == ' ' {
+                width += char_width;
+            }
+        }
+
+        width
+    }
+
+    /// Calculates the height of text in pixels at the current scale.
+    pub fn text_height(&self) -> u32 {
+        (8.0 * self.scale) as u32
+    }
+}

pacman/src/texture/ttf.rs

@@ -0,0 +1,269 @@
+//! TTF font rendering using pre-rendered character atlas.
+//!
+//! This module provides efficient TTF font rendering by pre-rendering all needed
+//! characters into a texture atlas at startup, avoiding expensive SDL2 font
+//! surface-to-texture conversions every frame.
+
+use glam::{UVec2, Vec2};
+use sdl2::pixels::Color;
+use sdl2::rect::Rect;
+use sdl2::render::{Canvas, RenderTarget, Texture, TextureCreator};
+
+use sdl2::ttf::Font;
+use sdl2::video::WindowContext;
+use std::collections::HashMap;
+
+use crate::error::{GameError, TextureError};
+
+/// Character atlas tile representing a single rendered character
+#[derive(Clone, Copy, Debug)]
+pub struct TtfCharTile {
+    pub pos: UVec2,
+    pub size: UVec2,
+    pub advance: u32, // Character advance width for proportional fonts
+}
+
+/// TTF text atlas containing pre-rendered characters for efficient rendering
+pub struct TtfAtlas {
+    /// The texture containing all rendered characters
+    texture: Texture,
+    /// Mapping from character to its position and size in the atlas
+    char_tiles: HashMap<char, TtfCharTile>,
+    /// Cached color modulation state to avoid redundant SDL2 calls
+    last_modulation: Option<Color>,
+    /// Cached maximum character height
+    max_char_height: u32,
+}
+
+const TTF_CHARS: &str = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.,:-/()ms μµ%± ";
+
+impl TtfAtlas {
+    /// Creates a new TTF text atlas by pre-rendering all needed characters.
+    ///
+    /// This should be called once at startup. It renders all characters that might
+    /// be used in text rendering into a single texture atlas for efficient GPU rendering.
+    pub fn new(texture_creator: &TextureCreator<WindowContext>, font: &Font) -> Result<Self, GameError> {
+        // Calculate character dimensions and advance widths for proportional fonts
+        let mut char_tiles = HashMap::new();
+        let mut max_height = 0u32;
+        let mut total_width = 0u32;
+        let mut char_metrics = Vec::new();
+
+        // First pass: measure all characters
+        for c in TTF_CHARS.chars() {
+            if c == ' ' {
+                // Handle space character specially - measure a non-space character for height
+                let space_height = font.size_of("0").map_err(|e| GameError::Sdl(e.to_string()))?.1;
+                let space_advance = font.size_of(" ").map_err(|e| GameError::Sdl(e.to_string()))?.0;
+                char_tiles.insert(
+                    c,
+                    TtfCharTile {
+                        pos: UVec2::ZERO,                  // Will be set during population
+                        size: UVec2::new(0, space_height), // Space has no visual content
+                        advance: space_advance,
+                    },
+                );
+                max_height = max_height.max(space_height);
+                char_metrics.push((c, 0, space_height, space_advance));
+            } else {
+                let (advance, height) = font.size_of(&c.to_string()).map_err(|e| GameError::Sdl(e.to_string()))?;
+                char_tiles.insert(
+                    c,
+                    TtfCharTile {
+                        pos: UVec2::ZERO, // Will be set during population
+                        size: UVec2::new(advance, height),
+                        advance,
+                    },
+                );
+                max_height = max_height.max(height);
+                total_width += advance;
+                char_metrics.push((c, advance, height, advance));
+            }
+        }
+
+        // Calculate atlas dimensions (pack characters horizontally for better space utilization)
+        let atlas_size = UVec2::new(total_width, max_height);
+
+        // Create atlas texture as a render target
+        let mut atlas_texture = texture_creator
+            .create_texture_target(None, atlas_size.x, atlas_size.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        atlas_texture.set_blend_mode(sdl2::render::BlendMode::Blend);
+
+        // Second pass: calculate positions
+        let mut current_x = 0u32;
+        for (c, width, _height, _advance) in char_metrics {
+            if let Some(tile) = char_tiles.get_mut(&c) {
+                tile.pos = UVec2::new(current_x, 0);
+                current_x += width;
+            }
+        }
+
+        Ok(Self {
+            texture: atlas_texture,
+            char_tiles,
+            last_modulation: None,
+            max_char_height: max_height,
+        })
+    }
+
+    /// Renders all characters to the atlas texture using a canvas.
+    /// This must be called after creation to populate the atlas.
+    pub fn populate_atlas<C: RenderTarget>(
+        &mut self,
+        canvas: &mut Canvas<C>,
+        texture_creator: &TextureCreator<WindowContext>,
+        font: &Font,
+    ) -> Result<(), GameError> {
+        let mut render_error: Option<GameError> = None;
+
+        let result = canvas.with_texture_canvas(&mut self.texture, |atlas_canvas| {
+            // Clear with transparent background
+            atlas_canvas.set_draw_color(Color::RGBA(0, 0, 0, 0));
+            atlas_canvas.clear();
+
+            for c in TTF_CHARS.chars() {
+                if c == ' ' {
+                    // Skip rendering space character - it has no visual content
+                    continue;
+                }
+
+                // Render character to surface
+                let surface = match font.render(&c.to_string()).blended(Color::WHITE) {
+                    Ok(s) => s,
+                    Err(e) => {
+                        render_error = Some(GameError::Sdl(e.to_string()));
+                        return;
+                    }
+                };
+
+                // Create texture from surface
+                let char_texture = match texture_creator.create_texture_from_surface(&surface) {
+                    Ok(t) => t,
+                    Err(e) => {
+                        render_error = Some(GameError::Sdl(e.to_string()));
+                        return;
+                    }
+                };
+
+                // Get character tile info
+                let tile = match self.char_tiles.get(&c) {
+                    Some(t) => t,
+                    None => {
+                        render_error = Some(GameError::Sdl(format!("Character '{}' not found in atlas tiles", c)));
+                        return;
+                    }
+                };
+
+                // Copy character to atlas
+                let dest = Rect::new(tile.pos.x as i32, tile.pos.y as i32, tile.size.x, tile.size.y);
+                if let Err(e) = atlas_canvas.copy(&char_texture, None, dest) {
+                    render_error = Some(GameError::Sdl(e.to_string()));
+                    return;
+                }
+            }
+        });
+
+        // Check the result of with_texture_canvas and any render error
+        if let Err(e) = result {
+            return Err(GameError::Sdl(e.to_string()));
+        }
+
+        if let Some(error) = render_error {
+            return Err(error);
+        }
+
+        Ok(())
+    }
+
+    /// Gets a character tile from the atlas
+    pub fn get_char_tile(&self, c: char) -> Option<&TtfCharTile> {
+        self.char_tiles.get(&c)
+    }
+}
+
+/// TTF text renderer that uses the pre-rendered character atlas
+pub struct TtfRenderer {
+    scale: f32,
+}
+
+impl TtfRenderer {
+    pub fn new(scale: f32) -> Self {
+        Self { scale }
+    }
+
+    /// Renders a string of text at the given position with the specified color
+    pub fn render_text<C: RenderTarget>(
+        &self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut TtfAtlas,
+        text: &str,
+        position: Vec2,
+        color: Color,
+    ) -> Result<(), TextureError> {
+        let mut x_offset = 0.0;
+
+        // Apply color modulation once at the beginning if needed
+        if atlas.last_modulation != Some(color) {
+            atlas.texture.set_color_mod(color.r, color.g, color.b);
+            atlas.texture.set_alpha_mod(color.a);
+            atlas.last_modulation = Some(color);
+        }
+
+        for c in text.chars() {
+            // Get character tile info first to avoid borrowing conflicts
+            let char_tile = atlas.get_char_tile(c);
+
+            if let Some(char_tile) = char_tile {
+                if char_tile.size.x > 0 && char_tile.size.y > 0 {
+                    // Only render non-space characters
+                    let dest = Rect::new(
+                        (position.x + x_offset) as i32,
+                        position.y as i32,
+                        (char_tile.size.x as f32 * self.scale) as u32,
+                        (char_tile.size.y as f32 * self.scale) as u32,
+                    );
+
+                    // Render the character directly
+                    let src = Rect::new(
+                        char_tile.pos.x as i32,
+                        char_tile.pos.y as i32,
+                        char_tile.size.x,
+                        char_tile.size.y,
+                    );
+                    canvas.copy(&atlas.texture, src, dest).map_err(TextureError::RenderFailed)?;
+                }
+
+                // Advance by character advance width (proportional spacing)
+                x_offset += char_tile.advance as f32 * self.scale;
+            } else {
+                // Fallback for unsupported characters - use a reasonable default
+                x_offset += 8.0 * self.scale;
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Calculate the width of a text string in pixels
+    pub fn text_width(&self, atlas: &TtfAtlas, text: &str) -> u32 {
+        let mut total_width = 0u32;
+
+        for c in text.chars() {
+            if let Some(char_tile) = atlas.get_char_tile(c) {
+                total_width += (char_tile.advance as f32 * self.scale) as u32;
+            } else {
+                // Fallback for unsupported characters
+                total_width += (8.0 * self.scale) as u32;
+            }
+        }
+
+        total_width
+    }
+
+    /// Calculate the height of text in pixels
+    pub fn text_height(&self, atlas: &TtfAtlas) -> u32 {
+        // Find the maximum height among all characters
+        (atlas.max_char_height as f32 * self.scale) as u32
+    }
+}