test: add tests for collision, items, directional, sprite

enum macros for FruitKind

.config/nextest.toml

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

.github/workflows/build.yaml

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

.github/workflows/coverage.yaml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master
@@ -42,39 +42,15 @@ 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: |
-          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
+          cargo llvm-cov --no-fail-fast --lcov --output-path lcov.info nextest
 
       - name: Upload coverage to Coveralls
-        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
+        uses: coverallsapp/github-action@v2
+        with:
+          files: ./lcov.info
+          format: lcov
+          allow-empty: false

.github/workflows/tests.yaml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master

.gitignore

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

.pre-commit-config.yaml

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

Cargo.toml

@@ -6,7 +6,7 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-tracing = { version = "0.1.41", features = ["max_level_debug", "release_max_level_debug"]}
+tracing = { version = "0.1.40", features = ["max_level_debug", "release_max_level_debug"]}
 tracing-error = "0.2.0"
 tracing-subscriber = {version = "0.3.17", features = ["env-filter"]}
 lazy_static = "1.5.0"
@@ -15,23 +15,14 @@ spin_sleep = "1.3.2"
 rand = { version = "0.9.2", default-features = false, features = ["small_rng", "os_rng"] }
 pathfinding = "4.14"
 once_cell = "1.21.3"
-thiserror = "2.0.14"
+thiserror = "1.0"
 anyhow = "1.0"
-glam = "0.30.5"
+glam = { version = "0.30.4", features = [] }
 serde = { version = "1.0.219", features = ["derive"] }
-serde_json = "1.0.142"
+serde_json = "1.0.141"
 smallvec = "1.15.1"
 strum = "0.27.2"
 strum_macros = "0.27.2"
-phf = { version = "0.12.1", features = ["macros"] }
-bevy_ecs = "0.16.1"
-bitflags = "2.9.1"
-parking_lot = "0.12.3"
-micromap = "0.1.0"
-thousands = "0.2.0"
-pretty_assertions = "1.4.1"
-num-width = "0.1.0"
-circular-buffer = "1.1.0"
 
 [profile.release]
 lto = true
@@ -65,9 +56,4 @@ x86_64-apple-darwin = { triplet = "x64-osx" }
 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.12.1", features = ["macros"] }
+libc = "0.2.16"

Justfile

@@ -1,33 +0,0 @@
-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

README.md

@@ -1,6 +1,6 @@
 # Pac-Man
 
-[![Tests Status][badge-test]][test] [![Build Status][badge-build]][build] [![If you're seeing this, Coveralls.io is broken again and it's not my fault.][badge-coverage]][coverage] [![Online Demo][badge-online-demo]][demo] [![Last Commit][badge-last-commit]][commits]
+[![Tests Status][badge-test]][test] [![Build Status][badge-build]][build] [![Code Coverage][badge-coverage]][coverage] [![Online Demo][badge-online-demo]][demo] [![Last Commit][badge-last-commit]][commits]
 
 [badge-test]: https://github.com/Xevion/Pac-Man/actions/workflows/tests.yaml/badge.svg
 [badge-build]: https://github.com/Xevion/Pac-Man/actions/workflows/build.yaml/badge.svg
@@ -72,8 +72,6 @@ I wanted to hit a log of goals and features, making it a 'perfect' project that
 
 Since this project is still in progress, I'm only going to cover non-obvious build details. By reading the code, build scripts, and copying the online build workflows, you should be able to replicate the build process.
 
-- We use rustc 1.86.0 for the build, due to bulk-memory-opt related issues on wasm32-unknown-emscripten.
-  - Technically, we could probably use stable or even nightly on desktop targets, but using different versions for different targets is a pain, mainly because of clippy warnings changing between versions.
 - Install `cargo-vcpkg` with `cargo install cargo-vcpkg`, then run `cargo vcpkg build` to build the requisite dependencies via vcpkg.
 - For the WASM build, you need to have the Emscripten SDK cloned; you can do so with `git clone https://github.com/emscripten-core/emsdk.git`
   - The first time you clone, you'll need to install the appropriate SDK version with `./emsdk install 3.1.43` and then activate it with `./emsdk activate 3.1.43`. On Windows, use `./emsdk/emsdk.ps1` instead.

