feat: ecs keyboard interactions

- 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/build.yaml

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

.github/workflows/tests.yaml

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

.gitignore

@@ -1,7 +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.toml

@@ -15,12 +15,16 @@ 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 = "1.0"
+thiserror = "2.0"
 anyhow = "1.0"
-glam = { version = "0.30.4", features = [] }
+glam = { version = "0.30.5", features = [] }
 serde = { version = "1.0.219", features = ["derive"] }
-serde_json = "1.0.141"
+serde_json = "1.0.142"
 smallvec = "1.15.1"
+strum = "0.27.2"
+strum_macros = "0.27.2"
+phf = { version = "0.11", features = ["macros"] }
+bevy_ecs = "0.16.1"
 
 [profile.release]
 lto = true
@@ -54,4 +58,9 @@ x86_64-apple-darwin = { triplet = "x64-osx" }
 aarch64-apple-darwin = { triplet = "arm64-osx" }
 
 [target.'cfg(target_os = "emscripten")'.dependencies]
-libc = "0.2.16"
+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

README.md

@@ -1,6 +1,6 @@
 # Pac-Man
 
-[![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]
+[![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]
 
 [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,6 +72,8 @@ 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,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");
+}

rust-toolchain.toml

@@ -1,2 +1,4 @@
 [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,12 +1,11 @@
 use std::time::{Duration, Instant};
 
 use glam::Vec2;
-use sdl2::event::{Event, WindowEvent};
-use sdl2::keyboard::Keycode;
 use sdl2::render::{Canvas, ScaleMode, Texture, TextureCreator};
+use sdl2::ttf::Sdl2TtfContext;
 use sdl2::video::{Window, WindowContext};
-use sdl2::EventPump;
-use tracing::{error, event};
+use sdl2::{AudioSubsystem, EventPump, Sdl, VideoSubsystem};
+use tracing::{error, warn};
 
 use crate::error::{GameError, GameResult};
 
@@ -14,26 +13,28 @@ use crate::constants::{CANVAS_SIZE, LOOP_TIME, SCALE};
 use crate::game::Game;
 use crate::platform::get_platform;
 
-pub struct App<'a> {
-    game: Game,
-    canvas: Canvas<Window>,
-    event_pump: EventPump,
-    backbuffer: Texture<'a>,
-    paused: bool,
+pub struct App {
+    pub game: Game,
     last_tick: Instant,
+    focused: bool,
     cursor_pos: Vec2,
 }
 
-impl App<'_> {
+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",
@@ -45,35 +46,33 @@ impl App<'_> {
             .build()
             .map_err(|e| GameError::Sdl(e.to_string()))?;
 
-        let mut canvas = window.into_canvas().build().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let mut canvas = Box::leak(Box::new(
+            window
+                .into_canvas()
+                .accelerated()
+                .present_vsync()
+                .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: &'static TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
+        let texture_creator: &'static mut TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
 
-        let mut game = Game::new(texture_creator_static, &ttf_context, &audio_subsystem)?;
-        game.audio.set_mute(cfg!(debug_assertions));
-
-        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()))?;
+        let game = Game::new(canvas, texture_creator, event_pump)?;
+        // game.audio.set_mute(cfg!(debug_assertions));
 
         // 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()))?;
+        // 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 {
+        Ok(App {
             game,
-            canvas,
-            event_pump,
-            backbuffer,
-            paused: false,
+            focused: true,
             last_tick: Instant::now(),
             cursor_pos: Vec2::ZERO,
         })
@@ -83,78 +82,51 @@ impl App<'_> {
         {
             let start = Instant::now();
 
-            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);
-                    }
-                    _ => {}
-                }
-            }
+            // 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);
+            //         }
+            //         _ => {}
+            //     }
+            // }
 
             let dt = self.last_tick.elapsed().as_secs_f32();
             self.last_tick = Instant::now();
 
-            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);
-                }
+            let exit = self.game.tick(dt);
+
+            if exit {
+                return false;
             }
 
+            // if let Err(e) = self.game.draw(&mut self.canvas, &mut self.backbuffer) {
+            //     error!("Failed to draw game: {}", e);
+            // }
+
             if start.elapsed() < LOOP_TIME {
                 let time = LOOP_TIME.saturating_sub(start.elapsed());
                 if time != Duration::ZERO {
-                    get_platform().sleep(time);
+                    get_platform().sleep(time, self.focused);
                 }
             } else {
-                event!(
-                    tracing::Level::WARN,
-                    "Game loop behind schedule by: {:?}",
-                    start.elapsed() - LOOP_TIME
-                );
+                warn!("Game loop behind schedule by: {:?}", start.elapsed() - LOOP_TIME);
             }
 
             true

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/ecs/interact.rs

