feat: cache dynamicly rendered map texture

- Moved game logic from `game.rs` to `game/mod.rs` and `game/state.rs` for better organization.
- Updated `App` to utilize the new `Game` struct and its state management.
- Refactored error handling
- Removed unused audio subsystem references

.config/nextest.toml

@@ -1,2 +1,5 @@
 [profile.default]
 fail-fast = false
+
+[profile.coverage]
+status-level = "none"

.github/workflows/coverage.yaml

@@ -42,15 +42,39 @@ jobs:
 
       - uses: taiki-e/install-action@cargo-llvm-cov
       - uses: taiki-e/install-action@nextest
+      - uses: taiki-e/install-action@just
 
-      # Note: We manually link zlib. This should be synchronized with the flags set for Linux in .cargo/config.toml.
       - name: Generate coverage report
         run: |
-          cargo llvm-cov --no-fail-fast --lcov --output-path lcov.info nextest
+          just coverage
+
+      - name: Download Coveralls CLI
+        run: |
+          # use GitHub Releases URL instead of coveralls.io because they can't maintain their own files; it 404s
+          curl -L https://github.com/coverallsapp/coverage-reporter/releases/download/v0.6.15/coveralls-linux-x86_64.tar.gz | tar -xz -C /usr/local/bin
 
       - name: Upload coverage to Coveralls
-        uses: coverallsapp/github-action@v2
-        with:
-          files: ./lcov.info
-          format: lcov
-          allow-empty: false
+        env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+        run: |
+          if [ ! -f "lcov.info" ]; then
+            echo "Error: lcov.info file not found. Coverage generation may have failed."
+            exit 1
+          fi
+
+          for i in {1..10}; do
+            echo "Attempt $i: Uploading coverage to Coveralls..."
+            if coveralls -n report lcov.info; then
+              echo "Successfully uploaded coverage report."
+              exit 0
+            fi
+
+            if [ $i -lt 10 ]; then
+              delay=$((2**i))
+              echo "Attempt $i failed. Retrying in $delay seconds..."
+              sleep $delay
+            fi
+          done
+
+          echo "Failed to upload coverage report after 10 attempts."
+          exit 1

.gitignore

@@ -1,8 +1,17 @@
+# IDE, Other files
+.vscode
+.idea
+rust-sdl2-emscripten/
+
+# Build files
 target/
 dist/
 emsdk/
-.idea
-rust-sdl2-emscripten/
-assets/site/build.css
+
+# Site build f iles
 tailwindcss-*
+assets/site/build.css
+
+# Coverage reports
 lcov.info
+coverage.html

Cargo.lock