bacon.toml

@@ -34,30 +34,6 @@ 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
@@ -83,4 +59,3 @@ c = "job:clippy"
 alt-c = "job:check"
 ctrl-alt-c = "job:check-all"
 shift-c = "job:clippy-all"
-f = "job:coverage"

build.rs

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

rust-toolchain.toml

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

src/app.rs

@@ -1,9 +1,12 @@
 use std::time::{Duration, Instant};
 
-use sdl2::render::TextureCreator;
-use sdl2::ttf::Sdl2TtfContext;
-use sdl2::video::WindowContext;
-use sdl2::{AudioSubsystem, EventPump, Sdl, VideoSubsystem};
+use glam::Vec2;
+use sdl2::event::{Event, WindowEvent};
+use sdl2::keyboard::Keycode;
+use sdl2::render::{Canvas, ScaleMode, Texture, TextureCreator};
+use sdl2::video::{Window, WindowContext};
+use sdl2::EventPump;
+use tracing::{error, event};
 
 use crate::error::{GameError, GameResult};
 
@@ -11,42 +14,26 @@ use crate::constants::{CANVAS_SIZE, LOOP_TIME, SCALE};
 use crate::game::Game;
 use crate::platform::get_platform;
 
-/// Main application wrapper that manages SDL initialization, window lifecycle, and the game loop.
-///
-/// Handles platform-specific setup, maintains consistent frame timing, and delegates
-/// game logic to the contained `Game` instance. The app manages focus state to
-/// optimize CPU usage when the window loses focus.
-pub struct App {
-    pub game: Game,
+pub struct App<'a> {
+    game: Game,
+    canvas: Canvas<Window>,
+    event_pump: EventPump,
+    backbuffer: Texture<'a>,
+    paused: bool,
     last_tick: Instant,
-    focused: bool,
+    cursor_pos: Vec2,
 }
 
-impl App {
-    /// Initializes SDL subsystems, creates the game window, and sets up the game state.
-    ///
-    /// Performs comprehensive initialization including video/audio subsystems, platform-specific
-    /// console setup, window creation with proper scaling, and canvas configuration. All SDL
-    /// resources are leaked to maintain 'static lifetimes required by the game architecture.
-    ///
-    /// # Errors
-    ///
-    /// Returns `GameError::Sdl` if any SDL initialization step fails, or propagates
-    /// errors from `Game::new()` during game state setup.
+impl App<'_> {
     pub fn new() -> GameResult<Self> {
-        let sdl_context: &'static Sdl = Box::leak(Box::new(sdl2::init().map_err(|e| GameError::Sdl(e.to_string()))?));
-        let video_subsystem: &'static VideoSubsystem =
-            Box::leak(Box::new(sdl_context.video().map_err(|e| GameError::Sdl(e.to_string()))?));
-        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 =
-            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()))?));
-
         // Initialize platform-specific console
         get_platform().init_console()?;
 