@@ -0,0 +1,172 @@
+use bevy_ecs::{
+    event::{EventReader, EventWriter},
+    query::With,
+    system::{Query, Res, ResMut},
+};
+
+use crate::{
+    ecs::{DeltaTime, GlobalState, PlayerControlled, Position, Velocity},
+    error::{EntityError, GameError},
+    game::events::GameEvent,
+    input::commands::GameCommand,
+    map::builder::Map,
+};
+
+pub fn movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut entities: Query<(&PlayerControlled, &mut Velocity, &mut Position)>,
+    mut errors: EventWriter<GameError>,
+) {
+    for (player, mut velocity, mut position) in entities.iter_mut() {
+        let distance = velocity.speed.unwrap_or(0.0) * delta_time.0;
+
+        // Decrement the remaining frames for the next direction
+        if let Some((direction, remaining)) = velocity.next_direction {
+            if remaining > 0 {
+                velocity.next_direction = Some((direction, remaining - 1));
+            } else {
+                velocity.next_direction = None;
+            }
+        }
+
+        match *position {
+            Position::AtNode(node_id) => {
+                // We're not moving, but a buffered direction is available.
+                if let Some((next_direction, _)) = velocity.next_direction {
+                    if let Some(edge) = map.graph.find_edge_in_direction(node_id, next_direction) {
+                        // if edge.permissions.can_traverse(edge) {
+                        //     // Start moving in that direction
+                        *position = Position::BetweenNodes {
+                            from: node_id,
+                            to: edge.target,
+                            traversed: distance,
+                        };
+                        velocity.direction = next_direction;
+                        // } else {
+                        //     return Err(crate::error::GameError::Entity(crate::error::EntityError::InvalidMovement(
+                        //         format!(
+                        //             "Cannot traverse edge from {} to {} in direction {:?}",
+                        //             node_id, edge.target, next_direction
+                        //         ),
+                        //     )));
+                        // }
+                    } else {
+                        errors.write(
+                            EntityError::InvalidMovement(format!(
+                                "No edge found in direction {:?} from node {}",
+                                next_direction, node_id
+                            ))
+                            .into(),
+                        );
+                    }
+
+                    velocity.next_direction = None; // Consume the buffered direction regardless of whether we started moving with it
+                }
+            }
+            Position::BetweenNodes { from, to, traversed } => {
+                // There is no point in any of the next logic if we don't travel at all
+                if distance <= 0.0 {
+                    return;
+                }
+
+                let edge = map
+                    .graph
+                    .find_edge(from, to)
+                    .ok_or_else(|| {
+                        errors.write(
+                            EntityError::InvalidMovement(format!(
+                                "Inconsistent state: Traverser is on a non-existent edge from {} to {}.",
+                                from, to
+                            ))
+                            .into(),
+                        );
+                        return;
+                    })
+                    .unwrap();
+
+                let new_traversed = traversed + distance;
+
+                if new_traversed < edge.distance {
+                    // Still on the same edge, just update the distance.
+                    *position = Position::BetweenNodes {
+                        from,
+                        to,
+                        traversed: new_traversed,
+                    };
+                } else {
+                    let overflow = new_traversed - edge.distance;
+                    let mut moved = false;
+
+                    // If we buffered a direction, try to find an edge in that direction
+                    if let Some((next_dir, _)) = velocity.next_direction {
+                        if let Some(edge) = map.graph.find_edge_in_direction(to, next_dir) {
+                            // if edge.permissions.can_traverse(edge) {
+                            //     *position = Position::BetweenNodes {
+                            //         from: to,
+                            //         to: edge.target,
+                            //         traversed: overflow,
+                            //     };
+
+                            velocity.direction = next_dir; // Remember our new direction
+                            velocity.next_direction = None; // Consume the buffered direction
+                            moved = true;
+                            // }
+                        }
+                    }
+
+                    // If we didn't move, try to continue in the current direction
+                    if !moved {
+                        if let Some(edge) = map.graph.find_edge_in_direction(to, velocity.direction) {
+                            // if edge.permissions.can_traverse(edge) {
+                            *position = Position::BetweenNodes {
+                                from: to,
+                                to: edge.target,
+                                traversed: overflow,
+                            };
+                            // } else {
+                            //     *position = Position::AtNode(to);
+                            //     velocity.next_direction = None;
+                            // }
+                        } else {
+                            *position = Position::AtNode(to);
+                            velocity.next_direction = None;
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+// Handles
+pub fn interact_system(
+    mut events: EventReader<GameEvent>,
+    mut state: ResMut<GlobalState>,
+    mut players: Query<(&PlayerControlled, &mut Velocity)>,
+    mut errors: EventWriter<GameError>,
+) {
+    // Get the player's velocity (handling to ensure there is only one player)
+    let mut velocity = match players.single_mut() {
+        Ok((_, velocity)) => velocity,
+        Err(e) => {
+            errors.write(GameError::InvalidState(format!("Player not found: {}", e)).into());
+            return;
+        }
+    };
+
+    // Handle events
+    for event in events.read() {
+        match event {
+            GameEvent::Command(command) => match command {
+                GameCommand::MovePlayer(direction) => {
+                    velocity.direction = *direction;
+                }
+                GameCommand::Exit => {
+                    state.exit = true;
+                }
+                _ => {}
+            },
+        }
+    }
+}

src/ecs/mod.rs

@@ -0,0 +1,150 @@
+//! The Entity-Component-System (ECS) module.
+//!
+//! This module contains all the ECS-related logic, including components, systems,
+//! and resources.
+
+use bevy_ecs::{bundle::Bundle, component::Component, resource::Resource};
+use glam::Vec2;
+
+use crate::{
+    entity::{direction::Direction, graph::Graph, traversal},
+    error::{EntityError, GameResult},
+    texture::{
+        animated::AnimatedTexture,
+        directional::DirectionalAnimatedTexture,
+        sprite::{AtlasTile, Sprite},
+    },
+};
+
+/// A tag component for entities that are controlled by the player.
+#[derive(Default, Component)]
+pub struct PlayerControlled;
+
+/// 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,
+}
+
+/// A component for entities that have a directional animated texture.
+#[derive(Component)]
+pub struct DirectionalAnimated {
+    pub textures: [Option<AnimatedTexture>; 4],
+    pub stopped_textures: [Option<AnimatedTexture>; 4],
+}
+
+/// A unique identifier for a node, represented by its index in the graph's storage.
+pub type NodeId = usize;
+
+/// Represents the current position of an entity traversing the graph.
+///
+/// This enum allows for precise tracking of whether an entity is exactly at a node
+/// or moving along an edge between two nodes.
+#[derive(Component, Debug, Copy, Clone, PartialEq)]
+pub enum Position {
+    /// The traverser is located exactly at a node.
+    AtNode(NodeId),
+    /// The traverser is on an edge between two nodes.
+    BetweenNodes {
+        from: NodeId,
+        to: NodeId,
+        /// The floating-point distance traversed along the edge from the `from` node.
+        traversed: 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.
+    pub fn get_pixel_pos(&self, graph: &Graph) -> GameResult<Vec2> {
+        let pos = match self {
+            Position::AtNode(node_id) => {
+                let node = graph.get_node(*node_id).ok_or(EntityError::NodeNotFound(*node_id))?;
+                node.position
+            }
+            Position::BetweenNodes { from, to, traversed } => {
+                let from_node = graph.get_node(*from).ok_or(EntityError::NodeNotFound(*from))?;
+                let to_node = graph.get_node(*to).ok_or(EntityError::NodeNotFound(*to))?;
+                let edge = graph
+                    .find_edge(*from, *to)
+                    .ok_or(EntityError::EdgeNotFound { from: *from, to: *to })?;
+                from_node.position + (to_node.position - from_node.position) * (traversed / edge.distance)
+            }
+        };
+
+        Ok(Vec2::new(
+            pos.x + crate::constants::BOARD_PIXEL_OFFSET.x as f32,
+            pos.y + crate::constants::BOARD_PIXEL_OFFSET.y as f32,
+        ))
+    }
+}
+
+impl Default for Position {
+    fn default() -> Self {
+        Position::AtNode(0)
+    }
+}
+
+#[allow(dead_code)]
+impl Position {
+    /// Returns `true` if the position is exactly at a node.
+    pub fn is_at_node(&self) -> bool {
+        matches!(self, Position::AtNode(_))
+    }
+
+    /// Returns the `NodeId` of the current or most recently departed node.
+    #[allow(clippy::wrong_self_convention)]
+    pub fn from_node_id(&self) -> NodeId {
+        match self {
+            Position::AtNode(id) => *id,
+            Position::BetweenNodes { from, .. } => *from,
+        }
+    }
+
+    /// Returns the `NodeId` of the destination node, if currently on an edge.
+    #[allow(clippy::wrong_self_convention)]
+    pub fn to_node_id(&self) -> Option<NodeId> {
+        match self {
+            Position::AtNode(_) => None,
+            Position::BetweenNodes { to, .. } => Some(*to),
+        }
+    }
+
+    /// Returns `true` if the traverser is stopped at a node.
+    pub fn is_stopped(&self) -> bool {
+        matches!(self, Position::AtNode(_))
+    }
+}
+
+/// A component for entities that have a velocity, with a direction and speed.
+#[derive(Default, Component)]
+pub struct Velocity {
+    pub direction: Direction,
+    pub next_direction: Option<(Direction, u8)>,
+    pub speed: Option<f32>,
+}
+
+#[derive(Bundle)]
+pub struct PlayerBundle {
+    pub player: PlayerControlled,
+    pub position: Position,
+    pub velocity: Velocity,
+    pub sprite: Renderable,
+    pub directional_animated: DirectionalAnimated,
+}
+
+#[derive(Resource)]
+pub struct GlobalState {
+    pub exit: bool,
+}
+
+#[derive(Resource)]
+pub struct DeltaTime(pub f32);
+
+pub mod interact;
+pub mod render;

src/ecs/render.rs

@@ -0,0 +1,95 @@
+use crate::ecs::{DeltaTime, DirectionalAnimated, Position, Renderable, Velocity};
+use crate::error::{EntityError, GameError, TextureError};
+use crate::map::builder::Map;
+use crate::texture::sprite::SpriteAtlas;
+use bevy_ecs::entity::Entity;
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::system::{NonSendMut, Query, Res};
+use sdl2::render::{Canvas, Texture};
+use sdl2::video::Window;
+
+/// Updates the directional animated texture of an entity.
+pub fn directional_render_system(
+    dt: Res<DeltaTime>,
+    mut renderables: Query<(&Velocity, &mut DirectionalAnimated, &mut Renderable)>,
+    mut errors: EventWriter<GameError>,
+) {
+    for (velocity, mut texture, mut renderable) in renderables.iter_mut() {
+        let texture = if velocity.speed.is_none() {
+            texture.stopped_textures[velocity.direction.as_usize()].as_mut()
+        } else {
+            texture.textures[velocity.direction.as_usize()].as_mut()
+        };
+
+        if let Some(texture) = texture {
+            texture.tick(dt.0);
+            renderable.sprite = *texture.current_tile();
+        } else {
+            errors.write(TextureError::RenderFailed(format!("Entity has no texture")).into());
+            continue;
+        }
+    }
+}
+
+pub struct MapTextureResource(pub Texture<'static>);
+pub struct BackbufferResource(pub Texture<'static>);
+
+pub fn render_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    map_texture: NonSendMut<MapTextureResource>,
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut atlas: NonSendMut<SpriteAtlas>,
+    map: Res<Map>,
+    mut renderables: Query<(Entity, &mut Renderable, &Position)>,
+    mut errors: EventWriter<GameError>,
+) {
+    // Clear the main canvas first
+    canvas.set_draw_color(sdl2::pixels::Color::BLACK);
+    canvas.clear();
+
+    // Render to backbuffer
+    canvas
+        .with_texture_canvas(&mut backbuffer.0, |backbuffer_canvas| {
+            // Clear the backbuffer
+            backbuffer_canvas.set_draw_color(sdl2::pixels::Color::BLACK);
+            backbuffer_canvas.clear();
+
+            // Copy the pre-rendered map texture to the backbuffer
+            backbuffer_canvas
+                .copy(&map_texture.0, None, None)
+                .err()
+                .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+
+            // Render all entities to the backbuffer
+            for (_, mut renderable, position) in renderables.iter_mut() {
+                let pos = position.get_pixel_pos(&map.graph);
+                match pos {
+                    Ok(pos) => {
+                        let dest = crate::helpers::centered_with_size(
+                            glam::IVec2::new(pos.x as i32, pos.y as i32),
+                            glam::UVec2::new(renderable.sprite.size.x as u32, renderable.sprite.size.y as u32),
+                        );
+
+                        renderable
+                            .sprite
+                            .render(backbuffer_canvas, &mut atlas, dest)
+                            .err()
+                            .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+                    }
+                    Err(e) => {
+                        errors.write(e.into());
+                    }
+                }
+            }
+        })
+        .err()
+        .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+
+    // Copy backbuffer to main canvas and present
+    canvas
+        .copy(&backbuffer.0, None, None)
+        .err()
+        .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+
+    canvas.present();
+}