@@ -194,7 +194,8 @@ dependencies = [
  "libc",
  "once_cell",
  "pathfinding",
- "rand",
+ "phf",
+ "rand 0.9.2",
  "sdl2",
  "serde",
  "serde_json",
@@ -223,6 +224,48 @@ dependencies = [
  "thiserror",
 ]
 
+[[package]]
+name = "phf"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
+dependencies = [
+ "phf_macros",
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_generator"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
+dependencies = [
+ "phf_shared",
+ "rand 0.8.5",
+]
+
+[[package]]
+name = "phf_macros"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f84ac04429c13a7ff43785d75ad27569f2951ce0ffd30a3321230db2fc727216"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "phf_shared"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
+dependencies = [
+ "siphasher",
+]
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.13"
@@ -253,15 +296,30 @@ version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 
+[[package]]
+name = "rand"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+dependencies = [
+ "rand_core 0.6.4",
+]
+
 [[package]]
 name = "rand"
 version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
 dependencies = [
- "rand_core",
+ "rand_core 0.9.3",
 ]
 
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+
 [[package]]
 name = "rand_core"
 version = "0.9.3"
@@ -399,6 +457,12 @@ dependencies = [
  "lazy_static",
 ]
 
+[[package]]
+name = "siphasher"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56199f7ddabf13fe5074ce809e7d3f42b42ae711800501b5b16ea82ad029c39d"
+
 [[package]]
 name = "smallvec"
 version = "1.15.1"

Cargo.toml

@@ -23,6 +23,7 @@ serde_json = "1.0.142"
 smallvec = "1.15.1"
 strum = "0.27.2"
 strum_macros = "0.27.2"
+phf = { version = "0.11", features = ["macros"] }
 
 [profile.release]
 lto = true
@@ -57,3 +58,8 @@ aarch64-apple-darwin = { triplet = "arm64-osx" }
 
 [target.'cfg(target_os = "emscripten")'.dependencies]
 libc = "0.2.175"
+
+[build-dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+phf = { version = "0.11", features = ["macros"] }

Justfile

@@ -0,0 +1,33 @@
+set shell := ["bash", "-c"]
+set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
+
+# Regex to exclude files from coverage report, double escapes for Justfile + CLI
+# You can use src\\\\..., but the filename alone is acceptable too
+coverage_exclude_pattern := "src\\\\app.rs|audio.rs|src\\\\error.rs|platform\\\\emscripten.rs"
+
+# !!! --ignore-filename-regex should be used on both reports & coverage testing
+# !!! --remap-path-prefix prevents the absolute path from being used in the generated report
+
+# Generate HTML report (for humans, source line inspection)
+html: coverage
+    cargo llvm-cov report \
+    --remap-path-prefix \
+    --ignore-filename-regex "{{ coverage_exclude_pattern }}" \
+    --html \
+    --open
+
+# Display report (for humans)
+report-coverage: coverage
+    cargo llvm-cov report \
+    --remap-path-prefix \
+    --ignore-filename-regex "{{ coverage_exclude_pattern }}"
+
+# Run & generate report (for CI)
+coverage:
+    cargo llvm-cov \
+    --lcov \
+    --remap-path-prefix \
+    --ignore-filename-regex "{{ coverage_exclude_pattern }}" \
+    --output-path lcov.info \
+    --profile coverage \
+    --no-fail-fast nextest

bacon.toml

@@ -34,6 +34,30 @@ command = [
 need_stdout = true
 analyzer = "nextest"
 
+[jobs.coverage]
+command = [
+    "just", "report-coverage"
+]
+need_stdout = true
+ignored_lines = [
+    "info:",
+    "\\s+Compiling",
+    "test result: ok",
+    "^\\s*$",
+    "running \\d+ test",
+    "Nextest run ID",
+    "[─]+",
+    "test.+ok",
+    "PASS|START",
+    "Starting \\d+ test",
+    "\\s*#",
+    "\\s*Finished.+in \\d+",
+    "\\s*Summary\\s+\\[",
+    "\\s*Blocking",
+    "Finished report saved to"
+]
+on_change_strategy = "wait_then_restart"
+
 [jobs.doc]
 command = ["cargo", "doc", "--no-deps"]
 need_stdout = false
@@ -59,3 +83,4 @@ c = "job:clippy"
 alt-c = "job:check"
 ctrl-alt-c = "job:check-all"
 shift-c = "job:clippy-all"
+f = "job:coverage"

build.rs

@@ -0,0 +1,50 @@
+use std::collections::HashMap;
+use std::env;
+use std::fs::File;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize)]
+struct AtlasMapper {
+    frames: HashMap<String, MapperFrame>,
+}
+
+#[derive(Copy, Clone, Debug, Deserialize)]
+struct MapperFrame {
+    x: u16,
+    y: u16,
+    width: u16,
+    height: u16,
+}
+
+fn main() {
+    let path = Path::new(&env::var("OUT_DIR").unwrap()).join("atlas_data.rs");
+    let mut file = BufWriter::new(File::create(&path).unwrap());
+
+    let atlas_json = include_str!("./assets/game/atlas.json");
+    let atlas_mapper: AtlasMapper = serde_json::from_str(atlas_json).unwrap();
+
+    writeln!(&mut file, "use phf::phf_map;").unwrap();
+
+    writeln!(&mut file, "use crate::texture::sprite::MapperFrame;").unwrap();
+
+    writeln!(
+        &mut file,
+        "pub static ATLAS_FRAMES: phf::Map<&'static str, MapperFrame> = phf_map! {{"
+    )
+    .unwrap();
+
+    for (name, frame) in atlas_mapper.frames {
+        writeln!(
+            &mut file,
+            "    \"{}\" => MapperFrame {{ x: {}, y: {}, width: {}, height: {} }},",
+            name, frame.x, frame.y, frame.width, frame.height
+        )
+        .unwrap();
+    }
+
+    writeln!(&mut file, "}};").unwrap();
+    println!("cargo:rerun-if-changed=assets/game/atlas.json");
+}

src/app.rs

@@ -30,9 +30,9 @@ impl App {
         let sdl_context: &'static Sdl = Box::leak(Box::new(sdl2::init().map_err(|e| GameError::Sdl(e.to_string()))?));
         let video_subsystem: &'static VideoSubsystem =
             Box::leak(Box::new(sdl_context.video().map_err(|e| GameError::Sdl(e.to_string()))?));
-        let audio_subsystem: &'static AudioSubsystem =
+        let _audio_subsystem: &'static AudioSubsystem =
             Box::leak(Box::new(sdl_context.audio().map_err(|e| GameError::Sdl(e.to_string()))?));
-        let ttf_context: &'static Sdl2TtfContext =
+        let _ttf_context: &'static Sdl2TtfContext =
             Box::leak(Box::new(sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?));
         let event_pump: &'static mut EventPump =
             Box::leak(Box::new(sdl_context.event_pump().map_err(|e| GameError::Sdl(e.to_string()))?));
@@ -58,7 +58,7 @@ impl App {
 
         let texture_creator: &'static TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
 
-        let mut game = Game::new(texture_creator, ttf_context, audio_subsystem)?;
+        let mut game = Game::new(texture_creator)?;
         // game.audio.set_mute(cfg!(debug_assertions));
 
         let mut backbuffer = texture_creator
@@ -119,7 +119,7 @@ impl App {
                         keycode: Some(Keycode::Space),
                         ..
                     } => {
-                        self.game.debug_mode = !self.game.debug_mode;
+                        self.game.toggle_debug_mode();
                     }
                     Event::KeyDown { keycode: Some(key), .. } => {
                         self.game.keyboard_event(key);

src/asset.rs

@@ -3,28 +3,15 @@
 //! On desktop, assets are embedded using include_bytes!; on Emscripten, assets are loaded from the filesystem.
 
 use std::borrow::Cow;
-use std::io;
-use thiserror::Error;
+use strum_macros::EnumIter;
 
-#[derive(Error, Debug)]
-pub enum AssetError {
-    #[error("IO error: {0}")]
-    Io(#[from] io::Error),
-    #[error("Asset not found: {0}")]
-    NotFound(String),
-    #[error("Invalid asset format: {0}")]
-    InvalidFormat(String),
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, EnumIter)]
 pub enum Asset {
     Wav1,
     Wav2,
     Wav3,
     Wav4,
     Atlas,
-    AtlasJson,
-    // Add more as needed
 }
 
 impl Asset {
@@ -37,15 +24,16 @@ impl Asset {
             Wav3 => "sound/waka/3.ogg",
             Wav4 => "sound/waka/4.ogg",
             Atlas => "atlas.png",
-            AtlasJson => "atlas.json",
         }
     }
 }
 
 mod imp {
     use super::*;
+    use crate::error::AssetError;
     use crate::platform::get_platform;
 
+    /// Returns the raw bytes of the given asset.
     pub fn get_asset_bytes(asset: Asset) -> Result<Cow<'static, [u8]>, AssetError> {
         get_platform().get_asset_bytes(asset)
     }

src/constants.rs

@@ -18,8 +18,6 @@ pub const SCALE: f32 = 2.6;
 pub const BOARD_CELL_OFFSET: UVec2 = UVec2::new(0, 3);
 /// The offset of the game board from the top-left corner of the window, in pixels.
 pub const BOARD_PIXEL_OFFSET: UVec2 = UVec2::new(BOARD_CELL_OFFSET.x * CELL_SIZE, BOARD_CELL_OFFSET.y * CELL_SIZE);
-/// The size of the game board, in pixels.
-pub const BOARD_PIXEL_SIZE: UVec2 = UVec2::new(BOARD_CELL_SIZE.x * CELL_SIZE, BOARD_CELL_SIZE.y * CELL_SIZE);
 /// The size of the canvas, in pixels.
 pub const CANVAS_SIZE: UVec2 = UVec2::new(
     (BOARD_CELL_SIZE.x + BOARD_CELL_OFFSET.x) * CELL_SIZE,

src/entity/collision.rs

@@ -1,7 +1,7 @@
 use smallvec::SmallVec;
 use std::collections::HashMap;
 
-use crate::entity::traversal::Position;
+use crate::entity::{graph::NodeId, traversal::Position};
 
 /// Trait for entities that can participate in collision detection.
 pub trait Collidable {
@@ -19,7 +19,7 @@ pub trait Collidable {
 #[derive(Default)]
 pub struct CollisionSystem {
     /// Maps node IDs to lists of entity IDs that are at that node
-    node_entities: HashMap<usize, Vec<EntityId>>,
+    node_entities: HashMap<NodeId, Vec<EntityId>>,
     /// Maps entity IDs to their current positions
     entity_positions: HashMap<EntityId, Position>,
     /// Next available entity ID
@@ -62,7 +62,7 @@ impl CollisionSystem {
     }
 
     /// Gets all entity IDs at a specific node
-    pub fn entities_at_node(&self, node: usize) -> &[EntityId] {
+    pub fn entities_at_node(&self, node: NodeId) -> &[EntityId] {
         self.node_entities.get(&node).map(|v| v.as_slice()).unwrap_or(&[])
     }
 
@@ -115,7 +115,7 @@ fn positions_overlap(a: &Position, b: &Position) -> bool {
 }
 
 /// Gets all nodes that an entity is currently at or between.
-fn get_nodes(pos: &Position) -> SmallVec<[usize; 2]> {
+fn get_nodes(pos: &Position) -> SmallVec<[NodeId; 2]> {
     let mut nodes = SmallVec::new();
     match pos {
         Position::AtNode(node) => nodes.push(*node),

src/entity/ghost.rs

@@ -164,10 +164,8 @@ impl Ghost {
                         })?,
                 ];
 
-            textures[direction.as_usize()] =
-                Some(AnimatedTexture::new(moving_tiles, 0.2).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
-            stopped_textures[direction.as_usize()] =
-                Some(AnimatedTexture::new(stopped_tiles, 0.1).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
+            textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.2)?);
+            stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
         }
 
         Ok(Self {

src/entity/graph.rs

@@ -192,14 +192,15 @@ impl Graph {
 
         // 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 we're not replacing the edge, we don't want to replace an edge that already exists in this direction
-            if !replace && e.direction == direction {
-                Some(Err("Edge already exists in this direction."))
-            } else if e.target == to {
-                Some(Err("Edge already exists."))
-            } else {
-                None
+            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;
         }

src/entity/item.rs

@@ -1,7 +1,7 @@
 use crate::{
     constants,
     entity::{collision::Collidable, graph::Graph},
-    error::EntityError,
+    error::{EntityError, GameResult},
     texture::sprite::{Sprite, SpriteAtlas},
 };
 use sdl2::render::{Canvas, RenderTarget};
@@ -95,16 +95,18 @@ impl Item {
         self.item_type.get_score()
     }
 
-    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) -> anyhow::Result<()> {
-        if !self.collected {
-            let node = graph
-                .get_node(self.node_index)
-                .ok_or(EntityError::NodeNotFound(self.node_index))?;
-            let position = node.position + constants::BOARD_PIXEL_OFFSET.as_vec2();
-            self.sprite.render(canvas, atlas, position)
-        } else {
-            Ok(())
+    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) -> GameResult<()> {
+        if self.collected {
+            return Ok(());
         }
+
+        let node = graph
+            .get_node(self.node_index)
+            .ok_or(EntityError::NodeNotFound(self.node_index))?;
+        let position = node.position + constants::BOARD_PIXEL_OFFSET.as_vec2();
+
+        self.sprite.render(canvas, atlas, position)?;
+        Ok(())
     }
 }
 

src/entity/pacman.rs

@@ -98,10 +98,8 @@ impl Pacman {
             let stopped_tiles = vec![SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_b.png"))
                 .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?];
 
-            textures[direction.as_usize()] =
-                Some(AnimatedTexture::new(moving_tiles, 0.08).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
-            stopped_textures[direction.as_usize()] =
-                Some(AnimatedTexture::new(stopped_tiles, 0.1).map_err(|e| GameError::Texture(TextureError::Animated(e)))?);
+            textures[direction.as_usize()] = Some(AnimatedTexture::new(moving_tiles, 0.08)?);
+            stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
         }
 
         Ok(Self {

src/error.rs

@@ -3,22 +3,22 @@
 //! This module defines all error types used throughout the application,
 //! providing a consistent error handling approach.
 
-use thiserror::Error;
+use std::io;
 
 /// Main error type for the Pac-Man game.
 ///
 /// This is the primary error type that should be used in public APIs.
 /// It can represent any error that can occur during game operation.
-#[derive(Error, Debug)]
+#[derive(thiserror::Error, Debug)]
 pub enum GameError {
     #[error("Asset error: {0}")]
-    Asset(#[from] crate::asset::AssetError),
+    Asset(#[from] AssetError),
 
     #[error("Platform error: {0}")]
-    Platform(#[from] crate::platform::PlatformError),
+    Platform(#[from] PlatformError),
 
     #[error("Map parsing error: {0}")]
-    MapParse(#[from] crate::map::parser::ParseError),
+    MapParse(#[from] ParseError),
 
     #[error("Map error: {0}")]
     Map(#[from] MapError),
@@ -36,26 +36,49 @@ pub enum GameError {
     Sdl(String),
 
     #[error("IO error: {0}")]
-    Io(#[from] std::io::Error),
+    Io(#[from] io::Error),
 
     #[error("Serialization error: {0}")]
     Serialization(#[from] serde_json::Error),
 
     #[error("Invalid state: {0}")]
     InvalidState(String),
+}
 
-    #[error("Resource not found: {0}")]
+#[derive(thiserror::Error, Debug)]
+pub enum AssetError {
+    #[error("IO error: {0}")]
+    Io(#[from] io::Error),
+    #[error("Asset not found: {0}")]
     NotFound(String),
+}
 
-    #[error("Configuration error: {0}")]
-    Config(String),
+/// Platform-specific errors.
+#[derive(thiserror::Error, Debug)]
+#[allow(dead_code)]
+pub enum PlatformError {
+    #[error("Console initialization failed: {0}")]
+    ConsoleInit(String),
+    #[error("Platform-specific error: {0}")]
+    Other(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(Error, Debug)]
+#[derive(thiserror::Error, Debug)]
 pub enum TextureError {
     #[error("Animated texture error: {0}")]
-    Animated(#[from] crate::texture::animated::AnimatedTextureError),
+    Animated(#[from] AnimatedTextureError),
 
     #[error("Failed to load texture: {0}")]
     LoadFailed(String),
@@ -70,8 +93,14 @@ pub enum TextureError {
     RenderFailed(String),
 }
 
+#[derive(thiserror::Error, Debug)]
+pub enum AnimatedTextureError {
+    #[error("Frame duration must be positive, got {0}")]
+    InvalidFrameDuration(f32),
+}
+
 /// Errors related to entity operations.
-#[derive(Error, Debug)]
+#[derive(thiserror::Error, Debug)]
 pub enum EntityError {
     #[error("Node not found in graph: {0}")]
     NodeNotFound(usize),
@@ -87,11 +116,11 @@ pub enum EntityError {
 }
 
 /// Errors related to game state operations.
-#[derive(Error, Debug)]
+#[derive(thiserror::Error, Debug)]
 pub enum GameStateError {}
 
 /// Errors related to map operations.
-#[derive(Error, Debug)]
+#[derive(thiserror::Error, Debug)]
 pub enum MapError {
     #[error("Node not found: {0}")]
     NodeNotFound(usize),

src/game/mod.rs

@@ -3,159 +3,47 @@
 use glam::{UVec2, Vec2};
 use rand::{rngs::SmallRng, Rng, SeedableRng};
 use sdl2::{
-    image::LoadTexture,
     keyboard::Keycode,
     pixels::Color,
     render::{Canvas, RenderTarget, Texture, TextureCreator},
     video::WindowContext,
 };
 
-use crate::error::{EntityError, GameError, GameResult, TextureError};
+use crate::entity::r#trait::Entity;
+use crate::error::{EntityError, GameError, GameResult};
 
-use crate::{
-    asset::{get_asset_bytes, Asset},
-    audio::Audio,
-    constants::{CELL_SIZE, RAW_BOARD},
-    entity::{
-        collision::{Collidable, CollisionSystem, EntityId},
-        ghost::{Ghost, GhostType},
-        item::Item,
-        pacman::Pacman,
-        r#trait::Entity,
-    },
-    map::Map,
-    texture::{
-        sprite::{AtlasMapper, AtlasTile, SpriteAtlas},
-        text::TextTexture,
-    },
+use crate::entity::{
+    collision::{Collidable, CollisionSystem, EntityId},
+    ghost::{Ghost, GhostType},
+    pacman::Pacman,
 };
 
-/// The main game state.
+use crate::map::render::MapRenderer;
+use crate::{constants, texture::sprite::SpriteAtlas};
+
+pub mod state;
+use state::GameState;
+
+/// The `Game` struct is the main entry point for the game.
 ///
-/// Contains all the information necessary to run the game, including
-/// the game state, rendering resources, and audio.
+/// It contains the game's state and logic, and is responsible for
+/// handling user input, updating the game state, and rendering the game.
 pub struct Game {
-    pub score: u32,
-    pub map: Map,
-    pub pacman: Pacman,
-    pub ghosts: Vec<Ghost>,
-    pub items: Vec<Item>,
-    pub debug_mode: bool,
-
-    // Collision system
-    collision_system: CollisionSystem,
-    pacman_id: EntityId,
-    ghost_ids: Vec<EntityId>,
-    item_ids: Vec<EntityId>,
-
-    // Rendering resources
-    atlas: SpriteAtlas,
-    map_texture: AtlasTile,
-    text_texture: TextTexture,
-
-    // Audio
-    pub audio: Audio,
+    state: GameState,
 }
 
 impl Game {
-    pub fn new(
-        texture_creator: &'static TextureCreator<WindowContext>,
-        _ttf_context: &sdl2::ttf::Sdl2TtfContext,
-        _audio_subsystem: &sdl2::AudioSubsystem,
-    ) -> GameResult<Game> {
-        let map = Map::new(RAW_BOARD)?;
+    pub fn new(texture_creator: &'static TextureCreator<WindowContext>) -> GameResult<Game> {
+        let state = GameState::new(texture_creator)?;
 
-        let pacman_start_pos = map
-            .find_starting_position(0)
-            .ok_or_else(|| GameError::NotFound("Pac-Man starting position".to_string()))?;
-        let pacman_start_node = *map
-            .grid_to_node
-            .get(&glam::IVec2::new(pacman_start_pos.x as i32, pacman_start_pos.y as i32))
-            .ok_or_else(|| GameError::NotFound("Pac-Man starting position not found in graph".to_string()))?;
-
-        let atlas_bytes = get_asset_bytes(Asset::Atlas)?;
-        let atlas_texture = Box::leak(Box::new(texture_creator.load_texture_bytes(&atlas_bytes).map_err(|e| {
-            if e.to_string().contains("format") || e.to_string().contains("unsupported") {
-                GameError::Texture(TextureError::InvalidFormat(format!("Unsupported texture format: {e}")))
-            } else {
-                GameError::Texture(TextureError::LoadFailed(e.to_string()))
-            }
-        })?));
-        let atlas_json = get_asset_bytes(Asset::AtlasJson)?;
-        let atlas_mapper: AtlasMapper = serde_json::from_slice(&atlas_json)?;
-        let atlas = SpriteAtlas::new(unsafe { std::mem::transmute_copy(atlas_texture) }, atlas_mapper);
-
-        let mut map_texture = SpriteAtlas::get_tile(&atlas, "maze/full.png")
-            .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("maze/full.png".to_string())))?;
-        map_texture.color = Some(Color::RGB(0x20, 0x20, 0xf9));
-
-        let text_texture = TextTexture::new(1.0);
-        let audio = Audio::new();
-        let pacman = Pacman::new(&map.graph, pacman_start_node, &atlas)?;
-
-        // Generate items (pellets and energizers)
-        let items = map.generate_items(&atlas)?;
-
-        // Create ghosts at random positions
-        let mut ghosts = Vec::new();
-        let ghost_types = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde];
-        let mut rng = SmallRng::from_os_rng();
-
-        if map.graph.node_count() == 0 {
-            return Err(GameError::Config("Game map has no nodes - invalid configuration".to_string()));
-            // TODO: This is a bug, we should handle this better
-        }
-
-        for &ghost_type in &ghost_types {
-            // Find a random node for the ghost to start at
-            let random_node = rng.random_range(0..map.graph.node_count());
-            let ghost = Ghost::new(&map.graph, random_node, ghost_type, &atlas)?;
-            ghosts.push(ghost);
-        }
-
-        // Initialize collision system
-        let mut collision_system = CollisionSystem::default();
-
-        // Register Pac-Man
-        let pacman_id = collision_system.register_entity(pacman.position());
-
-        // Register items
-        let mut item_ids = Vec::new();
-        for item in &items {
-            let item_id = collision_system.register_entity(item.position());
-            item_ids.push(item_id);
-        }
-
-        // Register ghosts
-        let mut ghost_ids = Vec::new();
-        for ghost in &ghosts {
-            let ghost_id = collision_system.register_entity(ghost.position());
-            ghost_ids.push(ghost_id);
-        }
-
-        Ok(Game {
-            score: 0,
-            map,
-            pacman,
-            ghosts,
-            items,
-            debug_mode: false,
-            collision_system,
-            pacman_id,
-            ghost_ids,
-            item_ids,
-            map_texture,
-            text_texture,
-            audio,
-            atlas,
-        })
+        Ok(Game { state })
     }
 
     pub fn keyboard_event(&mut self, keycode: Keycode) {
-        self.pacman.handle_key(keycode);
+        self.state.pacman.handle_key(keycode);
 
         if keycode == Keycode::M {
-            self.audio.set_mute(!self.audio.is_muted());
+            self.state.audio.set_mute(!self.state.audio.is_muted());
         }
 
         if keycode == Keycode::R {
@@ -167,60 +55,50 @@ impl Game {
 
     /// Resets the game state, randomizing ghost positions and resetting Pac-Man
     fn reset_game_state(&mut self) -> GameResult<()> {
-        // Reset Pac-Man to starting position
-        let pacman_start_pos = self
-            .map
-            .find_starting_position(0)
-            .ok_or_else(|| GameError::NotFound("Pac-Man starting position".to_string()))?;
-        let pacman_start_node = *self
-            .map
-            .grid_to_node
-            .get(&glam::IVec2::new(pacman_start_pos.x as i32, pacman_start_pos.y as i32))
-            .ok_or_else(|| GameError::NotFound("Pac-Man starting position not found in graph".to_string()))?;
-
-        self.pacman = Pacman::new(&self.map.graph, pacman_start_node, &self.atlas)?;
+        let pacman_start_node = self.state.map.start_positions.pacman;
+        self.state.pacman = Pacman::new(&self.state.map.graph, pacman_start_node, &self.state.atlas)?;
 
         // Reset items
-        self.items = self.map.generate_items(&self.atlas)?;
+        self.state.items = self.state.map.generate_items(&self.state.atlas)?;
 
         // Randomize ghost positions
         let ghost_types = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde];
         let mut rng = SmallRng::from_os_rng();
 
-        for (i, ghost) in self.ghosts.iter_mut().enumerate() {
-            let random_node = rng.random_range(0..self.map.graph.node_count());
-            *ghost = Ghost::new(&self.map.graph, random_node, ghost_types[i], &self.atlas)?;
+        for (i, ghost) in self.state.ghosts.iter_mut().enumerate() {
+            let random_node = rng.random_range(0..self.state.map.graph.node_count());
+            *ghost = Ghost::new(&self.state.map.graph, random_node, ghost_types[i], &self.state.atlas)?;
         }
 
         // Reset collision system
-        self.collision_system = CollisionSystem::default();
+        self.state.collision_system = CollisionSystem::default();
 
         // Re-register Pac-Man
-        self.pacman_id = self.collision_system.register_entity(self.pacman.position());
+        self.state.pacman_id = self.state.collision_system.register_entity(self.state.pacman.position());
 
         // Re-register items
-        self.item_ids.clear();
-        for item in &self.items {
-            let item_id = self.collision_system.register_entity(item.position());
-            self.item_ids.push(item_id);
+        self.state.item_ids.clear();
+        for item in &self.state.items {
+            let item_id = self.state.collision_system.register_entity(item.position());
+            self.state.item_ids.push(item_id);
         }
 
         // Re-register ghosts
-        self.ghost_ids.clear();
-        for ghost in &self.ghosts {
-            let ghost_id = self.collision_system.register_entity(ghost.position());
-            self.ghost_ids.push(ghost_id);
+        self.state.ghost_ids.clear();
+        for ghost in &self.state.ghosts {
+            let ghost_id = self.state.collision_system.register_entity(ghost.position());
+            self.state.ghost_ids.push(ghost_id);
         }
 
         Ok(())
     }
 
     pub fn tick(&mut self, dt: f32) {
-        self.pacman.tick(dt, &self.map.graph);
+        self.state.pacman.tick(dt, &self.state.map.graph);
 
         // Update all ghosts
-        for ghost in &mut self.ghosts {
-            ghost.tick(dt, &self.map.graph);
+        for ghost in &mut self.state.ghosts {
+            ghost.tick(dt, &self.state.map.graph);
         }
 
         // Update collision system positions
@@ -230,29 +108,42 @@ impl Game {
         self.check_collisions();
     }
 
+    /// Toggles the debug mode on and off.
+    ///
+    /// When debug mode is enabled, the game will render additional information
+    /// that is useful for debugging, such as the collision grid and entity paths.
+    pub fn toggle_debug_mode(&mut self) {
+        self.state.debug_mode = !self.state.debug_mode;
+    }
+
     fn update_collision_positions(&mut self) {
         // Update Pac-Man's position
-        self.collision_system.update_position(self.pacman_id, self.pacman.position());
+        self.state
+            .collision_system
+            .update_position(self.state.pacman_id, self.state.pacman.position());
 
         // Update ghost positions
-        for (ghost, &ghost_id) in self.ghosts.iter().zip(&self.ghost_ids) {
-            self.collision_system.update_position(ghost_id, ghost.position());
+        for (ghost, &ghost_id) in self.state.ghosts.iter().zip(&self.state.ghost_ids) {
+            self.state.collision_system.update_position(ghost_id, ghost.position());
         }
     }
 
     fn check_collisions(&mut self) {
         // Check Pac-Man vs Items
-        let potential_collisions = self.collision_system.potential_collisions(&self.pacman.position());
+        let potential_collisions = self
+            .state
+            .collision_system
+            .potential_collisions(&self.state.pacman.position());
 
         for entity_id in potential_collisions {
-            if entity_id != self.pacman_id {
+            if entity_id != self.state.pacman_id {
                 // Check if this is an item collision
                 if let Some(item_index) = self.find_item_by_id(entity_id) {
-                    let item = &mut self.items[item_index];
+                    let item = &mut self.state.items[item_index];
                     if !item.is_collected() {
                         item.collect();
-                        self.score += item.get_score();
-                        self.audio.eat();
+                        self.state.score += item.get_score();
+                        self.state.audio.eat();
 
                         // Handle energizer effects
                         if matches!(item.item_type, crate::entity::item::ItemType::Energizer) {
@@ -272,35 +163,60 @@ impl Game {
     }
 
     fn find_item_by_id(&self, entity_id: EntityId) -> Option<usize> {
-        self.item_ids.iter().position(|&id| id == entity_id)
+        self.state.item_ids.iter().position(|&id| id == entity_id)
     }
 
     fn find_ghost_by_id(&self, entity_id: EntityId) -> Option<usize> {
-        self.ghost_ids.iter().position(|&id| id == entity_id)
+        self.state.ghost_ids.iter().position(|&id| id == entity_id)
     }
 
     pub fn draw<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>, backbuffer: &mut Texture) -> GameResult<()> {
+        // Only render the map texture once and cache it
+        if !self.state.map_rendered {
+            let mut map_texture = self
+                .state
+                .texture_creator
+                .create_texture_target(None, constants::CANVAS_SIZE.x, constants::CANVAS_SIZE.y)
+                .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+            canvas
+                .with_texture_canvas(&mut map_texture, |map_canvas| {
+                    let mut map_tiles = Vec::with_capacity(35);
+                    for i in 0..35 {
+                        let tile_name = format!("maze/tiles/{}.png", i);
+                        let tile = SpriteAtlas::get_tile(&self.state.atlas, &tile_name).unwrap();
+                        map_tiles.push(tile);
+                    }
+                    MapRenderer::render_map(map_canvas, &mut self.state.atlas, &mut map_tiles);
+                })
+                .map_err(|e| GameError::Sdl(e.to_string()))?;
+            self.state.map_texture = Some(map_texture);
+            self.state.map_rendered = true;
+        }
+
         canvas
             .with_texture_canvas(backbuffer, |canvas| {
                 canvas.set_draw_color(Color::BLACK);
                 canvas.clear();
-                self.map.render(canvas, &mut self.atlas, &mut self.map_texture);
+                if let Some(ref map_texture) = self.state.map_texture {
+                    canvas.copy(map_texture, None, None).unwrap();
+                }
 
                 // Render all items
-                for item in &self.items {
-                    if let Err(e) = item.render(canvas, &mut self.atlas, &self.map.graph) {
+                for item in &self.state.items {
+                    if let Err(e) = item.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
                         tracing::error!("Failed to render item: {}", e);
                     }
                 }
 
                 // Render all ghosts
-                for ghost in &self.ghosts {
-                    if let Err(e) = ghost.render(canvas, &mut self.atlas, &self.map.graph) {
+                for ghost in &self.state.ghosts {
+                    if let Err(e) = ghost.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
                         tracing::error!("Failed to render ghost: {}", e);
                     }
                 }
 
-                if let Err(e) = self.pacman.render(canvas, &mut self.atlas, &self.map.graph) {
+                if let Err(e) = self.state.pacman.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
                     tracing::error!("Failed to render pacman: {}", e);
                 }
             })
@@ -318,10 +234,11 @@ impl Game {
         canvas
             .copy(backbuffer, None, None)
             .map_err(|e| GameError::Sdl(e.to_string()))?;
-        if self.debug_mode {
-            if let Err(e) = self
-                .map
-                .debug_render_with_cursor(canvas, &mut self.text_texture, &mut self.atlas, cursor_pos)
+        if self.state.debug_mode {
+            if let Err(e) =
+                self.state
+                    .map
+                    .debug_render_with_cursor(canvas, &mut self.state.text_texture, &mut self.state.atlas, cursor_pos)
             {
                 tracing::error!("Failed to render debug cursor: {}", e);
             }
@@ -337,10 +254,10 @@ impl Game {
     /// Each ghost's path is drawn in its respective color with a small offset
     /// to prevent overlapping lines.
     fn render_pathfinding_debug<T: RenderTarget>(&self, canvas: &mut Canvas<T>) -> GameResult<()> {
-        let pacman_node = self.pacman.current_node_id();
+        let pacman_node = self.state.pacman.current_node_id();
 
-        for ghost in self.ghosts.iter() {
-            if let Ok(path) = ghost.calculate_path_to_target(&self.map.graph, pacman_node) {
+        for ghost in self.state.ghosts.iter() {
+            if let Ok(path) = ghost.calculate_path_to_target(&self.state.map.graph, pacman_node) {
                 if path.len() < 2 {
                     continue; // Skip if path is too short
                 }
@@ -367,6 +284,7 @@ impl Game {
                 let mut offset_positions = Vec::new();
                 for &node_id in &path {
                     let node = self
+                        .state
                         .map
                         .graph
                         .get_node(node_id)
@@ -379,7 +297,7 @@ impl Game {
                 for window in offset_positions.windows(2) {
                     if let (Some(from), Some(to)) = (window.first(), window.get(1)) {
                         // Skip if the distance is too far (used for preventing lines between tunnel portals)
-                        if from.distance_squared(*to) > (CELL_SIZE * 16).pow(2) as f32 {
+                        if from.distance_squared(*to) > (crate::constants::CELL_SIZE * 16).pow(2) as f32 {
                             continue;
                         }
 
@@ -397,23 +315,23 @@ impl Game {
 
     fn draw_hud<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>) -> GameResult<()> {
         let lives = 3;
-        let score_text = format!("{:02}", self.score);
+        let score_text = format!("{:02}", self.state.score);
         let x_offset = 4;
         let y_offset = 2;
         let lives_offset = 3;
         let score_offset = 7 - (score_text.len() as i32);
-        self.text_texture.set_scale(1.0);
-        if let Err(e) = self.text_texture.render(
+        self.state.text_texture.set_scale(1.0);
+        if let Err(e) = self.state.text_texture.render(
             canvas,
-            &mut self.atlas,
+            &mut self.state.atlas,
             &format!("{lives}UP   HIGH SCORE   "),
             UVec2::new(8 * lives_offset as u32 + x_offset, y_offset),
         ) {
             tracing::error!("Failed to render HUD text: {}", e);
         }
-        if let Err(e) = self.text_texture.render(
+        if let Err(e) = self.state.text_texture.render(
             canvas,
-            &mut self.atlas,
+            &mut self.state.atlas,
             &score_text,
             UVec2::new(8 * score_offset as u32 + x_offset, 8 + y_offset),
         ) {