+        let sdl_context = sdl2::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let video_subsystem = sdl_context.video().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let audio_subsystem = sdl_context.audio().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let ttf_context = sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+
         let window = video_subsystem
             .window(
                 "Pac-Man",
@@ -58,84 +45,116 @@ impl App {
             .build()
             .map_err(|e| GameError::Sdl(e.to_string()))?;
 
-        let canvas = Box::leak(Box::new(
-            window
-                .into_canvas()
-                .accelerated()
-                .build()
-                .map_err(|e| GameError::Sdl(e.to_string()))?,
-        ));
-
+        let mut canvas = window.into_canvas().build().map_err(|e| GameError::Sdl(e.to_string()))?;
         canvas
             .set_logical_size(CANVAS_SIZE.x, CANVAS_SIZE.y)
             .map_err(|e| GameError::Sdl(e.to_string()))?;
 
-        let texture_creator: &'static mut TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
+        let texture_creator_static: &'static TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
 
-        let game = Game::new(canvas, texture_creator, event_pump)?;
-        // game.audio.set_mute(cfg!(debug_assertions));
+        let mut game = Game::new(texture_creator_static, &ttf_context, &audio_subsystem)?;
+        game.audio.set_mute(cfg!(debug_assertions));
 
-        Ok(App {
+        let mut backbuffer = texture_creator_static
+            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        backbuffer.set_scale_mode(ScaleMode::Nearest);
+
+        let event_pump = sdl_context.event_pump().map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        // Initial draw
+        game.draw(&mut canvas, &mut backbuffer)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+        game.present_backbuffer(&mut canvas, &backbuffer, glam::Vec2::ZERO)
+            .map_err(|e| GameError::Sdl(e.to_string()))?;
+
+        Ok(Self {
             game,
-            focused: true,
+            canvas,
+            event_pump,
+            backbuffer,
+            paused: false,
             last_tick: Instant::now(),
+            cursor_pos: Vec2::ZERO,
         })
     }
 
-    /// Executes a single frame of the game loop with consistent timing and optional sleep.
-    ///
-    /// Calculates delta time since the last frame, runs game logic via `game.tick()`,
-    /// and implements frame rate limiting by sleeping for remaining time if the frame
-    /// completed faster than the target `LOOP_TIME`. Sleep behavior varies based on
-    /// window focus to conserve CPU when the game is not active.
-    ///
-    /// # Returns
-    ///
-    /// `true` if the game should continue running, `false` if the game requested exit.
     pub fn run(&mut self) -> bool {
         {
             let start = Instant::now();
 
-            // for event in self
-            //     .game
-            //     .world
-            //     .get_non_send_resource_mut::<&'static mut EventPump>()
-            //     .unwrap()
-            //     .poll_iter()
-            // {
-            //     match event {
-            //         Event::Window { win_event, .. } => match win_event {
-            //             WindowEvent::FocusGained => {
-            //                 self.focused = true;
-            //             }
-            //             WindowEvent::FocusLost => {
-            //                 self.focused = false;
-            //             }
-            //             _ => {}
-            //         },
-            //         Event::MouseMotion { x, y, .. } => {
-            //             // Convert window coordinates to logical coordinates
-            //             self.cursor_pos = Vec2::new(x as f32, y as f32);
-            //         }
-            //         _ => {}
-            //     }
-            // }
+            for event in self.event_pump.poll_iter() {
+                match event {
+                    Event::Window { win_event, .. } => match win_event {
+                        WindowEvent::Hidden => {
+                            event!(tracing::Level::DEBUG, "Window hidden");
+                        }
+                        WindowEvent::Shown => {
+                            event!(tracing::Level::DEBUG, "Window shown");
+                        }
+                        _ => {}
+                    },
+                    // It doesn't really make sense to have this available in the browser
+                    #[cfg(not(target_os = "emscripten"))]
+                    Event::Quit { .. }
+                    | Event::KeyDown {
+                        keycode: Some(Keycode::Escape) | Some(Keycode::Q),
+                        ..
+                    } => {
+                        event!(tracing::Level::INFO, "Exit requested. Exiting...");
+                        return false;
+                    }
+                    Event::KeyDown {
+                        keycode: Some(Keycode::P),
+                        ..
+                    } => {
+                        self.paused = !self.paused;
+                        event!(tracing::Level::INFO, "{}", if self.paused { "Paused" } else { "Unpaused" });
+                    }
+                    Event::KeyDown {
+                        keycode: Some(Keycode::Space),
+                        ..
+                    } => {
+                        self.game.debug_mode = !self.game.debug_mode;
+                    }
+                    Event::KeyDown { keycode: Some(key), .. } => {
+                        self.game.keyboard_event(key);
+                    }
+                    Event::MouseMotion { x, y, .. } => {
+                        // Convert window coordinates to logical coordinates
+                        self.cursor_pos = Vec2::new(x as f32, y as f32);
+                    }
+                    _ => {}
+                }
+            }
 
             let dt = self.last_tick.elapsed().as_secs_f32();
             self.last_tick = Instant::now();
 
-            let exit = self.game.tick(dt);
-
-            if exit {
-                return false;
+            if !self.paused {
+                self.game.tick(dt);
+                if let Err(e) = self.game.draw(&mut self.canvas, &mut self.backbuffer) {
+                    error!("Failed to draw game: {}", e);
+                }
+                if let Err(e) = self
+                    .game
+                    .present_backbuffer(&mut self.canvas, &self.backbuffer, self.cursor_pos)
+                {
+                    error!("Failed to present backbuffer: {}", e);
+                }
             }
 
-            // Sleep if we still have time left
             if start.elapsed() < LOOP_TIME {
                 let time = LOOP_TIME.saturating_sub(start.elapsed());
                 if time != Duration::ZERO {
-                    get_platform().sleep(time, self.focused);
+                    get_platform().sleep(time);
                 }
+            } else {
+                event!(
+                    tracing::Level::WARN,
+                    "Game loop behind schedule by: {:?}",
+                    start.elapsed() - LOOP_TIME
+                );
             }
 
             true

src/asset.rs

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

src/audio.rs

@@ -114,11 +114,9 @@ impl Audio {
         }
     }
 
-    /// Plays the next waka eating sound in the cycle of four variants.
+    /// Plays the "eat" sound effect.
     ///
-    /// 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.
+    /// If audio is disabled or muted, this function does nothing.
     #[allow(dead_code)]
     pub fn eat(&mut self) {
         if self.disabled || self.muted || self.sounds.is_empty() {
@@ -138,11 +136,9 @@ impl Audio {
         self.next_sound_index = (self.next_sound_index + 1) % self.sounds.len();
     }
 
-    /// Instantly mutes or unmutes all audio channels by adjusting their volume.
+    /// Instantly mute or unmute all channels.
     ///
-    /// 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.
+    /// If audio is disabled, this function does nothing.
     pub fn set_mute(&mut self, mute: bool) {
         if !self.disabled {
             let channels = 4;
@@ -155,19 +151,12 @@ impl Audio {
         self.muted = mute;
     }
 
-    /// 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.
+    /// Returns `true` if the audio is muted.
     pub fn is_muted(&self) -> bool {
         self.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.
+    /// Returns `true` if the audio system is disabled.
     #[allow(dead_code)]
     pub fn is_disabled(&self) -> bool {
         self.disabled

src/constants.rs

@@ -4,11 +4,6 @@ use std::time::Duration;
 
 use glam::UVec2;
 
-/// Target frame duration for 60 FPS game loop timing.
-///
-/// Calculated as 1/60th of a second (≈16.67ms).
-///
-/// Written out explicitly to satisfy const-eval constraints.
 pub const LOOP_TIME: Duration = Duration::from_nanos((1_000_000_000.0 / 60.0) as u64);
 
 /// The size of each cell, in pixels.
@@ -19,41 +14,34 @@ 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.
+/// The offset of the game board from the top-left corner of the window, in cells.
 pub const BOARD_CELL_OFFSET: UVec2 = UVec2::new(0, 3);
-
-/// 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.
+/// 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,
     (BOARD_CELL_SIZE.y + BOARD_CELL_OFFSET.y) * CELL_SIZE,
 );
 
-/// Map tile types that define gameplay behavior and collision properties.
+/// An enum representing the different types of tiles on the map.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum MapTile {
-    /// Traversable space with no collectible items
+    /// An empty tile.
     Empty,
+    /// A wall tile.
     Wall,
-    /// Small collectible. Implicitly a traversable tile.
+    /// A regular pellet.
     Pellet,
-    /// Large collectible. Implicitly a traversable tile.
+    /// A power pellet.
     PowerPellet,
-    /// Special traversable tile that connects to tunnel portals.
+    /// A tunnel tile.
     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.
+/// The raw layout of the game board, as a 2D array of characters.
 pub const RAW_BOARD: [&str; BOARD_CELL_SIZE.y as usize] = [
     "############################",
     "#............##............#",