fix: set PlayerLives default to 3, use resource for HUD lives count in top left

yes I am fully aware that the UP is not the player lives, I'm just
wanting the indicator to be somewhere and I'll make the proper indicator
tomorrow probably

.config/nextest.toml

@@ -3,3 +3,10 @@ fail-fast = false
 
 [profile.coverage]
 status-level = "none"
+
+[[profile.default.overrides]]
+filter = 'test(pacman::game::)'
+test-group = 'serial'
+
+[test-groups]
+serial = { max-threads = 1 }

.gitattributes

@@ -1 +1,2 @@
 * text=auto eol=lf
+scripts/* linguist-detectable=false

.github/workflows/build.yaml

@@ -151,7 +151,7 @@ jobs:
           done
 
       - name: Upload Artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         if: github.ref == 'refs/heads/master' && github.event_name == 'push'
         with:
           path: "./dist/"

.github/workflows/coverage.yaml

@@ -4,7 +4,7 @@ on: ["push", "pull_request"]
 
 env:
   CARGO_TERM_COLOR: always
-  RUST_TOOLCHAIN: 1.86.0
+  RUST_TOOLCHAIN: nightly
 
 jobs:
   coverage:
@@ -48,33 +48,9 @@ jobs:
         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
-
-      - 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
+      - name: Coveralls upload
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.COVERALLS_REPO_TOKEN }}
+          path-to-lcov: lcov.info
+          debug: true

.gitignore

@@ -14,4 +14,13 @@ assets/site/build.css
 
 # Coverage reports
 lcov.info
+codecov.json
 coverage.html
+
+# Profiling output
+flamegraph.svg
+/profile.*
+
+# temporary
+assets/game/sound/*.wav
+/*.py

.pre-commit-config.yaml

@@ -12,6 +12,13 @@ repos:
       - id: forbid-submodules
       - id: mixed-line-ending
 
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.2.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: []
+
   - repo: local
     hooks:
       - id: cargo-fmt
@@ -20,3 +27,31 @@ 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
+
+      - id: bump-version
+        name: bump version based on commit message
+        entry: python scripts/bump-version.py
+        language: system
+        stages: [commit-msg]
+        always_run: true
+
+      - id: tag-version
+        name: tag version based on commit message
+        entry: python scripts/tag-version.py
+        language: system
+        stages: [post-commit]
+        always_run: true

Cargo.toml

@@ -1,53 +1,97 @@
 [package]
 name = "pacman"
-version = "0.2.0"
+version = "0.77.1"
+authors = ["Xevion"]
 edition = "2021"
+rust-version = "1.86.0"
+description = "A cross-platform retro Pac-Man clone, written in Rust and supported by SDL2"
+readme = true
+homepage = "https://pacman.xevion.dev"
+repository = "https://github.com/Xevion/Pac-Man"
+license = "GPL-3.0-or-later"
+keywords = ["game", "pacman", "arcade", "sdl2"]
+categories = ["games", "emulators"]
+publish = false
+exclude = ["/assets/unpacked/**", "/assets/site/**", "/bacon.toml", "/Justfile"]
+default-run = "pacman"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-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"
-sdl2 = { version = "0.38.0", features = ["image", "ttf"] }
-spin_sleep = "1.3.2"
-rand = { version = "0.9.2", default-features = false, features = ["small_rng", "os_rng"] }
+bevy_ecs = "0.16.1"
+glam = "0.30.5"
 pathfinding = "4.14"
-once_cell = "1.21.3"
-thiserror = "2.0"
+tracing = { version = "0.1.41", features = ["max_level_debug", "release_max_level_debug"]}
+tracing-error = "0.2.0"
+tracing-subscriber = {version = "0.3.20", features = ["env-filter"]}
+time = { version = "0.3.43", features = ["formatting", "macros"] }
+thiserror = "2.0.16"
 anyhow = "1.0"
-glam = { version = "0.30.5", features = [] }
-serde = { version = "1.0.219", features = ["derive"] }
-serde_json = "1.0.142"
 smallvec = "1.15.1"
+bitflags = "2.9.4"
+micromap = "0.1.0"
+circular-buffer = "1.1.0"
+parking_lot = "0.12.3"
 strum = "0.27.2"
 strum_macros = "0.27.2"
+thousands = "0.2.0"
+num-width = "0.1.0"
+# While not actively used in code, `build.rs` generates code that relies on this. Keep the versions synchronized.
+phf = { version = "0.13.1", features = ["macros"] }
 
+# Windows-specific dependencies
+[target.'cfg(target_os = "windows")'.dependencies]
+# Used for customizing console output on Windows; both are required due to the `windows` crate having poor Result handling with `GetStdHandle`.
+windows = { version = "0.61.3", features = ["Win32_Security", "Win32_Storage_FileSystem", "Win32_System_Console"] }
+windows-sys = { version = "0.60.2", features = ["Win32_System_Console"] }
+
+# Desktop-specific dependencies
+[target.'cfg(not(target_os = "emscripten"))'.dependencies]
+# On desktop platforms, build SDL2 with cargo-vcpkg
+sdl2 = { version = "0.38", default-features = false, features = ["image", "ttf", "gfx", "mixer", "unsafe_textures", "static-link", "use-vcpkg"] }
+rand = { version = "0.9.2", default-features = false, features = ["thread_rng"] }
+spin_sleep = "1.3.2"
+
+# Browser-specific dependencies
+[target.'cfg(target_os = "emscripten")'.dependencies]
+# On Emscripten, we don't use cargo-vcpkg
+sdl2 = { version = "0.38", default-features = false, features = ["image", "ttf", "gfx", "mixer", "unsafe_textures"] }
+# TODO: Document why Emscripten cannot use `os_rng`.
+rand = { version = "0.9.2", default-features = false, features = ["small_rng", "os_rng"] }
+libc = "0.2.175"  # TODO: Describe why this is required.
+
+[dev-dependencies]
+pretty_assertions = "1.4.1"
+speculoos = "0.13.0"
+
+[build-dependencies]
+phf = { version = "0.13.1", features = ["macros"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.143"
+
+# phf generates runtime code which machete will not detect
+[package.metadata.cargo-machete]
+ignored = ["phf"]
+
+# Release profile for profiling (essentially the default 'release' profile with debug enabled)
+[profile.profile]
+inherits = "release"
+debug = true
+# Undo the customizations for our release profile
+opt-level = 3
+lto = false
+panic = 'unwind'
+
+# Optimized release profile for size
 [profile.release]
+opt-level = "z"
 lto = true
 panic = "abort"
-opt-level = "z"
-
-[target.'cfg(target_os = "windows")'.dependencies.winapi]
-version = "0.3"
-features = ["consoleapi", "fileapi", "handleapi", "processenv", "winbase", "wincon", "winnt", "winuser", "windef", "minwindef"]
-
-
-[target.'cfg(target_os = "emscripten")'.dependencies.sdl2]
-version = "0.38"
-default-features = false
-features = ["ttf","image","gfx","mixer"]
-
-[target.'cfg(not(target_os = "emscripten"))'.dependencies.sdl2]
-version = "0.38"
-default-features = false
-features = ["ttf","image","gfx","mixer","static-link","use-vcpkg"]
 
 [package.metadata.vcpkg]
 dependencies = ["sdl2", "sdl2-image", "sdl2-ttf", "sdl2-gfx", "sdl2-mixer"]
 git = "https://github.com/microsoft/vcpkg"
-rev = "2024.05.24" # release 2024.05.24 # to check for a new one, check https://github.com/microsoft/vcpkg/releases
+rev = "2024.05.24" # to check for a new one, check https://github.com/microsoft/vcpkg/releases
 
 [package.metadata.vcpkg.target]
 x86_64-pc-windows-msvc = { triplet = "x64-windows-static-md" }
@@ -55,5 +99,5 @@ x86_64-unknown-linux-gnu = { triplet = "x64-linux" }
 x86_64-apple-darwin = { triplet = "x64-osx" }
 aarch64-apple-darwin = { triplet = "arm64-osx" }
 
-[target.'cfg(target_os = "emscripten")'.dependencies]
-libc = "0.2.175"
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage,coverage_nightly)'] }

Justfile

@@ -1,9 +1,8 @@
 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"
+
+binary_extension := if os() == "windows" { ".exe" } else { "" }
 
 # !!! --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
@@ -12,22 +11,29 @@ coverage_exclude_pattern := "src\\\\app.rs|audio.rs|src\\\\error.rs|platform\\\\
 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 }}"
+    cargo llvm-cov report --remap-path-prefix
 
-# Run & generate report (for CI)
+# Run & generate LCOV report (as base report)
 coverage:
-    cargo llvm-cov \
+    cargo +nightly llvm-cov \
     --lcov \
     --remap-path-prefix \
-    --ignore-filename-regex "{{ coverage_exclude_pattern }}" \
+    --workspace \
     --output-path lcov.info \
     --profile coverage \
     --no-fail-fast nextest
+
+# Profile the project using 'samply'
+samply:
+    cargo build --profile profile
+    samply record ./target/profile/pacman{{ binary_extension }}
+
+# Build the project for Emscripten
+web *args:
+    bun run web.build.ts {{args}};
+    caddy file-server --root dist

LICENSE

@@ -0,0 +1,675 @@
+# GNU GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc.
+<https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+## Preamble
+
+The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+the GNU General Public License is intended to guarantee your freedom
+to share and change all versions of a program--to make sure it remains
+free software for all its users. We, the Free Software Foundation, use
+the GNU General Public License for most of our software; it applies
+also to any other work released this way by its authors. You can apply
+it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights. Therefore, you
+have certain responsibilities if you distribute copies of the
+software, or if you modify it: responsibilities to respect the freedom
+of others.
+
+For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received. You must make sure that they, too, receive
+or can get the source code. And you must show them these terms so they
+know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the
+manufacturer can do so. This is fundamentally incompatible with the
+aim of protecting users' freedom to change the software. The
+systematic pattern of such abuse occurs in the area of products for
+individuals to use, which is precisely where it is most unacceptable.
+Therefore, we have designed this version of the GPL to prohibit the
+practice for those products. If such problems arise substantially in
+other domains, we stand ready to extend this provision to those
+domains in future versions of the GPL, as needed to protect the
+freedom of users.
+
+Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish
+to avoid the special danger that patents applied to a free program
+could make it effectively proprietary. To prevent this, the GPL
+assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+## TERMS AND CONDITIONS
+
+### 0. Definitions.
+
+"This License" refers to version 3 of the GNU General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds
+of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of
+an exact copy. The resulting work is called a "modified version" of
+the earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user
+through a computer network, with no transfer of a copy, is not
+conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to
+the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+### 1. Source Code.
+
+The "source code" for a work means the preferred form of the work for
+making modifications to it. "Object code" means any non-source form of
+a work.
+
+A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+### 2. Basic Permissions.
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright. Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below. Sublicensing is not allowed; section 10 makes
+it unnecessary.
+
+### 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such
+circumvention is effected by exercising rights under this License with
+respect to the covered work, and you disclaim any intention to limit
+operation or modification of the work as a means of enforcing, against
+the work's users, your or third parties' legal rights to forbid
+circumvention of technological measures.
+
+### 4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+### 5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these
+conditions:
+
+- a) The work must carry prominent notices stating that you modified
+  it, and giving a relevant date.
+- b) The work must carry prominent notices stating that it is
+  released under this License and any conditions added under
+  section 7. This requirement modifies the requirement in section 4
+  to "keep intact all notices".
+- c) You must license the entire work, as a whole, under this
+  License to anyone who comes into possession of a copy. This
+  License will therefore apply, along with any applicable section 7
+  additional terms, to the whole of the work, and all its parts,
+  regardless of how they are packaged. This License gives no
+  permission to license the work in any other way, but it does not
+  invalidate such permission if you have separately received it.
+- d) If the work has interactive user interfaces, each must display
+  Appropriate Legal Notices; however, if the Program has interactive
+  interfaces that do not display Appropriate Legal Notices, your
+  work need not make them do so.
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+### 6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+- a) Convey the object code in, or embodied in, a physical product
+  (including a physical distribution medium), accompanied by the
+  Corresponding Source fixed on a durable physical medium
+  customarily used for software interchange.
+- b) Convey the object code in, or embodied in, a physical product
+  (including a physical distribution medium), accompanied by a
+  written offer, valid for at least three years and valid for as
+  long as you offer spare parts or customer support for that product
+  model, to give anyone who possesses the object code either (1) a
+  copy of the Corresponding Source for all the software in the
+  product that is covered by this License, on a durable physical
+  medium customarily used for software interchange, for a price no
+  more than your reasonable cost of physically performing this
+  conveying of source, or (2) access to copy the Corresponding
+  Source from a network server at no charge.
+- c) Convey individual copies of the object code with a copy of the
+  written offer to provide the Corresponding Source. This
+  alternative is allowed only occasionally and noncommercially, and
+  only if you received the object code with such an offer, in accord
+  with subsection 6b.
+- d) Convey the object code by offering access from a designated
+  place (gratis or for a charge), and offer equivalent access to the
+  Corresponding Source in the same way through the same place at no
+  further charge. You need not require recipients to copy the
+  Corresponding Source along with the object code. If the place to
+  copy the object code is a network server, the Corresponding Source
+  may be on a different server (operated by you or a third party)
+  that supports equivalent copying facilities, provided you maintain
+  clear directions next to the object code saying where to find the
+  Corresponding Source. Regardless of what server hosts the
+  Corresponding Source, you remain obligated to ensure that it is
+  available for as long as needed to satisfy these requirements.
+- e) Convey the object code using peer-to-peer transmission,
+  provided you inform other peers where the object code and
+  Corresponding Source of the work are being offered to the general
+  public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal,
+family, or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling. In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of
+coverage. For a particular product received by a particular user,
+"normally used" refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected
+to use, the product. A product is a consumer product regardless of
+whether the product has substantial commercial, industrial or
+non-consumer uses, unless such uses represent the only significant
+mode of use of the product.
+
+"Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to
+install and execute modified versions of a covered work in that User
+Product from a modified version of its Corresponding Source. The
+information must suffice to ensure that the continued functioning of
+the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or
+updates for a work that has been modified or installed by the
+recipient, or for the User Product in which it has been modified or
+installed. Access to a network may be denied when the modification
+itself materially and adversely affects the operation of the network
+or violates the rules and protocols for communication across the
+network.
+
+Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+### 7. Additional Terms.
+
+"Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders
+of that material) supplement the terms of this License with terms:
+
+- a) Disclaiming warranty or limiting liability differently from the
+  terms of sections 15 and 16 of this License; or
+- b) Requiring preservation of specified reasonable legal notices or
+  author attributions in that material or in the Appropriate Legal
+  Notices displayed by works containing it; or
+- c) Prohibiting misrepresentation of the origin of that material,
+  or requiring that modified versions of such material be marked in
+  reasonable ways as different from the original version; or
+- d) Limiting the use for publicity purposes of names of licensors
+  or authors of the material; or
+- e) Declining to grant rights under trademark law for use of some
+  trade names, trademarks, or service marks; or
+- f) Requiring indemnification of licensors and authors of that
+  material by anyone who conveys the material (or modified versions
+  of it) with contractual assumptions of liability to the recipient,
+  for any liability that these contractual assumptions directly
+  impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the
+above requirements apply either way.
+
+### 8. Termination.
+
+You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+### 9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run
+a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+### 10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+### 11. Patents.
+
+A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned
+or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+A patent license is "discriminatory" if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License. You may not convey a covered work if you
+are a party to an arrangement with a third party that is in the
+business of distributing software, under which you make payment to the
+third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by
+you (or copies made from those copies), or (b) primarily for and in
+connection with specific products or compilations that contain the
+covered work, unless you entered into that arrangement, or that patent
+license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+### 12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under
+this License and any other pertinent obligations, then as a
+consequence you may not convey it at all. For example, if you agree to
+terms that obligate you to collect a royalty for further conveying
+from those to whom you convey the Program, the only way you could
+satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+### 13. Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+### 14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU General Public License from time to time. Such new versions
+will be similar in spirit to the present version, but may differ in
+detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies that a certain numbered version of the GNU General Public
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that numbered version or
+of any later version published by the Free Software Foundation. If the
+Program does not specify a version number of the GNU General Public
+License, you may choose any version ever published by the Free
+Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU General Public License can be used, that proxy's public
+statement of acceptance of a version permanently authorizes you to
+choose that version for the Program.
+
+Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+### 15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+### 16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
+LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### 17. Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+## How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program. It is safest to
+attach them to the start of each source file to most effectively state
+the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+        <one line to give the program's name and a brief idea of what it does.>
+        Copyright (C) <year>  <name of author>
+
+        This program is free software: you can redistribute it and/or modify
+        it under the terms of the GNU General Public License as published by
+        the Free Software Foundation, either version 3 of the License, or
+        (at your option) any later version.
+
+        This program is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        GNU General Public License for more details.
+
+        You should have received a copy of the GNU General Public License
+        along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper
+mail.
+
+If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+        <program>  Copyright (C) <year>  <name of author>
+        This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+        This is free software, and you are welcome to redistribute it
+        under certain conditions; type `show c' for details.
+
+The hypothetical commands \`show w' and \`show c' should show the
+appropriate parts of the General Public License. Of course, your
+program's commands might be different; for a GUI interface, you would
+use an "about box".
+
+You should also get your employer (if you work as a programmer) or
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. For more information on this, and how to apply and follow
+the GNU GPL, see <https://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating your
+program into proprietary programs. If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library. If this is what you want to do, use the
+GNU Lesser General Public License instead of this License. But first,
+please read <https://www.gnu.org/licenses/why-not-lgpl.html>.

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

bacon.toml

@@ -28,16 +28,18 @@ need_stdout = false
 
 [jobs.test]
 command = [
-    "cargo", "nextest", "run",
-    "--hide-progress-bar", "--failure-output", "final"
+    "cargo",
+    "nextest",
+    "run",
+    "--hide-progress-bar",
+    "--failure-output",
+    "final",
 ]
 need_stdout = true
 analyzer = "nextest"
 
 [jobs.coverage]
-command = [
-    "just", "report-coverage"
-]
+command = ["just", "report-coverage"]
 need_stdout = true
 ignored_lines = [
     "info:",
@@ -54,7 +56,7 @@ ignored_lines = [
     "\\s*Finished.+in \\d+",
     "\\s*Summary\\s+\\[",
     "\\s*Blocking",
-    "Finished report saved to"
+    "Finished report saved to",
 ]
 on_change_strategy = "wait_then_restart"
 
@@ -66,21 +68,26 @@ need_stdout = false
 [jobs.doc-open]
 command = ["cargo", "doc", "--no-deps", "--open"]
 need_stdout = false
-on_success = "back" # so that we don't open the browser at each change
+on_success = "back"                               # so that we don't open the browser at each change
 
 [jobs.run]
-command = [
-    "cargo", "run",
-]
+command = ["cargo", "run"]
 need_stdout = true
 allow_warnings = true
 background = false
 on_change_strategy = "kill_then_restart"
 # kill = ["pkill", "-TERM", "-P"]'
 
+[jobs.precommit]
+command = ["pre-commit", "run", "--all-files"]
+need_stdout = true
+background = false
+on_change_strategy = "kill_then_restart"
+
 [keybindings]
 c = "job:clippy"
 alt-c = "job:check"
 ctrl-alt-c = "job:check-all"
 shift-c = "job:clippy-all"
 f = "job:coverage"
+p = "job:precommit"

build.rs

@@ -0,0 +1,54 @@
+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,
+}
+
+impl MapperFrame {
+    fn to_u16vec2_format(self) -> String {
+        format!(
+            "MapperFrame {{ pos: glam::U16Vec2::new({}, {}), size: glam::U16Vec2::new({}, {}) }}",
+            self.x, self.y, self.width, self.height
+        )
+    }
+}
+
+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, "    \"{}\" => {},", name, frame.to_u16vec2_format()).unwrap();
+    }
+
+    writeln!(&mut file, "}};").unwrap();
+    println!("cargo:rerun-if-changed=assets/game/atlas.json");
+}

scripts/bump-version.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+Pre-commit hook script to automatically bump Cargo.toml version based on commit message.
+
+This script parses the commit message for version bump keywords and uses cargo set-version
+to update the version in Cargo.toml accordingly.
+
+Supported keywords:
+- "major" or "breaking": Bump major version (1.0.0 -> 2.0.0)
+- "minor" or "feature": Bump minor version (1.0.0 -> 1.1.0)
+- "patch" or "fix" or "bugfix": Bump patch version (1.0.0 -> 1.0.1)
+
+Usage: python scripts/bump-version.py <commit_message_file>
+"""
+
+import sys
+import re
+import subprocess
+import os
+from pathlib import Path
+
+
+def get_current_version():
+    """Get the current version from Cargo.toml."""
+    try:
+        result = subprocess.run(
+            ["cargo", "metadata", "--format-version", "1", "--no-deps"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+
+        # Parse the JSON output to get version
+        import json
+        metadata = json.loads(result.stdout)
+        return metadata["packages"][0]["version"]
+    except (subprocess.CalledProcessError, json.JSONDecodeError, KeyError) as e:
+        print(f"Error getting current version: {e}", file=sys.stderr)
+        return None
+
+
+def bump_version(current_version, bump_type):
+    """Calculate the new version based on bump type."""
+    try:
+        major, minor, patch = map(int, current_version.split('.'))
+
+        if bump_type == "major":
+            return f"{major + 1}.0.0"
+        elif bump_type == "minor":
+            return f"{major}.{minor + 1}.0"
+        elif bump_type == "patch":
+            return f"{major}.{minor}.{patch + 1}"
+        else:
+            return None
+    except ValueError:
+        print(f"Invalid version format: {current_version}", file=sys.stderr)
+        return None
+
+
+def set_version(new_version):
+    """Set the new version using cargo set-version."""
+    try:
+        result = subprocess.run(
+            ["cargo", "set-version", new_version],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        print(f"Successfully bumped version to {new_version}")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"Error setting version: {e}", file=sys.stderr)
+        print(f"stdout: {e.stdout}", file=sys.stderr)
+        print(f"stderr: {e.stderr}", file=sys.stderr)
+        return False
+
+
+def parse_commit_message(commit_message_file):
+    """Parse the commit message file for version bump keywords."""
+    try:
+        with open(commit_message_file, 'r', encoding='utf-8') as f:
+            message = f.read().lower()
+    except FileNotFoundError:
+        print(f"Commit message file not found: {commit_message_file}", file=sys.stderr)
+        return None
+    except Exception as e:
+        print(f"Error reading commit message: {e}", file=sys.stderr)
+        return None
+
+    # Check for version bump keywords
+    if re.search(r'\b(major|breaking)\b', message):
+        return "major"
+    elif re.search(r'\b(minor|feature)\b', message):
+        return "minor"
+    elif re.search(r'\b(patch|fix|bugfix)\b', message):
+        return "patch"
+
+    return None
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python scripts/bump-version.py <commit_message_file>", file=sys.stderr)
+        sys.exit(1)
+
+    commit_message_file = sys.argv[1]
+
+    # Parse commit message for version bump type
+    bump_type = parse_commit_message(commit_message_file)
+
+    if not bump_type:
+        print("No version bump keywords found in commit message")
+        sys.exit(0)
+
+    print(f"Found version bump type: {bump_type}")
+
+    # Get current version
+    current_version = get_current_version()
+    if not current_version:
+        print("Failed to get current version", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Current version: {current_version}")
+
+    # Calculate new version
+    new_version = bump_version(current_version, bump_type)
+    if not new_version:
+        print("Failed to calculate new version", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"New version: {new_version}")
+
+    # Set the new version
+    if set_version(new_version):
+        print("Version bump completed successfully")
+        sys.exit(0)
+    else:
+        print("Version bump failed", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/tag-version.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Post-commit hook script to automatically create git tags based on the version in Cargo.toml.
+
+This script reads the current version from Cargo.toml and creates a git tag with that version.
+It's designed to run after the version has been bumped by the bump-version.py script.
+
+Usage: python scripts/tag-version.py
+"""
+
+import sys
+import subprocess
+import re
+from pathlib import Path
+
+
+def get_version_from_cargo_toml():
+    """Get the current version from Cargo.toml."""
+    cargo_toml_path = Path("Cargo.toml")
+
+    if not cargo_toml_path.exists():
+        print("Cargo.toml not found", file=sys.stderr)
+        return None
+
+    try:
+        with open(cargo_toml_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        # Look for version = "x.y.z" pattern
+        version_match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content)
+
+        if version_match:
+            return version_match.group(1)
+        else:
+            print("Could not find version in Cargo.toml", file=sys.stderr)
+            return None
+
+    except Exception as e:
+        print(f"Error reading Cargo.toml: {e}", file=sys.stderr)
+        return None
+
+
+def get_existing_tags():
+    """Get list of existing git tags."""
+    try:
+        result = subprocess.run(
+            ["git", "tag", "--list"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.strip().split('\n') if result.stdout.strip() else []
+    except subprocess.CalledProcessError as e:
+        print(f"Error getting git tags: {e}", file=sys.stderr)
+        return []
+
+
+def create_git_tag(version):
+    """Create a git tag with the specified version."""
+    tag_name = f"v{version}"
+
+    try:
+        # Check if tag already exists
+        existing_tags = get_existing_tags()
+        if tag_name in existing_tags:
+            print(f"Tag {tag_name} already exists, skipping")
+            return True
+
+        # Create the tag
+        result = subprocess.run(
+            ["git", "tag", tag_name],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+
+        print(f"Successfully created tag: {tag_name}")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"Error creating git tag: {e}", file=sys.stderr)
+        print(f"stdout: {e.stdout}", file=sys.stderr)
+        print(f"stderr: {e.stderr}", file=sys.stderr)
+        return False
+
+
+def is_git_repository():
+    """Check if we're in a git repository."""
+    try:
+        subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            capture_output=True,
+            check=True
+        )
+        return True
+    except subprocess.CalledProcessError:
+        return False
+
+
+def main():
+    # Check if we're in a git repository
+    if not is_git_repository():
+        print("Not in a git repository, skipping tag creation")
+        sys.exit(0)
+
+    # Get the current version from Cargo.toml
+    version = get_version_from_cargo_toml()
+
+    if not version:
+        print("Could not determine version, skipping tag creation")
+        sys.exit(0)
+
+    print(f"Current version: {version}")
+
+    # Create the git tag
+    if create_git_tag(version):
+        print("Tag creation completed successfully")
+        sys.exit(0)
+    else:
+        print("Tag creation failed", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/app.rs

@@ -1,44 +1,40 @@
+use std::collections::HashMap;
 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::{AudioSubsystem, EventPump, Sdl, VideoSubsystem};
-use tracing::{error, event};
-
 use crate::error::{GameError, GameResult};
 
 use crate::constants::{CANVAS_SIZE, LOOP_TIME, SCALE};
+use crate::formatter;
 use crate::game::Game;
-use crate::platform::get_platform;
+use crate::platform;
+use sdl2::pixels::PixelFormatEnum;
+use sdl2::render::RendererInfo;
+use sdl2::{AudioSubsystem, Sdl};
+use tracing::debug;
 
+/// Main application wrapper that manages SDL initialization, window lifecycle, and the game loop.
 pub struct App {
-    game: Game,
-    canvas: Canvas<Window>,
-    event_pump: &'static mut EventPump,
-    backbuffer: Texture<'static>,
-    paused: bool,
+    pub game: Game,
     last_tick: Instant,
-    cursor_pos: Vec2,
+    focused: bool,
+    // Keep SDL alive for the app lifetime so subsystems (audio) are not shut down
+    _sdl_context: Sdl,
+    _audio_subsystem: AudioSubsystem,
 }
 
 impl App {
+    /// Initializes SDL subsystems, creates the game window, and sets up the game state.
+    ///
+    /// # Errors
+    ///
+    /// Returns `GameError::Sdl` if any SDL initialization step fails, or propagates
+    /// errors from `Game::new()` during game state setup.
     pub fn new() -> GameResult<Self> {
-        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 ttf_context = sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let video_subsystem = sdl_context.video().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let audio_subsystem = sdl_context.audio().map_err(|e| GameError::Sdl(e.to_string()))?;
+        let event_pump = sdl_context.event_pump().map_err(|e| GameError::Sdl(e.to_string()))?;
 
         let window = video_subsystem
             .window(
@@ -51,114 +47,97 @@ 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()))?;
+        #[derive(Debug)]
+        struct DriverDetail {
+            info: RendererInfo,
+            index: usize,
+        }
+
+        let drivers: HashMap<&'static str, DriverDetail> = sdl2::render::drivers()
+            .enumerate()
+            .map(|(index, d)| (d.name, DriverDetail { info: d, index }))
+            .collect::<HashMap<_, _>>();
+
+        let get_driver =
+            |name: &'static str| -> Option<u32> { drivers.get(name.to_lowercase().as_str()).map(|d| d.index as u32) };
+
+        {
+            let mut names = drivers.keys().collect::<Vec<_>>();
+            names.sort_by_key(|k| get_driver(k));
+            debug!("Drivers: {names:?}")
+        }
+
+        // Count the number of times each pixel format is supported by each driver
+        let pixel_format_counts: HashMap<PixelFormatEnum, usize> = drivers
+            .values()
+            .flat_map(|d| d.info.texture_formats.iter())
+            .fold(HashMap::new(), |mut counts, format| {
+                *counts.entry(*format).or_insert(0) += 1;
+                counts
+            });
+
+        debug!("Pixel format counts: {pixel_format_counts:?}");
+
+        let index = get_driver("direct3d");
+        debug!("Driver index: {index:?}");
+
+        let mut canvas = window
+            .into_canvas()
+            .accelerated()
+            // .index(index)
+            .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()))?;
+        debug!("Renderer: {:?}", canvas.info());
 
-        let texture_creator: &'static TextureCreator<WindowContext> = Box::leak(Box::new(canvas.texture_creator()));
+        let texture_creator = canvas.texture_creator();
 
-        let mut game = Game::new(texture_creator)?;
-        // game.audio.set_mute(cfg!(debug_assertions));
+        let game = Game::new(canvas, ttf_context, texture_creator, event_pump)?;
 
-        let mut backbuffer = texture_creator
-            .create_texture_target(None, CANVAS_SIZE.x, CANVAS_SIZE.y)
-            .map_err(|e| GameError::Sdl(e.to_string()))?;
-        backbuffer.set_scale_mode(ScaleMode::Nearest);
-
-        // 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 {
+        Ok(App {
             game,
-            canvas,
-            event_pump,
-            backbuffer,
-            paused: false,
+            focused: true,
             last_tick: Instant::now(),
-            cursor_pos: Vec2::ZERO,
+            _sdl_context: sdl_context,
+            _audio_subsystem: audio_subsystem,
         })
     }
 
+    /// Executes a single frame of the game loop with consistent timing and optional sleep.
+    ///
+    /// Calculates delta time since the last frame, runs game logic via `game.tick()`,
+    /// and implements frame rate limiting by sleeping for remaining time if the frame
+    /// completed faster than the target `LOOP_TIME`. Sleep behavior varies based on
+    /// window focus to conserve CPU when the game is not active.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the game should continue running, `false` if the game requested exit.
     pub fn run(&mut self) -> bool {
         {
             let start = Instant::now();
 
-            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.toggle_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();
+            self.last_tick = start;
 
-            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);
-                }
+            // Increment the global tick counter for tracing
+            formatter::increment_tick();
+
+            let exit = self.game.tick(dt);
+
+            if exit {
+                return false;
             }
 
+            // Sleep if we still have time left
             if start.elapsed() < LOOP_TIME {
                 let time = LOOP_TIME.saturating_sub(start.elapsed());
                 if time != Duration::ZERO {
-                    get_platform().sleep(time);
+                    platform::sleep(time, self.focused);
                 }
-            } else {
-                event!(
-                    tracing::Level::WARN,
-                    "Game loop behind schedule by: {:?}",
-                    start.elapsed() - LOOP_TIME
-                );
             }
 
             true

src/asset.rs

@@ -5,18 +5,30 @@
 use std::borrow::Cow;
 use strum_macros::EnumIter;
 
+/// 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)]
 pub enum Asset {
     Wav1,
     Wav2,
     Wav3,
     Wav4,
-    Atlas,
-    AtlasJson,
-    // Add more as needed
+    /// Main sprite atlas containing all game graphics (atlas.png)
+    AtlasImage,
+    /// Terminal Vector font for text rendering (TerminalVector.ttf)
+    Font,
+    /// Sound effect for Pac-Man's death
+    DeathSound,
 }
 
 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::*;
@@ -25,8 +37,9 @@ impl Asset {
             Wav2 => "sound/waka/2.ogg",
             Wav3 => "sound/waka/3.ogg",
             Wav4 => "sound/waka/4.ogg",
-            Atlas => "atlas.png",
-            AtlasJson => "atlas.json",
+            AtlasImage => "atlas.png",
+            Font => "TerminalVector.ttf",
+            DeathSound => "sound/pacman_death.wav",
         }
     }
 }
@@ -34,10 +47,21 @@ impl Asset {
 mod imp {
     use super::*;
     use crate::error::AssetError;
-    use crate::platform::get_platform;
+    use crate::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)
+        platform::get_asset_bytes(asset)
     }
 }
 

src/audio.rs

@@ -16,6 +16,7 @@ const SOUND_ASSETS: [Asset; 4] = [Asset::Wav1, Asset::Wav2, Asset::Wav3, Asset::
 pub struct Audio {
     _mixer_context: Option<mixer::Sdl2MixerContext>,
     sounds: Vec<Chunk>,
+    death_sound: Option<Chunk>,
     next_sound_index: usize,
     muted: bool,
     disabled: bool,
@@ -44,6 +45,7 @@ impl Audio {
             return Self {
                 _mixer_context: None,
                 sounds: Vec::new(),
+                death_sound: None,
                 next_sound_index: 0,
                 muted: false,
                 disabled: true,
@@ -65,6 +67,7 @@ impl Audio {
                 return Self {
                     _mixer_context: None,
                     sounds: Vec::new(),
+                    death_sound: None,
                     next_sound_index: 0,
                     muted: false,
                     disabled: true,
@@ -93,12 +96,33 @@ impl Audio {
             }
         }
 
+        let death_sound = match get_asset_bytes(Asset::DeathSound) {
+            Ok(data) => match RWops::from_bytes(&data) {
+                Ok(rwops) => match rwops.load_wav() {
+                    Ok(chunk) => Some(chunk),
+                    Err(e) => {
+                        tracing::warn!("Failed to load death sound from asset API: {}", e);
+                        None
+                    }
+                },
+                Err(e) => {
+                    tracing::warn!("Failed to create RWops for death sound: {}", e);
+                    None
+                }
+            },
+            Err(e) => {
+                tracing::warn!("Failed to load death sound asset: {}", e);
+                None
+            }
+        };
+
         // If no sounds loaded successfully, disable audio
-        if sounds.is_empty() {
+        if sounds.is_empty() && death_sound.is_none() {
             tracing::warn!("No sounds loaded successfully. Audio will be disabled.");
             return Self {
                 _mixer_context: Some(mixer_context),
                 sounds: Vec::new(),
+                death_sound: None,
                 next_sound_index: 0,
                 muted: false,
                 disabled: true,
@@ -108,15 +132,18 @@ impl Audio {
         Audio {
             _mixer_context: Some(mixer_context),
             sounds,
+            death_sound,
             next_sound_index: 0,
             muted: false,
             disabled: false,
         }
     }
 
-    /// Plays the "eat" sound effect.
+    /// Plays the next waka eating sound in the cycle of four variants.
     ///
-    /// If audio is disabled or muted, this function does nothing.
+    /// 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.
     #[allow(dead_code)]
     pub fn eat(&mut self) {
         if self.disabled || self.muted || self.sounds.is_empty() {
@@ -136,9 +163,29 @@ impl Audio {
         self.next_sound_index = (self.next_sound_index + 1) % self.sounds.len();
     }
 
-    /// Instantly mute or unmute all channels.
+    /// Plays the death sound effect.
+    pub fn death(&mut self) {
+        if self.disabled || self.muted {
+            return;
+        }
+
+        if let Some(chunk) = &self.death_sound {
+            mixer::Channel::all().play(chunk, 0).ok();
+        }
+    }
+
+    /// Halts all currently playing audio channels.
+    pub fn stop_all(&mut self) {
+        if !self.disabled {
+            mixer::Channel::all().halt();
+        }
+    }
+
+    /// Instantly mutes or unmutes all audio channels by adjusting their volume.
     ///
-    /// If audio is disabled, this function does nothing.
+    /// Sets all 4 mixer channels to zero volume when muting, or restores them to
+    /// their default volume (32) when unmuting. The mute state is tracked internally
+    /// regardless of whether audio is disabled, allowing the state to be preserved.
     pub fn set_mute(&mut self, mute: bool) {
         if !self.disabled {
             let channels = 4;
@@ -151,12 +198,19 @@ impl Audio {
         self.muted = mute;
     }
 
-    /// Returns `true` if the audio is muted.
+    /// Returns the current mute state regardless of whether audio is functional.
+    ///
+    /// This tracks the user's mute preference and will return `true` if muted
+    /// even when the audio system is disabled due to initialization failures.
     pub fn is_muted(&self) -> bool {
         self.muted
     }
 
-    /// Returns `true` if the audio system is disabled.
+    /// 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.
     #[allow(dead_code)]
     pub fn is_disabled(&self) -> bool {
         self.disabled

src/bin/aspect_demo.rs

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

src/bin/timing_demo.rs

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

src/constants.rs

@@ -4,7 +4,12 @@ use std::time::Duration;
 
 use glam::UVec2;
 
-pub const LOOP_TIME: Duration = Duration::from_nanos((1_000_000_000.0 / 60.0) as u64);
+/// Target frame duration for 60 FPS game loop timing.
+///
+/// Calculated as 1/60th of a second (≈16.67ms).
+///
+/// Uses integer arithmetic to avoid floating-point precision loss.
+pub const LOOP_TIME: Duration = Duration::from_nanos(1_000_000_000 / 60);
 
 /// The size of each cell, in pixels.
 pub const CELL_SIZE: u32 = 8;
@@ -14,32 +19,81 @@ pub const BOARD_CELL_SIZE: UVec2 = UVec2::new(28, 31);
 /// The scale factor for the window (integer zoom)
 pub const SCALE: f32 = 2.6;
 
-/// The offset of the game board from the top-left corner of the window, in cells.
+/// Game board offset from window origin to reserve space for HUD elements.
+///
+/// The 3-cell vertical offset (24 pixels) provides space at the top of the
+/// screen for score display, player lives, and other UI elements.
 pub const BOARD_CELL_OFFSET: UVec2 = UVec2::new(0, 3);
-/// The offset of the game board from the top-left corner of the window, in pixels.
+
+/// Pixel-space equivalent of `BOARD_CELL_OFFSET` for rendering calculations.
+///
+/// Automatically calculated from the cell offset to maintain consistency
+/// when the cell size changes. Used for positioning sprites and debug overlays.
 pub const BOARD_PIXEL_OFFSET: UVec2 = UVec2::new(BOARD_CELL_OFFSET.x * CELL_SIZE, BOARD_CELL_OFFSET.y * CELL_SIZE);
+
+/// Animation timing constants for ghost state management
+pub mod animation {
+    /// Normal ghost movement animation speed (ticks per frame at 60 ticks/sec)
+    pub const GHOST_NORMAL_SPEED: u16 = 12;
+    /// Eaten ghost (eyes) animation speed (ticks per frame at 60 ticks/sec)
+    pub const GHOST_EATEN_SPEED: u16 = 6;
+    /// Frightened ghost animation speed (ticks per frame at 60 ticks/sec)
+    pub const GHOST_FRIGHTENED_SPEED: u16 = 12;
+
+    /// Time in ticks when frightened ghosts start flashing (2 seconds at 60 FPS)
+    pub const FRIGHTENED_FLASH_START_TICKS: u32 = 120;
+}
 /// 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,
 );
 
-/// An enum representing the different types of tiles on the map.
+pub const LARGE_SCALE: f32 = 2.6;
+
+pub const LARGE_CANVAS_SIZE: UVec2 = UVec2::new(
+    (((BOARD_CELL_SIZE.x + BOARD_CELL_OFFSET.x) * CELL_SIZE) as f32 * LARGE_SCALE) as u32,
+    (((BOARD_CELL_SIZE.y + BOARD_CELL_OFFSET.y) * CELL_SIZE) as f32 * LARGE_SCALE) as u32,
+);
+
+/// Collider size constants for different entity types
+pub mod collider {
+    use super::CELL_SIZE;
+
+    /// Collider size for player and ghosts (1.375x cell size)
+    pub const PLAYER_GHOST_SIZE: f32 = CELL_SIZE as f32 * 1.375;
+    /// Collider size for pellets (0.4x cell size)
+    pub const PELLET_SIZE: f32 = CELL_SIZE as f32 * 0.4;
+    /// Collider size for power pellets/energizers (0.95x cell size)
+    pub const POWER_PELLET_SIZE: f32 = CELL_SIZE as f32 * 0.95;
+}
+
+/// UI and rendering constants
+pub mod ui {
+    /// Debug font size in points
+    pub const DEBUG_FONT_SIZE: u16 = 12;
+    /// Power pellet blink rate in ticks (at 60 FPS, 12 ticks = 0.2 seconds)
+    pub const POWER_PELLET_BLINK_RATE: u32 = 12;
+}
+
+/// Map tile types that define gameplay behavior and collision properties.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum MapTile {
-    /// An empty tile.
+    /// Traversable space with no collectible items
     Empty,
-    /// A wall tile.
     Wall,
-    /// A regular pellet.
+    /// Small collectible. Implicitly a traversable tile.
     Pellet,
-    /// A power pellet.
+    /// Large collectible. Implicitly a traversable tile.
     PowerPellet,
-    /// A tunnel tile.
+    /// Special traversable tile that connects to tunnel portals.
     Tunnel,
 }
 
-/// The raw layout of the game board, as a 2D array of characters.
+/// ASCII art representation of the classic Pac-Man maze layout.
+///
+/// Uses character symbols to define the game world. This layout is parsed by `MapTileParser`
+/// to generate the navigable graph and collision geometry.
 pub const RAW_BOARD: [&str; BOARD_CELL_SIZE.y as usize] = [
     "############################",
     "#............##............#",
@@ -73,3 +127,15 @@ pub const RAW_BOARD: [&str; BOARD_CELL_SIZE.y as usize] = [
     "#..........................#",
     "############################",
 ];
+
+/// Game initialization constants
+pub mod startup {
+    /// Number of frames for the startup sequence (3 seconds at 60 FPS)
+    pub const STARTUP_FRAMES: u32 = 60 * 3;
+}
+
+/// Game mechanics constants
+pub mod mechanics {
+    /// Player movement speed multiplier
+    pub const PLAYER_SPEED: f32 = 1.15;
+}

src/entity/collision.rs

@@ -1,128 +0,0 @@
-use smallvec::SmallVec;
-use std::collections::HashMap;
-
-use crate::entity::{graph::NodeId, traversal::Position};
-
-/// Trait for entities that can participate in collision detection.
-pub trait Collidable {
-    /// Returns the current position of this entity.
-    fn position(&self) -> Position;
-
-    /// Checks if this entity is colliding with another entity.
-    #[allow(dead_code)]
-    fn is_colliding_with(&self, other: &dyn Collidable) -> bool {
-        positions_overlap(&self.position(), &other.position())
-    }
-}
-
-/// System for tracking entities by their positions for efficient collision detection.
-#[derive(Default)]
-pub struct CollisionSystem {
-    /// Maps node IDs to lists of entity IDs that are at that node
-    node_entities: HashMap<NodeId, Vec<EntityId>>,
-    /// Maps entity IDs to their current positions
-    entity_positions: HashMap<EntityId, Position>,
-    /// Next available entity ID
-    next_id: EntityId,
-}
-
-/// Unique identifier for an entity in the collision system
-pub type EntityId = u32;
-
-impl CollisionSystem {
-    /// Registers an entity with the collision system and returns its ID
-    pub fn register_entity(&mut self, position: Position) -> EntityId {
-        let id = self.next_id;
-        self.next_id += 1;
-
-        self.entity_positions.insert(id, position);
-        self.update_node_entities(id, position);
-
-        id
-    }
-
-    /// Updates an entity's position
-    pub fn update_position(&mut self, entity_id: EntityId, new_position: Position) {
-        if let Some(old_position) = self.entity_positions.get(&entity_id) {
-            // Remove from old nodes
-            self.remove_from_nodes(entity_id, *old_position);
-        }
-
-        // Update position and add to new nodes
-        self.entity_positions.insert(entity_id, new_position);
-        self.update_node_entities(entity_id, new_position);
-    }
-
-    /// Removes an entity from the collision system
-    #[allow(dead_code)]
-    pub fn remove_entity(&mut self, entity_id: EntityId) {
-        if let Some(position) = self.entity_positions.remove(&entity_id) {
-            self.remove_from_nodes(entity_id, position);
-        }
-    }
-
-    /// Gets all entity IDs at a specific node
-    pub fn entities_at_node(&self, node: NodeId) -> &[EntityId] {
-        self.node_entities.get(&node).map(|v| v.as_slice()).unwrap_or(&[])
-    }
-
-    /// Gets all entity IDs that could collide with an entity at the given position
-    pub fn potential_collisions(&self, position: &Position) -> Vec<EntityId> {
-        let mut collisions = Vec::new();
-        let nodes = get_nodes(position);
-
-        for node in nodes {
-            collisions.extend(self.entities_at_node(node));
-        }
-
-        // Remove duplicates
-        collisions.sort_unstable();
-        collisions.dedup();
-        collisions
-    }
-
-    /// Updates the node_entities map when an entity's position changes
-    fn update_node_entities(&mut self, entity_id: EntityId, position: Position) {
-        let nodes = get_nodes(&position);
-        for node in nodes {
-            self.node_entities.entry(node).or_default().push(entity_id);
-        }
-    }
-
-    /// Removes an entity from all nodes it was previously at
-    fn remove_from_nodes(&mut self, entity_id: EntityId, position: Position) {
-        let nodes = get_nodes(&position);
-        for node in nodes {
-            if let Some(entities) = self.node_entities.get_mut(&node) {
-                entities.retain(|&id| id != entity_id);
-                if entities.is_empty() {
-                    self.node_entities.remove(&node);
-                }
-            }
-        }
-    }
-}
-
-/// Checks if two positions overlap (entities are at the same location).
-fn positions_overlap(a: &Position, b: &Position) -> bool {
-    let a_nodes = get_nodes(a);
-    let b_nodes = get_nodes(b);
-
-    // Check if any nodes overlap
-    a_nodes.iter().any(|a_node| b_nodes.contains(a_node))
-
-    // TODO: More complex overlap detection, the above is a simple check, but it could become an early filter for more precise calculations later
-}
-
-/// Gets all nodes that an entity is currently at or between.
-fn get_nodes(pos: &Position) -> SmallVec<[NodeId; 2]> {
-    let mut nodes = SmallVec::new();
-    match pos {
-        Position::AtNode(node) => nodes.push(*node),
-        Position::BetweenNodes { from, to, .. } => {
-            nodes.push(*from);
-            nodes.push(*to);
-        }
-    }
-    nodes
-}

src/entity/ghost.rs

@@ -1,254 +0,0 @@
-//! Ghost entity implementation.
-//!
-//! This module contains the ghost character logic, including movement,
-//! animation, and rendering. Ghosts move through the game graph using
-//! a traverser and display directional animated textures.
-
-use pathfinding::prelude::dijkstra;
-use rand::prelude::*;
-use smallvec::SmallVec;
-use tracing::error;
-
-use crate::entity::{
-    collision::Collidable,
-    direction::Direction,
-    graph::{Edge, EdgePermissions, Graph, NodeId},
-    r#trait::Entity,
-    traversal::Traverser,
-};
-use crate::texture::animated::AnimatedTexture;
-use crate::texture::directional::DirectionalAnimatedTexture;
-use crate::texture::sprite::SpriteAtlas;
-
-use crate::error::{EntityError, GameError, GameResult, TextureError};
-
-/// Determines if a ghost can traverse a given edge.
-///
-/// Ghosts can move through edges that allow all entities or ghost-only edges.
-fn can_ghost_traverse(edge: Edge) -> bool {
-    matches!(edge.permissions, EdgePermissions::All | EdgePermissions::GhostsOnly)
-}
-
-/// The four classic ghost types.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum GhostType {
-    Blinky,
-    Pinky,
-    Inky,
-    Clyde,
-}
-
-impl GhostType {
-    /// Returns the ghost type name for atlas lookups.
-    pub fn as_str(self) -> &'static str {
-        match self {
-            GhostType::Blinky => "blinky",
-            GhostType::Pinky => "pinky",
-            GhostType::Inky => "inky",
-            GhostType::Clyde => "clyde",
-        }
-    }
-
-    /// Returns the base movement speed for this ghost type.
-    pub fn base_speed(self) -> f32 {
-        match self {
-            GhostType::Blinky => 1.0,
-            GhostType::Pinky => 0.95,
-            GhostType::Inky => 0.9,
-            GhostType::Clyde => 0.85,
-        }
-    }
-}
-
-/// A ghost entity that roams the game world.
-///
-/// Ghosts move through the game world using a graph-based navigation system
-/// and display directional animated sprites. They randomly choose directions
-/// at each intersection.
-pub struct Ghost {
-    /// Handles movement through the game graph
-    pub traverser: Traverser,
-    /// The type of ghost (affects appearance and speed)
-    pub ghost_type: GhostType,
-    /// Manages directional animated textures for different movement states
-    texture: DirectionalAnimatedTexture,
-    /// Current movement speed
-    speed: f32,
-}
-
-impl Entity for Ghost {
-    fn traverser(&self) -> &Traverser {
-        &self.traverser
-    }
-
-    fn traverser_mut(&mut self) -> &mut Traverser {
-        &mut self.traverser
-    }
-
-    fn texture(&self) -> &DirectionalAnimatedTexture {
-        &self.texture
-    }
-
-    fn texture_mut(&mut self) -> &mut DirectionalAnimatedTexture {
-        &mut self.texture
-    }
-
-    fn speed(&self) -> f32 {
-        self.speed
-    }
-
-    fn can_traverse(&self, edge: Edge) -> bool {
-        can_ghost_traverse(edge)
-    }
-
-    fn tick(&mut self, dt: f32, graph: &Graph) {
-        // Choose random direction when at a node
-        if self.traverser.position.is_at_node() {
-            self.choose_random_direction(graph);
-        }
-
-        if let Err(e) = self.traverser.advance(graph, dt * 60.0 * self.speed, &can_ghost_traverse) {
-            error!("Ghost movement error: {}", e);
-        }
-        self.texture.tick(dt);
-    }
-}
-
-impl Ghost {
-    /// Creates a new ghost instance at the specified starting node.
-    ///
-    /// Sets up animated textures for all four directions with moving and stopped states.
-    /// The moving animation cycles through two sprite variants.
-    pub fn new(graph: &Graph, start_node: NodeId, ghost_type: GhostType, atlas: &SpriteAtlas) -> GameResult<Self> {
-        let mut textures = [None, None, None, None];
-        let mut stopped_textures = [None, None, None, None];
-
-        for direction in Direction::DIRECTIONS {
-            let moving_prefix = match direction {
-                Direction::Up => "up",
-                Direction::Down => "down",
-                Direction::Left => "left",
-                Direction::Right => "right",
-            };
-            let moving_tiles = vec![
-                SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "a"))
-                    .ok_or_else(|| {
-                        GameError::Texture(TextureError::AtlasTileNotFound(format!(
-                            "ghost/{}/{}_{}.png",
-                            ghost_type.as_str(),
-                            moving_prefix,
-                            "a"
-                        )))
-                    })?,
-                SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "b"))
-                    .ok_or_else(|| {
-                        GameError::Texture(TextureError::AtlasTileNotFound(format!(
-                            "ghost/{}/{}_{}.png",
-                            ghost_type.as_str(),
-                            moving_prefix,
-                            "b"
-                        )))
-                    })?,
-            ];
-
-            let stopped_tiles =
-                vec![
-                    SpriteAtlas::get_tile(atlas, &format!("ghost/{}/{}_{}.png", ghost_type.as_str(), moving_prefix, "a"))
-                        .ok_or_else(|| {
-                            GameError::Texture(TextureError::AtlasTileNotFound(format!(
-                                "ghost/{}/{}_{}.png",
-                                ghost_type.as_str(),
-                                moving_prefix,
-                                "a"
-                            )))
-                        })?,
-                ];
-
-            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 {
-            traverser: Traverser::new(graph, start_node, Direction::Left, &can_ghost_traverse),
-            ghost_type,
-            texture: DirectionalAnimatedTexture::new(textures, stopped_textures),
-            speed: ghost_type.base_speed(),
-        })
-    }
-
-    /// Chooses a random available direction at the current intersection.
-    fn choose_random_direction(&mut self, graph: &Graph) {
-        let current_node = self.traverser.position.from_node_id();
-        let intersection = &graph.adjacency_list[current_node];
-
-        // Collect all available directions
-        let mut available_directions = SmallVec::<[_; 4]>::new();
-        for direction in Direction::DIRECTIONS {
-            if let Some(edge) = intersection.get(direction) {
-                if can_ghost_traverse(edge) {
-                    available_directions.push(direction);
-                }
-            }
-        }
-        // Choose a random direction (avoid reversing unless necessary)
-        if !available_directions.is_empty() {
-            let mut rng = SmallRng::from_os_rng();
-
-            // Filter out the opposite direction if possible, but allow it if we have limited options
-            let opposite = self.traverser.direction.opposite();
-            let filtered_directions: Vec<_> = available_directions
-                .iter()
-                .filter(|&&dir| dir != opposite || available_directions.len() <= 2)
-                .collect();
-
-            if let Some(&random_direction) = filtered_directions.choose(&mut rng) {
-                self.traverser.set_next_direction(*random_direction);
-            }
-        }
-    }
-
-    /// Calculates the shortest path from the ghost's current position to a target node using Dijkstra's algorithm.
-    ///
-    /// Returns a vector of NodeIds representing the path, or an error if pathfinding fails.
-    /// The path includes the current node and the target node.
-    pub fn calculate_path_to_target(&self, graph: &Graph, target: NodeId) -> GameResult<Vec<NodeId>> {
-        let start_node = self.traverser.position.from_node_id();
-
-        // Use Dijkstra's algorithm to find the shortest path
-        let result = dijkstra(
-            &start_node,
-            |&node_id| {
-                // Get all edges from the current node
-                graph.adjacency_list[node_id]
-                    .edges()
-                    .filter(|edge| can_ghost_traverse(*edge))
-                    .map(|edge| (edge.target, (edge.distance * 100.0) as u32))
-                    .collect::<Vec<_>>()
-            },
-            |&node_id| node_id == target,
-        );
-
-        result.map(|(path, _cost)| path).ok_or_else(|| {
-            GameError::Entity(EntityError::PathfindingFailed(format!(
-                "No path found from node {} to target {}",
-                start_node, target
-            )))
-        })
-    }
-
-    /// Returns the ghost's color for debug rendering.
-    pub fn debug_color(&self) -> sdl2::pixels::Color {
-        match self.ghost_type {
-            GhostType::Blinky => sdl2::pixels::Color::RGB(255, 0, 0),    // Red
-            GhostType::Pinky => sdl2::pixels::Color::RGB(255, 182, 255), // Pink
-            GhostType::Inky => sdl2::pixels::Color::RGB(0, 255, 255),    // Cyan
-            GhostType::Clyde => sdl2::pixels::Color::RGB(255, 182, 85),  // Orange
-        }
-    }
-}
-
-impl Collidable for Ghost {
-    fn position(&self) -> crate::entity::traversal::Position {
-        self.traverser.position
-    }
-}

src/entity/item.rs

@@ -1,117 +0,0 @@
-use crate::{
-    constants,
-    entity::{collision::Collidable, graph::Graph},
-    error::{EntityError, GameResult},
-    texture::sprite::{Sprite, SpriteAtlas},
-};
-use sdl2::render::{Canvas, RenderTarget};
-use strum_macros::{EnumCount, EnumIter};
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum ItemType {
-    Pellet,
-    Energizer,
-    #[allow(dead_code)]
-    Fruit {
-        kind: FruitKind,
-    },
-}
-
-impl ItemType {
-    pub fn get_score(self) -> u32 {
-        match self {
-            ItemType::Pellet => 10,
-            ItemType::Energizer => 50,
-            ItemType::Fruit { kind } => kind.get_score(),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, EnumIter, EnumCount)]
-#[allow(dead_code)]
-pub enum FruitKind {
-    Apple,
-    Strawberry,
-    Orange,
-    Melon,
-    Bell,
-    Key,
-    Galaxian,
-}
-
-impl FruitKind {
-    #[allow(dead_code)]
-    pub fn index(self) -> u8 {
-        match self {
-            FruitKind::Apple => 0,
-            FruitKind::Strawberry => 1,
-            FruitKind::Orange => 2,
-            FruitKind::Melon => 3,
-            FruitKind::Bell => 4,
-            FruitKind::Key => 5,
-            FruitKind::Galaxian => 6,
-        }
-    }
-
-    pub fn get_score(self) -> u32 {
-        match self {
-            FruitKind::Apple => 100,
-            FruitKind::Strawberry => 300,
-            FruitKind::Orange => 500,
-            FruitKind::Melon => 700,
-            FruitKind::Bell => 1000,
-            FruitKind::Key => 2000,
-            FruitKind::Galaxian => 3000,
-        }
-    }
-}
-
-pub struct Item {
-    pub node_index: usize,
-    pub item_type: ItemType,
-    pub sprite: Sprite,
-    pub collected: bool,
-}
-
-impl Item {
-    pub fn new(node_index: usize, item_type: ItemType, sprite: Sprite) -> Self {
-        Self {
-            node_index,
-            item_type,
-            sprite,
-            collected: false,
-        }
-    }
-
-    pub fn is_collected(&self) -> bool {
-        self.collected
-    }
-
-    pub fn collect(&mut self) {
-        self.collected = true;
-    }
-
-    pub fn get_score(&self) -> u32 {
-        self.item_type.get_score()
-    }
-
-    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(())
-    }
-}
-
-impl Collidable for Item {
-    fn position(&self) -> crate::entity::traversal::Position {
-        crate::entity::traversal::Position::AtNode(self.node_index)
-    }
-}

src/entity/mod.rs

@@ -1,8 +0,0 @@
-pub mod collision;
-pub mod direction;
-pub mod ghost;
-pub mod graph;
-pub mod item;
-pub mod pacman;
-pub mod r#trait;
-pub mod traversal;

src/entity/pacman.rs

@@ -1,134 +0,0 @@
-//! Pac-Man entity implementation.
-//!
-//! This module contains the main player character logic, including movement,
-//! animation, and rendering. Pac-Man moves through the game graph using
-//! a traverser and displays directional animated textures.
-
-use crate::entity::{
-    collision::Collidable,
-    direction::Direction,
-    graph::{Edge, EdgePermissions, Graph, NodeId},
-    r#trait::Entity,
-    traversal::Traverser,
-};
-use crate::texture::animated::AnimatedTexture;
-use crate::texture::directional::DirectionalAnimatedTexture;
-use crate::texture::sprite::SpriteAtlas;
-use sdl2::keyboard::Keycode;
-use tracing::error;
-
-use crate::error::{GameError, GameResult, TextureError};
-
-/// Determines if Pac-Man can traverse a given edge.
-///
-/// Pac-Man can only move through edges that allow all entities.
-fn can_pacman_traverse(edge: Edge) -> bool {
-    matches!(edge.permissions, EdgePermissions::All)
-}
-
-/// The main player character entity.
-///
-/// Pac-Man moves through the game world using a graph-based navigation system
-/// and displays directional animated sprites based on movement state.
-pub struct Pacman {
-    /// Handles movement through the game graph
-    pub traverser: Traverser,
-    /// Manages directional animated textures for different movement states
-    texture: DirectionalAnimatedTexture,
-}
-
-impl Entity for Pacman {
-    fn traverser(&self) -> &Traverser {
-        &self.traverser
-    }
-
-    fn traverser_mut(&mut self) -> &mut Traverser {
-        &mut self.traverser
-    }
-
-    fn texture(&self) -> &DirectionalAnimatedTexture {
-        &self.texture
-    }
-
-    fn texture_mut(&mut self) -> &mut DirectionalAnimatedTexture {
-        &mut self.texture
-    }
-
-    fn speed(&self) -> f32 {
-        1.125
-    }
-
-    fn can_traverse(&self, edge: Edge) -> bool {
-        can_pacman_traverse(edge)
-    }
-
-    fn tick(&mut self, dt: f32, graph: &Graph) {
-        if let Err(e) = self.traverser.advance(graph, dt * 60.0 * 1.125, &can_pacman_traverse) {
-            error!("Pac-Man movement error: {}", e);
-        }
-        self.texture.tick(dt);
-    }
-}
-
-impl Pacman {
-    /// Creates a new Pac-Man instance at the specified starting node.
-    ///
-    /// Sets up animated textures for all four directions with moving and stopped states.
-    /// The moving animation cycles through open mouth, closed mouth, and full sprites.
-    pub fn new(graph: &Graph, start_node: NodeId, atlas: &SpriteAtlas) -> GameResult<Self> {
-        let mut textures = [None, None, None, None];
-        let mut stopped_textures = [None, None, None, None];
-
-        for direction in Direction::DIRECTIONS {
-            let moving_prefix = match direction {
-                Direction::Up => "pacman/up",
-                Direction::Down => "pacman/down",
-                Direction::Left => "pacman/left",
-                Direction::Right => "pacman/right",
-            };
-            let moving_tiles = vec![
-                SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_a.png"))
-                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_a.png"))))?,
-                SpriteAtlas::get_tile(atlas, &format!("{moving_prefix}_b.png"))
-                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound(format!("{moving_prefix}_b.png"))))?,
-                SpriteAtlas::get_tile(atlas, "pacman/full.png")
-                    .ok_or_else(|| GameError::Texture(TextureError::AtlasTileNotFound("pacman/full.png".to_string())))?,
-            ];
-
-            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)?);
-            stopped_textures[direction.as_usize()] = Some(AnimatedTexture::new(stopped_tiles, 0.1)?);
-        }
-
-        Ok(Self {
-            traverser: Traverser::new(graph, start_node, Direction::Left, &can_pacman_traverse),
-            texture: DirectionalAnimatedTexture::new(textures, stopped_textures),
-        })
-    }
-
-    /// Handles keyboard input to change Pac-Man's direction.
-    ///
-    /// Maps arrow keys to directions and queues the direction change
-    /// for the next valid intersection.
-    pub fn handle_key(&mut self, keycode: Keycode) {
-        let direction = match keycode {
-            Keycode::Up => Some(Direction::Up),
-            Keycode::Down => Some(Direction::Down),
-            Keycode::Left => Some(Direction::Left),
-            Keycode::Right => Some(Direction::Right),
-            _ => None,
-        };
-
-        if let Some(direction) = direction {
-            self.traverser.set_next_direction(direction);
-        }
-    }
-}
-
-impl Collidable for Pacman {
-    fn position(&self) -> crate::entity::traversal::Position {
-        self.traverser.position
-    }
-}

src/entity/trait.rs

@@ -1,114 +0,0 @@
-//! Entity trait for common movement and rendering functionality.
-//!
-//! This module defines a trait that captures the shared behavior between
-//! different game entities like Ghosts and Pac-Man, including movement,
-//! rendering, and position calculations.
-
-use glam::Vec2;
-use sdl2::render::{Canvas, RenderTarget};
-
-use crate::entity::direction::Direction;
-use crate::entity::graph::{Edge, Graph, NodeId};
-use crate::entity::traversal::{Position, Traverser};
-use crate::error::{EntityError, GameError, GameResult, TextureError};
-use crate::texture::directional::DirectionalAnimatedTexture;
-use crate::texture::sprite::SpriteAtlas;
-
-/// Trait defining common functionality for game entities that move through the graph.
-///
-/// This trait provides a unified interface for entities that:
-/// - Move through the game graph using a traverser
-/// - Render using directional animated textures
-/// - Have position calculations and movement speed
-#[allow(dead_code)]
-pub trait Entity {
-    /// Returns a reference to the entity's traverser for movement control.
-    fn traverser(&self) -> &Traverser;
-
-    /// Returns a mutable reference to the entity's traverser for movement control.
-    fn traverser_mut(&mut self) -> &mut Traverser;
-
-    /// Returns a reference to the entity's directional animated texture.
-    fn texture(&self) -> &DirectionalAnimatedTexture;
-
-    /// Returns a mutable reference to the entity's directional animated texture.
-    fn texture_mut(&mut self) -> &mut DirectionalAnimatedTexture;
-
-    /// Returns the movement speed multiplier for this entity.
-    fn speed(&self) -> f32;
-
-    /// Determines if this entity can traverse a given edge.
-    fn can_traverse(&self, edge: Edge) -> bool;
-
-    /// Updates the entity's position and animation state.
-    ///
-    /// This method advances movement through the graph and updates texture animation.
-    fn tick(&mut self, dt: f32, graph: &Graph);
-
-    /// 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.
-    fn get_pixel_pos(&self, graph: &Graph) -> GameResult<Vec2> {
-        let pos = match self.traverser().position {
-            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, 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,
-        ))
-    }
-
-    /// Returns the current node ID that the entity is at or moving towards.
-    ///
-    /// If the entity is at a node, returns that node ID.
-    /// If the entity is between nodes, returns the node it's moving towards.
-    fn current_node_id(&self) -> NodeId {
-        match self.traverser().position {
-            Position::AtNode(node_id) => node_id,
-            Position::BetweenNodes { to, .. } => to,
-        }
-    }
-
-    /// Sets the next direction for the entity to take.
-    ///
-    /// The direction is buffered and will be applied at the next opportunity,
-    /// typically when the entity reaches a new node.
-    fn set_next_direction(&mut self, direction: Direction) {
-        self.traverser_mut().set_next_direction(direction);
-    }
-
-    /// Renders the entity at its current position.
-    ///
-    /// Draws the appropriate directional sprite based on the entity's
-    /// current movement state and direction.
-    fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, graph: &Graph) -> GameResult<()> {
-        let pixel_pos = self.get_pixel_pos(graph)?;
-        let dest = crate::helpers::centered_with_size(
-            glam::IVec2::new(pixel_pos.x as i32, pixel_pos.y as i32),
-            glam::UVec2::new(16, 16),
-        );
-
-        if self.traverser().position.is_stopped() {
-            self.texture()
-                .render_stopped(canvas, atlas, dest, self.traverser().direction)
-                .map_err(|e| GameError::Texture(TextureError::RenderFailed(e.to_string())))?;
-        } else {
-            self.texture()
-                .render(canvas, atlas, dest, self.traverser().direction)
-                .map_err(|e| GameError::Texture(TextureError::RenderFailed(e.to_string())))?;
-        }
-
-        Ok(())
-    }
-}

src/entity/traversal.rs

@@ -1,229 +0,0 @@
-use tracing::error;
-
-use crate::error::GameResult;
-
-use super::direction::Direction;
-use super::graph::{Edge, Graph, NodeId};
-
-/// 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(Debug, PartialEq, Clone, Copy)]
-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,
-    },
-}
-
-#[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(_))
-    }
-}
-
-/// Manages an entity's movement through the graph.
-///
-/// A `Traverser` encapsulates the state of an entity's position and direction,
-/// providing a way to advance along the graph's paths based on a given distance.
-/// It also handles direction changes, buffering the next intended direction.
-pub struct Traverser {
-    /// The current position of the traverser in the graph.
-    pub position: Position,
-    /// The current direction of movement.
-    pub direction: Direction,
-    /// Buffered direction change with remaining frame count for timing.
-    ///
-    /// The `u8` value represents the number of frames remaining before
-    /// the buffered direction expires. This allows for responsive controls
-    /// by storing direction changes for a limited time.
-    pub next_direction: Option<(Direction, u8)>,
-}
-
-impl Traverser {
-    /// Creates a new traverser starting at the given node ID.
-    ///
-    /// The traverser will immediately attempt to start moving in the initial direction.
-    pub fn new<F>(graph: &Graph, start_node: NodeId, initial_direction: Direction, can_traverse: &F) -> Self
-    where
-        F: Fn(Edge) -> bool,
-    {
-        let mut traverser = Traverser {
-            position: Position::AtNode(start_node),
-            direction: initial_direction,
-            next_direction: Some((initial_direction, 1)),
-        };
-
-        // This will kickstart the traverser into motion
-        if let Err(e) = traverser.advance(graph, 0.0, can_traverse) {
-            error!("Traverser initialization error: {}", e);
-        }
-
-        traverser
-    }
-
-    /// Sets the next direction for the traverser to take.
-    ///
-    /// The direction is buffered and will be applied at the next opportunity,
-    /// typically when the traverser reaches a new node. This allows for responsive
-    /// controls, as the new direction is stored for a limited time.
-    pub fn set_next_direction(&mut self, new_direction: Direction) {
-        if self.direction != new_direction {
-            self.next_direction = Some((new_direction, 30));
-        }
-    }
-
-    /// Advances the traverser along the graph by a specified distance.
-    ///
-    /// This method updates the traverser's position based on its current state
-    /// and the distance to travel.
-    ///
-    /// - If at a node, it checks for a buffered direction to start moving.
-    /// - If between nodes, it moves along the current edge.
-    /// - If it reaches a node, it attempts to transition to a new edge based on
-    ///   the buffered direction or by continuing straight.
-    /// - If no valid move is possible, it stops at the node.
-    ///
-    /// Returns an error if the movement is invalid (e.g., trying to move in an impossible direction).
-    pub fn advance<F>(&mut self, graph: &Graph, distance: f32, can_traverse: &F) -> GameResult<()>
-    where
-        F: Fn(Edge) -> bool,
-    {
-        // Decrement the remaining frames for the next direction
-        if let Some((direction, remaining)) = self.next_direction {
-            if remaining > 0 {
-                self.next_direction = Some((direction, remaining - 1));
-            } else {
-                self.next_direction = None;
-            }
-        }
-
-        match self.position {
-            Position::AtNode(node_id) => {
-                // We're not moving, but a buffered direction is available.
-                if let Some((next_direction, _)) = self.next_direction {
-                    if let Some(edge) = graph.find_edge_in_direction(node_id, next_direction) {
-                        if can_traverse(edge) {
-                            // Start moving in that direction
-                            self.position = Position::BetweenNodes {
-                                from: node_id,
-                                to: edge.target,
-                                traversed: distance.max(0.0),
-                            };
-                            self.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 {
-                        return Err(crate::error::GameError::Entity(crate::error::EntityError::InvalidMovement(
-                            format!("No edge found in direction {:?} from node {}", next_direction, node_id),
-                        )));
-                    }
-
-                    self.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 Ok(());
-                }
-
-                let edge = graph.find_edge(from, to).ok_or_else(|| {
-                    crate::error::GameError::Entity(crate::error::EntityError::InvalidMovement(format!(
-                        "Inconsistent state: Traverser is on a non-existent edge from {} to {}.",
-                        from, to
-                    )))
-                })?;
-
-                let new_traversed = traversed + distance;
-
-                if new_traversed < edge.distance {
-                    // Still on the same edge, just update the distance.
-                    self.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, _)) = self.next_direction {
-                        if let Some(edge) = graph.find_edge_in_direction(to, next_dir) {
-                            if can_traverse(edge) {
-                                self.position = Position::BetweenNodes {
-                                    from: to,
-                                    to: edge.target,
-                                    traversed: overflow,
-                                };
-
-                                self.direction = next_dir; // Remember our new direction
-                                self.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) = graph.find_edge_in_direction(to, self.direction) {
-                            if can_traverse(edge) {
-                                self.position = Position::BetweenNodes {
-                                    from: to,
-                                    to: edge.target,
-                                    traversed: overflow,
-                                };
-                            } else {
-                                self.position = Position::AtNode(to);
-                                self.next_direction = None;
-                            }
-                        } else {
-                            self.position = Position::AtNode(to);
-                            self.next_direction = None;
-                        }
-                    }
-                }
-            }
-        }
-
-        Ok(())
-    }
-}

src/error.rs

@@ -5,11 +5,13 @@
 
 use std::io;
 
+use bevy_ecs::event::Event;
+
 /// Main error type for the Pac-Man game.
 ///
 /// This is the primary error type that should be used in public APIs.
 /// It can represent any error that can occur during game operation.
-#[derive(thiserror::Error, Debug)]
+#[derive(thiserror::Error, Debug, Event)]
 pub enum GameError {
     #[error("Asset error: {0}")]
     Asset(#[from] AssetError),
@@ -29,18 +31,12 @@ pub enum GameError {
     #[error("Entity error: {0}")]
     Entity(#[from] EntityError),
 
-    #[error("Game state error: {0}")]
-    GameState(#[from] GameStateError),
-
     #[error("SDL error: {0}")]
     Sdl(String),
 
     #[error("IO error: {0}")]
     Io(#[from] io::Error),
 
-    #[error("Serialization error: {0}")]
-    Serialization(#[from] serde_json::Error),
-
     #[error("Invalid state: {0}")]
     InvalidState(String),
 }
@@ -49,6 +45,8 @@ pub enum GameError {
 pub enum AssetError {
     #[error("IO error: {0}")]
     Io(#[from] io::Error),
+
+    #[allow(dead_code)]
     #[error("Asset not found: {0}")]
     NotFound(String),
 }
@@ -77,9 +75,6 @@ pub enum ParseError {
 /// Errors related to texture operations.
 #[derive(thiserror::Error, Debug)]
 pub enum TextureError {
-    #[error("Animated texture error: {0}")]
-    Animated(#[from] AnimatedTextureError),
-
     #[error("Failed to load texture: {0}")]
     LoadFailed(String),
 
@@ -93,12 +88,6 @@ 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(thiserror::Error, Debug)]
 pub enum EntityError {
@@ -107,18 +96,8 @@ pub enum EntityError {
 
     #[error("Edge not found: from {from} to {to}")]
     EdgeNotFound { from: usize, to: usize },
-
-    #[error("Invalid movement: {0}")]
-    InvalidMovement(String),
-
-    #[error("Pathfinding failed: {0}")]
-    PathfindingFailed(String),
 }
 
-/// Errors related to game state operations.
-#[derive(thiserror::Error, Debug)]
-pub enum GameStateError {}
-
 /// Errors related to map operations.
 #[derive(thiserror::Error, Debug)]
 pub enum MapError {

src/events.rs

@@ -0,0 +1,42 @@
+use bevy_ecs::{entity::Entity, event::Event};
+
+use crate::map::direction::Direction;
+
+/// Player input commands that trigger specific game actions.
+///
+/// Commands are generated by the input system in response to keyboard events
+/// and processed by appropriate game systems to modify state or behavior.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum GameCommand {
+    /// Request immediate game shutdown
+    Exit,
+    /// Set Pac-Man's movement direction
+    MovePlayer(Direction),
+    /// Cycle through debug visualization modes
+    ToggleDebug,
+    /// Toggle audio mute state
+    MuteAudio,
+    /// Restart the current level with fresh entity positions and items
+    ResetLevel,
+    /// Pause or resume game ticking logic
+    TogglePause,
+}
+
+/// Global events that flow through the ECS event system to coordinate game behavior.
+///
+/// Events enable loose coupling between systems - input generates commands, collision
+/// detection reports overlaps, and various systems respond appropriately without
+/// direct dependencies.
+#[derive(Event, Clone, Copy, Debug, PartialEq, Eq)]
+pub enum GameEvent {
+    /// Player input command to be processed by relevant game systems
+    Command(GameCommand),
+    /// Physical overlap detected between two entities requiring gameplay response
+    Collision(Entity, Entity),
+}
+
+impl From<GameCommand> for GameEvent {
+    fn from(command: GameCommand) -> Self {
+        GameEvent::Command(command)
+    }
+}

src/formatter.rs

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

src/game.rs

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

src/game/mod.rs

@@ -1,327 +0,0 @@
-//! This module contains the main game logic and state.
-
-use glam::{UVec2, Vec2};
-use rand::{rngs::SmallRng, Rng, SeedableRng};
-use sdl2::{
-    keyboard::Keycode,
-    pixels::Color,
-    render::{Canvas, RenderTarget, Texture, TextureCreator},
-    video::WindowContext,
-};
-
-use crate::error::{EntityError, GameError, GameResult};
-
-use crate::entity::{
-    collision::{Collidable, CollisionSystem, EntityId},
-    ghost::{Ghost, GhostType},
-    pacman::Pacman,
-    r#trait::Entity,
-};
-
-pub mod state;
-use state::GameState;
-
-/// The `Game` struct is the main entry point for the game.
-///
-/// 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 {
-    state: GameState,
-}
-
-impl Game {
-    pub fn new(texture_creator: &'static TextureCreator<WindowContext>) -> GameResult<Game> {
-        let state = GameState::new(texture_creator)?;
-
-        Ok(Game { state })
-    }
-
-    pub fn keyboard_event(&mut self, keycode: Keycode) {
-        self.state.pacman.handle_key(keycode);
-
-        if keycode == Keycode::M {
-            self.state.audio.set_mute(!self.state.audio.is_muted());
-        }
-
-        if keycode == Keycode::R {
-            if let Err(e) = self.reset_game_state() {
-                tracing::error!("Failed to reset game state: {}", e);
-            }
-        }
-    }
-
-    /// Resets the game state, randomizing ghost positions and resetting Pac-Man
-    fn reset_game_state(&mut self) -> GameResult<()> {
-        let pacman_start_node = self.state.map.start_positions.pacman;
-        self.state.pacman = Pacman::new(&self.state.map.graph, pacman_start_node, &self.state.atlas)?;
-
-        // Reset items
-        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.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.state.collision_system = CollisionSystem::default();
-
-        // Re-register Pac-Man
-        self.state.pacman_id = self.state.collision_system.register_entity(self.state.pacman.position());
-
-        // Re-register items
-        self.state.item_ids.clear();
-        for item in &self.state.items {
-            let item_id = self.state.collision_system.register_entity(item.position());
-            self.state.item_ids.push(item_id);
-        }
-
-        // Re-register ghosts
-        self.state.ghost_ids.clear();
-        for ghost in &self.state.ghosts {
-            let ghost_id = self.state.collision_system.register_entity(ghost.position());
-            self.state.ghost_ids.push(ghost_id);
-        }
-
-        Ok(())
-    }
-
-    pub fn tick(&mut self, dt: f32) {
-        self.state.pacman.tick(dt, &self.state.map.graph);
-
-        // Update all ghosts
-        for ghost in &mut self.state.ghosts {
-            ghost.tick(dt, &self.state.map.graph);
-        }
-
-        // Update collision system positions
-        self.update_collision_positions();
-
-        // Check for collisions
-        self.check_collisions();
-    }
-
-    /// Toggles the debug mode on and off.
-    ///
-    /// When debug mode is enabled, the game will render additional information
-    /// that is useful for debugging, such as the collision grid and entity paths.
-    pub fn toggle_debug_mode(&mut self) {
-        self.state.debug_mode = !self.state.debug_mode;
-    }
-
-    fn update_collision_positions(&mut self) {
-        // Update Pac-Man's position
-        self.state
-            .collision_system
-            .update_position(self.state.pacman_id, self.state.pacman.position());
-
-        // Update ghost positions
-        for (ghost, &ghost_id) in self.state.ghosts.iter().zip(&self.state.ghost_ids) {
-            self.state.collision_system.update_position(ghost_id, ghost.position());
-        }
-    }
-
-    fn check_collisions(&mut self) {
-        // Check Pac-Man vs Items
-        let potential_collisions = self
-            .state
-            .collision_system
-            .potential_collisions(&self.state.pacman.position());
-
-        for entity_id in potential_collisions {
-            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.state.items[item_index];
-                    if !item.is_collected() {
-                        item.collect();
-                        self.state.score += item.get_score();
-                        self.state.audio.eat();
-
-                        // Handle energizer effects
-                        if matches!(item.item_type, crate::entity::item::ItemType::Energizer) {
-                            // TODO: Make ghosts frightened
-                            tracing::info!("Energizer collected! Ghosts should become frightened.");
-                        }
-                    }
-                }
-
-                // Check if this is a ghost collision
-                if let Some(_ghost_index) = self.find_ghost_by_id(entity_id) {
-                    // TODO: Handle Pac-Man being eaten by ghost
-                    tracing::info!("Pac-Man collided with ghost!");
-                }
-            }
-        }
-    }
-
-    fn find_item_by_id(&self, entity_id: EntityId) -> Option<usize> {
-        self.state.item_ids.iter().position(|&id| id == entity_id)
-    }
-
-    fn find_ghost_by_id(&self, entity_id: EntityId) -> Option<usize> {
-        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<()> {
-        canvas
-            .with_texture_canvas(backbuffer, |canvas| {
-                canvas.set_draw_color(Color::BLACK);
-                canvas.clear();
-                self.state
-                    .map
-                    .render(canvas, &mut self.state.atlas, &mut self.state.map_tiles);
-
-                // Render all items
-                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.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.state.pacman.render(canvas, &mut self.state.atlas, &self.state.map.graph) {
-                    tracing::error!("Failed to render pacman: {}", e);
-                }
-            })
-            .map_err(|e| GameError::Sdl(e.to_string()))?;
-
-        Ok(())
-    }
-
-    pub fn present_backbuffer<T: RenderTarget>(
-        &mut self,
-        canvas: &mut Canvas<T>,
-        backbuffer: &Texture,
-        cursor_pos: glam::Vec2,
-    ) -> GameResult<()> {
-        canvas
-            .copy(backbuffer, None, None)
-            .map_err(|e| GameError::Sdl(e.to_string()))?;
-        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);
-            }
-            self.render_pathfinding_debug(canvas)?;
-        }
-        self.draw_hud(canvas)?;
-        canvas.present();
-        Ok(())
-    }
-
-    /// Renders pathfinding debug lines from each ghost to Pac-Man.
-    ///
-    /// 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.state.pacman.current_node_id();
-
-        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
-                }
-
-                // Set the ghost's color
-                canvas.set_draw_color(ghost.debug_color());
-
-                // Calculate offset based on ghost index to prevent overlapping lines
-                // let offset = (i as f32) * 2.0 - 3.0; // Offset range: -3.0 to 3.0
-
-                // Calculate a consistent offset direction for the entire path
-                // let first_node = self.map.graph.get_node(path[0]).unwrap();
-                // let last_node = self.map.graph.get_node(path[path.len() - 1]).unwrap();
-
-                // Use the overall direction from start to end to determine the perpendicular offset
-                let offset = match ghost.ghost_type {
-                    GhostType::Blinky => Vec2::new(0.25, 0.5),
-                    GhostType::Pinky => Vec2::new(-0.25, -0.25),
-                    GhostType::Inky => Vec2::new(0.5, -0.5),
-                    GhostType::Clyde => Vec2::new(-0.5, 0.25),
-                } * 5.0;
-
-                // Calculate offset positions for all nodes using the same perpendicular direction
-                let mut offset_positions = Vec::new();
-                for &node_id in &path {
-                    let node = self
-                        .state
-                        .map
-                        .graph
-                        .get_node(node_id)
-                        .ok_or(GameError::Entity(EntityError::NodeNotFound(node_id)))?;
-                    let pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-                    offset_positions.push(pos + offset);
-                }
-
-                // Draw lines between the offset positions
-                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) > (crate::constants::CELL_SIZE * 16).pow(2) as f32 {
-                            continue;
-                        }
-
-                        // Draw the line
-                        canvas
-                            .draw_line((from.x as i32, from.y as i32), (to.x as i32, to.y as i32))
-                            .map_err(|e| GameError::Sdl(e.to_string()))?;
-                    }
-                }
-            }
-        }
-
-        Ok(())
-    }
-
-    fn draw_hud<T: RenderTarget>(&mut self, canvas: &mut Canvas<T>) -> GameResult<()> {
-        let lives = 3;
-        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.state.text_texture.set_scale(1.0);
-        if let Err(e) = self.state.text_texture.render(
-            canvas,
-            &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.state.text_texture.render(
-            canvas,
-            &mut self.state.atlas,
-            &score_text,
-            UVec2::new(8 * score_offset as u32 + x_offset, 8 + y_offset),
-        ) {
-            tracing::error!("Failed to render score text: {}", e);
-        }
-
-        // Display FPS information in top-left corner
-        // let fps_text = format!("FPS: {:.1} (1s) / {:.1} (10s)", self.fps_1s, self.fps_10s);
-        // self.render_text_on(
-        //     canvas,
-        //     &*texture_creator,
-        //     &fps_text,
-        //     IVec2::new(10, 10),
-        //     Color::RGB(255, 255, 0), // Yellow color for FPS display
-        // );
-
-        Ok(())
-    }
-}

src/game/state.rs

@@ -1,140 +0,0 @@
-use sdl2::{image::LoadTexture, render::TextureCreator, video::WindowContext};
-use smallvec::SmallVec;
-
-use crate::{
-    asset::{get_asset_bytes, Asset},
-    audio::Audio,
-    constants::RAW_BOARD,
-    entity::{
-        collision::{Collidable, CollisionSystem},
-        ghost::{Ghost, GhostType},
-        item::Item,
-        pacman::Pacman,
-    },
-    error::{GameError, GameResult, TextureError},
-    game::EntityId,
-    map::Map,
-    texture::{
-        sprite::{AtlasMapper, AtlasTile, SpriteAtlas},
-        text::TextTexture,
-    },
-};
-
-/// The `GameState` struct holds all the essential data for the game.
-///
-/// This includes the score, map, entities (Pac-Man, ghosts, items),
-/// collision system, and rendering resources. By centralizing the game's state,
-/// we can cleanly separate it from the game's logic, making it easier to manage
-/// and reason about.
-pub struct GameState {
-    pub score: u32,
-    pub map: Map,
-    pub map_tiles: Vec<AtlasTile>,
-    pub pacman: Pacman,
-    pub pacman_id: EntityId,
-    pub ghosts: SmallVec<[Ghost; 4]>,
-    pub ghost_ids: SmallVec<[EntityId; 4]>,
-    pub items: Vec<Item>,
-    pub item_ids: Vec<EntityId>,
-    pub debug_mode: bool,
-
-    // Collision system
-    pub(crate) collision_system: CollisionSystem,
-
-    // Rendering resources
-    pub(crate) atlas: SpriteAtlas,
-    pub(crate) text_texture: TextTexture,
-
-    // Audio
-    pub audio: Audio,
-}
-
-impl GameState {
-    /// Creates a new `GameState` by initializing all the game's data.
-    ///
-    /// This function sets up the map, Pac-Man, ghosts, items, collision system,
-    /// and all rendering resources required to start the game. It returns a `GameResult`
-    /// to handle any potential errors during initialization.
-    pub fn new(texture_creator: &'static TextureCreator<WindowContext>) -> GameResult<Self> {
-        let map = Map::new(RAW_BOARD)?;
-
-        let pacman_start_node = map.start_positions.pacman;
-
-        let atlas_bytes = get_asset_bytes(Asset::Atlas)?;
-        let atlas_texture = texture_creator.load_texture_bytes(&atlas_bytes).map_err(|e| {
-            if e.to_string().contains("format") || e.to_string().contains("unsupported") {
-                GameError::Texture(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(atlas_texture, atlas_mapper);
-
-        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(&atlas, &tile_name)
-                .ok_or(GameError::Texture(TextureError::AtlasTileNotFound(tile_name)))?;
-            map_tiles.push(tile);
-        }
-
-        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)?;
-
-        // Initialize collision system
-        let mut collision_system = CollisionSystem::default();
-
-        // Register Pac-Man
-        let pacman_id = collision_system.register_entity(pacman.position());
-
-        // Register items
-        let item_ids = items
-            .iter()
-            .map(|item| collision_system.register_entity(item.position()))
-            .collect();
-
-        // Create and register ghosts
-        let ghosts = [GhostType::Blinky, GhostType::Pinky, GhostType::Inky, GhostType::Clyde]
-            .iter()
-            .zip(
-                [
-                    map.start_positions.blinky,
-                    map.start_positions.pinky,
-                    map.start_positions.inky,
-                    map.start_positions.clyde,
-                ]
-                .iter(),
-            )
-            .map(|(ghost_type, start_node)| Ghost::new(&map.graph, *start_node, *ghost_type, &atlas))
-            .collect::<GameResult<SmallVec<[_; 4]>>>()?;
-
-        // Register ghosts
-        let ghost_ids = ghosts
-            .iter()
-            .map(|ghost| collision_system.register_entity(ghost.position()))
-            .collect();
-
-        Ok(Self {
-            map,
-            atlas,
-            map_tiles,
-            pacman,
-            pacman_id,
-            ghosts,
-            ghost_ids,
-            items,
-            item_ids,
-            text_texture,
-            audio,
-            score: 0,
-            debug_mode: false,
-            collision_system,
-        })
-    }
-}

src/helpers.rs

@@ -1,10 +0,0 @@
-use glam::{IVec2, UVec2};
-use sdl2::rect::Rect;
-
-pub fn centered_with_size(pixel_pos: IVec2, size: UVec2) -> Rect {
-    // Ensure the position doesn't cause integer overflow when centering
-    let x = pixel_pos.x.saturating_sub(size.x as i32 / 2);
-    let y = pixel_pos.y.saturating_sub(size.y as i32 / 2);
-
-    Rect::new(x, y, size.x, size.y)
-}

src/lib.rs

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

src/main.rs

@@ -1,40 +1,43 @@
+// Note: This disables the console window on Windows. We manually re-attach to the parent terminal or process later on.
 #![windows_subsystem = "windows"]
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
 
 use crate::{app::App, constants::LOOP_TIME};
 use tracing::info;
-use tracing_error::ErrorLayer;
-use tracing_subscriber::layer::SubscriberExt;
 
+#[cfg_attr(coverage_nightly, coverage(off))]
 mod app;
-mod asset;
+#[cfg_attr(coverage_nightly, coverage(off))]
 mod audio;
-mod constants;
-
-mod entity;
+#[cfg_attr(coverage_nightly, coverage(off))]
 mod error;
-mod game;
-mod helpers;
-mod map;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod events;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod formatter;
+#[cfg_attr(coverage_nightly, coverage(off))]
 mod platform;
+
+mod asset;
+mod constants;
+mod game;
+mod map;
+mod systems;
 mod texture;
 
 /// The main entry point of the application.
 ///
 /// This function initializes SDL, the window, the game state, and then enters
 /// the main game loop.
+#[cfg_attr(coverage_nightly, coverage(off))]
 pub fn main() {
-    // Setup tracing
-    let subscriber = tracing_subscriber::fmt()
-        .with_ansi(cfg!(not(target_os = "emscripten")))
-        .with_max_level(tracing::Level::DEBUG)
-        .finish()
-        .with(ErrorLayer::default());
-
-    tracing::subscriber::set_global_default(subscriber).expect("Could not set global default");
+    // On Windows, this connects output streams to the console dynamically
+    // On Emscripten, this connects the subscriber to the browser console
+    platform::init_console().expect("Could not initialize console");
 
     let mut app = App::new().expect("Could not create app");
 
-    info!("Starting game loop ({:?})", LOOP_TIME);
+    info!(loop_time = ?LOOP_TIME, "Starting game loop");
 
     loop {
         if !app.run() {

src/map/builder.rs

@@ -1,36 +1,48 @@
 //! Map construction and building functionality.
-
-use crate::constants::{MapTile, BOARD_CELL_SIZE, CELL_SIZE, RAW_BOARD};
-use crate::entity::direction::Direction;
-use crate::entity::graph::{EdgePermissions, Graph, Node, NodeId};
-use crate::entity::item::{Item, ItemType};
+use crate::constants::{MapTile, BOARD_CELL_SIZE, CELL_SIZE};
+use crate::map::direction::Direction;
+use crate::map::graph::{Graph, Node, TraversalFlags};
 use crate::map::parser::MapTileParser;
-use crate::map::render::MapRenderer;
-use crate::texture::sprite::{AtlasTile, Sprite, SpriteAtlas};
-use glam::{IVec2, Vec2};
-use sdl2::render::{Canvas, RenderTarget};
+use crate::systems::movement::NodeId;
+use bevy_ecs::resource::Resource;
+use glam::{I8Vec2, IVec2, Vec2};
 use std::collections::{HashMap, VecDeque};
 use tracing::debug;
 
 use crate::error::{GameResult, MapError};
 
-/// The starting positions of the entities in the game.
+/// Predefined spawn locations for all game entities within the navigation graph.
+///
+/// These positions are determined during map parsing and graph construction.
 pub struct NodePositions {
+    /// Pac-Man's starting position in the lower section of the maze
     pub pacman: NodeId,
+    /// Blinky starts at the ghost house entrance
     pub blinky: NodeId,
+    /// Pinky starts in the left area of the ghost house
     pub pinky: NodeId,
+    /// Inky starts in the right area of the ghost house
     pub inky: NodeId,
+    /// Clyde starts in the center of the ghost house
     pub clyde: NodeId,
 }
 
-/// The main map structure containing the game board and navigation graph.
+/// Complete maze representation combining visual layout with navigation pathfinding.
+///
+/// Transforms the ASCII board layout into a fully connected navigation graph
+/// while preserving tile-based collision and rendering data. The graph enables
+/// smooth entity movement with proper pathfinding, while the grid mapping allows
+/// efficient spatial queries and debug visualization.
+#[derive(Resource)]
 pub struct Map {
-    /// The node map for entity movement.
+    /// Connected graph of navigable positions.
     pub graph: Graph,
-    /// A mapping from grid positions to node IDs.
-    pub grid_to_node: HashMap<IVec2, NodeId>,
-    /// A mapping of the starting positions of the entities.
+    /// Bidirectional mapping between 2D grid coordinates and graph node indices.
+    pub grid_to_node: HashMap<I8Vec2, NodeId>,
+    /// Predetermined spawn locations for all game entities
     pub start_positions: NodePositions,
+    /// 2D array of tile types for collision detection and rendering
+    tiles: [[MapTile; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize],
 }
 
 impl Map {
@@ -64,8 +76,8 @@ impl Map {
         let mut queue = VecDeque::new();
         queue.push_back(start_pos);
         let pos = Vec2::new(
-            (start_pos.x * CELL_SIZE as i32) as f32,
-            (start_pos.y * CELL_SIZE as i32) as f32,
+            (start_pos.x as i32 * CELL_SIZE as i32) as f32,
+            (start_pos.y as i32 * CELL_SIZE as i32) as f32,
         ) + cell_offset;
         let node_id = graph.add_node(Node { position: pos });
         grid_to_node.insert(start_pos, node_id);
@@ -77,9 +89,9 @@ impl Map {
 
                 // Skip if the new position is out of bounds
                 if new_position.x < 0
-                    || new_position.x >= BOARD_CELL_SIZE.x as i32
+                    || new_position.x as i32 >= BOARD_CELL_SIZE.x as i32
                     || new_position.y < 0
-                    || new_position.y >= BOARD_CELL_SIZE.y as i32
+                    || new_position.y as i32 >= BOARD_CELL_SIZE.y as i32
                 {
                     continue;
                 }
@@ -96,8 +108,8 @@ impl Map {
                 ) {
                     // Add the new position to the graph/queue
                     let pos = Vec2::new(
-                        (new_position.x * CELL_SIZE as i32) as f32,
-                        (new_position.y * CELL_SIZE as i32) as f32,
+                        (new_position.x as i32 * CELL_SIZE as i32) as f32,
+                        (new_position.y as i32 * CELL_SIZE as i32) as f32,
                     ) + cell_offset;
                     let new_node_id = graph.add_node(Node { position: pos });
                     grid_to_node.insert(new_position, new_node_id);
@@ -120,7 +132,7 @@ impl Map {
         for (grid_pos, &node_id) in &grid_to_node {
             for dir in Direction::DIRECTIONS {
                 // If the node doesn't have an edge in this direction, look for a neighbor in that direction
-                if graph.adjacency_list[node_id].get(dir).is_none() {
+                if graph.adjacency_list[node_id as usize].get(dir).is_none() {
                     let neighbor = grid_pos + dir.as_ivec2();
                     // If the neighbor exists, connect the node to it
                     if let Some(&neighbor_id) = grid_to_node.get(&neighbor) {
@@ -151,75 +163,45 @@ impl Map {
             graph,
             grid_to_node,
             start_positions,
+            tiles: map,
         })
     }
 
-    /// Renders the map to the given canvas.
-    ///
-    /// This function draws the static map texture to the screen at the correct
-    /// position and scale.
-    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, map_tiles: &mut [AtlasTile]) {
-        MapRenderer::render_map(canvas, atlas, map_tiles);
+    pub fn iter_nodes(&self) -> impl Iterator<Item = (&NodeId, &MapTile)> {
+        self.grid_to_node.iter().map(move |(pos, node_id)| {
+            let tile = &self.tiles[pos.x as usize][pos.y as usize];
+            (node_id, tile)
+        })
     }
 
-    /// Generates Item entities for pellets and energizers from the parsed map.
-    pub fn generate_items(&self, atlas: &SpriteAtlas) -> GameResult<Vec<Item>> {
-        // Pre-load sprites to avoid repeated texture lookups
-        let pellet_sprite = SpriteAtlas::get_tile(atlas, "maze/pellet.png")
-            .ok_or_else(|| MapError::InvalidConfig("Pellet texture not found".to_string()))?;
-        let energizer_sprite = SpriteAtlas::get_tile(atlas, "maze/energizer.png")
-            .ok_or_else(|| MapError::InvalidConfig("Energizer texture not found".to_string()))?;
-
-        // Pre-allocate with estimated capacity (typical Pac-Man maps have ~240 pellets + 4 energizers)
-        let mut items = Vec::with_capacity(250);
-
-        // Parse the raw board once
-        let parsed_map = MapTileParser::parse_board(RAW_BOARD)?;
-        let map = parsed_map.tiles;
-
-        // Iterate through the map and collect items more efficiently
-        for (x, row) in map.iter().enumerate() {
-            for (y, tile) in row.iter().enumerate() {
-                match tile {
-                    MapTile::Pellet | MapTile::PowerPellet => {
-                        let grid_pos = IVec2::new(x as i32, y as i32);
-                        if let Some(&node_id) = self.grid_to_node.get(&grid_pos) {
-                            let (item_type, sprite) = match tile {
-                                MapTile::Pellet => (ItemType::Pellet, Sprite::new(pellet_sprite)),
-                                MapTile::PowerPellet => (ItemType::Energizer, Sprite::new(energizer_sprite)),
-                                _ => unreachable!(), // We already filtered for these types
-                            };
-                            items.push(Item::new(node_id, item_type, sprite));
-                        }
-                    }
-                    _ => {}
-                }
+    /// Returns the `MapTile` at a given node id.
+    pub fn tile_at_node(&self, node_id: NodeId) -> Option<MapTile> {
+        // reverse lookup: node -> grid
+        for (grid_pos, id) in &self.grid_to_node {
+            if *id == node_id {
+                return Some(self.tiles[grid_pos.x as usize][grid_pos.y as usize]);
             }
         }
-
-        Ok(items)
+        None
     }
 
-    /// Renders a debug visualization with cursor-based highlighting.
+    /// Constructs the ghost house area with restricted access and internal navigation.
     ///
-    /// This function provides interactive debugging by highlighting the nearest node
-    /// to the cursor, showing its ID, and highlighting its connections.
-    pub fn debug_render_with_cursor<T: RenderTarget>(
-        &self,
-        canvas: &mut Canvas<T>,
-        text_renderer: &mut crate::texture::text::TextTexture,
-        atlas: &mut SpriteAtlas,
-        cursor_pos: glam::Vec2,
-    ) -> GameResult<()> {
-        MapRenderer::debug_render_with_cursor(&self.graph, canvas, text_renderer, atlas, cursor_pos)
-    }
-
-    /// Builds the house structure in the graph.
+    /// Creates a multi-level ghost house with entrance control, internal movement
+    /// areas, and starting positions for each ghost. The house entrance uses
+    /// ghost-only traversal flags to prevent Pac-Man from entering while allowing
+    /// ghosts to exit. Internal nodes are arranged in vertical lines to provide
+    /// distinct starting areas for each ghost character.
+    ///
+    /// # Returns
+    ///
+    /// Tuple of node IDs: (house_entrance, left_center, center_center, right_center)
+    /// representing the four key positions within the ghost house structure.
     fn build_house(
         graph: &mut Graph,
-        grid_to_node: &HashMap<IVec2, NodeId>,
-        house_door: &[Option<IVec2>; 2],
-    ) -> GameResult<(usize, usize, usize, usize)> {
+        grid_to_node: &HashMap<I8Vec2, NodeId>,
+        house_door: &[Option<I8Vec2>; 2],
+    ) -> GameResult<(NodeId, NodeId, NodeId, NodeId)> {
         // Calculate the position of the house entrance node
         let (house_entrance_node_id, house_entrance_node_position) = {
             // Translate the grid positions to the actual node ids
@@ -240,10 +222,13 @@ impl Map {
 
             // Calculate the position of the house node
             let (node_id, node_position) = {
-                let left_pos = graph.get_node(*left_node).ok_or(MapError::NodeNotFound(*left_node))?.position;
+                let left_pos = graph
+                    .get_node(*left_node)
+                    .ok_or(MapError::NodeNotFound(*left_node as usize))?
+                    .position;
                 let right_pos = graph
                     .get_node(*right_node)
-                    .ok_or(MapError::NodeNotFound(*right_node))?
+                    .ok_or(MapError::NodeNotFound(*right_node as usize))?
                     .position;
                 let house_node = graph.add_node(Node {
                     position: left_pos.lerp(right_pos, 0.5),
@@ -267,10 +252,10 @@ impl Map {
             // Place the nodes at, above, and below the center position
             let center_node_id = graph.add_node(Node { position: center_pos });
             let top_node_id = graph.add_node(Node {
-                position: center_pos + (Direction::Up.as_ivec2() * (CELL_SIZE as i32 / 2)).as_vec2(),
+                position: center_pos + IVec2::from(Direction::Up.as_ivec2()).as_vec2() * (CELL_SIZE as f32 / 2.0),
             });
             let bottom_node_id = graph.add_node(Node {
-                position: center_pos + (Direction::Down.as_ivec2() * (CELL_SIZE as i32 / 2)).as_vec2(),
+                position: center_pos + IVec2::from(Direction::Down.as_ivec2()).as_vec2() * (CELL_SIZE as f32 / 2.0),
             });
 
             // Connect the center node to the top and bottom nodes
@@ -286,7 +271,7 @@ impl Map {
 
         // Calculate the position of the center line's center node
         let center_line_center_position =
-            house_entrance_node_position + (Direction::Down.as_ivec2() * (3 * CELL_SIZE as i32)).as_vec2();
+            house_entrance_node_position + IVec2::from(Direction::Down.as_ivec2()).as_vec2() * (3.0 * CELL_SIZE as f32);
 
         // Create the center line
         let (center_center_node_id, center_top_node_id) = create_house_line(graph, center_line_center_position)?;
@@ -300,7 +285,7 @@ impl Map {
                 false,
                 None,
                 Direction::Down,
-                EdgePermissions::GhostsOnly,
+                TraversalFlags::GHOST,
             )
             .map_err(|e| MapError::InvalidConfig(format!("Failed to create ghost-only entrance to house: {e}")))?;
 
@@ -311,20 +296,20 @@ impl Map {
                 false,
                 None,
                 Direction::Up,
-                EdgePermissions::GhostsOnly,
+                TraversalFlags::GHOST,
             )
             .map_err(|e| MapError::InvalidConfig(format!("Failed to create ghost-only exit from house: {e}")))?;
 
         // Create the left line
         let (left_center_node_id, _) = create_house_line(
             graph,
-            center_line_center_position + (Direction::Left.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
+            center_line_center_position + IVec2::from(Direction::Left.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
         )?;
 
         // Create the right line
         let (right_center_node_id, _) = create_house_line(
             graph,
-            center_line_center_position + (Direction::Right.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
+            center_line_center_position + IVec2::from(Direction::Right.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
         )?;
 
         debug!("Left center node id: {left_center_node_id}");
@@ -348,11 +333,14 @@ impl Map {
         ))
     }
 
-    /// Builds the tunnel connections in the graph.
+    /// Creates horizontal tunnel portals for instant teleportation across the maze.
+    ///
+    /// Establishes the tunnel system that allows entities to instantly travel from the left edge of the maze to the right edge.
+    /// Creates hidden intermediate nodes beyond the visible tunnel entrances and connects them with zero-distance edges for instantaneous traversal.
     fn build_tunnels(
         graph: &mut Graph,
-        grid_to_node: &HashMap<IVec2, NodeId>,
-        tunnel_ends: &[Option<IVec2>; 2],
+        grid_to_node: &HashMap<I8Vec2, NodeId>,
+        tunnel_ends: &[Option<I8Vec2>; 2],
     ) -> GameResult<()> {
         // Create the hidden tunnel nodes
         let left_tunnel_hidden_node_id = {
@@ -368,15 +356,10 @@ impl Map {
                     Direction::Left,
                     Node {
                         position: left_tunnel_entrance_node.position
-                            + (Direction::Left.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
+                            + IVec2::from(Direction::Left.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
                     },
                 )
-                .map_err(|e| {
-                    MapError::InvalidConfig(format!(
-                        "Failed to connect left tunnel entrance to left tunnel hidden node: {}",
-                        e
-                    ))
-                })?
+                .expect("Failed to connect left tunnel entrance to left tunnel hidden node")
         };
 
         // Create the right tunnel nodes
@@ -393,15 +376,10 @@ impl Map {
                     Direction::Right,
                     Node {
                         position: right_tunnel_entrance_node.position
-                            + (Direction::Right.as_ivec2() * (CELL_SIZE as i32 * 2)).as_vec2(),
+                            + IVec2::from(Direction::Right.as_ivec2()).as_vec2() * (CELL_SIZE as f32 * 2.0),
                     },
                 )
-                .map_err(|e| {
-                    MapError::InvalidConfig(format!(
-                        "Failed to connect right tunnel entrance to right tunnel hidden node: {}",
-                        e
-                    ))
-                })?
+                .expect("Failed to connect right tunnel entrance to right tunnel hidden node")
         };
 
         // Connect the left tunnel hidden node to the right tunnel hidden node
@@ -413,12 +391,7 @@ impl Map {
                 Some(0.0),
                 Direction::Left,
             )
-            .map_err(|e| {
-                MapError::InvalidConfig(format!(
-                    "Failed to connect left tunnel hidden node to right tunnel hidden node: {}",
-                    e
-                ))
-            })?;
+            .expect("Failed to connect left tunnel hidden node to right tunnel hidden node");
 
         Ok(())
     }

src/map/direction.rs

@@ -1,11 +1,15 @@
-use glam::IVec2;
+use glam::I8Vec2;
+use strum_macros::AsRefStr;
 
 /// The four cardinal directions.
-#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, AsRefStr)]
+#[repr(usize)]
+#[strum(serialize_all = "lowercase")]
 pub enum Direction {
     Up,
     Down,
     Left,
+    #[default]
     Right,
 }
 
@@ -24,8 +28,8 @@ impl Direction {
         }
     }
 
-    /// Returns the direction as an IVec2.
-    pub fn as_ivec2(self) -> IVec2 {
+    /// Returns the direction as an I8Vec2.
+    pub fn as_ivec2(self) -> I8Vec2 {
         self.into()
     }
 
@@ -41,13 +45,13 @@ impl Direction {
     }
 }
 
-impl From<Direction> for IVec2 {
+impl From<Direction> for I8Vec2 {
     fn from(dir: Direction) -> Self {
         match dir {
-            Direction::Up => -IVec2::Y,
-            Direction::Down => IVec2::Y,
-            Direction::Left => -IVec2::X,
-            Direction::Right => IVec2::X,
+            Direction::Up => -I8Vec2::Y,
+            Direction::Down => I8Vec2::Y,
+            Direction::Left => -I8Vec2::X,
+            Direction::Right => I8Vec2::X,
         }
     }
 }

src/map/graph.rs

@@ -1,18 +1,21 @@
 use glam::Vec2;
 
+use crate::systems::movement::NodeId;
+
 use super::direction::Direction;
 
-/// A unique identifier for a node, represented by its index in the graph's storage.
-pub type NodeId = usize;
+use bitflags::bitflags;
 
-/// Defines who can traverse a given edge.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
-pub enum EdgePermissions {
-    /// Anyone can use this edge.
-    #[default]
-    All,
-    /// Only ghosts can use this edge.
-    GhostsOnly,
+bitflags! {
+    /// Defines who can traverse a given edge using flags for fast checking.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+    pub struct TraversalFlags: u8 {
+        const PACMAN = 1 << 0;
+        const GHOST = 1 << 1;
+
+        /// Convenience flag for edges that all entities can use
+        const ALL = Self::PACMAN.bits() | Self::GHOST.bits();
+    }
 }
 
 /// Represents a directed edge from one node to another with a given weight (e.g., distance).
@@ -25,7 +28,7 @@ pub struct Edge {
     /// The cardinal direction of this edge.
     pub direction: Direction,
     /// Defines who is allowed to traverse this edge.
-    pub permissions: EdgePermissions,
+    pub traversal_flags: TraversalFlags,
 }
 
 /// Represents a node in the graph, defined by its position.
@@ -104,7 +107,7 @@ impl Graph {
 
     /// Adds a new node with the given data to the graph and returns its ID.
     pub fn add_node(&mut self, data: Node) -> NodeId {
-        let id = self.nodes.len();
+        let id = self.nodes.len() as NodeId;
         self.nodes.push(data);
         self.adjacency_list.push(Intersection::default());
         id
@@ -126,15 +129,15 @@ impl Graph {
         distance: Option<f32>,
         direction: Direction,
     ) -> Result<(), &'static str> {
-        if from >= self.adjacency_list.len() {
+        if from as usize >= self.adjacency_list.len() {
             return Err("From node does not exist.");
         }
-        if to >= self.adjacency_list.len() {
+        if to as usize >= self.adjacency_list.len() {
             return Err("To node does not exist.");
         }
 
-        let edge_a = self.add_edge(from, to, replace, distance, direction, EdgePermissions::default());
-        let edge_b = self.add_edge(to, from, replace, distance, direction.opposite(), EdgePermissions::default());
+        let edge_a = self.add_edge(from, to, replace, distance, direction, TraversalFlags::ALL);
+        let edge_b = self.add_edge(to, from, replace, distance, direction.opposite(), TraversalFlags::ALL);
 
         if edge_a.is_err() && edge_b.is_err() {
             return Err("Failed to connect nodes in both directions.");
@@ -162,7 +165,7 @@ impl Graph {
         replace: bool,
         distance: Option<f32>,
         direction: Direction,
-        permissions: EdgePermissions,
+        traversal_flags: TraversalFlags,
     ) -> Result<(), &'static str> {
         let edge = Edge {
             target: to,
@@ -175,20 +178,20 @@ impl Graph {
                 }
                 None => {
                     // If no distance is provided, calculate it based on the positions of the nodes
-                    let from_pos = self.nodes[from].position;
-                    let to_pos = self.nodes[to].position;
+                    let from_pos = self.nodes[from as usize].position;
+                    let to_pos = self.nodes[to as usize].position;
                     from_pos.distance(to_pos)
                 }
             },
             direction,
-            permissions,
+            traversal_flags,
         };
 
-        if from >= self.adjacency_list.len() {
+        if from as usize >= self.adjacency_list.len() {
             return Err("From node does not exist.");
         }
 
-        let adjacency_list = &mut self.adjacency_list[from];
+        let adjacency_list = &mut self.adjacency_list[from as usize];
 
         // Check if the edge already exists in this direction or to the same target
         if let Some(err) = adjacency_list.edges().find_map(|e| {
@@ -212,22 +215,30 @@ impl Graph {
 
     /// Retrieves an immutable reference to a node's data.
     pub fn get_node(&self, id: NodeId) -> Option<&Node> {
-        self.nodes.get(id)
+        self.nodes.get(id as usize)
     }
 
-    /// Returns the total number of nodes in the graph.
-    pub fn node_count(&self) -> usize {
-        self.nodes.len()
+    /// Returns an iterator over all nodes in the graph.
+    pub fn nodes(&self) -> impl Iterator<Item = &Node> {
+        self.nodes.iter()
+    }
+
+    /// Returns an iterator over all edges in the graph.
+    pub fn edges(&self) -> impl Iterator<Item = (NodeId, Edge)> + '_ {
+        self.adjacency_list
+            .iter()
+            .enumerate()
+            .flat_map(|(node_id, intersection)| intersection.edges().map(move |edge| (node_id as NodeId, edge)))
     }
 
     /// Finds a specific edge from a source node to a target node.
     pub fn find_edge(&self, from: NodeId, to: NodeId) -> Option<Edge> {
-        self.adjacency_list.get(from)?.edges().find(|edge| edge.target == to)
+        self.adjacency_list.get(from as usize)?.edges().find(|edge| edge.target == to)
     }
 
     /// Finds an edge originating from a given node that follows a specific direction.
     pub fn find_edge_in_direction(&self, from: NodeId, direction: Direction) -> Option<Edge> {
-        self.adjacency_list.get(from)?.get(direction)
+        self.adjacency_list.get(from as usize)?.get(direction)
     }
 }
 

src/map/mod.rs

@@ -1,9 +1,8 @@
 //! This module defines the game map and provides functions for interacting with it.
 
 pub mod builder;
+pub mod direction;
+pub mod graph;
 pub mod layout;
 pub mod parser;
 pub mod render;
-
-// Re-export main types for convenience
-pub use builder::Map;

src/map/parser.rs

@@ -2,34 +2,42 @@
 
 use crate::constants::{MapTile, BOARD_CELL_SIZE};
 use crate::error::ParseError;
-use glam::IVec2;
+use glam::I8Vec2;
 
-/// Represents the parsed data from a raw board layout.
+/// Structured representation of parsed ASCII board layout with extracted special positions.
+///
+/// Contains the complete board state after character-to-tile conversion, along with
+/// the locations of special gameplay elements that require additional processing
+/// during graph construction. Special positions are extracted during parsing to
+/// enable proper map builder initialization.
 #[derive(Debug)]
 pub struct ParsedMap {
-    /// The parsed tile layout.
+    /// 2D array of tiles converted from ASCII characters
     pub tiles: [[MapTile; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize],
-    /// The positions of the house door tiles.
-    pub house_door: [Option<IVec2>; 2],
-    /// The positions of the tunnel end tiles.
-    pub tunnel_ends: [Option<IVec2>; 2],
-    /// Pac-Man's starting position.
-    pub pacman_start: Option<IVec2>,
+    /// Two positions marking the ghost house entrance (represented by '=' characters)
+    pub house_door: [Option<I8Vec2>; 2],
+    /// Two positions marking tunnel portals for wraparound teleportation ('T' characters)
+    pub tunnel_ends: [Option<I8Vec2>; 2],
+    /// Starting position for Pac-Man (marked by 'X' character in the layout)
+    pub pacman_start: Option<I8Vec2>,
 }
 
 /// Parser for converting raw board layouts into structured map data.
 pub struct MapTileParser;
 
 impl MapTileParser {
-    /// Parses a single character into a map tile.
+    /// Converts ASCII characters from the board layout into corresponding tile types.
     ///
-    /// # Arguments
+    /// Interprets the character-based maze representation: walls (`#`), collectible
+    /// pellets (`.` and `o`), traversable spaces (` `), tunnel entrances (`T`),
+    /// ghost house doors (`=`), and entity spawn markers (`X`). Special characters
+    /// that don't represent tiles in the final map (like spawn markers) are
+    /// converted to `Empty` tiles while their positions are tracked separately.
     ///
-    /// * `c` - The character to parse
+    /// # Errors
     ///
-    /// # Returns
-    ///
-    /// The parsed map tile, or an error if the character is unknown.
+    /// Returns `ParseError::UnknownCharacter` for any character not defined
+    /// in the game's ASCII art vocabulary.
     pub fn parse_character(c: char) -> Result<MapTile, ParseError> {
         match c {
             '#' => Ok(MapTile::Wall),
@@ -80,7 +88,7 @@ impl MapTileParser {
         let mut tiles = [[MapTile::Empty; BOARD_CELL_SIZE.y as usize]; BOARD_CELL_SIZE.x as usize];
         let mut house_door = [None; 2];
         let mut tunnel_ends = [None; 2];
-        let mut pacman_start: Option<IVec2> = None;
+        let mut pacman_start: Option<I8Vec2> = None;
 
         for (y, line) in raw_board.iter().enumerate().take(BOARD_CELL_SIZE.y as usize) {
             for (x, character) in line.chars().enumerate().take(BOARD_CELL_SIZE.x as usize) {
@@ -90,16 +98,16 @@ impl MapTileParser {
                 match tile {
                     MapTile::Tunnel => {
                         if tunnel_ends[0].is_none() {
-                            tunnel_ends[0] = Some(IVec2::new(x as i32, y as i32));
+                            tunnel_ends[0] = Some(I8Vec2::new(x as i8, y as i8));
                         } else {
-                            tunnel_ends[1] = Some(IVec2::new(x as i32, y as i32));
+                            tunnel_ends[1] = Some(I8Vec2::new(x as i8, y as i8));
                         }
                     }
                     MapTile::Wall if character == '=' => {
                         if house_door[0].is_none() {
-                            house_door[0] = Some(IVec2::new(x as i32, y as i32));
+                            house_door[0] = Some(I8Vec2::new(x as i8, y as i8));
                         } else {
-                            house_door[1] = Some(IVec2::new(x as i32, y as i32));
+                            house_door[1] = Some(I8Vec2::new(x as i8, y as i8));
                         }
                     }
                     _ => {}
@@ -107,7 +115,7 @@ impl MapTileParser {
 
                 // Track Pac-Man's starting position
                 if character == 'X' {
-                    pacman_start = Some(IVec2::new(x as i32, y as i32));
+                    pacman_start = Some(I8Vec2::new(x as i8, y as i8));
                 }
 
                 tiles[x][y] = tile;

src/map/render.rs

@@ -3,14 +3,10 @@
 use crate::constants::{BOARD_CELL_OFFSET, CELL_SIZE};
 use crate::map::layout::TILE_MAP;
 use crate::texture::sprite::{AtlasTile, SpriteAtlas};
-use crate::texture::text::TextTexture;
-use glam::Vec2;
 use sdl2::pixels::Color;
-use sdl2::rect::{Point, Rect};
+use sdl2::rect::Rect;
 use sdl2::render::{Canvas, RenderTarget};
 
-use crate::error::{EntityError, GameError, GameResult};
-
 /// Handles rendering operations for the map.
 pub struct MapRenderer;
 
@@ -19,7 +15,7 @@ impl MapRenderer {
     ///
     /// This function draws the static map texture to the screen at the correct
     /// position and scale.
-    pub fn render_map<T: RenderTarget>(canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, map_tiles: &mut [AtlasTile]) {
+    pub fn render_map<T: RenderTarget>(canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, map_tiles: &[AtlasTile]) {
         for (y, row) in TILE_MAP.iter().enumerate() {
             for (x, &tile_index) in row.iter().enumerate() {
                 let mut tile = map_tiles[tile_index];
@@ -37,111 +33,4 @@ impl MapRenderer {
             }
         }
     }
-
-    /// Renders a debug visualization with cursor-based highlighting.
-    ///
-    /// This function provides interactive debugging by highlighting the nearest node
-    /// to the cursor, showing its ID, and highlighting its connections.
-    pub fn debug_render_with_cursor<T: RenderTarget>(
-        graph: &crate::entity::graph::Graph,
-        canvas: &mut Canvas<T>,
-        text_renderer: &mut TextTexture,
-        atlas: &mut SpriteAtlas,
-        cursor_pos: Vec2,
-    ) -> GameResult<()> {
-        // Find the nearest node to the cursor
-        let nearest_node = Self::find_nearest_node(graph, cursor_pos);
-
-        // Draw all connections in blue
-        canvas.set_draw_color(Color::RGB(0, 0, 128)); // Dark blue for regular connections
-        for i in 0..graph.node_count() {
-            let node = graph.get_node(i).ok_or(GameError::Entity(EntityError::NodeNotFound(i)))?;
-            let pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-
-            for edge in graph.adjacency_list[i].edges() {
-                let end_pos = graph
-                    .get_node(edge.target)
-                    .ok_or(GameError::Entity(EntityError::NodeNotFound(edge.target)))?
-                    .position
-                    + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-                canvas
-                    .draw_line((pos.x as i32, pos.y as i32), (end_pos.x as i32, end_pos.y as i32))
-                    .map_err(|e| GameError::Sdl(e.to_string()))?;
-            }
-        }
-
-        // Draw all nodes in green
-        canvas.set_draw_color(Color::RGB(0, 128, 0)); // Dark green for regular nodes
-        for i in 0..graph.node_count() {
-            let node = graph.get_node(i).ok_or(GameError::Entity(EntityError::NodeNotFound(i)))?;
-            let pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-
-            canvas
-                .fill_rect(Rect::new(0, 0, 3, 3).centered_on(Point::new(pos.x as i32, pos.y as i32)))
-                .map_err(|e| GameError::Sdl(e.to_string()))?;
-        }
-
-        // Highlight connections from the nearest node in bright blue
-        if let Some(nearest_id) = nearest_node {
-            let nearest_pos = graph
-                .get_node(nearest_id)
-                .ok_or(GameError::Entity(EntityError::NodeNotFound(nearest_id)))?
-                .position
-                + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-
-            canvas.set_draw_color(Color::RGB(0, 255, 255)); // Bright cyan for highlighted connections
-            for edge in graph.adjacency_list[nearest_id].edges() {
-                let end_pos = graph
-                    .get_node(edge.target)
-                    .ok_or(GameError::Entity(EntityError::NodeNotFound(edge.target)))?
-                    .position
-                    + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-                canvas
-                    .draw_line(
-                        (nearest_pos.x as i32, nearest_pos.y as i32),
-                        (end_pos.x as i32, end_pos.y as i32),
-                    )
-                    .map_err(|e| GameError::Sdl(e.to_string()))?;
-            }
-
-            // Highlight the nearest node in bright green
-            canvas.set_draw_color(Color::RGB(0, 255, 0)); // Bright green for highlighted node
-            canvas
-                .fill_rect(Rect::new(0, 0, 5, 5).centered_on(Point::new(nearest_pos.x as i32, nearest_pos.y as i32)))
-                .map_err(|e| GameError::Sdl(e.to_string()))?;
-
-            // Draw node ID text (small, offset to top right)
-            text_renderer.set_scale(0.5); // Small text
-            let id_text = format!("#{nearest_id}");
-            let text_pos = glam::UVec2::new(
-                (nearest_pos.x + 4.0) as u32, // Offset to the right
-                (nearest_pos.y - 6.0) as u32, // Offset to the top
-            );
-            if let Err(e) = text_renderer.render(canvas, atlas, &id_text, text_pos) {
-                tracing::error!("Failed to render node ID text: {}", e);
-            }
-        }
-
-        Ok(())
-    }
-
-    /// Finds the nearest node to the given cursor position.
-    pub fn find_nearest_node(graph: &crate::entity::graph::Graph, cursor_pos: Vec2) -> Option<usize> {
-        let mut nearest_id = None;
-        let mut nearest_distance = f32::INFINITY;
-
-        for i in 0..graph.node_count() {
-            if let Some(node) = graph.get_node(i) {
-                let node_pos = node.position + crate::constants::BOARD_PIXEL_OFFSET.as_vec2();
-                let distance = cursor_pos.distance(node_pos);
-
-                if distance < nearest_distance {
-                    nearest_distance = distance;
-                    nearest_id = Some(i);
-                }
-            }
-        }
-
-        nearest_id
-    }
 }

src/platform/desktop.rs

@@ -3,76 +3,176 @@
 use std::borrow::Cow;
 use std::time::Duration;
 
+use rand::rngs::ThreadRng;
+
 use crate::asset::Asset;
 use crate::error::{AssetError, PlatformError};
-use crate::platform::Platform;
 
 /// Desktop platform implementation.
-pub struct DesktopPlatform;
-
-impl Platform for DesktopPlatform {
-    fn sleep(&self, duration: Duration) {
+pub fn sleep(duration: Duration, focused: bool) {
+    if focused {
         spin_sleep::sleep(duration);
-    }
-
-    fn get_time(&self) -> f64 {
-        std::time::Instant::now().elapsed().as_secs_f64()
-    }
-
-    fn init_console(&self) -> Result<(), PlatformError> {
-        #[cfg(windows)]
-        {
-            unsafe {
-                use winapi::{
-                    shared::ntdef::NULL,
-                    um::{
-                        fileapi::{CreateFileA, OPEN_EXISTING},
-                        handleapi::INVALID_HANDLE_VALUE,
-                        processenv::SetStdHandle,
-                        winbase::{STD_ERROR_HANDLE, STD_OUTPUT_HANDLE},
-                        wincon::{AttachConsole, GetConsoleWindow},
-                        winnt::{FILE_SHARE_READ, FILE_SHARE_WRITE, GENERIC_READ, GENERIC_WRITE},
-                    },
-                };
-
-                if !std::ptr::eq(GetConsoleWindow(), std::ptr::null_mut()) {
-                    return Ok(());
-                }
-
-                if AttachConsole(winapi::um::wincon::ATTACH_PARENT_PROCESS) != 0 {
-                    let handle = CreateFileA(
-                        c"CONOUT$".as_ptr(),
-                        GENERIC_READ | GENERIC_WRITE,
-                        FILE_SHARE_READ | FILE_SHARE_WRITE,
-                        std::ptr::null_mut(),
-                        OPEN_EXISTING,
-                        0,
-                        NULL,
-                    );
-
-                    if handle != INVALID_HANDLE_VALUE {
-                        SetStdHandle(STD_OUTPUT_HANDLE, handle);
-                        SetStdHandle(STD_ERROR_HANDLE, handle);
-                    }
-                }
-            }
-        }
-
-        Ok(())
-    }
-
-    fn get_canvas_size(&self) -> Option<(u32, u32)> {
-        None // Desktop doesn't need this
-    }
-
-    fn get_asset_bytes(&self, asset: Asset) -> Result<Cow<'static, [u8]>, AssetError> {
-        match asset {
-            Asset::Wav1 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/1.ogg"))),
-            Asset::Wav2 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/2.ogg"))),
-            Asset::Wav3 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/3.ogg"))),
-            Asset::Wav4 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/4.ogg"))),
-            Asset::Atlas => Ok(Cow::Borrowed(include_bytes!("../../assets/game/atlas.png"))),
-            Asset::AtlasJson => Ok(Cow::Borrowed(include_bytes!("../../assets/game/atlas.json"))),
-        }
+    } else {
+        std::thread::sleep(duration);
     }
 }
+
+pub fn init_console() -> Result<(), PlatformError> {
+    #[cfg(windows)]
+    {
+        use crate::platform::tracing_buffer::setup_switchable_subscriber;
+        use tracing::{debug, info};
+        use windows::Win32::System::Console::GetConsoleWindow;
+
+        // Setup buffered tracing subscriber that will buffer logs until console is ready
+        let switchable_writer = setup_switchable_subscriber();
+
+        // Check if we already have a console window
+        if unsafe { !GetConsoleWindow().0.is_null() } {
+            debug!("Already have a console window");
+            return Ok(());
+        } else {
+            debug!("No existing console window found");
+        }
+
+        if let Some(file_type) = is_output_setup()? {
+            debug!(r#type = file_type, "Existing output detected");
+        } else {
+            debug!("No existing output detected");
+
+            // Try to attach to parent console for direct cargo run
+            attach_to_parent_console()?;
+            info!("Successfully attached to parent console");
+        }
+
+        // Now that console is initialized, flush buffered logs and switch to direct output
+        debug!("Switching to direct logging mode and flushing buffer...");
+        if let Err(error) = switchable_writer.switch_to_direct_mode() {
+            use tracing::warn;
+
+            warn!("Failed to flush buffered logs to console: {error:?}");
+        }
+    }
+
+    Ok(())
+}
+
+pub fn get_asset_bytes(asset: Asset) -> Result<Cow<'static, [u8]>, AssetError> {
+    match asset {
+        Asset::Wav1 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/1.ogg"))),
+        Asset::Wav2 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/2.ogg"))),
+        Asset::Wav3 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/3.ogg"))),
+        Asset::Wav4 => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/waka/4.ogg"))),
+        Asset::AtlasImage => Ok(Cow::Borrowed(include_bytes!("../../assets/game/atlas.png"))),
+        Asset::Font => Ok(Cow::Borrowed(include_bytes!("../../assets/game/TerminalVector.ttf"))),
+        Asset::DeathSound => Ok(Cow::Borrowed(include_bytes!("../../assets/game/sound/pacman_death.wav"))),
+    }
+}
+
+pub fn rng() -> ThreadRng {
+    rand::rng()
+}
+
+/* Internal functions */
+
+/// Check if the output stream has been setup by a parent process
+/// Windows-only
+#[cfg(windows)]
+fn is_output_setup() -> Result<Option<&'static str>, PlatformError> {
+    use tracing::{debug, warn};
+
+    use windows::Win32::Storage::FileSystem::{
+        GetFileType, FILE_TYPE_CHAR, FILE_TYPE_DISK, FILE_TYPE_PIPE, FILE_TYPE_REMOTE, FILE_TYPE_UNKNOWN,
+    };
+
+    use windows_sys::Win32::{
+        Foundation::INVALID_HANDLE_VALUE,
+        System::Console::{GetStdHandle, STD_OUTPUT_HANDLE},
+    };
+
+    // Get the process's standard output handle, check if it's invalid
+    let handle = match unsafe { GetStdHandle(STD_OUTPUT_HANDLE) } {
+        INVALID_HANDLE_VALUE => {
+            return Err(PlatformError::ConsoleInit("Invalid handle".to_string()));
+        }
+        handle => handle,
+    };
+
+    // Identify the file type of the handle and whether it's 'well known' (i.e. we trust it to be a reasonable output destination)
+    let (well_known, file_type) = match unsafe {
+        use windows::Win32::Foundation::HANDLE;
+        GetFileType(HANDLE(handle))
+    } {
+        FILE_TYPE_PIPE => (true, "pipe"),
+        FILE_TYPE_CHAR => (true, "char"),
+        FILE_TYPE_DISK => (true, "disk"),
+        FILE_TYPE_UNKNOWN => (false, "unknown"),
+        FILE_TYPE_REMOTE => (false, "remote"),
+        unexpected => {
+            warn!("Unexpected file type: {unexpected:?}");
+            (false, "unknown")
+        }
+    };
+
+    debug!("File type: {file_type:?}, well known: {well_known}");
+
+    // If it's anything recognizable and valid, assume that a parent process has setup an output stream
+    Ok(well_known.then_some(file_type))
+}
+
+/// Try to attach to parent console
+/// Windows-only
+#[cfg(windows)]
+fn attach_to_parent_console() -> Result<(), PlatformError> {
+    use windows::{
+        core::PCSTR,
+        Win32::{
+            Foundation::{GENERIC_READ, GENERIC_WRITE},
+            Storage::FileSystem::{CreateFileA, FILE_FLAGS_AND_ATTRIBUTES, FILE_SHARE_READ, FILE_SHARE_WRITE, OPEN_EXISTING},
+            System::Console::{
+                AttachConsole, FreeConsole, SetStdHandle, ATTACH_PARENT_PROCESS, STD_ERROR_HANDLE, STD_OUTPUT_HANDLE,
+            },
+        },
+    };
+
+    // Attach the process to the parent's console
+    unsafe { AttachConsole(ATTACH_PARENT_PROCESS) }
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to attach to parent console: {:?}", e)))?;
+
+    let handle = unsafe {
+        let pcstr = PCSTR::from_raw(c"CONOUT$".as_ptr() as *const u8);
+        CreateFileA::<PCSTR>(
+            pcstr,
+            (GENERIC_READ | GENERIC_WRITE).0,
+            FILE_SHARE_READ | FILE_SHARE_WRITE,
+            None,
+            OPEN_EXISTING,
+            FILE_FLAGS_AND_ATTRIBUTES(0),
+            None,
+        )
+    }
+    .map_err(|e| PlatformError::ConsoleInit(format!("Failed to create console handle: {:?}", e)))?;
+
+    // Set the console's output and then error handles
+    if let Some(handle_error) = unsafe { SetStdHandle(STD_OUTPUT_HANDLE, handle) }
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set console output handle: {:?}", e)))
+        .and_then(|_| {
+            unsafe { SetStdHandle(STD_ERROR_HANDLE, handle) }
+                .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set console error handle: {:?}", e)))
+        })
+        .err()
+    {
+        // If either set handle call fails, free the console
+        unsafe { FreeConsole() }
+            // Free the console if the SetStdHandle calls fail
+            .map_err(|free_error| {
+                PlatformError::ConsoleInit(format!(
+                    "Failed to free console after SetStdHandle failed: {free_error:?} ({handle_error:?})"
+                ))
+            })
+            // And then return the original error if the FreeConsole call succeeds
+            .and(Err(handle_error))?;
+    }
+
+    Ok(())
+}

src/platform/emscripten.rs

@@ -1,62 +1,96 @@
 //! Emscripten platform implementation.
 
-use std::borrow::Cow;
-use std::time::Duration;
-
 use crate::asset::Asset;
 use crate::error::{AssetError, PlatformError};
-use crate::platform::Platform;
-
-/// Emscripten platform implementation.
-pub struct EmscriptenPlatform;
-
-impl Platform for EmscriptenPlatform {
-    fn sleep(&self, duration: Duration) {
-        unsafe {
-            emscripten_sleep(duration.as_millis() as u32);
-        }
-    }
-
-    fn get_time(&self) -> f64 {
-        unsafe { emscripten_get_now() }
-    }
-
-    fn init_console(&self) -> Result<(), PlatformError> {
-        Ok(()) // No-op for Emscripten
-    }
-
-    fn get_canvas_size(&self) -> Option<(u32, u32)> {
-        Some(unsafe { get_canvas_size() })
-    }
-
-    fn get_asset_bytes(&self, asset: Asset) -> Result<Cow<'static, [u8]>, AssetError> {
-        use sdl2::rwops::RWops;
-        use std::io::Read;
-
-        let path = format!("assets/game/{}", asset.path());
-        let mut rwops = RWops::from_file(&path, "rb").map_err(|_| AssetError::NotFound(asset.path().to_string()))?;
-
-        let len = rwops.len().ok_or_else(|| AssetError::NotFound(asset.path().to_string()))?;
-
-        let mut buf = vec![0u8; len];
-        rwops
-            .read_exact(&mut buf)
-            .map_err(|e| AssetError::Io(std::io::Error::other(e)))?;
-
-        Ok(Cow::Owned(buf))
-    }
-}
+use crate::formatter::CustomFormatter;
+use rand::{rngs::SmallRng, SeedableRng};
+use sdl2::rwops::RWops;
+use std::borrow::Cow;
+use std::ffi::CString;
+use std::io::{self, Read, Write};
+use std::time::Duration;
 
 // Emscripten FFI functions
+#[allow(dead_code)]
 extern "C" {
-    fn emscripten_get_now() -> f64;
     fn emscripten_sleep(ms: u32);
     fn emscripten_get_element_css_size(target: *const u8, width: *mut f64, height: *mut f64) -> i32;
+    // Standard C functions that Emscripten redirects to console
+    fn printf(format: *const u8, ...) -> i32;
 }
 
-unsafe fn get_canvas_size() -> (u32, u32) {
+pub fn sleep(duration: Duration, _focused: bool) {
+    unsafe {
+        emscripten_sleep(duration.as_millis() as u32);
+    }
+}
+
+pub fn init_console() -> Result<(), PlatformError> {
+    use tracing_subscriber::{fmt, layer::SubscriberExt, EnvFilter};
+
+    // Set up a custom tracing subscriber that writes directly to emscripten console
+    let subscriber = tracing_subscriber::registry()
+        .with(
+            fmt::layer()
+                .with_writer(|| EmscriptenConsoleWriter)
+                .with_ansi(false)
+                .event_format(CustomFormatter),
+        )
+        .with(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("debug")));
+
+    tracing::subscriber::set_global_default(subscriber)
+        .map_err(|e| PlatformError::ConsoleInit(format!("Failed to set tracing subscriber: {}", e)))?;
+
+    Ok(())
+}
+
+/// A writer that outputs to the browser console via printf (redirected by emscripten)
+struct EmscriptenConsoleWriter;
+
+impl Write for EmscriptenConsoleWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        if let Ok(s) = std::str::from_utf8(buf) {
+            if let Ok(cstr) = CString::new(s.trim_end_matches('\n')) {
+                let format_str = CString::new("%s\n").unwrap();
+                unsafe {
+                    printf(format_str.as_ptr().cast(), cstr.as_ptr());
+                }
+            }
+        }
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+#[allow(dead_code)]
+pub fn get_canvas_size() -> Option<(u32, u32)> {
     let mut width = 0.0;
     let mut height = 0.0;
-    emscripten_get_element_css_size(c"canvas".as_ptr().cast(), &mut width, &mut height);
-    (width as u32, height as u32)
+
+    unsafe {
+        emscripten_get_element_css_size(c"canvas".as_ptr().cast(), &mut width, &mut height);
+        if width == 0.0 || height == 0.0 {
+            return None;
+        }
+    }
+    Some((width as u32, height as u32))
+}
+
+pub fn get_asset_bytes(asset: Asset) -> Result<Cow<'static, [u8]>, AssetError> {
+    let path = format!("assets/game/{}", asset.path());
+    let mut rwops = RWops::from_file(&path, "rb").map_err(|_| AssetError::NotFound(asset.path().to_string()))?;
+
+    let len = rwops.len().ok_or_else(|| AssetError::NotFound(asset.path().to_string()))?;
+
+    let mut buf = vec![0u8; len];
+    rwops.read_exact(&mut buf).map_err(|e| AssetError::Io(io::Error::other(e)))?;
+
+    Ok(Cow::Owned(buf))
+}
+
+pub fn rng() -> SmallRng {
+    SmallRng::from_os_rng()
 }

src/platform/mod.rs

@@ -1,48 +1,13 @@
 //! Platform abstraction layer for cross-platform functionality.
 
-use crate::asset::Asset;
-use crate::error::{AssetError, PlatformError};
-use std::borrow::Cow;
-use std::time::Duration;
+#[cfg(not(target_os = "emscripten"))]
+mod desktop;
+#[cfg(not(target_os = "emscripten"))]
+pub mod tracing_buffer;
+#[cfg(not(target_os = "emscripten"))]
+pub use desktop::*;
 
-pub mod desktop;
-pub mod emscripten;
-
-/// Platform abstraction trait that defines cross-platform functionality.
-pub trait Platform {
-    /// Sleep for the specified duration using platform-appropriate method.
-    fn sleep(&self, duration: Duration);
-
-    /// Get the current time in seconds since some reference point.
-    /// This is available for future use in timing and performance monitoring.
-    #[allow(dead_code)]
-    fn get_time(&self) -> f64;
-
-    /// Initialize platform-specific console functionality.
-    fn init_console(&self) -> Result<(), PlatformError>;
-
-    /// Get canvas size for platforms that need it (e.g., Emscripten).
-    /// This is available for future use in responsive design.
-    #[allow(dead_code)]
-    fn get_canvas_size(&self) -> Option<(u32, u32)>;
-
-    /// Load asset bytes using platform-appropriate method.
-    fn get_asset_bytes(&self, asset: Asset) -> Result<Cow<'static, [u8]>, AssetError>;
-}
-
-/// Get the current platform implementation.
-#[allow(dead_code)]
-pub fn get_platform() -> &'static dyn Platform {
-    static DESKTOP: desktop::DesktopPlatform = desktop::DesktopPlatform;
-    static EMSCRIPTEN: emscripten::EmscriptenPlatform = emscripten::EmscriptenPlatform;
-
-    #[cfg(not(target_os = "emscripten"))]
-    {
-        &DESKTOP
-    }
-
-    #[cfg(target_os = "emscripten")]
-    {
-        &EMSCRIPTEN
-    }
-}
+#[cfg(target_os = "emscripten")]
+pub use emscripten::*;
+#[cfg(target_os = "emscripten")]
+mod emscripten;

src/platform/tracing_buffer.rs

@@ -0,0 +1,153 @@
+#![allow(dead_code)]
+//! Buffered tracing setup for handling logs before console attachment.
+
+use crate::formatter::CustomFormatter;
+use parking_lot::Mutex;
+use std::io;
+use std::io::Write;
+use std::sync::Arc;
+use tracing::{debug, Level};
+use tracing_error::ErrorLayer;
+use tracing_subscriber::fmt::MakeWriter;
+use tracing_subscriber::layer::SubscriberExt;
+
+/// A thread-safe buffered writer that stores logs in memory until flushed.
+#[derive(Clone)]
+pub struct BufferedWriter {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+impl BufferedWriter {
+    /// Creates a new buffered writer.
+    pub fn new() -> Self {
+        Self {
+            buffer: Arc::new(Mutex::new(Vec::new())),
+        }
+    }
+
+    /// Flushes all buffered content to the provided writer and clears the buffer.
+    pub fn flush_to<W: Write>(&self, mut writer: W) -> io::Result<()> {
+        let mut buffer = self.buffer.lock();
+        if !buffer.is_empty() {
+            writer.write_all(&buffer)?;
+            writer.flush()?;
+            buffer.clear();
+        }
+        Ok(())
+    }
+
+    /// Returns the current buffer size in bytes.
+    pub fn buffer_size(&self) -> usize {
+        self.buffer.lock().len()
+    }
+}
+
+impl Write for BufferedWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        let mut buffer = self.buffer.lock();
+        buffer.extend_from_slice(buf);
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        // For buffered writer, flush is a no-op since we're storing in memory
+        Ok(())
+    }
+}
+
+impl Default for BufferedWriter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// A writer that can switch between buffering and direct output.
+#[derive(Clone, Default)]
+pub struct SwitchableWriter {
+    buffered_writer: BufferedWriter,
+    direct_mode: std::sync::Arc<parking_lot::Mutex<bool>>,
+}
+
+impl SwitchableWriter {
+    pub fn switch_to_direct_mode(&self) -> io::Result<()> {
+        let buffer_size = {
+            // Acquire the lock
+            let mut mode = self.direct_mode.lock();
+
+            // Get buffer size before flushing for debug logging
+            let buffer_size = self.buffered_writer.buffer_size();
+
+            // Flush any buffered content
+            self.buffered_writer.flush_to(io::stdout())?;
+
+            // Switch to direct mode (and drop the lock)
+            *mode = true;
+
+            buffer_size
+        };
+
+        // Log how much was buffered (this will now go directly to stdout)
+        debug!("Flushed {buffer_size:?} bytes of buffered logs to console");
+
+        Ok(())
+    }
+}
+
+impl io::Write for SwitchableWriter {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        if *self.direct_mode.lock() {
+            io::stdout().write(buf)
+        } else {
+            self.buffered_writer.clone().write(buf)
+        }
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        if *self.direct_mode.lock() {
+            io::stdout().flush()
+        } else {
+            // For buffered mode, flush is a no-op
+            Ok(())
+        }
+    }
+}
+
+/// A make writer that uses the switchable writer.
+#[derive(Clone)]
+pub struct SwitchableMakeWriter {
+    writer: SwitchableWriter,
+}
+
+impl SwitchableMakeWriter {
+    pub fn new(writer: SwitchableWriter) -> Self {
+        Self { writer }
+    }
+}
+
+impl<'a> MakeWriter<'a> for SwitchableMakeWriter {
+    type Writer = SwitchableWriter;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        self.writer.clone()
+    }
+}
+
+/// Sets up a switchable tracing subscriber that can transition from buffered to direct output.
+///
+/// Returns the switchable writer that can be used to control the behavior.
+pub fn setup_switchable_subscriber() -> SwitchableWriter {
+    let switchable_writer = SwitchableWriter::default();
+    let make_writer = SwitchableMakeWriter::new(switchable_writer.clone());
+
+    let _subscriber = tracing_subscriber::fmt()
+        .with_ansi(cfg!(not(target_os = "emscripten")))
+        .with_max_level(Level::DEBUG)
+        .event_format(CustomFormatter)
+        .with_writer(make_writer)
+        .finish()
+        .with(ErrorLayer::default());
+
+    tracing::subscriber::set_global_default(_subscriber).expect("Could not set global default switchable subscriber");
+
+    switchable_writer
+}

src/systems/audio.rs

@@ -0,0 +1,78 @@
+//! Audio system for handling sound playback in the Pac-Man game.
+//!
+//! This module provides an ECS-based audio system that integrates with SDL2_mixer
+//! for playing sound effects. The system uses NonSendMut resources to handle SDL2's
+//! main-thread requirements while maintaining Bevy ECS compatibility.
+
+use bevy_ecs::{
+    event::{Event, EventReader, EventWriter},
+    resource::Resource,
+    system::{NonSendMut, ResMut},
+};
+
+use crate::{audio::Audio, error::GameError};
+
+/// Resource for tracking audio state
+#[derive(Resource, Debug, Clone, Default)]
+pub struct AudioState {
+    /// Whether audio is currently muted
+    pub muted: bool,
+    /// Current sound index for cycling through eat sounds
+    pub sound_index: usize,
+}
+
+/// Events for triggering audio playback
+#[derive(Event, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AudioEvent {
+    /// Play the "eat" sound when Pac-Man consumes a pellet
+    PlayEat,
+    /// Play the death sound
+    PlayDeath,
+    /// Stop all currently playing sounds
+    StopAll,
+}
+
+/// Non-send resource wrapper for SDL2 audio system
+///
+/// This wrapper is needed because SDL2 audio components are not Send,
+/// but Bevy ECS requires Send for regular resources. Using NonSendMut
+/// allows us to use SDL2 audio on the main thread while integrating
+/// with the ECS system.
+pub struct AudioResource(pub Audio);
+
+/// System that processes audio events and plays sounds
+pub fn audio_system(
+    mut audio: NonSendMut<AudioResource>,
+    mut audio_state: ResMut<AudioState>,
+    mut audio_events: EventReader<AudioEvent>,
+    _errors: EventWriter<GameError>,
+) {
+    // Set mute state if it has changed
+    if audio.0.is_muted() != audio_state.muted {
+        audio.0.set_mute(audio_state.muted);
+    }
+
+    // Process audio events
+    for event in audio_events.read() {
+        match event {
+            AudioEvent::PlayEat => {
+                if !audio.0.is_disabled() && !audio_state.muted {
+                    audio.0.eat();
+                    // Update the sound index for cycling through sounds
+                    audio_state.sound_index = (audio_state.sound_index + 1) % 4;
+                    // 4 eat sounds available
+                }
+            }
+            AudioEvent::PlayDeath => {
+                if !audio.0.is_disabled() && !audio_state.muted {
+                    audio.0.death();
+                }
+            }
+            AudioEvent::StopAll => {
+                if !audio.0.is_disabled() {
+                    audio.0.stop_all();
+                }
+            }
+        }
+    }
+}

src/systems/blinking.rs

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

src/systems/collision.rs

@@ -0,0 +1,163 @@
+use bevy_ecs::{
+    component::Component,
+    entity::Entity,
+    event::{EventReader, EventWriter},
+    query::With,
+    system::{Commands, Query, Res, ResMut},
+};
+
+use crate::error::GameError;
+use crate::events::GameEvent;
+use crate::map::builder::Map;
+use crate::systems::{
+    components::GhostState, movement::Position, AudioEvent, DyingSequence, Frozen, GameStage, Ghost, PlayerControlled,
+    ScoreResource,
+};
+
+/// A component for defining the collision area of an entity.
+#[derive(Component)]
+pub struct Collider {
+    pub size: f32,
+}
+
+impl Collider {
+    /// Checks if this collider collides with another collider at the given distance.
+    pub fn collides_with(&self, other_size: f32, distance: f32) -> bool {
+        let collision_distance = (self.size + other_size) / 2.0;
+        distance < collision_distance
+    }
+}
+
+/// Marker components for collision filtering optimization
+#[derive(Component)]
+pub struct PacmanCollider;
+
+#[derive(Component)]
+pub struct GhostCollider;
+
+#[derive(Component)]
+pub struct ItemCollider;
+
+/// Helper function to check collision between two entities with colliders.
+pub fn check_collision(
+    pos1: &Position,
+    collider1: &Collider,
+    pos2: &Position,
+    collider2: &Collider,
+    map: &Map,
+) -> Result<bool, GameError> {
+    let pixel1 = pos1
+        .get_pixel_position(&map.graph)
+        .map_err(|e| GameError::InvalidState(format!("Failed to get pixel position for entity 1: {}", e)))?;
+    let pixel2 = pos2
+        .get_pixel_position(&map.graph)
+        .map_err(|e| GameError::InvalidState(format!("Failed to get pixel position for entity 2: {}", e)))?;
+
+    let distance = pixel1.distance(pixel2);
+    Ok(collider1.collides_with(collider2.size, distance))
+}
+
+/// Detects overlapping entities and generates collision events for gameplay systems.
+///
+/// Performs distance-based collision detection between Pac-Man and collectible items
+/// using each entity's position and collision radius. When entities overlap, emits
+/// a `GameEvent::Collision` for the item system to handle scoring and removal.
+/// Collision detection accounts for both entities being in motion and supports
+/// circular collision boundaries for accurate gameplay feel.
+///
+/// Also detects collisions between Pac-Man and ghosts for gameplay mechanics like
+/// power pellet effects, ghost eating, and player death.
+#[allow(clippy::too_many_arguments)]
+pub fn collision_system(
+    map: Res<Map>,
+    pacman_query: Query<(Entity, &Position, &Collider), With<PacmanCollider>>,
+    item_query: Query<(Entity, &Position, &Collider), With<ItemCollider>>,
+    ghost_query: Query<(Entity, &Position, &Collider), With<GhostCollider>>,
+    mut events: EventWriter<GameEvent>,
+    mut errors: EventWriter<GameError>,
+) {
+    // Check PACMAN × ITEM collisions
+    for (pacman_entity, pacman_pos, pacman_collider) in pacman_query.iter() {
+        for (item_entity, item_pos, item_collider) in item_query.iter() {
+            match check_collision(pacman_pos, pacman_collider, item_pos, item_collider, &map) {
+                Ok(colliding) => {
+                    if colliding {
+                        events.write(GameEvent::Collision(pacman_entity, item_entity));
+                    }
+                }
+                Err(e) => {
+                    errors.write(GameError::InvalidState(format!(
+                        "Collision system failed to check collision between entities {:?} and {:?}: {}",
+                        pacman_entity, item_entity, e
+                    )));
+                }
+            }
+        }
+
+        // Check PACMAN × GHOST collisions
+        for (ghost_entity, ghost_pos, ghost_collider) in ghost_query.iter() {
+            match check_collision(pacman_pos, pacman_collider, ghost_pos, ghost_collider, &map) {
+                Ok(colliding) => {
+                    if colliding {
+                        events.write(GameEvent::Collision(pacman_entity, ghost_entity));
+                    }
+                }
+                Err(e) => {
+                    errors.write(GameError::InvalidState(format!(
+                        "Collision system failed to check collision between entities {:?} and {:?}: {}",
+                        pacman_entity, ghost_entity, e
+                    )));
+                }
+            }
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn ghost_collision_system(
+    mut commands: Commands,
+    mut collision_events: EventReader<GameEvent>,
+    mut score: ResMut<ScoreResource>,
+    mut game_state: ResMut<GameStage>,
+    pacman_query: Query<Entity, With<PlayerControlled>>,
+    ghost_query: Query<(Entity, &Ghost), With<GhostCollider>>,
+    mut ghost_state_query: Query<&mut GhostState>,
+    mut events: EventWriter<AudioEvent>,
+) {
+    for event in collision_events.read() {
+        if let GameEvent::Collision(entity1, entity2) = event {
+            // Check if one is Pacman and the other is a ghost
+            let (pacman_entity, ghost_entity) = if pacman_query.get(*entity1).is_ok() && ghost_query.get(*entity2).is_ok() {
+                (*entity1, *entity2)
+            } else if pacman_query.get(*entity2).is_ok() && ghost_query.get(*entity1).is_ok() {
+                (*entity2, *entity1)
+            } else {
+                continue;
+            };
+
+            // Check if the ghost is frightened
+            if let Ok((ghost_ent, _ghost_type)) = ghost_query.get(ghost_entity) {
+                if let Ok(mut ghost_state) = ghost_state_query.get_mut(ghost_ent) {
+                    // Check if ghost is in frightened state
+                    if matches!(*ghost_state, GhostState::Frightened { .. }) {
+                        // Pac-Man eats the ghost
+                        // Add score (200 points per ghost eaten)
+                        score.0 += 200;
+
+                        // Set ghost state to Eyes
+                        *ghost_state = GhostState::Eyes;
+
+                        // Play eat sound
+                        events.write(AudioEvent::PlayEat);
+                    } else if matches!(*ghost_state, GhostState::Normal) {
+                        // Pac-Man dies
+                        *game_state = GameStage::PlayerDying(DyingSequence::Frozen { remaining_ticks: 60 });
+                        commands.entity(pacman_entity).insert(Frozen);
+                        commands.entity(ghost_entity).insert(Frozen);
+                        events.write(AudioEvent::StopAll);
+                    }
+                }
+            }
+        }
+    }
+}

src/systems/components.rs

@@ -0,0 +1,403 @@
+use std::collections::HashMap;
+
+use bevy_ecs::{bundle::Bundle, component::Component, resource::Resource};
+use bitflags::bitflags;
+
+use crate::{
+    map::graph::TraversalFlags,
+    systems::{
+        movement::{BufferedDirection, Position, Velocity},
+        Collider, GhostCollider, ItemCollider, PacmanCollider,
+    },
+    texture::{
+        animated::{DirectionalTiles, TileSequence},
+        sprite::AtlasTile,
+    },
+};
+
+/// A tag component for entities that are controlled by the player.
+#[derive(Default, Component)]
+pub struct PlayerControlled;
+
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Ghost {
+    Blinky,
+    Pinky,
+    Inky,
+    Clyde,
+}
+
+impl Ghost {
+    /// Returns the ghost type name for atlas lookups.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Ghost::Blinky => "blinky",
+            Ghost::Pinky => "pinky",
+            Ghost::Inky => "inky",
+            Ghost::Clyde => "clyde",
+        }
+    }
+
+    /// Returns the base movement speed for this ghost type.
+    pub fn base_speed(self) -> f32 {
+        match self {
+            Ghost::Blinky => 1.0,
+            Ghost::Pinky => 0.95,
+            Ghost::Inky => 0.9,
+            Ghost::Clyde => 0.85,
+        }
+    }
+
+    /// Returns the ghost's color for debug rendering.
+    #[allow(dead_code)]
+    pub fn debug_color(&self) -> sdl2::pixels::Color {
+        match self {
+            Ghost::Blinky => sdl2::pixels::Color::RGB(255, 0, 0),    // Red
+            Ghost::Pinky => sdl2::pixels::Color::RGB(255, 182, 255), // Pink
+            Ghost::Inky => sdl2::pixels::Color::RGB(0, 255, 255),    // Cyan
+            Ghost::Clyde => sdl2::pixels::Color::RGB(255, 182, 85),  // Orange
+        }
+    }
+}
+
+/// A tag component denoting the type of entity.
+#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum EntityType {
+    Player,
+    Ghost,
+    Pellet,
+    PowerPellet,
+}
+
+impl EntityType {
+    /// Returns the traversal flags for this entity type.
+    pub fn traversal_flags(&self) -> TraversalFlags {
+        match self {
+            EntityType::Player => TraversalFlags::PACMAN,
+            EntityType::Ghost => TraversalFlags::GHOST,
+            _ => TraversalFlags::empty(), // Static entities don't traverse
+        }
+    }
+    pub fn score_value(&self) -> Option<u32> {
+        match self {
+            EntityType::Pellet => Some(10),
+            EntityType::PowerPellet => Some(50),
+            _ => None,
+        }
+    }
+
+    pub fn is_collectible(&self) -> bool {
+        matches!(self, EntityType::Pellet | EntityType::PowerPellet)
+    }
+}
+
+/// 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,
+}
+
+/// Directional animation component with shared timing across all directions
+#[derive(Component, Clone)]
+pub struct DirectionalAnimation {
+    pub moving_tiles: DirectionalTiles,
+    pub stopped_tiles: DirectionalTiles,
+    pub current_frame: usize,
+    pub time_bank: u16,
+    pub frame_duration: u16,
+}
+
+impl DirectionalAnimation {
+    /// Creates a new directional animation with the given tiles and frame duration
+    pub fn new(moving_tiles: DirectionalTiles, stopped_tiles: DirectionalTiles, frame_duration: u16) -> Self {
+        Self {
+            moving_tiles,
+            stopped_tiles,
+            current_frame: 0,
+            time_bank: 0,
+            frame_duration,
+        }
+    }
+}
+
+/// Tag component to mark animations that should loop when they reach the end
+#[derive(Component, Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Looping;
+
+/// Linear animation component for non-directional animations (frightened ghosts)
+#[derive(Component, Resource, Clone)]
+pub struct LinearAnimation {
+    pub tiles: TileSequence,
+    pub current_frame: usize,
+    pub time_bank: u16,
+    pub frame_duration: u16,
+    pub finished: bool,
+}
+
+impl LinearAnimation {
+    /// Creates a new linear animation with the given tiles and frame duration
+    pub fn new(tiles: TileSequence, frame_duration: u16) -> Self {
+        Self {
+            tiles,
+            current_frame: 0,
+            time_bank: 0,
+            frame_duration,
+            finished: false,
+        }
+    }
+}
+
+bitflags! {
+    #[derive(Component, Default, Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+    pub struct CollisionLayer: u8 {
+        const PACMAN = 1 << 0;
+        const GHOST = 1 << 1;
+        const ITEM = 1 << 2;
+    }
+}
+
+#[derive(Resource)]
+pub struct GlobalState {
+    pub exit: bool,
+}
+
+#[derive(Resource)]
+pub struct ScoreResource(pub u32);
+
+#[derive(Resource)]
+pub struct DeltaTime {
+    /// Floating-point delta time in seconds
+    pub seconds: f32,
+    /// Integer tick delta (usually 1, but can be different for testing)
+    pub ticks: u32,
+}
+
+#[allow(dead_code)]
+impl DeltaTime {
+    /// Creates a new DeltaTime from a floating-point delta time in seconds
+    ///
+    /// While this method exists as a helper, it does not mean that seconds and ticks are interchangeable.
+    pub fn from_seconds(seconds: f32) -> Self {
+        Self {
+            seconds,
+            ticks: (seconds * 60.0).round() as u32,
+        }
+    }
+
+    /// Creates a new DeltaTime from an integer tick delta
+    ///
+    /// While this method exists as a helper, it does not mean that seconds and ticks are interchangeable.
+    pub fn from_ticks(ticks: u32) -> Self {
+        Self {
+            seconds: ticks as f32 / 60.0,
+            ticks,
+        }
+    }
+}
+
+/// Movement modifiers that can affect Pac-Man's speed or handling.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct MovementModifiers {
+    /// Multiplier applied to base speed (e.g., tunnels)
+    pub speed_multiplier: f32,
+    /// True when currently in a tunnel slowdown region
+    pub tunnel_slowdown_active: bool,
+}
+
+impl Default for MovementModifiers {
+    fn default() -> Self {
+        Self {
+            speed_multiplier: 1.0,
+            tunnel_slowdown_active: false,
+        }
+    }
+}
+
+/// Tag component for entities that should be frozen during startup
+#[derive(Component, Debug, Clone, Copy)]
+pub struct Frozen;
+
+/// Tag component for eaten ghosts
+#[derive(Component, Debug, Clone, Copy)]
+pub struct Eaten;
+
+/// Tag component for Pac-Man during his death animation.
+/// This is mainly because the Frozen tag would stop both movement and animation, while the Dying tag can signal that the animation should continue despite being frozen.
+#[derive(Component, Debug, Clone, Copy)]
+pub struct Dying;
+
+#[derive(Component, Debug, Clone, Copy)]
+pub enum GhostState {
+    /// Normal ghost behavior - chasing Pac-Man
+    Normal,
+    /// Frightened state after power pellet - ghost can be eaten
+    Frightened {
+        remaining_ticks: u32,
+        flash: bool,
+        remaining_flash_ticks: u32,
+    },
+    /// Eyes state - ghost has been eaten and is returning to ghost house
+    Eyes,
+}
+
+/// Component to track the last animation state for efficient change detection
+#[derive(Component, Debug, Clone, Copy, PartialEq)]
+pub struct LastAnimationState(pub GhostAnimation);
+
+impl GhostState {
+    /// Creates a new frightened state with the specified duration
+    pub fn new_frightened(total_ticks: u32, flash_start_ticks: u32) -> Self {
+        Self::Frightened {
+            remaining_ticks: total_ticks,
+            flash: false,
+            remaining_flash_ticks: flash_start_ticks, // Time until flashing starts
+        }
+    }
+
+    /// Ticks the ghost state, returning true if the state changed.
+    pub fn tick(&mut self) -> bool {
+        if let GhostState::Frightened {
+            remaining_ticks,
+            flash,
+            remaining_flash_ticks,
+        } = self
+        {
+            // Transition out of frightened state
+            if *remaining_ticks == 0 {
+                *self = GhostState::Normal;
+                return true;
+            }
+
+            *remaining_ticks -= 1;
+
+            if *remaining_flash_ticks > 0 {
+                *remaining_flash_ticks = remaining_flash_ticks.saturating_sub(1);
+                if *remaining_flash_ticks == 0 {
+                    *flash = true;
+                    true
+                } else {
+                    false
+                }
+            } else {
+                false
+            }
+        } else {
+            false
+        }
+    }
+
+    /// Returns the appropriate animation state for this ghost state
+    pub fn animation_state(&self) -> GhostAnimation {
+        match self {
+            GhostState::Normal => GhostAnimation::Normal,
+            GhostState::Eyes => GhostAnimation::Eyes,
+            GhostState::Frightened { flash: false, .. } => GhostAnimation::Frightened { flash: false },
+            GhostState::Frightened { flash: true, .. } => GhostAnimation::Frightened { flash: true },
+        }
+    }
+}
+
+/// Enumeration of different ghost animation states.
+/// Note that this is used in micromap which has a fixed size based on the number of variants,
+/// so extending this should be done with caution, and will require updating the micromap's capacity.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum GhostAnimation {
+    /// Normal ghost appearance with directional movement animations
+    Normal,
+    /// Blue ghost appearance when vulnerable (power pellet active)
+    Frightened { flash: bool },
+    /// Eyes-only animation when ghost has been consumed by Pac-Man (Eaten state)
+    Eyes,
+}
+
+/// Global resource containing pre-loaded animation sets for all ghost types.
+///
+/// This resource is initialized once during game startup and provides O(1) access
+/// to animation sets for each ghost type. The animation system uses this resource
+/// to efficiently switch between different ghost states without runtime asset loading.
+///
+/// The HashMap is keyed by `Ghost` enum variants (Blinky, Pinky, Inky, Clyde) and
+/// contains the normal directional animation for each ghost type.
+#[derive(Resource)]
+pub struct GhostAnimations {
+    pub normal: HashMap<Ghost, DirectionalAnimation>,
+    pub eyes: DirectionalAnimation,
+    pub frightened: LinearAnimation,
+    pub frightened_flashing: LinearAnimation,
+}
+
+impl GhostAnimations {
+    /// Creates a new GhostAnimations resource with the provided data.
+    pub fn new(
+        normal: HashMap<Ghost, DirectionalAnimation>,
+        eyes: DirectionalAnimation,
+        frightened: LinearAnimation,
+        frightened_flashing: LinearAnimation,
+    ) -> Self {
+        Self {
+            normal,
+            eyes,
+            frightened,
+            frightened_flashing,
+        }
+    }
+
+    /// Gets the normal directional animation for the specified ghost type.
+    pub fn get_normal(&self, ghost_type: &Ghost) -> Option<&DirectionalAnimation> {
+        self.normal.get(ghost_type)
+    }
+
+    /// Gets the eyes animation (shared across all ghosts).
+    pub fn eyes(&self) -> &DirectionalAnimation {
+        &self.eyes
+    }
+
+    /// Gets the frightened animations (shared across all ghosts).
+    pub fn frightened(&self, flash: bool) -> &LinearAnimation {
+        if flash {
+            &self.frightened_flashing
+        } else {
+            &self.frightened
+        }
+    }
+}
+
+#[derive(Bundle)]
+pub struct PlayerBundle {
+    pub player: PlayerControlled,
+    pub position: Position,
+    pub velocity: Velocity,
+    pub buffered_direction: BufferedDirection,
+    pub sprite: Renderable,
+    pub directional_animation: DirectionalAnimation,
+    pub entity_type: EntityType,
+    pub collider: Collider,
+    pub movement_modifiers: MovementModifiers,
+    pub pacman_collider: PacmanCollider,
+}
+
+#[derive(Bundle)]
+pub struct ItemBundle {
+    pub position: Position,
+    pub sprite: Renderable,
+    pub entity_type: EntityType,
+    pub collider: Collider,
+    pub item_collider: ItemCollider,
+}
+
+#[derive(Bundle)]
+pub struct GhostBundle {
+    pub ghost: Ghost,
+    pub position: Position,
+    pub velocity: Velocity,
+    pub sprite: Renderable,
+    pub directional_animation: DirectionalAnimation,
+    pub entity_type: EntityType,
+    pub collider: Collider,
+    pub ghost_collider: GhostCollider,
+    pub ghost_state: GhostState,
+    pub last_animation_state: LastAnimationState,
+}

src/systems/debug.rs

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

src/systems/ghost.rs

@@ -0,0 +1,224 @@
+use crate::platform;
+use crate::systems::components::{
+    DirectionalAnimation, Frozen, GhostAnimation, GhostState, LastAnimationState, LinearAnimation, Looping,
+};
+use crate::{
+    map::{
+        builder::Map,
+        direction::Direction,
+        graph::{Edge, TraversalFlags},
+    },
+    systems::{
+        components::{DeltaTime, Ghost},
+        movement::{Position, Velocity},
+    },
+};
+
+use crate::systems::GhostAnimations;
+use bevy_ecs::query::Without;
+use bevy_ecs::system::{Commands, Query, Res};
+use rand::seq::IndexedRandom;
+use smallvec::SmallVec;
+
+/// Autonomous ghost AI system implementing randomized movement with backtracking avoidance.
+pub fn ghost_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut ghosts: Query<(&Ghost, &mut Velocity, &mut Position), Without<Frozen>>,
+) {
+    for (_ghost, mut velocity, mut position) in ghosts.iter_mut() {
+        let mut distance = velocity.speed * 60.0 * delta_time.seconds;
+        loop {
+            match *position {
+                Position::Stopped { node: current_node } => {
+                    let intersection = &map.graph.adjacency_list[current_node as usize];
+                    let opposite = velocity.direction.opposite();
+
+                    let mut non_opposite_options: SmallVec<[Edge; 3]> = SmallVec::new();
+
+                    // Collect all available directions that ghosts can traverse
+                    for edge in Direction::DIRECTIONS.iter().flat_map(|d| intersection.get(*d)) {
+                        if edge.traversal_flags.contains(TraversalFlags::GHOST) && edge.direction != opposite {
+                            non_opposite_options.push(edge);
+                        }
+                    }
+
+                    let new_edge: Edge = if non_opposite_options.is_empty() {
+                        if let Some(edge) = intersection.get(opposite) {
+                            edge
+                        } else {
+                            break;
+                        }
+                    } else {
+                        *non_opposite_options.choose(&mut platform::rng()).unwrap()
+                    };
+
+                    velocity.direction = new_edge.direction;
+                    *position = Position::Moving {
+                        from: current_node,
+                        to: new_edge.target,
+                        remaining_distance: new_edge.distance,
+                    };
+                }
+                Position::Moving { .. } => {
+                    if let Some(overflow) = position.tick(distance) {
+                        distance = overflow;
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// System that handles eaten ghost behavior and respawn logic.
+///
+/// When a ghost is eaten by Pac-Man, it enters an "eaten" state where:
+/// 1. It displays eyes-only animation
+/// 2. It moves directly back to the ghost house at increased speed
+/// 3. Once it reaches the ghost house center, it respawns as a normal ghost
+///
+/// This system runs after the main movement system to override eaten ghost movement.
+pub fn eaten_ghost_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut eaten_ghosts: Query<(&Ghost, &mut Position, &mut Velocity, &mut GhostState)>,
+) {
+    for (ghost_type, mut position, mut velocity, mut ghost_state) in eaten_ghosts.iter_mut() {
+        // Only process ghosts that are in Eyes state
+        if !matches!(*ghost_state, GhostState::Eyes) {
+            continue;
+        }
+        // Set higher speed for eaten ghosts returning to ghost house
+        let original_speed = velocity.speed;
+        velocity.speed = ghost_type.base_speed() * 2.0; // Move twice as fast when eaten
+
+        // Calculate direction towards ghost house center (using Clyde's start position)
+        let ghost_house_center = map.start_positions.clyde;
+
+        match *position {
+            Position::Stopped { node: current_node } => {
+                // Find path to ghost house center and start moving
+                if let Some(direction) = find_direction_to_target(&map, current_node, ghost_house_center) {
+                    velocity.direction = direction;
+                    *position = Position::Moving {
+                        from: current_node,
+                        to: map.graph.adjacency_list[current_node as usize].get(direction).unwrap().target,
+                        remaining_distance: map.graph.adjacency_list[current_node as usize]
+                            .get(direction)
+                            .unwrap()
+                            .distance,
+                    };
+                }
+            }
+            Position::Moving { to, .. } => {
+                let distance = velocity.speed * 60.0 * delta_time.seconds;
+                if let Some(_overflow) = position.tick(distance) {
+                    // Reached target node, check if we're at ghost house center
+                    if to == ghost_house_center {
+                        // Respawn the ghost - set state back to normal
+                        *ghost_state = GhostState::Normal;
+                        // Reset to stopped at ghost house center
+                        *position = Position::Stopped {
+                            node: ghost_house_center,
+                        };
+                    } else {
+                        // Continue pathfinding to ghost house
+                        if let Some(next_direction) = find_direction_to_target(&map, to, ghost_house_center) {
+                            velocity.direction = next_direction;
+                            *position = Position::Moving {
+                                from: to,
+                                to: map.graph.adjacency_list[to as usize].get(next_direction).unwrap().target,
+                                remaining_distance: map.graph.adjacency_list[to as usize].get(next_direction).unwrap().distance,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+
+        // Restore original speed
+        velocity.speed = original_speed;
+    }
+}
+
+/// Helper function to find the direction from a node towards a target node.
+/// Uses simple greedy pathfinding - prefers straight lines when possible.
+fn find_direction_to_target(
+    map: &Map,
+    from_node: crate::systems::movement::NodeId,
+    target_node: crate::systems::movement::NodeId,
+) -> Option<Direction> {
+    let from_pos = map.graph.get_node(from_node).unwrap().position;
+    let target_pos = map.graph.get_node(target_node).unwrap().position;
+
+    let dx = target_pos.x as i32 - from_pos.x as i32;
+    let dy = target_pos.y as i32 - from_pos.y as i32;
+
+    // Prefer horizontal movement first, then vertical
+    let preferred_dirs = if dx.abs() > dy.abs() {
+        if dx > 0 {
+            [Direction::Right, Direction::Up, Direction::Down, Direction::Left]
+        } else {
+            [Direction::Left, Direction::Up, Direction::Down, Direction::Right]
+        }
+    } else if dy > 0 {
+        [Direction::Down, Direction::Left, Direction::Right, Direction::Up]
+    } else {
+        [Direction::Up, Direction::Left, Direction::Right, Direction::Down]
+    };
+
+    // Return first available direction towards target
+    for direction in preferred_dirs {
+        if let Some(edge) = map.graph.adjacency_list[from_node as usize].get(direction) {
+            if edge.traversal_flags.contains(TraversalFlags::GHOST) {
+                return Some(direction);
+            }
+        }
+    }
+
+    None
+}
+
+/// Unified system that manages ghost state transitions and animations with component swapping
+pub fn ghost_state_system(
+    mut commands: Commands,
+    animations: Res<GhostAnimations>,
+    mut ghosts: Query<(bevy_ecs::entity::Entity, &Ghost, &mut GhostState, &mut LastAnimationState)>,
+) {
+    for (entity, ghost_type, mut ghost_state, mut last_animation_state) in ghosts.iter_mut() {
+        // Tick the ghost state to handle internal transitions (like flashing)
+        let _ = ghost_state.tick();
+
+        // Only update animation if the animation state actually changed
+        let current_animation_state = ghost_state.animation_state();
+        if last_animation_state.0 != current_animation_state {
+            match current_animation_state {
+                GhostAnimation::Frightened { flash } => {
+                    // Remove DirectionalAnimation, add LinearAnimation with Looping component
+                    commands
+                        .entity(entity)
+                        .remove::<DirectionalAnimation>()
+                        .insert(animations.frightened(flash).clone())
+                        .insert(Looping);
+                }
+                GhostAnimation::Normal => {
+                    // Remove LinearAnimation and Looping, add DirectionalAnimation
+                    commands
+                        .entity(entity)
+                        .remove::<(LinearAnimation, Looping)>()
+                        .insert(animations.get_normal(ghost_type).unwrap().clone());
+                }
+                GhostAnimation::Eyes => {
+                    // Remove LinearAnimation and Looping, add DirectionalAnimation (eyes animation)
+                    commands
+                        .entity(entity)
+                        .remove::<(LinearAnimation, Looping)>()
+                        .insert(animations.eyes().clone());
+                }
+            }
+            last_animation_state.0 = current_animation_state;
+        }
+    }
+}

src/systems/input.rs

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

src/systems/item.rs

@@ -0,0 +1,74 @@
+use bevy_ecs::{
+    entity::Entity,
+    event::{EventReader, EventWriter},
+    query::With,
+    system::{Commands, Query, ResMut},
+};
+
+use crate::{
+    constants::animation::FRIGHTENED_FLASH_START_TICKS,
+    events::GameEvent,
+    systems::{AudioEvent, EntityType, GhostCollider, GhostState, ItemCollider, PacmanCollider, ScoreResource},
+};
+
+/// Determines if a collision between two entity types should be handled by the item system.
+///
+/// Returns `true` if one entity is a player and the other is a collectible item.
+#[allow(dead_code)]
+pub fn is_valid_item_collision(entity1: EntityType, entity2: EntityType) -> bool {
+    match (entity1, entity2) {
+        (EntityType::Player, entity) | (entity, EntityType::Player) => entity.is_collectible(),
+        _ => false,
+    }
+}
+
+pub fn item_system(
+    mut commands: Commands,
+    mut collision_events: EventReader<GameEvent>,
+    mut score: ResMut<ScoreResource>,
+    pacman_query: Query<Entity, With<PacmanCollider>>,
+    item_query: Query<(Entity, &EntityType), With<ItemCollider>>,
+    mut ghost_query: Query<&mut GhostState, With<GhostCollider>>,
+    mut events: EventWriter<AudioEvent>,
+) {
+    for event in collision_events.read() {
+        if let GameEvent::Collision(entity1, entity2) = event {
+            // Check if one is Pacman and the other is an item
+            let (_pacman_entity, item_entity) = if pacman_query.get(*entity1).is_ok() && item_query.get(*entity2).is_ok() {
+                (*entity1, *entity2)
+            } else if pacman_query.get(*entity2).is_ok() && item_query.get(*entity1).is_ok() {
+                (*entity2, *entity1)
+            } else {
+                continue;
+            };
+
+            // Get the item type and update score
+            if let Ok((item_ent, entity_type)) = item_query.get(item_entity) {
+                if let Some(score_value) = entity_type.score_value() {
+                    score.0 += score_value;
+
+                    // Remove the collected item
+                    commands.entity(item_ent).despawn();
+
+                    // Trigger audio if appropriate
+                    if entity_type.is_collectible() {
+                        events.write(AudioEvent::PlayEat);
+                    }
+
+                    // Make ghosts frightened when power pellet is collected
+                    if *entity_type == EntityType::PowerPellet {
+                        // Convert seconds to frames (assumes 60 FPS)
+                        let total_ticks = 60 * 5; // 5 seconds total
+
+                        // Set all ghosts to frightened state, except those in Eyes state
+                        for mut ghost_state in ghost_query.iter_mut() {
+                            if !matches!(*ghost_state, GhostState::Eyes) {
+                                *ghost_state = GhostState::new_frightened(total_ticks, FRIGHTENED_FLASH_START_TICKS);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

src/systems/mod.rs

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

src/systems/movement.rs

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

src/systems/player.rs

@@ -0,0 +1,168 @@
+use bevy_ecs::{
+    event::{EventReader, EventWriter},
+    query::{With, Without},
+    system::{Query, Res, ResMut},
+};
+
+use crate::{
+    error::GameError,
+    events::{GameCommand, GameEvent},
+    map::{builder::Map, graph::Edge},
+    systems::{
+        components::{DeltaTime, EntityType, Frozen, GlobalState, MovementModifiers, PlayerControlled},
+        debug::DebugState,
+        movement::{BufferedDirection, Position, Velocity},
+        AudioState,
+    },
+};
+
+pub fn can_traverse(entity_type: EntityType, edge: Edge) -> bool {
+    let entity_flags = entity_type.traversal_flags();
+    edge.traversal_flags.contains(entity_flags)
+}
+
+/// Processes player input commands and updates game state accordingly.
+///
+/// Handles keyboard-driven commands like movement direction changes, debug mode
+/// toggling, audio muting, and game exit requests. Movement commands are buffered
+/// to allow direction changes before reaching intersections, improving gameplay
+/// responsiveness. Non-movement commands immediately modify global game state.
+pub fn player_control_system(
+    mut events: EventReader<GameEvent>,
+    mut state: ResMut<GlobalState>,
+    mut debug_state: ResMut<DebugState>,
+    mut audio_state: ResMut<AudioState>,
+    mut players: Query<&mut BufferedDirection, (With<PlayerControlled>, Without<Frozen>)>,
+    mut errors: EventWriter<GameError>,
+) {
+    // Handle events
+    for event in events.read() {
+        if let GameEvent::Command(command) = event {
+            match command {
+                GameCommand::MovePlayer(direction) => {
+                    // Get the player's movable component (ensuring there is only one player)
+                    let mut buffered_direction = match players.single_mut() {
+                        Ok(tuple) => tuple,
+                        Err(e) => {
+                            errors.write(GameError::InvalidState(format!(
+                                "No/multiple entities queried for player system: {}",
+                                e
+                            )));
+                            return;
+                        }
+                    };
+
+                    *buffered_direction = BufferedDirection::Some {
+                        direction: *direction,
+                        remaining_time: 0.25,
+                    };
+                }
+                GameCommand::Exit => {
+                    state.exit = true;
+                }
+                GameCommand::ToggleDebug => {
+                    debug_state.enabled = !debug_state.enabled;
+                }
+                GameCommand::MuteAudio => {
+                    audio_state.muted = !audio_state.muted;
+                    tracing::info!("Audio {}", if audio_state.muted { "muted" } else { "unmuted" });
+                }
+                _ => {}
+            }
+        }
+    }
+}
+
+/// Executes frame-by-frame movement for Pac-Man.
+///
+/// Handles movement logic including buffered direction changes, edge traversal validation, and continuous movement between nodes.
+/// When stopped, prioritizes buffered directions for responsive controls, falling back to current direction.
+/// Supports movement chaining within a single frame when traveling at high speeds.
+#[allow(clippy::type_complexity)]
+pub fn player_movement_system(
+    map: Res<Map>,
+    delta_time: Res<DeltaTime>,
+    mut entities: Query<
+        (&MovementModifiers, &mut Position, &mut Velocity, &mut BufferedDirection),
+        (With<PlayerControlled>, Without<Frozen>),
+    >,
+) {
+    for (modifiers, mut position, mut velocity, mut buffered_direction) in entities.iter_mut() {
+        // Decrement the buffered direction remaining time
+        if let BufferedDirection::Some {
+            direction,
+            remaining_time,
+        } = *buffered_direction
+        {
+            if remaining_time <= 0.0 {
+                *buffered_direction = BufferedDirection::None;
+            } else {
+                *buffered_direction = BufferedDirection::Some {
+                    direction,
+                    remaining_time: remaining_time - delta_time.seconds,
+                };
+            }
+        }
+
+        let mut distance = velocity.speed * modifiers.speed_multiplier * 60.0 * delta_time.seconds;
+
+        loop {
+            match *position {
+                Position::Stopped { .. } => {
+                    // If there is a buffered direction, travel it's edge first if available.
+                    if let BufferedDirection::Some { direction, .. } = *buffered_direction {
+                        // If there's no edge in that direction, ignore the buffered direction.
+                        if let Some(edge) = map.graph.find_edge_in_direction(position.current_node(), direction) {
+                            // If there is an edge in that direction (and it's traversable), start moving towards it and consume the buffered direction.
+                            if can_traverse(EntityType::Player, edge) {
+                                velocity.direction = edge.direction;
+                                *position = Position::Moving {
+                                    from: position.current_node(),
+                                    to: edge.target,
+                                    remaining_distance: edge.distance,
+                                };
+                                *buffered_direction = BufferedDirection::None;
+                            }
+                        }
+                    }
+
+                    // If there is no buffered direction (or it's not yet valid), continue in the current direction.
+                    if let Some(edge) = map.graph.find_edge_in_direction(position.current_node(), velocity.direction) {
+                        if can_traverse(EntityType::Player, edge) {
+                            velocity.direction = edge.direction;
+                            *position = Position::Moving {
+                                from: position.current_node(),
+                                to: edge.target,
+                                remaining_distance: edge.distance,
+                            };
+                        }
+                    } else {
+                        // No edge in our current direction either, erase the buffered direction and stop.
+                        *buffered_direction = BufferedDirection::None;
+                        break;
+                    }
+                }
+                Position::Moving { .. } => {
+                    if let Some(overflow) = position.tick(distance) {
+                        distance = overflow;
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Applies tunnel slowdown based on the current node tile
+pub fn player_tunnel_slowdown_system(map: Res<Map>, mut q: Query<(&Position, &mut MovementModifiers), With<PlayerControlled>>) {
+    if let Ok((position, mut modifiers)) = q.single_mut() {
+        let node = position.current_node();
+        let in_tunnel = map
+            .tile_at_node(node)
+            .map(|t| t == crate::constants::MapTile::Tunnel)
+            .unwrap_or(false);
+        modifiers.tunnel_slowdown_active = in_tunnel;
+        modifiers.speed_multiplier = if in_tunnel { 0.6 } else { 1.0 };
+    }
+}

src/systems/profiling.rs

@@ -0,0 +1,379 @@
+use bevy_ecs::system::IntoSystem;
+use bevy_ecs::{resource::Resource, system::System};
+use circular_buffer::CircularBuffer;
+use num_width::NumberWidth;
+use parking_lot::Mutex;
+use smallvec::SmallVec;
+use std::fmt::Display;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+use strum::{EnumCount, IntoEnumIterator};
+use strum_macros::{EnumCount, EnumIter, IntoStaticStr};
+use thousands::Separable;
+
+/// The maximum number of systems that can be profiled. Must not be exceeded, or it will panic.
+const MAX_SYSTEMS: usize = SystemId::COUNT;
+/// The number of durations to keep in the circular buffer.
+const TIMING_WINDOW_SIZE: usize = 30;
+
+/// A timing buffer that tracks durations and automatically inserts zero durations for skipped ticks.
+#[derive(Debug, Default)]
+pub struct TimingBuffer {
+    /// Circular buffer storing timing durations
+    buffer: CircularBuffer<TIMING_WINDOW_SIZE, Duration>,
+    /// The last tick when this buffer was updated
+    last_tick: u64,
+}
+
+impl TimingBuffer {
+    /// Adds a timing duration for the current tick.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `current_tick` is less than `last_tick`, indicating time went backwards.
+    pub fn add_timing(&mut self, duration: Duration, current_tick: u64) {
+        if current_tick < self.last_tick {
+            panic!(
+                "Time went backwards: current_tick ({}) < last_tick ({})",
+                current_tick, self.last_tick
+            );
+        }
+
+        // Insert zero durations for any skipped ticks (but not the current tick)
+        if current_tick > self.last_tick {
+            let skipped_ticks = current_tick - self.last_tick - 1;
+            for _ in 0..skipped_ticks {
+                self.buffer.push_back(Duration::ZERO);
+            }
+        }
+
+        // Add the actual timing
+        self.buffer.push_back(duration);
+        self.last_tick = current_tick;
+    }
+
+    /// Gets statistics for this timing buffer.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `current_tick` is less than `last_tick`, indicating time went backwards.
+    pub fn get_stats(&mut self, current_tick: u64) -> (Duration, Duration) {
+        // Insert zero durations for any skipped ticks since last update (but not the current tick)
+        if current_tick > self.last_tick {
+            let skipped_ticks = current_tick - self.last_tick - 1;
+            for _ in 0..skipped_ticks {
+                self.buffer.push_back(Duration::ZERO);
+            }
+            self.last_tick = current_tick;
+        }
+
+        // Calculate statistics using Welford's algorithm
+        let mut sample_count = 0u16;
+        let mut running_mean = 0.0;
+        let mut sum_squared_diff = 0.0;
+
+        let skip = self.last_tick.saturating_sub(current_tick);
+        for duration in self.buffer.iter().skip(skip as usize) {
+            let duration_secs = duration.as_secs_f32();
+            sample_count += 1;
+
+            let diff_from_mean = duration_secs - running_mean;
+            running_mean += diff_from_mean / sample_count as f32;
+
+            let diff_from_new_mean = duration_secs - running_mean;
+            sum_squared_diff += diff_from_mean * diff_from_new_mean;
+        }
+
+        if sample_count > 0 {
+            let variance = if sample_count > 1 {
+                sum_squared_diff / (sample_count - 1) as f32
+            } else {
+                0.0
+            };
+
+            (
+                Duration::from_secs_f32(running_mean),
+                Duration::from_secs_f32(variance.sqrt()),
+            )
+        } else {
+            (Duration::ZERO, Duration::ZERO)
+        }
+    }
+}
+
+/// A resource that tracks the current game tick using an atomic counter.
+/// This ensures thread-safe access to the tick counter across systems.
+#[derive(Resource, Debug)]
+pub struct Timing {
+    /// Atomic counter for the current game tick
+    current_tick: AtomicU64,
+}
+
+impl Timing {
+    /// Creates a new Timing resource starting at tick 0
+    pub fn new() -> Self {
+        Self {
+            current_tick: AtomicU64::new(0),
+        }
+    }
+
+    /// Gets the current tick value
+    pub fn get_current_tick(&self) -> u64 {
+        self.current_tick.load(Ordering::Relaxed)
+    }
+
+    /// Increments the tick counter and returns the new value
+    pub fn increment_tick(&self) -> u64 {
+        self.current_tick.fetch_add(1, Ordering::Relaxed) + 1
+    }
+}
+
+impl Default for Timing {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[derive(EnumCount, EnumIter, IntoStaticStr, Debug, PartialEq, Eq, Hash, Copy, Clone)]
+pub enum SystemId {
+    Total,
+    Input,
+    PlayerControls,
+    Ghost,
+    Movement,
+    Audio,
+    Blinking,
+    DirectionalRender,
+    LinearRender,
+    DirtyRender,
+    HudRender,
+    Render,
+    DebugRender,
+    Present,
+    Collision,
+    Item,
+    PlayerMovement,
+    GhostCollision,
+    Stage,
+    GhostStateAnimation,
+    EatenGhost,
+}
+
+impl Display for SystemId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        // Use strum_macros::IntoStaticStr to get the static string
+        write!(f, "{}", Into::<&'static str>::into(self).to_ascii_lowercase())
+    }
+}
+
+#[derive(Resource, Debug)]
+pub struct SystemTimings {
+    /// Statically sized map of system names to timing buffers.
+    pub timings: micromap::Map<SystemId, Mutex<TimingBuffer>, MAX_SYSTEMS>,
+}
+
+impl Default for SystemTimings {
+    fn default() -> Self {
+        let mut timings = micromap::Map::new();
+
+        // Pre-populate with all SystemId variants to avoid runtime allocations
+        for id in SystemId::iter() {
+            timings.insert(id, Mutex::new(TimingBuffer::default()));
+        }
+
+        Self { timings }
+    }
+}
+
+impl SystemTimings {
+    pub fn add_timing(&self, id: SystemId, duration: Duration, current_tick: u64) {
+        // Since all SystemId variants are pre-populated, we can use a simple read lock
+        let buffer = self
+            .timings
+            .get(&id)
+            .expect("SystemId not found in pre-populated map - this is a bug");
+        buffer.lock().add_timing(duration, current_tick);
+    }
+
+    /// Add timing for the Total system (total frame time including scheduler.run)
+    pub fn add_total_timing(&self, duration: Duration, current_tick: u64) {
+        self.add_timing(SystemId::Total, duration, current_tick);
+    }
+
+    pub fn get_stats(&self, current_tick: u64) -> micromap::Map<SystemId, (Duration, Duration), MAX_SYSTEMS> {
+        let mut stats = micromap::Map::new();
+
+        // Iterate over all SystemId variants to ensure every system has an entry
+        for id in SystemId::iter() {
+            let buffer = self
+                .timings
+                .get(&id)
+                .expect("SystemId not found in pre-populated map - this is a bug");
+
+            let (average, standard_deviation) = buffer.lock().get_stats(current_tick);
+            stats.insert(id, (average, standard_deviation));
+        }
+
+        stats
+    }
+
+    pub fn format_timing_display(&self, current_tick: u64) -> SmallVec<[String; SystemId::COUNT]> {
+        let stats = self.get_stats(current_tick);
+
+        // Get the Total system metrics instead of averaging all systems
+        let (total_avg, total_std) = stats
+            .get(&SystemId::Total)
+            .copied()
+            .unwrap_or((Duration::ZERO, Duration::ZERO));
+
+        let effective_fps = match 1.0 / total_avg.as_secs_f64() {
+            f if f > 100.0 => format!("{:>5} FPS", (f as u32).separate_with_commas()),
+            f if f < 10.0 => format!("{:.1} FPS", f),
+            f => format!("{:5.0} FPS", f),
+        };
+
+        // Collect timing data for formatting
+        let mut timing_data = vec![(effective_fps, total_avg, total_std)];
+
+        // Sort the stats by average duration, excluding the Total system
+        let mut sorted_stats: Vec<_> = stats.iter().filter(|(id, _)| **id != SystemId::Total).collect();
+        sorted_stats.sort_by(|a, b| b.1 .0.cmp(&a.1 .0));
+
+        // Add the top 7 most expensive systems (excluding Total)
+        for (name, (avg, std_dev)) in sorted_stats.iter().take(9) {
+            timing_data.push((name.to_string(), *avg, *std_dev));
+        }
+
+        // Use the formatting module to format the data
+        format_timing_display(timing_data)
+    }
+}
+
+pub fn profile<S, M>(id: SystemId, system: S) -> impl FnMut(&mut bevy_ecs::world::World)
+where
+    S: IntoSystem<(), (), M> + 'static,
+{
+    let mut system: S::System = IntoSystem::into_system(system);
+    let mut is_initialized = false;
+    move |world: &mut bevy_ecs::world::World| {
+        if !is_initialized {
+            system.initialize(world);
+            is_initialized = true;
+        }
+
+        let start = std::time::Instant::now();
+        system.run((), world);
+        let duration = start.elapsed();
+
+        if let (Some(timings), Some(timing)) = (world.get_resource::<SystemTimings>(), world.get_resource::<Timing>()) {
+            let current_tick = timing.get_current_tick();
+            timings.add_timing(id, duration, current_tick);
+        }
+    }
+}
+
+// Helper to split a duration into a integer, decimal, and unit
+fn get_value(duration: &Duration) -> (u64, u32, &'static str) {
+    let (int, decimal, unit) = match duration {
+        // if greater than 1 second, return as seconds
+        n if n >= &Duration::from_secs(1) => {
+            let secs = n.as_secs();
+            let decimal = n.as_millis() as u64 % 1000;
+            (secs, decimal as u32, "s")
+        }
+        // if greater than 1 millisecond, return as milliseconds
+        n if n >= &Duration::from_millis(1) => {
+            let ms = n.as_millis() as u64;
+            let decimal = n.as_micros() as u64 % 1000;
+            (ms, decimal as u32, "ms")
+        }
+        // if greater than 1 microsecond, return as microseconds
+        n if n >= &Duration::from_micros(1) => {
+            let us = n.as_micros() as u64;
+            let decimal = n.as_nanos() as u64 % 1000;
+            (us, decimal as u32, "µs")
+        }
+        // otherwise, return as nanoseconds
+        n => {
+            let ns = n.as_nanos() as u64;
+            (ns, 0, "ns")
+        }
+    };
+
+    (int, decimal, unit)
+}
+
+/// Formats timing data into a vector of strings with proper alignment
+pub fn format_timing_display(
+    timing_data: impl IntoIterator<Item = (String, Duration, Duration)>,
+) -> SmallVec<[String; SystemId::COUNT]> {
+    let mut iter = timing_data.into_iter().peekable();
+    if iter.peek().is_none() {
+        return SmallVec::new();
+    }
+
+    struct Entry {
+        name: String,
+        avg_int: u64,
+        avg_decimal: u32,
+        avg_unit: &'static str,
+        std_int: u64,
+        std_decimal: u32,
+        std_unit: &'static str,
+    }
+
+    let entries = iter
+        .map(|(name, avg, std_dev)| {
+            let (avg_int, avg_decimal, avg_unit) = get_value(&avg);
+            let (std_int, std_decimal, std_unit) = get_value(&std_dev);
+
+            Entry {
+                name: name.clone(),
+                avg_int,
+                avg_decimal,
+                avg_unit,
+                std_int,
+                std_decimal,
+                std_unit,
+            }
+        })
+        .collect::<SmallVec<[Entry; 12]>>();
+
+    let (max_avg_int_width, max_avg_decimal_width, max_std_int_width, max_std_decimal_width) =
+        entries
+            .iter()
+            .fold((0, 3, 0, 3), |(avg_int_w, avg_dec_w, std_int_w, std_dec_w), e| {
+                (
+                    avg_int_w.max(e.avg_int.width() as usize),
+                    avg_dec_w.max(e.avg_decimal.width() as usize),
+                    std_int_w.max(e.std_int.width() as usize),
+                    std_dec_w.max(e.std_decimal.width() as usize),
+                )
+            });
+
+    let max_name_width = SystemId::iter()
+        .map(|id| id.to_string().len())
+        .max()
+        .expect("SystemId::iter() returned an empty iterator");
+
+    entries.iter().map(|e| {
+            format!(
+                "{name:max_name_width$} : {avg_int:max_avg_int_width$}.{avg_decimal:<max_avg_decimal_width$}{avg_unit} ± {std_int:max_std_int_width$}.{std_decimal:<max_std_decimal_width$}{std_unit}",
+                // Content
+                name = e.name,
+                avg_int = e.avg_int,
+                avg_decimal = e.avg_decimal,
+                std_int = e.std_int,
+                std_decimal = e.std_decimal,
+                // Units
+                avg_unit = e.avg_unit,
+                std_unit = e.std_unit,
+                // Padding
+                max_name_width = max_name_width,
+                max_avg_int_width = max_avg_int_width,
+                max_avg_decimal_width = max_avg_decimal_width,
+                max_std_int_width = max_std_int_width,
+                max_std_decimal_width = max_std_decimal_width
+            )
+        }).collect::<SmallVec<[String; SystemId::COUNT]>>()
+}

src/systems/render.rs

@@ -0,0 +1,439 @@
+use crate::map::builder::Map;
+use crate::systems::input::TouchState;
+use crate::systems::{
+    debug_render_system, BatchedLinesResource, Collider, CursorPosition, DebugState, DebugTextureResource, DeltaTime,
+    DirectionalAnimation, Dying, Frozen, GameStage, LinearAnimation, Looping, PlayerLives, Position, Renderable, ScoreResource,
+    StartupSequence, SystemId, SystemTimings, TtfAtlasResource, Velocity,
+};
+use crate::texture::sprite::SpriteAtlas;
+use crate::texture::text::TextTexture;
+use crate::{
+    constants::CANVAS_SIZE,
+    error::{GameError, TextureError},
+};
+use bevy_ecs::component::Component;
+use bevy_ecs::entity::Entity;
+use bevy_ecs::event::EventWriter;
+use bevy_ecs::query::{Changed, Has, Or, With, Without};
+use bevy_ecs::removal_detection::RemovedComponents;
+use bevy_ecs::resource::Resource;
+use bevy_ecs::system::{NonSendMut, Query, Res, ResMut};
+use sdl2::pixels::Color;
+use sdl2::rect::{Point, Rect};
+use sdl2::render::{BlendMode, Canvas, Texture};
+use sdl2::video::Window;
+use std::time::Instant;
+
+#[derive(Resource, Default)]
+pub struct RenderDirty(pub bool);
+
+#[derive(Component)]
+pub struct Hidden;
+
+/// Enum to identify which texture is being rendered to in the combined render system
+#[derive(Debug, Clone, Copy)]
+enum RenderTarget {
+    Backbuffer,
+    Debug,
+}
+
+#[allow(clippy::type_complexity)]
+pub fn dirty_render_system(
+    mut dirty: ResMut<RenderDirty>,
+    changed: Query<(), Or<(Changed<Renderable>, Changed<Position>)>>,
+    removed_hidden: RemovedComponents<Hidden>,
+    removed_renderables: RemovedComponents<Renderable>,
+) {
+    if !changed.is_empty() || !removed_hidden.is_empty() || !removed_renderables.is_empty() {
+        dirty.0 = true;
+    }
+}
+
+/// Updates directional animated entities with synchronized timing across directions.
+///
+/// This runs before the render system to update sprites based on current direction and movement state.
+/// All directions share the same frame timing to ensure perfect synchronization.
+pub fn directional_render_system(
+    dt: Res<DeltaTime>,
+    mut query: Query<(&Position, &Velocity, &mut DirectionalAnimation, &mut Renderable), Without<Frozen>>,
+) {
+    let ticks = (dt.seconds * 60.0).round() as u16; // Convert from seconds to ticks at 60 ticks/sec
+
+    for (position, velocity, mut anim, mut renderable) in query.iter_mut() {
+        let stopped = matches!(position, Position::Stopped { .. });
+
+        // Only tick animation when moving to preserve stopped frame
+        if !stopped {
+            // Tick shared animation state
+            anim.time_bank += ticks;
+            while anim.time_bank >= anim.frame_duration {
+                anim.time_bank -= anim.frame_duration;
+                anim.current_frame += 1;
+            }
+        }
+
+        // Get tiles for current direction and movement state
+        let tiles = if stopped {
+            anim.stopped_tiles.get(velocity.direction)
+        } else {
+            anim.moving_tiles.get(velocity.direction)
+        };
+
+        if !tiles.is_empty() {
+            let new_tile = tiles.get_tile(anim.current_frame);
+            if renderable.sprite != new_tile {
+                renderable.sprite = new_tile;
+            }
+        }
+    }
+}
+
+/// System that updates `Renderable` sprites for entities with `LinearAnimation`.
+#[allow(clippy::type_complexity)]
+pub fn linear_render_system(
+    dt: Res<DeltaTime>,
+    mut query: Query<(&mut LinearAnimation, &mut Renderable, Has<Looping>), Or<(Without<Frozen>, With<Dying>)>>,
+) {
+    for (mut anim, mut renderable, looping) in query.iter_mut() {
+        if anim.finished {
+            continue;
+        }
+
+        anim.time_bank += dt.ticks as u16;
+        let frames_to_advance = (anim.time_bank / anim.frame_duration) as usize;
+
+        if frames_to_advance == 0 {
+            continue;
+        }
+
+        let total_frames = anim.tiles.len();
+
+        if !looping && anim.current_frame + frames_to_advance >= total_frames {
+            anim.finished = true;
+            anim.current_frame = total_frames - 1;
+        } else {
+            anim.current_frame += frames_to_advance;
+        }
+
+        anim.time_bank %= anim.frame_duration;
+        renderable.sprite = anim.tiles.get_tile(anim.current_frame);
+    }
+}
+
+/// A non-send resource for the map texture. This just wraps the texture with a type so it can be differentiated when exposed as a resource.
+pub struct MapTextureResource(pub Texture);
+
+/// A non-send resource for the backbuffer texture. This just wraps the texture with a type so it can be differentiated when exposed as a resource.
+pub struct BackbufferResource(pub Texture);
+
+/// Renders touch UI overlay for mobile/testing.
+pub fn touch_ui_render_system(
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    touch_state: Res<TouchState>,
+    mut errors: EventWriter<GameError>,
+) {
+    if let Some(ref touch_data) = touch_state.active_touch {
+        let _ = canvas.with_texture_canvas(&mut backbuffer.0, |canvas| {
+            // Set blend mode for transparency
+            canvas.set_blend_mode(BlendMode::Blend);
+
+            // Draw semi-transparent circle at touch start position
+            canvas.set_draw_color(Color::RGBA(255, 255, 255, 100));
+            let center = Point::new(touch_data.start_pos.x as i32, touch_data.start_pos.y as i32);
+
+            // Draw a simple circle by drawing filled rectangles (basic approach)
+            let radius = 30;
+            for dy in -radius..=radius {
+                for dx in -radius..=radius {
+                    if dx * dx + dy * dy <= radius * radius {
+                        let point = Point::new(center.x + dx, center.y + dy);
+                        if let Err(e) = canvas.draw_point(point) {
+                            errors.write(TextureError::RenderFailed(format!("Touch UI render error: {}", e)).into());
+                            return;
+                        }
+                    }
+                }
+            }
+
+            // Draw direction indicator if we have a direction
+            if let Some(direction) = touch_data.current_direction {
+                canvas.set_draw_color(Color::RGBA(0, 255, 0, 150));
+
+                // Draw arrow indicating direction
+                let arrow_length = 40;
+                let (dx, dy) = match direction {
+                    crate::map::direction::Direction::Up => (0, -arrow_length),
+                    crate::map::direction::Direction::Down => (0, arrow_length),
+                    crate::map::direction::Direction::Left => (-arrow_length, 0),
+                    crate::map::direction::Direction::Right => (arrow_length, 0),
+                };
+
+                let end_point = Point::new(center.x + dx, center.y + dy);
+                if let Err(e) = canvas.draw_line(center, end_point) {
+                    errors.write(TextureError::RenderFailed(format!("Touch arrow render error: {}", e)).into());
+                }
+
+                // Draw arrowhead (simple approach)
+                let arrow_size = 8;
+                match direction {
+                    crate::map::direction::Direction::Up => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y + arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y + arrow_size));
+                    }
+                    crate::map::direction::Direction::Down => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y - arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y - arrow_size));
+                    }
+                    crate::map::direction::Direction::Left => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y - arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x + arrow_size, end_point.y + arrow_size));
+                    }
+                    crate::map::direction::Direction::Right => {
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y - arrow_size));
+                        let _ = canvas.draw_line(end_point, Point::new(end_point.x - arrow_size, end_point.y + arrow_size));
+                    }
+                }
+            }
+        });
+    }
+}
+
+/// Renders the HUD (score, lives, etc.) on top of the game.
+pub fn hud_render_system(
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    mut atlas: NonSendMut<SpriteAtlas>,
+    player_lives: Res<PlayerLives>,
+    score: Res<ScoreResource>,
+    stage: Res<GameStage>,
+    mut errors: EventWriter<GameError>,
+) {
+    let _ = canvas.with_texture_canvas(&mut backbuffer.0, |canvas| {
+        let mut text_renderer = TextTexture::new(1.0);
+
+        // Render lives and high score text in white
+        let lives = player_lives.0;
+        let lives_text = format!("{lives}UP   HIGH SCORE   ");
+        let lives_position = glam::UVec2::new(4 + 8 * 3, 2); // x_offset + lives_offset * 8, y_offset
+
+        if let Err(e) = text_renderer.render(canvas, &mut atlas, &lives_text, lives_position) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render lives text: {}", e)).into());
+        }
+
+        // Render score text
+        let score_text = format!("{:02}", score.0);
+        let score_offset = 7 - (score_text.len() as i32);
+        let score_position = glam::UVec2::new(4 + 8 * score_offset as u32, 10); // x_offset + score_offset * 8, 8 + y_offset
+
+        if let Err(e) = text_renderer.render(canvas, &mut atlas, &score_text, score_position) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render score text: {}", e)).into());
+        }
+
+        // Render high score text
+        let high_score_text = format!("{:02}", score.0);
+        let high_score_offset = 17 - (high_score_text.len() as i32);
+        let high_score_position = glam::UVec2::new(4 + 8 * high_score_offset as u32, 10); // x_offset + score_offset * 8, 8 + y_offset
+        if let Err(e) = text_renderer.render(canvas, &mut atlas, &high_score_text, high_score_position) {
+            errors.write(TextureError::RenderFailed(format!("Failed to render high score text: {}", e)).into());
+        }
+
+        // Render GAME OVER text
+        if matches!(*stage, GameStage::GameOver) {
+            let game_over_text = "GAME  OVER";
+            let game_over_width = text_renderer.text_width(game_over_text);
+            let game_over_position = glam::UVec2::new((CANVAS_SIZE.x - game_over_width) / 2, 160);
+            if let Err(e) = text_renderer.render_with_color(canvas, &mut atlas, game_over_text, game_over_position, Color::RED) {
+                errors.write(TextureError::RenderFailed(format!("Failed to render GAME OVER text: {}", e)).into());
+            }
+        }
+
+        // Render text based on StartupSequence stage
+        if matches!(
+            *stage,
+            GameStage::Starting(StartupSequence::TextOnly { .. })
+                | GameStage::Starting(StartupSequence::CharactersVisible { .. })
+        ) {
+            let ready_text = "READY!";
+            let ready_width = text_renderer.text_width(ready_text);
+            let ready_position = glam::UVec2::new((CANVAS_SIZE.x - ready_width) / 2, 160);
+            if let Err(e) = text_renderer.render_with_color(canvas, &mut atlas, ready_text, ready_position, Color::YELLOW) {
+                errors.write(TextureError::RenderFailed(format!("Failed to render READY text: {}", e)).into());
+            }
+
+            if matches!(*stage, GameStage::Starting(StartupSequence::TextOnly { .. })) {
+                let player_one_text = "PLAYER ONE";
+                let player_one_width = text_renderer.text_width(player_one_text);
+                let player_one_position = glam::UVec2::new((CANVAS_SIZE.x - player_one_width) / 2, 113);
+
+                if let Err(e) =
+                    text_renderer.render_with_color(canvas, &mut atlas, player_one_text, player_one_position, Color::CYAN)
+                {
+                    errors.write(TextureError::RenderFailed(format!("Failed to render PLAYER ONE text: {}", e)).into());
+                }
+            }
+        }
+    });
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn render_system(
+    canvas: &mut Canvas<Window>,
+    map_texture: &NonSendMut<MapTextureResource>,
+    atlas: &mut SpriteAtlas,
+    map: &Res<Map>,
+    dirty: &Res<RenderDirty>,
+    renderables: &Query<(Entity, &Renderable, &Position), Without<Hidden>>,
+    errors: &mut EventWriter<GameError>,
+) {
+    if !dirty.0 {
+        return;
+    }
+
+    // Clear the backbuffer
+    canvas.set_draw_color(sdl2::pixels::Color::BLACK);
+    canvas.clear();
+
+    // Copy the pre-rendered map texture to the backbuffer
+    if let Err(e) = canvas.copy(&map_texture.0, None, None) {
+        errors.write(TextureError::RenderFailed(e.to_string()).into());
+    }
+
+    // Render all entities to the backbuffer
+    for (_, renderable, position) in renderables
+        .iter()
+        .sort_by_key::<(Entity, &Renderable, &Position), _>(|(_, renderable, _)| renderable.layer)
+        .rev()
+    {
+        let pos = position.get_pixel_position(&map.graph);
+        match pos {
+            Ok(pos) => {
+                let dest = Rect::from_center(
+                    Point::from((pos.x as i32, pos.y as i32)),
+                    renderable.sprite.size.x as u32,
+                    renderable.sprite.size.y as u32,
+                );
+
+                renderable
+                    .sprite
+                    .render(canvas, atlas, dest)
+                    .err()
+                    .map(|e| errors.write(TextureError::RenderFailed(e.to_string()).into()));
+            }
+            Err(e) => {
+                errors.write(e);
+            }
+        }
+    }
+}
+
+/// Combined render system that renders to both backbuffer and debug textures in a single
+/// with_multiple_texture_canvas call for reduced overhead
+#[allow(clippy::too_many_arguments)]
+pub fn combined_render_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    map_texture: NonSendMut<MapTextureResource>,
+    mut backbuffer: NonSendMut<BackbufferResource>,
+    mut debug_texture: NonSendMut<DebugTextureResource>,
+    mut atlas: NonSendMut<SpriteAtlas>,
+    mut ttf_atlas: NonSendMut<TtfAtlasResource>,
+    batched_lines: Res<BatchedLinesResource>,
+    debug_state: Res<DebugState>,
+    timings: Res<SystemTimings>,
+    timing: Res<crate::systems::profiling::Timing>,
+    map: Res<Map>,
+    dirty: Res<RenderDirty>,
+    renderables: Query<(Entity, &Renderable, &Position), Without<Hidden>>,
+    colliders: Query<(&Collider, &Position)>,
+    cursor: Res<CursorPosition>,
+    mut errors: EventWriter<GameError>,
+) {
+    if !dirty.0 {
+        return;
+    }
+
+    // Prepare textures and render targets
+    let textures = [
+        (&mut backbuffer.0, RenderTarget::Backbuffer),
+        (&mut debug_texture.0, RenderTarget::Debug),
+    ];
+
+    // Record timing for each system independently
+    let mut render_duration = None;
+    let mut debug_render_duration = None;
+
+    let result = canvas.with_multiple_texture_canvas(textures.iter(), |texture_canvas, render_target| match render_target {
+        RenderTarget::Backbuffer => {
+            let start_time = Instant::now();
+
+            render_system(
+                texture_canvas,
+                &map_texture,
+                &mut atlas,
+                &map,
+                &dirty,
+                &renderables,
+                &mut errors,
+            );
+
+            render_duration = Some(start_time.elapsed());
+        }
+        RenderTarget::Debug => {
+            if !debug_state.enabled {
+                return;
+            }
+
+            let start_time = Instant::now();
+
+            debug_render_system(
+                texture_canvas,
+                &mut ttf_atlas,
+                &batched_lines,
+                &debug_state,
+                &timings,
+                &timing,
+                &map,
+                &colliders,
+                &cursor,
+            );
+
+            debug_render_duration = Some(start_time.elapsed());
+        }
+    });
+
+    if let Err(e) = result {
+        errors.write(TextureError::RenderFailed(e.to_string()).into());
+    }
+
+    // Record timings for each system independently
+    let current_tick = timing.get_current_tick();
+
+    if let Some(duration) = render_duration {
+        timings.add_timing(SystemId::Render, duration, current_tick);
+    }
+    if let Some(duration) = debug_render_duration {
+        timings.add_timing(SystemId::DebugRender, duration, current_tick);
+    }
+}
+
+pub fn present_system(
+    mut canvas: NonSendMut<&mut Canvas<Window>>,
+    mut dirty: ResMut<RenderDirty>,
+    backbuffer: NonSendMut<BackbufferResource>,
+    debug_texture: NonSendMut<DebugTextureResource>,
+    debug_state: Res<DebugState>,
+) {
+    if dirty.0 {
+        // Copy the backbuffer to the main canvas
+        canvas.copy(&backbuffer.0, None, None).unwrap();
+
+        // Copy the debug texture to the canvas
+        if debug_state.enabled {
+            canvas.set_blend_mode(BlendMode::Blend);
+            canvas.copy(&debug_texture.0, None, None).unwrap();
+        }
+
+        canvas.present();
+        dirty.0 = false;
+    }
+}

src/systems/state.rs

@@ -0,0 +1,315 @@
+use std::mem::discriminant;
+
+use crate::{
+    map::builder::Map,
+    systems::{
+        AudioEvent, Blinking, DirectionalAnimation, Dying, Eaten, Frozen, Ghost, GhostCollider, GhostState, Hidden,
+        LinearAnimation, Looping, PlayerControlled, Position,
+    },
+};
+use bevy_ecs::{
+    entity::Entity,
+    event::EventWriter,
+    query::{With, Without},
+    resource::Resource,
+    system::{Commands, Query, Res, ResMut},
+};
+
+#[derive(Resource, Clone)]
+pub struct PlayerAnimation(pub DirectionalAnimation);
+
+#[derive(Resource, Clone)]
+pub struct PlayerDeathAnimation(pub LinearAnimation);
+
+/// A resource to track the overall stage of the game from a high-level perspective.
+#[derive(Resource, Debug, PartialEq, Eq, Clone, Copy)]
+pub enum GameStage {
+    Starting(StartupSequence),
+    /// The main gameplay loop is active.
+    Playing,
+    /// The player has died and the death sequence is in progress.
+    PlayerDying(DyingSequence),
+    /// The level is restarting after a death.
+    LevelRestarting,
+    /// The game has ended.
+    GameOver,
+}
+
+/// A resource that manages the multi-stage startup sequence of the game.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum StartupSequence {
+    /// Stage 1: Text-only stage
+    /// - Player & ghosts are hidden
+    /// - READY! and PLAYER ONE text are shown
+    /// - Energizers do not blink
+    TextOnly {
+        /// Remaining ticks in this stage
+        remaining_ticks: u32,
+    },
+    /// Stage 2: Characters visible stage
+    /// - PLAYER ONE text is hidden, READY! text remains
+    /// - Ghosts and Pac-Man are now shown
+    CharactersVisible {
+        /// Remaining ticks in this stage
+        remaining_ticks: u32,
+    },
+}
+
+impl Default for GameStage {
+    fn default() -> Self {
+        Self::Playing
+    }
+}
+
+/// The state machine for the multi-stage death sequence.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum DyingSequence {
+    /// Initial stage: entities are frozen, waiting for a delay.
+    Frozen { remaining_ticks: u32 },
+    /// Second stage: Pac-Man's death animation is playing.
+    Animating { remaining_ticks: u32 },
+    /// Third stage: Pac-Man is now gone, waiting a moment before the level restarts.
+    Hidden { remaining_ticks: u32 },
+}
+
+/// A resource to store the number of player lives.
+#[derive(Resource, Debug)]
+pub struct PlayerLives(pub u8);
+
+impl Default for PlayerLives {
+    fn default() -> Self {
+        Self(3)
+    }
+}
+
+/// Handles startup sequence transitions and component management
+#[allow(clippy::too_many_arguments)]
+#[allow(clippy::type_complexity)]
+pub fn stage_system(
+    mut game_state: ResMut<GameStage>,
+    player_death_animation: Res<PlayerDeathAnimation>,
+    player_animation: Res<PlayerAnimation>,
+    mut player_lives: ResMut<PlayerLives>,
+    map: Res<Map>,
+    mut commands: Commands,
+    mut audio_events: EventWriter<AudioEvent>,
+    mut blinking_query: Query<Entity, With<Blinking>>,
+    mut player_query: Query<(Entity, &mut Position), With<PlayerControlled>>,
+    mut ghost_query: Query<(Entity, &Ghost, &mut Position), (With<GhostCollider>, Without<PlayerControlled>)>,
+) {
+    let old_state = *game_state;
+    let new_state: GameStage = match &mut *game_state {
+        GameStage::Starting(startup) => match startup {
+            StartupSequence::TextOnly { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    GameStage::Starting(StartupSequence::TextOnly {
+                        remaining_ticks: *remaining_ticks - 1,
+                    })
+                } else {
+                    GameStage::Starting(StartupSequence::CharactersVisible { remaining_ticks: 60 })
+                }
+            }
+            StartupSequence::CharactersVisible { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    GameStage::Starting(StartupSequence::CharactersVisible {
+                        remaining_ticks: *remaining_ticks - 1,
+                    })
+                } else {
+                    GameStage::Playing
+                }
+            }
+        },
+        GameStage::Playing => GameStage::Playing,
+        GameStage::PlayerDying(dying) => match dying {
+            DyingSequence::Frozen { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    GameStage::PlayerDying(DyingSequence::Frozen {
+                        remaining_ticks: *remaining_ticks - 1,
+                    })
+                } else {
+                    let death_animation = &player_death_animation.0;
+                    let remaining_ticks = (death_animation.tiles.len() * death_animation.frame_duration as usize) as u32;
+                    GameStage::PlayerDying(DyingSequence::Animating { remaining_ticks })
+                }
+            }
+            DyingSequence::Animating { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    GameStage::PlayerDying(DyingSequence::Animating {
+                        remaining_ticks: *remaining_ticks - 1,
+                    })
+                } else {
+                    GameStage::PlayerDying(DyingSequence::Hidden { remaining_ticks: 60 })
+                }
+            }
+            DyingSequence::Hidden { remaining_ticks } => {
+                if *remaining_ticks > 0 {
+                    GameStage::PlayerDying(DyingSequence::Hidden {
+                        remaining_ticks: *remaining_ticks - 1,
+                    })
+                } else {
+                    player_lives.0 = player_lives.0.saturating_sub(1);
+
+                    if player_lives.0 > 0 {
+                        GameStage::LevelRestarting
+                    } else {
+                        GameStage::GameOver
+                    }
+                }
+            }
+        },
+        GameStage::LevelRestarting => GameStage::Starting(StartupSequence::CharactersVisible { remaining_ticks: 60 }),
+        GameStage::GameOver => GameStage::GameOver,
+    };
+
+    if old_state == new_state {
+        return;
+    }
+
+    match (old_state, new_state) {
+        (GameStage::Playing, GameStage::PlayerDying(DyingSequence::Frozen { .. })) => {
+            // Freeze the player & ghosts
+            for entity in player_query
+                .iter_mut()
+                .map(|(e, _)| e)
+                .chain(ghost_query.iter_mut().map(|(e, _, _)| e))
+            {
+                commands.entity(entity).insert(Frozen);
+            }
+        }
+        (GameStage::PlayerDying(DyingSequence::Frozen { .. }), GameStage::PlayerDying(DyingSequence::Animating { .. })) => {
+            // Hide the ghosts
+            for (entity, _, _) in ghost_query.iter_mut() {
+                commands.entity(entity).insert(Hidden);
+            }
+
+            // Start Pac-Man's death animation
+            if let Ok((player_entity, _)) = player_query.single_mut() {
+                commands
+                    .entity(player_entity)
+                    .insert((Dying, player_death_animation.0.clone()));
+            }
+
+            // Play the death sound
+            audio_events.write(AudioEvent::PlayDeath);
+        }
+        (GameStage::PlayerDying(DyingSequence::Animating { .. }), GameStage::PlayerDying(DyingSequence::Hidden { .. })) => {
+            // Hide the player
+            if let Ok((player_entity, _)) = player_query.single_mut() {
+                commands.entity(player_entity).insert(Hidden);
+            }
+        }
+        (_, GameStage::LevelRestarting) => {
+            if let Ok((player_entity, mut pos)) = player_query.single_mut() {
+                *pos = Position::Stopped {
+                    node: map.start_positions.pacman,
+                };
+
+                // Freeze the blinking, force them to be visible (if they were hidden by blinking)
+                for entity in blinking_query.iter_mut() {
+                    commands.entity(entity).insert(Frozen).remove::<Hidden>();
+                }
+
+                // Reset the player animation
+                commands
+                    .entity(player_entity)
+                    .remove::<(Frozen, Dying, Hidden, LinearAnimation, Looping)>()
+                    .insert(player_animation.0.clone());
+            }
+
+            // Reset ghost positions and state
+            for (ghost_entity, ghost, mut ghost_pos) in ghost_query.iter_mut() {
+                *ghost_pos = Position::Stopped {
+                    node: match ghost {
+                        Ghost::Blinky => map.start_positions.blinky,
+                        Ghost::Pinky => map.start_positions.pinky,
+                        Ghost::Inky => map.start_positions.inky,
+                        Ghost::Clyde => map.start_positions.clyde,
+                    },
+                };
+                commands
+                    .entity(ghost_entity)
+                    .remove::<(Frozen, Hidden, Eaten)>()
+                    .insert(GhostState::Normal);
+            }
+        }
+        (
+            GameStage::Starting(StartupSequence::TextOnly { .. }),
+            GameStage::Starting(StartupSequence::CharactersVisible { .. }),
+        ) => {
+            // Unhide the player & ghosts
+            for entity in player_query
+                .iter_mut()
+                .map(|(e, _)| e)
+                .chain(ghost_query.iter_mut().map(|(e, _, _)| e))
+            {
+                commands.entity(entity).remove::<Hidden>();
+            }
+        }
+        (GameStage::Starting(StartupSequence::CharactersVisible { .. }), GameStage::Playing) => {
+            // Unfreeze the player & ghosts & blinking
+            for entity in player_query
+                .iter_mut()
+                .map(|(e, _)| e)
+                .chain(ghost_query.iter_mut().map(|(e, _, _)| e))
+                .chain(blinking_query.iter_mut())
+            {
+                commands.entity(entity).remove::<Frozen>();
+            }
+        }
+        (GameStage::PlayerDying(..), GameStage::GameOver) => {
+            // Freeze blinking
+            for entity in blinking_query.iter_mut() {
+                commands.entity(entity).insert(Frozen);
+            }
+        }
+        _ => {
+            let different = discriminant(&old_state) != discriminant(&new_state);
+            if different {
+                tracing::warn!(
+                    new_state = ?new_state,
+                    old_state = ?old_state,
+                    "Unhandled game stage transition");
+            }
+        }
+    }
+
+    *game_state = new_state;
+}
+
+// if let GameState::LevelRestarting = &*game_state {
+//     // When restarting, jump straight to the CharactersVisible stage
+//     // and unhide the entities.
+//     *startup = StartupSequence::new(0, 60 * 2); // 2 seconds for READY! text
+//     if let StartupSequence::TextOnly { .. } = *startup {
+//         // This will immediately transition to CharactersVisible on the next line
+//     } else {
+//         // Should be unreachable as we just set it
+//     }
+
+//     // Freeze Pac-Man and ghosts
+//     for entity in player_query.iter().chain(ghost_query.iter()) {
+//         commands.entity(entity).insert(Frozen);
+//     }
+
+//     *game_state = GameState::Playing;
+// }
+
+// if let Some((old_state, new_state)) = startup.tick() {
+//     debug!("StartupSequence transition from {old_state:?} to {new_state:?}");
+//     match (old_state, new_state) {
+//         (StartupSequence::TextOnly { .. }, StartupSequence::CharactersVisible { .. }) => {
+//             // Unhide the player & ghosts
+//             for entity in player_query.iter().chain(ghost_query.iter()) {
+//                 commands.entity(entity).remove::<Hidden>();
+//             }
+//         }
+//         (StartupSequence::CharactersVisible { .. }, StartupSequence::GameActive) => {
+//             // Unfreeze Pac-Man, ghosts and energizers
+//             for entity in player_query.iter().chain(ghost_query.iter()).chain(blinking_query.iter()) {
+//                 commands.entity(entity).remove::<Frozen>();
+//             }
+//             *game_state = GameState::Playing;
+//         }
+//         _ => {}
+//     }
+// }

src/texture/animated.rs

@@ -1,72 +1,65 @@
-use sdl2::rect::Rect;
-use sdl2::render::{Canvas, RenderTarget};
+use glam::U16Vec2;
 
-use crate::error::{AnimatedTextureError, GameError, GameResult, TextureError};
-use crate::texture::sprite::{AtlasTile, SpriteAtlas};
+use crate::{map::direction::Direction, texture::sprite::AtlasTile};
 
+/// A sequence of tiles for animation, backed by a vector.
 #[derive(Debug, Clone)]
-pub struct AnimatedTexture {
+pub struct TileSequence {
     tiles: Vec<AtlasTile>,
-    frame_duration: f32,
-    current_frame: usize,
-    time_bank: f32,
 }
 
-impl AnimatedTexture {
-    pub fn new(tiles: Vec<AtlasTile>, frame_duration: f32) -> GameResult<Self> {
-        if frame_duration <= 0.0 {
-            return Err(GameError::Texture(TextureError::Animated(
-                AnimatedTextureError::InvalidFrameDuration(frame_duration),
-            )));
+impl TileSequence {
+    /// Creates a new tile sequence from a slice of tiles.
+    pub fn new(tiles: &[AtlasTile]) -> Self {
+        Self { tiles: tiles.to_vec() }
+    }
+
+    /// Returns the tile at the given frame index, wrapping if necessary
+    pub fn get_tile(&self, frame: usize) -> AtlasTile {
+        if self.tiles.is_empty() {
+            // Return a default or handle the error appropriately
+            // For now, let's return a default tile, assuming it's a sensible default
+            return AtlasTile {
+                pos: U16Vec2::ZERO,
+                size: U16Vec2::ZERO,
+                color: None,
+            };
         }
-
-        Ok(Self {
-            tiles,
-            frame_duration,
-            current_frame: 0,
-            time_bank: 0.0,
-        })
+        self.tiles[frame % self.tiles.len()]
     }
 
-    pub fn tick(&mut self, dt: f32) {
-        self.time_bank += dt;
-        while self.time_bank >= self.frame_duration {
-            self.time_bank -= self.frame_duration;
-            self.current_frame = (self.current_frame + 1) % self.tiles.len();
-        }
-    }
-
-    pub fn current_tile(&self) -> &AtlasTile {
-        &self.tiles[self.current_frame]
-    }
-
-    pub fn render<T: RenderTarget>(&self, canvas: &mut Canvas<T>, atlas: &mut SpriteAtlas, dest: Rect) -> GameResult<()> {
-        let mut tile = *self.current_tile();
-        tile.render(canvas, atlas, dest)?;
-        Ok(())
-    }
-
-    /// Returns the current frame index.
-    #[allow(dead_code)]
-    pub fn current_frame(&self) -> usize {
-        self.current_frame
-    }
-
-    /// Returns the time bank.
-    #[allow(dead_code)]
-    pub fn time_bank(&self) -> f32 {
-        self.time_bank
-    }
-
-    /// Returns the frame duration.
-    #[allow(dead_code)]
-    pub fn frame_duration(&self) -> f32 {
-        self.frame_duration
-    }
-
-    /// Returns the number of tiles in the animation.
-    #[allow(dead_code)]
-    pub fn tiles_len(&self) -> usize {
+    pub fn len(&self) -> usize {
         self.tiles.len()
     }
+
+    /// Checks if the sequence contains any tiles.
+    pub fn is_empty(&self) -> bool {
+        self.tiles.is_empty()
+    }
+}
+
+/// A collection of tile sequences for each cardinal direction.
+#[derive(Debug, Clone)]
+pub struct DirectionalTiles {
+    pub up: TileSequence,
+    pub down: TileSequence,
+    pub left: TileSequence,
+    pub right: TileSequence,
+}
+
+impl DirectionalTiles {
+    /// Creates a new DirectionalTiles with different sequences per direction
+    pub fn new(up: TileSequence, down: TileSequence, left: TileSequence, right: TileSequence) -> Self {
+        Self { up, down, left, right }
+    }
+
+    /// Gets the tile sequence for the given direction
+    pub fn get(&self, direction: Direction) -> &TileSequence {
+        match direction {
+            Direction::Up => &self.up,
+            Direction::Down => &self.down,
+            Direction::Left => &self.left,
+            Direction::Right => &self.right,
+        }
+    }
 }

src/texture/blinking.rs

@@ -1,46 +0,0 @@
-#![allow(dead_code)]
-use crate::texture::sprite::AtlasTile;
-
-#[derive(Clone)]
-pub struct BlinkingTexture {
-    tile: AtlasTile,
-    blink_duration: f32,
-    time_bank: f32,
-    is_on: bool,
-}
-
-impl BlinkingTexture {
-    pub fn new(tile: AtlasTile, blink_duration: f32) -> Self {
-        Self {
-            tile,
-            blink_duration,
-            time_bank: 0.0,
-            is_on: true,
-        }
-    }
-
-    pub fn tick(&mut self, dt: f32) {
-        self.time_bank += dt;
-        if self.time_bank >= self.blink_duration {
-            self.time_bank -= self.blink_duration;
-            self.is_on = !self.is_on;
-        }
-    }
-
-    pub fn is_on(&self) -> bool {
-        self.is_on
-    }
-
-    pub fn tile(&self) -> &AtlasTile {
-        &self.tile
-    }
-
-    // Helper methods for testing
-    pub fn time_bank(&self) -> f32 {
-        self.time_bank
-    }
-
-    pub fn blink_duration(&self) -> f32 {
-        self.blink_duration
-    }
-}

src/texture/directional.rs

@@ -1,80 +0,0 @@
-use sdl2::rect::Rect;
-use sdl2::render::{Canvas, RenderTarget};
-
-use crate::entity::direction::Direction;
-use crate::error::GameResult;
-use crate::texture::animated::AnimatedTexture;
-use crate::texture::sprite::SpriteAtlas;
-
-#[derive(Clone)]
-pub struct DirectionalAnimatedTexture {
-    textures: [Option<AnimatedTexture>; 4],
-    stopped_textures: [Option<AnimatedTexture>; 4],
-}
-
-impl DirectionalAnimatedTexture {
-    pub fn new(textures: [Option<AnimatedTexture>; 4], stopped_textures: [Option<AnimatedTexture>; 4]) -> Self {
-        Self {
-            textures,
-            stopped_textures,
-        }
-    }
-
-    pub fn tick(&mut self, dt: f32) {
-        for texture in self.textures.iter_mut().flatten() {
-            texture.tick(dt);
-        }
-    }
-
-    pub fn render<T: RenderTarget>(
-        &self,
-        canvas: &mut Canvas<T>,
-        atlas: &mut SpriteAtlas,
-        dest: Rect,
-        direction: Direction,
-    ) -> GameResult<()> {
-        if let Some(texture) = &self.textures[direction.as_usize()] {
-            texture.render(canvas, atlas, dest)
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn render_stopped<T: RenderTarget>(
-        &self,
-        canvas: &mut Canvas<T>,
-        atlas: &mut SpriteAtlas,
-        dest: Rect,
-        direction: Direction,
-    ) -> GameResult<()> {
-        if let Some(texture) = &self.stopped_textures[direction.as_usize()] {
-            texture.render(canvas, atlas, dest)
-        } else {
-            Ok(())
-        }
-    }
-
-    /// Returns true if the texture has a direction.
-    #[allow(dead_code)]
-    pub fn has_direction(&self, direction: Direction) -> bool {
-        self.textures[direction.as_usize()].is_some()
-    }
-
-    /// Returns true if the texture has a stopped direction.
-    #[allow(dead_code)]
-    pub fn has_stopped_direction(&self, direction: Direction) -> bool {
-        self.stopped_textures[direction.as_usize()].is_some()
-    }
-
-    /// Returns the number of textures.
-    #[allow(dead_code)]
-    pub fn texture_count(&self) -> usize {
-        self.textures.iter().filter(|t| t.is_some()).count()
-    }
-
-    /// Returns the number of stopped textures.
-    #[allow(dead_code)]
-    pub fn stopped_texture_count(&self) -> usize {
-        self.stopped_textures.iter().filter(|t| t.is_some()).count()
-    }
-}

src/texture/mod.rs

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

src/texture/sprite.rs

@@ -3,52 +3,25 @@ use glam::U16Vec2;
 use sdl2::pixels::Color;
 use sdl2::rect::Rect;
 use sdl2::render::{Canvas, RenderTarget, Texture};
-use serde::Deserialize;
 use std::collections::HashMap;
 
 use crate::error::TextureError;
 
-/// A simple sprite for stationary items like pellets and energizers.
+/// Atlas frame mapping data loaded from JSON metadata files.
 #[derive(Clone, Debug)]
-pub struct Sprite {
-    pub atlas_tile: AtlasTile,
-}
-
-impl Sprite {
-    pub fn new(atlas_tile: AtlasTile) -> Self {
-        Self { atlas_tile }
-    }
-
-    pub fn render<C: RenderTarget>(
-        &self,
-        canvas: &mut Canvas<C>,
-        atlas: &mut SpriteAtlas,
-        position: glam::Vec2,
-    ) -> Result<(), TextureError> {
-        let dest = crate::helpers::centered_with_size(
-            glam::IVec2::new(position.x as i32, position.y as i32),
-            glam::UVec2::new(self.atlas_tile.size.x as u32, self.atlas_tile.size.y as u32),
-        );
-        let mut tile = self.atlas_tile;
-        tile.render(canvas, atlas, dest)?;
-        Ok(())
-    }
-}
-
-#[derive(Clone, Debug, Deserialize)]
 pub struct AtlasMapper {
+    /// Mapping from sprite name to frame bounds within the atlas texture
     pub frames: HashMap<String, MapperFrame>,
 }
 
-#[derive(Copy, Clone, Debug, Deserialize)]
+#[derive(Copy, Clone, Debug)]
 pub struct MapperFrame {
-    pub x: u16,
-    pub y: u16,
-    pub width: u16,
-    pub height: u16,
+    pub pos: U16Vec2,
+    pub size: U16Vec2,
 }
 
-#[derive(Copy, Clone, Debug)]
+/// A single tile within a sprite atlas, defined by its position and size.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
 pub struct AtlasTile {
     pub pos: U16Vec2,
     pub size: U16Vec2,
@@ -57,7 +30,7 @@ pub struct AtlasTile {
 
 impl AtlasTile {
     pub fn render<C: RenderTarget>(
-        &mut self,
+        &self,
         canvas: &mut Canvas<C>,
         atlas: &mut SpriteAtlas,
         dest: Rect,
@@ -68,7 +41,7 @@ impl AtlasTile {
     }
 
     pub fn render_with_color<C: RenderTarget>(
-        &mut self,
+        &self,
         canvas: &mut Canvas<C>,
         atlas: &mut SpriteAtlas,
         dest: Rect,
@@ -99,28 +72,49 @@ impl AtlasTile {
     }
 }
 
+/// High-performance sprite atlas providing fast texture region lookups and rendering.
+///
+/// Combines a single large texture with metadata mapping to enable efficient
+/// sprite rendering without texture switching. Caches color modulation state
+/// to minimize redundant SDL2 calls and supports both named sprite lookups
+/// and optional default color modulation configuration.
 pub struct SpriteAtlas {
-    texture: Texture<'static>,
+    /// The combined texture containing all sprite frames
+    texture: Texture,
+    /// Mapping from sprite names to their pixel coordinates within the texture
     tiles: HashMap<String, MapperFrame>,
     default_color: Option<Color>,
+    /// Cached color modulation state to avoid redundant SDL2 calls
     last_modulation: Option<Color>,
 }
 
 impl SpriteAtlas {
-    pub fn new(texture: Texture<'static>, mapper: AtlasMapper) -> Self {
+    pub fn new(texture: Texture, mapper: AtlasMapper) -> Self {
+        let tiles = mapper.frames.into_iter().collect();
+
         Self {
             texture,
-            tiles: mapper.frames,
+            tiles,
             default_color: None,
             last_modulation: None,
         }
     }
 
-    pub fn get_tile(&self, name: &str) -> Option<AtlasTile> {
-        self.tiles.get(name).map(|frame| AtlasTile {
-            pos: U16Vec2::new(frame.x, frame.y),
-            size: U16Vec2::new(frame.width, frame.height),
-            color: None,
+    /// Retrieves a sprite tile by name from the atlas with fast HashMap lookup.
+    ///
+    /// Returns an `AtlasTile` containing the texture coordinates and dimensions
+    /// for the named sprite, or `None` if the sprite name is not found in the
+    /// atlas. The returned tile can be used for immediate rendering or stored
+    /// for repeated use in animations and entity sprites.
+    pub fn get_tile(&self, name: &str) -> Result<AtlasTile, TextureError> {
+        let frame = self
+            .tiles
+            .get(name)
+            .ok_or_else(|| TextureError::AtlasTileNotFound(name.to_string()))?;
+        Ok(AtlasTile {
+            pos: frame.pos,
+            size: frame.size,
+            color: self.default_color,
         })
     }
 
@@ -130,7 +124,7 @@ impl SpriteAtlas {
     }
 
     #[allow(dead_code)]
-    pub fn texture(&self) -> &Texture<'static> {
+    pub fn texture(&self) -> &Texture {
         &self.texture
     }
 

src/texture/sprites.rs

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

src/texture/text.rs

@@ -10,10 +10,20 @@
 //!
 //! ```rust
 //! use pacman::texture::text::TextTexture;
+//! use sdl2::pixels::Color;
 //!
 //! // Create a text texture with 1.0 scale (8x8 pixels per character)
 //! let mut text_renderer = TextTexture::new(1.0);
 //!
+//! // Set default color for all text
+//! text_renderer.set_color(Color::WHITE);
+//!
+//! // Render text with default color
+//! text_renderer.render(&mut canvas, &mut atlas, "Hello", position)?;
+//!
+//! // Render text with specific color
+//! text_renderer.render_with_color(&mut canvas, &mut atlas, "World", position, Color::YELLOW)?;
+//!
 //! // Set scale for larger text
 //! text_renderer.set_scale(2.0);
 //!
@@ -46,13 +56,11 @@
 use anyhow::Result;
 use glam::UVec2;
 
+use sdl2::pixels::Color;
 use sdl2::render::{Canvas, RenderTarget};
 use std::collections::HashMap;
 
-use crate::{
-    error::{GameError, TextureError},
-    texture::sprite::{AtlasTile, SpriteAtlas},
-};
+use crate::texture::sprite::{AtlasTile, SpriteAtlas};
 
 /// Converts a character to its tile name in the atlas.
 fn char_to_tile_name(c: char) -> Option<String> {
@@ -79,6 +87,7 @@ fn char_to_tile_name(c: char) -> Option<String> {
 pub struct TextTexture {
     char_map: HashMap<char, AtlasTile>,
     scale: f32,
+    default_color: Option<Color>,
 }
 
 impl Default for TextTexture {
@@ -86,6 +95,7 @@ impl Default for TextTexture {
         Self {
             scale: 1.0,
             char_map: Default::default(),
+            default_color: None,
         }
     }
 }
@@ -103,29 +113,40 @@ impl TextTexture {
         &self.char_map
     }
 
-    pub fn get_tile(&mut self, c: char, atlas: &mut SpriteAtlas) -> Result<Option<&mut AtlasTile>> {
+    pub fn get_tile(&mut self, c: char, atlas: &mut SpriteAtlas) -> Result<Option<&AtlasTile>> {
         if self.char_map.contains_key(&c) {
-            return Ok(self.char_map.get_mut(&c));
+            return Ok(self.char_map.get(&c));
         }
 
         if let Some(tile_name) = char_to_tile_name(c) {
-            let tile = atlas
-                .get_tile(&tile_name)
-                .ok_or(GameError::Texture(TextureError::AtlasTileNotFound(tile_name)))?;
+            let tile = atlas.get_tile(&tile_name)?;
             self.char_map.insert(c, tile);
-            Ok(self.char_map.get_mut(&c))
+            Ok(self.char_map.get(&c))
         } else {
             Ok(None)
         }
     }
 
-    /// Renders a string of text at the given position.
+    /// Renders a string of text at the given position using the default color.
     pub fn render<C: RenderTarget>(
         &mut self,
         canvas: &mut Canvas<C>,
         atlas: &mut SpriteAtlas,
         text: &str,
         position: UVec2,
+    ) -> Result<()> {
+        let color = self.default_color.unwrap_or(Color::WHITE);
+        self.render_with_color(canvas, atlas, text, position, color)
+    }
+
+    /// Renders a string of text at the given position with a specific color.
+    pub fn render_with_color<C: RenderTarget>(
+        &mut self,
+        canvas: &mut Canvas<C>,
+        atlas: &mut SpriteAtlas,
+        text: &str,
+        position: UVec2,
+        color: Color,
     ) -> Result<()> {
         let mut x_offset = 0;
         let char_width = (8.0 * self.scale) as u32;
@@ -134,9 +155,9 @@ impl TextTexture {
         for c in text.chars() {
             // Get the tile from the char_map, or insert it if it doesn't exist
             if let Some(tile) = self.get_tile(c, atlas)? {
-                // Render the tile if it exists
+                // Render the tile with the specified color
                 let dest = sdl2::rect::Rect::new((position.x + x_offset) as i32, position.y as i32, char_width, char_height);
-                tile.render(canvas, atlas, dest)?;
+                tile.render_with_color(canvas, atlas, dest, color)?;
             }
 
             // Always advance x_offset for all characters (including spaces)
@@ -146,6 +167,16 @@ impl TextTexture {
         Ok(())
     }
 
+    /// Sets the default color for text rendering.
+    pub fn set_color(&mut self, color: Color) {
+        self.default_color = Some(color);
+    }
+
+    /// Gets the current default color.
+    pub fn color(&self) -> Option<Color> {
+        self.default_color
+    }
+
     /// Sets the scale for text rendering.
     pub fn set_scale(&mut self, scale: f32) {
         self.scale = scale;

src/texture/ttf.rs

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

tests/animated.rs

@@ -1,62 +0,0 @@
-use glam::U16Vec2;
-use pacman::error::{AnimatedTextureError, GameError, TextureError};
-use pacman::texture::animated::AnimatedTexture;
-use pacman::texture::sprite::AtlasTile;
-use sdl2::pixels::Color;
-
-fn mock_atlas_tile(id: u32) -> AtlasTile {
-    AtlasTile {
-        pos: U16Vec2::new(0, 0),
-        size: U16Vec2::new(16, 16),
-        color: Some(Color::RGB(id as u8, 0, 0)),
-    }
-}
-
-#[test]
-fn test_animated_texture_creation_errors() {
-    let tiles = vec![mock_atlas_tile(1), mock_atlas_tile(2)];
-
-    assert!(matches!(
-        AnimatedTexture::new(tiles.clone(), 0.0).unwrap_err(),
-        GameError::Texture(TextureError::Animated(AnimatedTextureError::InvalidFrameDuration(0.0)))
-    ));
-
-    assert!(matches!(
-        AnimatedTexture::new(tiles, -0.1).unwrap_err(),
-        GameError::Texture(TextureError::Animated(AnimatedTextureError::InvalidFrameDuration(-0.1)))
-    ));
-}
-
-#[test]
-fn test_animated_texture_advancement() {
-    let tiles = vec![mock_atlas_tile(1), mock_atlas_tile(2), mock_atlas_tile(3)];
-    let mut texture = AnimatedTexture::new(tiles, 0.1).unwrap();
-
-    assert_eq!(texture.current_frame(), 0);
-
-    texture.tick(0.25);
-    assert_eq!(texture.current_frame(), 2);
-    assert!((texture.time_bank() - 0.05).abs() < 0.001);
-}
-
-#[test]
-fn test_animated_texture_wrap_around() {
-    let tiles = vec![mock_atlas_tile(1), mock_atlas_tile(2)];
-    let mut texture = AnimatedTexture::new(tiles, 0.1).unwrap();
-
-    texture.tick(0.1);
-    assert_eq!(texture.current_frame(), 1);
-
-    texture.tick(0.1);
-    assert_eq!(texture.current_frame(), 0);
-}
-
-#[test]
-fn test_animated_texture_single_frame() {
-    let tiles = vec![mock_atlas_tile(1)];
-    let mut texture = AnimatedTexture::new(tiles, 0.1).unwrap();
-
-    texture.tick(0.1);
-    assert_eq!(texture.current_frame(), 0);
-    assert_eq!(texture.current_tile().color.unwrap().r, 1);
-}

tests/asset.rs

@@ -1,14 +1,17 @@
 use pacman::asset::Asset;
-use std::path::Path;
+use speculoos::prelude::*;
 use strum::IntoEnumIterator;
 
 #[test]
-fn test_asset_paths_valid() {
-    let base_path = Path::new("assets/game/");
-
+fn all_asset_paths_exist() {
     for asset in Asset::iter() {
-        let path = base_path.join(asset.path());
-        assert!(path.exists(), "Asset path does not exist: {:?}", path);
-        assert!(path.is_file(), "Asset path is not a file: {:?}", path);
+        let path = asset.path();
+        let full_path = format!("assets/game/{}", path);
+
+        let metadata = std::fs::metadata(&full_path)
+            .map_err(|e| format!("Error getting metadata for {}: {}", full_path, e))
+            .unwrap();
+        assert_that(&metadata.is_file()).is_true();
+        assert_that(&metadata.len()).is_greater_than(1024);
     }
 }

tests/blinking.rs

@@ -1,49 +1,316 @@
-use glam::U16Vec2;
-use pacman::texture::blinking::BlinkingTexture;
-use pacman::texture::sprite::AtlasTile;
-use sdl2::pixels::Color;
+use bevy_ecs::{entity::Entity, system::RunSystemOnce, world::World};
+use pacman::systems::{
+    blinking::{blinking_system, Blinking},
+    components::{DeltaTime, Renderable},
+    Frozen, Hidden,
+};
+use speculoos::prelude::*;
 
-fn mock_atlas_tile(id: u32) -> AtlasTile {
-    AtlasTile {
-        pos: U16Vec2::new(0, 0),
-        size: U16Vec2::new(16, 16),
-        color: Some(Color::RGB(id as u8, 0, 0)),
-    }
+mod common;
+
+/// Creates a test world with blinking system resources
+fn create_blinking_test_world() -> World {
+    let mut world = World::new();
+    world.insert_resource(DeltaTime::from_ticks(1));
+    world
+}
+
+/// Spawns a test entity with blinking and renderable components
+fn spawn_blinking_entity(world: &mut World, interval_ticks: u32) -> Entity {
+    world
+        .spawn((
+            Blinking::new(interval_ticks),
+            Renderable {
+                sprite: common::mock_atlas_tile(1),
+                layer: 0,
+            },
+        ))
+        .id()
+}
+
+/// Spawns a test entity with blinking, renderable, and hidden components
+fn spawn_hidden_blinking_entity(world: &mut World, interval_ticks: u32) -> Entity {
+    world
+        .spawn((
+            Blinking::new(interval_ticks),
+            Renderable {
+                sprite: common::mock_atlas_tile(1),
+                layer: 0,
+            },
+            Hidden,
+        ))
+        .id()
+}
+
+/// Spawns a test entity with blinking, renderable, and frozen components
+fn spawn_frozen_blinking_entity(world: &mut World, interval_ticks: u32) -> Entity {
+    world
+        .spawn((
+            Blinking::new(interval_ticks),
+            Renderable {
+                sprite: common::mock_atlas_tile(1),
+                layer: 0,
+            },
+            Frozen,
+        ))
+        .id()
+}
+
+/// Spawns a test entity with blinking, renderable, hidden, and frozen components
+fn spawn_frozen_hidden_blinking_entity(world: &mut World, interval_ticks: u32) -> Entity {
+    world
+        .spawn((
+            Blinking::new(interval_ticks),
+            Renderable {
+                sprite: common::mock_atlas_tile(1),
+                layer: 0,
+            },
+            Hidden,
+            Frozen,
+        ))
+        .id()
+}
+
+/// Runs the blinking system with the given delta time
+fn run_blinking_system(world: &mut World, delta_ticks: u32) {
+    world.resource_mut::<DeltaTime>().ticks = delta_ticks;
+    world.run_system_once(blinking_system).unwrap();
+}
+
+/// Checks if an entity has the Hidden component
+fn has_hidden_component(world: &World, entity: Entity) -> bool {
+    world.entity(entity).contains::<Hidden>()
+}
+
+/// Checks if an entity has the Frozen component
+fn has_frozen_component(world: &World, entity: Entity) -> bool {
+    world.entity(entity).contains::<Frozen>()
 }
 
 #[test]
-fn test_blinking_texture() {
-    let tile = mock_atlas_tile(1);
-    let mut texture = BlinkingTexture::new(tile, 0.5);
+fn test_blinking_component_creation() {
+    let blinking = Blinking::new(10);
 
-    assert!(texture.is_on());
-
-    texture.tick(0.5);
-    assert!(!texture.is_on());
-
-    texture.tick(0.5);
-    assert!(texture.is_on());
-
-    texture.tick(0.5);
-    assert!(!texture.is_on());
+    assert_that(&blinking.tick_timer).is_equal_to(0);
+    assert_that(&blinking.interval_ticks).is_equal_to(10);
 }
 
 #[test]
-fn test_blinking_texture_partial_duration() {
-    let tile = mock_atlas_tile(1);
-    let mut texture = BlinkingTexture::new(tile, 0.5);
+fn test_blinking_system_normal_interval_no_toggle() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 5);
 
-    texture.tick(0.625);
-    assert!(!texture.is_on());
-    assert_eq!(texture.time_bank(), 0.125);
+    // Run system with 3 ticks (less than interval)
+    run_blinking_system(&mut world, 3);
+
+    // Entity should not be hidden yet
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+
+    // Check that timer was updated
+    let blinking = world.entity(entity).get::<Blinking>().unwrap();
+    assert_that(&blinking.tick_timer).is_equal_to(3);
 }
 
 #[test]
-fn test_blinking_texture_negative_time() {
-    let tile = mock_atlas_tile(1);
-    let mut texture = BlinkingTexture::new(tile, 0.5);
+fn test_blinking_system_normal_interval_first_toggle() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 5);
 
-    texture.tick(-0.1);
-    assert!(texture.is_on());
-    assert_eq!(texture.time_bank(), -0.1);
+    // Run system with 5 ticks (exactly one interval)
+    run_blinking_system(&mut world, 5);
+
+    // Entity should now be hidden
+    assert_that(&has_hidden_component(&world, entity)).is_true();
+
+    // Check that timer was reset
+    let blinking = world.entity(entity).get::<Blinking>().unwrap();
+    assert_that(&blinking.tick_timer).is_equal_to(0);
+}
+
+#[test]
+fn test_blinking_system_normal_interval_second_toggle() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 5);
+
+    // First toggle: 5 ticks
+    run_blinking_system(&mut world, 5);
+    assert_that(&has_hidden_component(&world, entity)).is_true();
+
+    // Second toggle: another 5 ticks
+    run_blinking_system(&mut world, 5);
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+}
+
+#[test]
+fn test_blinking_system_normal_interval_multiple_intervals() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 3);
+
+    // Run system with 7 ticks (2 complete intervals + 1 remainder)
+    run_blinking_system(&mut world, 7);
+
+    // Should toggle twice (even number), so back to original state (not hidden)
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+
+    // Check that timer was updated to remainder
+    let blinking = world.entity(entity).get::<Blinking>().unwrap();
+    assert_that(&blinking.tick_timer).is_equal_to(1);
+}
+
+#[test]
+fn test_blinking_system_normal_interval_odd_intervals() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 2);
+
+    // Run system with 5 ticks (2 complete intervals + 1 remainder)
+    run_blinking_system(&mut world, 5);
+
+    // Should toggle twice (even number), so back to original state (not hidden)
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+
+    // Check that timer was updated to remainder
+    let blinking = world.entity(entity).get::<Blinking>().unwrap();
+    assert_that(&blinking.tick_timer).is_equal_to(1);
+}
+
+#[test]
+fn test_blinking_system_zero_interval_with_ticks() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 0);
+
+    // Run system with any positive ticks
+    run_blinking_system(&mut world, 1);
+
+    // Entity should be hidden immediately
+    assert_that(&has_hidden_component(&world, entity)).is_true();
+}
+
+#[test]
+fn test_blinking_system_zero_interval_no_ticks() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 0);
+
+    // Run system with 0 ticks
+    run_blinking_system(&mut world, 0);
+
+    // Entity should not be hidden (no time passed)
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+}
+
+#[test]
+fn test_blinking_system_zero_interval_toggle_back() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_hidden_blinking_entity(&mut world, 0);
+
+    // Run system with any positive ticks
+    run_blinking_system(&mut world, 1);
+
+    // Entity should be unhidden
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+}
+
+#[test]
+fn test_blinking_system_frozen_entity_unhidden() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_frozen_hidden_blinking_entity(&mut world, 5);
+
+    // Run system with ticks
+    run_blinking_system(&mut world, 10);
+
+    // Frozen entity should be unhidden and stay unhidden
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+    assert_that(&has_frozen_component(&world, entity)).is_true();
+}
+
+#[test]
+fn test_blinking_system_frozen_entity_no_blinking() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_frozen_blinking_entity(&mut world, 5);
+
+    // Run system with ticks
+    run_blinking_system(&mut world, 10);
+
+    // Frozen entity should not be hidden (blinking disabled)
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+    assert_that(&has_frozen_component(&world, entity)).is_true();
+}
+
+#[test]
+fn test_blinking_system_frozen_entity_timer_not_updated() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_frozen_blinking_entity(&mut world, 5);
+
+    // Run system with ticks
+    run_blinking_system(&mut world, 10);
+
+    // Timer should not be updated for frozen entities
+    let blinking = world.entity(entity).get::<Blinking>().unwrap();
+    assert_that(&blinking.tick_timer).is_equal_to(0);
+}
+
+#[test]
+fn test_blinking_system_entity_without_renderable_ignored() {
+    let mut world = create_blinking_test_world();
+
+    // Spawn entity with only Blinking component (no Renderable)
+    let entity = world.spawn(Blinking::new(5)).id();
+
+    // Run system
+    run_blinking_system(&mut world, 10);
+
+    // Entity should not be affected (not in query)
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+}
+
+#[test]
+fn test_blinking_system_entity_without_blinking_ignored() {
+    let mut world = create_blinking_test_world();
+
+    // Spawn entity with only Renderable component (no Blinking)
+    let entity = world
+        .spawn(Renderable {
+            sprite: common::mock_atlas_tile(1),
+            layer: 0,
+        })
+        .id();
+
+    // Run system
+    run_blinking_system(&mut world, 10);
+
+    // Entity should not be affected (not in query)
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+}
+
+#[test]
+fn test_blinking_system_large_interval() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 1000);
+
+    // Run system with 500 ticks (less than interval)
+    run_blinking_system(&mut world, 500);
+
+    // Entity should not be hidden yet
+    assert_that(&has_hidden_component(&world, entity)).is_false();
+
+    // Check that timer was updated
+    let blinking = world.entity(entity).get::<Blinking>().unwrap();
+    assert_that(&blinking.tick_timer).is_equal_to(500);
+}
+
+#[test]
+fn test_blinking_system_very_small_interval() {
+    let mut world = create_blinking_test_world();
+    let entity = spawn_blinking_entity(&mut world, 1);
+
+    // Run system with 1 tick
+    run_blinking_system(&mut world, 1);
+
+    // Entity should be hidden
+    assert_that(&has_hidden_component(&world, entity)).is_true();
+
+    // Run system with another 1 tick
+    run_blinking_system(&mut world, 1);
+
+    // Entity should be unhidden
+    assert_that(&has_hidden_component(&world, entity)).is_false();
 }

tests/collision.rs

@@ -1,119 +1,84 @@
-use pacman::entity::collision::{Collidable, CollisionSystem};
-use pacman::entity::traversal::Position;
+use bevy_ecs::system::RunSystemOnce;
+use pacman::systems::{check_collision, collision_system, Collider, EntityType, GhostState, Position};
+use speculoos::prelude::*;
 
-struct MockCollidable {
-    pos: Position,
-}
+mod common;
 
-impl Collidable for MockCollidable {
-    fn position(&self) -> Position {
-        self.pos
-    }
+#[test]
+fn test_collider_collision_detection() {
+    let collider1 = Collider { size: 10.0 };
+    let collider2 = Collider { size: 8.0 };
+
+    // Test collision detection
+    assert_that(&collider1.collides_with(collider2.size, 5.0)).is_true(); // Should collide (distance < 9.0)
+    assert_that(&collider1.collides_with(collider2.size, 15.0)).is_false(); // Should not collide (distance > 9.0)
 }
 
 #[test]
-fn test_is_colliding_with() {
-    let entity1 = MockCollidable {
-        pos: Position::AtNode(1),
-    };
-    let entity2 = MockCollidable {
-        pos: Position::AtNode(1),
-    };
-    let entity3 = MockCollidable {
-        pos: Position::AtNode(2),
-    };
-    let entity4 = MockCollidable {
-        pos: Position::BetweenNodes {
-            from: 1,
-            to: 2,
-            traversed: 0.5,
-        },
-    };
+fn test_check_collision_helper() {
+    let map = common::create_test_map();
+    let pos1 = Position::Stopped { node: 0 };
+    let pos2 = Position::Stopped { node: 0 }; // Same position
+    let collider1 = Collider { size: 10.0 };
+    let collider2 = Collider { size: 8.0 };
 
-    assert!(entity1.is_colliding_with(&entity2));
-    assert!(!entity1.is_colliding_with(&entity3));
-    assert!(entity1.is_colliding_with(&entity4));
-    assert!(entity3.is_colliding_with(&entity4));
+    // Test collision at same position
+    let result = check_collision(&pos1, &collider1, &pos2, &collider2, &map);
+    assert_that(&result.is_ok()).is_true();
+    assert_that(&result.unwrap()).is_true(); // Should collide at same position
+
+    // Test collision at different positions
+    let pos3 = Position::Stopped { node: 1 }; // Different position
+    let result = check_collision(&pos1, &collider1, &pos3, &collider2, &map);
+    assert_that(&result.is_ok()).is_true();
+    // May or may not collide depending on actual node positions
 }
 
 #[test]
-fn test_collision_system_register_and_query() {
-    let mut collision_system = CollisionSystem::default();
+fn test_collision_system_pacman_item() {
+    let mut world = common::create_test_world();
+    let _pacman = common::spawn_test_pacman(&mut world, 0);
+    let _item = common::spawn_test_item(&mut world, 0, EntityType::Pellet);
 
-    let pos1 = Position::AtNode(1);
-    let entity1 = collision_system.register_entity(pos1);
-
-    let pos2 = Position::BetweenNodes {
-        from: 1,
-        to: 2,
-        traversed: 0.5,
-    };
-    let entity2 = collision_system.register_entity(pos2);
-
-    let pos3 = Position::AtNode(3);
-    let entity3 = collision_system.register_entity(pos3);
-
-    // Test entities_at_node
-    assert_eq!(collision_system.entities_at_node(1), &[entity1, entity2]);
-    assert_eq!(collision_system.entities_at_node(2), &[entity2]);
-    assert_eq!(collision_system.entities_at_node(3), &[entity3]);
-    assert_eq!(collision_system.entities_at_node(4), &[] as &[u32]);
-
-    // Test potential_collisions
-    let mut collisions1 = collision_system.potential_collisions(&pos1);
-    collisions1.sort_unstable();
-    assert_eq!(collisions1, vec![entity1, entity2]);
-
-    let mut collisions2 = collision_system.potential_collisions(&pos2);
-    collisions2.sort_unstable();
-    assert_eq!(collisions2, vec![entity1, entity2]);
-
-    let mut collisions3 = collision_system.potential_collisions(&pos3);
-    collisions3.sort_unstable();
-    assert_eq!(collisions3, vec![entity3]);
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
 }
 
 #[test]
-fn test_collision_system_update() {
-    let mut collision_system = CollisionSystem::default();
+fn test_collision_system_pacman_ghost() {
+    let mut world = common::create_test_world();
+    let _pacman = common::spawn_test_pacman(&mut world, 0);
+    let _ghost = common::spawn_test_ghost(&mut world, 0, GhostState::Normal);
 
-    let entity1 = collision_system.register_entity(Position::AtNode(1));
-
-    assert_eq!(collision_system.entities_at_node(1), &[entity1]);
-    assert_eq!(collision_system.entities_at_node(2), &[] as &[u32]);
-
-    collision_system.update_position(entity1, Position::AtNode(2));
-
-    assert_eq!(collision_system.entities_at_node(1), &[] as &[u32]);
-    assert_eq!(collision_system.entities_at_node(2), &[entity1]);
-
-    collision_system.update_position(
-        entity1,
-        Position::BetweenNodes {
-            from: 2,
-            to: 3,
-            traversed: 0.1,
-        },
-    );
-
-    assert_eq!(collision_system.entities_at_node(1), &[] as &[u32]);
-    assert_eq!(collision_system.entities_at_node(2), &[entity1]);
-    assert_eq!(collision_system.entities_at_node(3), &[entity1]);
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
 }
 
 #[test]
-fn test_collision_system_remove() {
-    let mut collision_system = CollisionSystem::default();
+fn test_collision_system_no_collision() {
+    let mut world = common::create_test_world();
+    let _pacman = common::spawn_test_pacman(&mut world, 0);
+    let _ghost = common::spawn_test_ghost(&mut world, 1, GhostState::Normal); // Different node
 
-    let entity1 = collision_system.register_entity(Position::AtNode(1));
-    let entity2 = collision_system.register_entity(Position::AtNode(1));
-
-    assert_eq!(collision_system.entities_at_node(1), &[entity1, entity2]);
-
-    collision_system.remove_entity(entity1);
-
-    assert_eq!(collision_system.entities_at_node(1), &[entity2]);
-
-    collision_system.remove_entity(entity2);
-    assert_eq!(collision_system.entities_at_node(1), &[] as &[u32]);
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
+}
+
+#[test]
+fn test_collision_system_multiple_entities() {
+    let mut world = common::create_test_world();
+    let _pacman = common::spawn_test_pacman(&mut world, 0);
+    let _item = common::spawn_test_item(&mut world, 0, EntityType::Pellet);
+    let _ghost = common::spawn_test_ghost(&mut world, 0, GhostState::Normal);
+
+    // Run collision system - should not panic
+    world
+        .run_system_once(collision_system)
+        .expect("System should run successfully");
 }

tests/common/mod.rs

@@ -1,12 +1,27 @@
 #![allow(dead_code)]
 
+use bevy_ecs::{entity::Entity, event::Events, world::World};
+use glam::{U16Vec2, Vec2};
 use pacman::{
     asset::{get_asset_bytes, Asset},
-    texture::sprite::SpriteAtlas,
+    constants::RAW_BOARD,
+    events::GameEvent,
+    game::ATLAS_FRAMES,
+    map::{
+        builder::Map,
+        direction::Direction,
+        graph::{Graph, Node},
+    },
+    systems::{
+        AudioEvent, AudioState, BufferedDirection, Collider, DebugState, DeltaTime, EntityType, Ghost, GhostCollider, GhostState,
+        GlobalState, ItemCollider, MovementModifiers, PacmanCollider, PlayerControlled, Position, ScoreResource, Velocity,
+    },
+    texture::sprite::{AtlasMapper, AtlasTile, SpriteAtlas},
 };
 use sdl2::{
     image::LoadTexture,
-    render::{Canvas, Texture, TextureCreator},
+    pixels::Color,
+    render::{Canvas, TextureCreator},
     video::{Window, WindowContext},
     Sdl,
 };
@@ -27,13 +42,135 @@ pub fn setup_sdl() -> Result<(Canvas<Window>, TextureCreator<WindowContext>, Sdl
 
 pub fn create_atlas(canvas: &mut sdl2::render::Canvas<sdl2::video::Window>) -> SpriteAtlas {
     let texture_creator = canvas.texture_creator();
-    let atlas_bytes = get_asset_bytes(Asset::Atlas).unwrap();
-    let atlas_json = get_asset_bytes(Asset::AtlasJson).unwrap();
+    let atlas_bytes = get_asset_bytes(Asset::AtlasImage).unwrap();
 
     let texture = texture_creator.load_texture_bytes(&atlas_bytes).unwrap();
-    let texture: Texture<'static> = unsafe { std::mem::transmute(texture) };
 
-    let mapper: pacman::texture::sprite::AtlasMapper = serde_json::from_slice(&atlas_json).unwrap();
+    let atlas_mapper = AtlasMapper {
+        frames: ATLAS_FRAMES.into_iter().map(|(k, v)| (k.to_string(), *v)).collect(),
+    };
 
-    SpriteAtlas::new(texture, mapper)
+    SpriteAtlas::new(texture, atlas_mapper)
+}
+
+/// Creates a simple test graph with 3 connected nodes for testing
+pub fn create_test_graph() -> Graph {
+    let mut graph = Graph::new();
+
+    let node0 = graph.add_node(Node {
+        position: Vec2::new(0.0, 0.0),
+    });
+    let node1 = graph.add_node(Node {
+        position: Vec2::new(16.0, 0.0),
+    });
+    let node2 = graph.add_node(Node {
+        position: Vec2::new(0.0, 16.0),
+    });
+
+    graph.connect(node0, node1, false, None, Direction::Right).unwrap();
+    graph.connect(node0, node2, false, None, Direction::Down).unwrap();
+
+    graph
+}
+
+/// Creates a basic test world with required resources for ECS systems
+pub fn create_test_world() -> World {
+    let mut world = World::new();
+
+    // Add required resources
+    world.insert_resource(Events::<GameEvent>::default());
+    world.insert_resource(Events::<pacman::error::GameError>::default());
+    world.insert_resource(Events::<AudioEvent>::default());
+    world.insert_resource(ScoreResource(0));
+    world.insert_resource(AudioState::default());
+    world.insert_resource(GlobalState { exit: false });
+    world.insert_resource(DebugState::default());
+    world.insert_resource(DeltaTime {
+        seconds: 1.0 / 60.0,
+        ticks: 1,
+    }); // 60 FPS
+    world.insert_resource(create_test_map());
+
+    world
+}
+
+/// Creates a test map using the default RAW_BOARD
+pub fn create_test_map() -> Map {
+    Map::new(RAW_BOARD).expect("Failed to create test map")
+}
+
+/// Spawns a test Pac-Man entity at the specified node
+pub fn spawn_test_pacman(world: &mut World, node: usize) -> Entity {
+    world
+        .spawn((
+            Position::Stopped { node: node as u16 },
+            Collider { size: 10.0 },
+            PacmanCollider,
+            EntityType::Player,
+        ))
+        .id()
+}
+
+/// Spawns a controllable test player entity
+pub fn spawn_test_player(world: &mut World, node: usize) -> Entity {
+    world
+        .spawn((
+            PlayerControlled,
+            Position::Stopped { node: node as u16 },
+            Velocity {
+                speed: 1.0,
+                direction: Direction::Right,
+            },
+            BufferedDirection::None,
+            EntityType::Player,
+            MovementModifiers::default(),
+        ))
+        .id()
+}
+
+/// Spawns a test item entity at the specified node
+pub fn spawn_test_item(world: &mut World, node: usize, item_type: EntityType) -> Entity {
+    world
+        .spawn((
+            Position::Stopped { node: node as u16 },
+            Collider { size: 8.0 },
+            ItemCollider,
+            item_type,
+        ))
+        .id()
+}
+
+/// Spawns a test ghost entity at the specified node
+pub fn spawn_test_ghost(world: &mut World, node: usize, ghost_state: GhostState) -> Entity {
+    world
+        .spawn((
+            Position::Stopped { node: node as u16 },
+            Collider { size: 12.0 },
+            GhostCollider,
+            Ghost::Blinky,
+            EntityType::Ghost,
+            ghost_state,
+        ))
+        .id()
+}
+
+/// Sends a game event to the world
+pub fn send_game_event(world: &mut World, event: GameEvent) {
+    let mut events = world.resource_mut::<Events<GameEvent>>();
+    events.send(event);
+}
+
+/// Sends a collision event between two entities
+pub fn send_collision_event(world: &mut World, entity1: Entity, entity2: Entity) {
+    let mut events = world.resource_mut::<Events<GameEvent>>();
+    events.send(GameEvent::Collision(entity1, entity2));
+}
+
+/// Creates a mock atlas tile for testing
+pub fn mock_atlas_tile(id: u32) -> AtlasTile {
+    AtlasTile {
+        pos: U16Vec2::new(0, 0),
+        size: U16Vec2::new(16, 16),
+        color: Some(Color::RGB(id as u8, 0, 0)),
+    }
 }

tests/constants.rs

@@ -1,28 +0,0 @@
-use pacman::constants::*;
-
-#[test]
-fn test_raw_board_structure() {
-    assert_eq!(RAW_BOARD.len(), BOARD_CELL_SIZE.y as usize);
-
-    for row in RAW_BOARD.iter() {
-        assert_eq!(row.len(), BOARD_CELL_SIZE.x as usize);
-    }
-
-    // Test boundaries
-    assert!(RAW_BOARD[0].chars().all(|c| c == '#'));
-    assert!(RAW_BOARD[RAW_BOARD.len() - 1].chars().all(|c| c == '#'));
-
-    // Test tunnel row
-    let tunnel_row = RAW_BOARD[14];
-    assert_eq!(tunnel_row.chars().next().unwrap(), 'T');
-    assert_eq!(tunnel_row.chars().last().unwrap(), 'T');
-}
-
-#[test]
-fn test_raw_board_content() {
-    let power_pellet_count = RAW_BOARD.iter().flat_map(|row| row.chars()).filter(|&c| c == 'o').count();
-    assert_eq!(power_pellet_count, 4);
-
-    assert!(RAW_BOARD.iter().any(|row| row.contains('X')));
-    assert!(RAW_BOARD.iter().any(|row| row.contains("==")));
-}

tests/debug_rendering.rs

@@ -1,34 +0,0 @@
-use glam::Vec2;
-use pacman::entity::graph::{Graph, Node};
-use pacman::map::render::MapRenderer;
-
-#[test]
-fn test_find_nearest_node() {
-    let mut graph = Graph::new();
-
-    // Add some test nodes
-    let node1 = graph.add_node(Node {
-        position: Vec2::new(10.0, 10.0),
-    });
-    let node2 = graph.add_node(Node {
-        position: Vec2::new(50.0, 50.0),
-    });
-    let node3 = graph.add_node(Node {
-        position: Vec2::new(100.0, 100.0),
-    });
-
-    // Test cursor near node1
-    let cursor_pos = Vec2::new(12.0, 8.0);
-    let nearest = MapRenderer::find_nearest_node(&graph, cursor_pos);
-    assert_eq!(nearest, Some(node1));
-
-    // Test cursor near node2
-    let cursor_pos = Vec2::new(45.0, 55.0);
-    let nearest = MapRenderer::find_nearest_node(&graph, cursor_pos);
-    assert_eq!(nearest, Some(node2));
-
-    // Test cursor near node3
-    let cursor_pos = Vec2::new(98.0, 102.0);
-    let nearest = MapRenderer::find_nearest_node(&graph, cursor_pos);
-    assert_eq!(nearest, Some(node3));
-}

tests/direction.rs

@@ -1,5 +1,5 @@
-use glam::IVec2;
-use pacman::entity::direction::*;
+use pacman::map::direction::*;
+use speculoos::prelude::*;
 
 #[test]
 fn test_direction_opposite() {
@@ -11,21 +11,47 @@ fn test_direction_opposite() {
     ];
 
     for (dir, expected) in test_cases {
-        assert_eq!(dir.opposite(), expected);
+        assert_that(&dir.opposite()).is_equal_to(expected);
     }
 }
 
 #[test]
-fn test_direction_as_ivec2() {
-    let test_cases = [
-        (Direction::Up, -IVec2::Y),
-        (Direction::Down, IVec2::Y),
-        (Direction::Left, -IVec2::X),
-        (Direction::Right, IVec2::X),
-    ];
-
-    for (dir, expected) in test_cases {
-        assert_eq!(dir.as_ivec2(), expected);
-        assert_eq!(IVec2::from(dir), expected);
+fn test_direction_opposite_symmetry() {
+    // Test that opposite() is symmetric: opposite(opposite(d)) == d
+    for &dir in &Direction::DIRECTIONS {
+        assert_that(&dir.opposite().opposite()).is_equal_to(dir);
     }
 }
+
+#[test]
+fn test_direction_opposite_exhaustive() {
+    // Test that every direction has a unique opposite
+    let mut opposites = std::collections::HashSet::new();
+    for &dir in &Direction::DIRECTIONS {
+        let opposite = dir.opposite();
+        assert_that(&opposites.insert(opposite)).is_true();
+    }
+    assert_that(&opposites).has_length(4);
+}
+
+#[test]
+fn test_direction_as_usize_exhaustive() {
+    // Test that as_usize() returns unique values for all directions
+    let mut usizes = std::collections::HashSet::new();
+    for &dir in &Direction::DIRECTIONS {
+        let usize_val = dir.as_usize();
+        assert_that(&usizes.insert(usize_val)).is_true();
+    }
+    assert_that(&usizes).has_length(4);
+}
+
+#[test]
+fn test_direction_as_ivec2_exhaustive() {
+    // Test that as_ivec2() returns unique values for all directions
+    let mut ivec2s = std::collections::HashSet::new();
+    for &dir in &Direction::DIRECTIONS {
+        let ivec2_val = dir.as_ivec2();
+        assert_that(&ivec2s.insert(ivec2_val)).is_true();
+    }
+    assert_that(&ivec2s).has_length(4);
+}

tests/directional.rs

@@ -1,77 +0,0 @@
-use glam::U16Vec2;
-use pacman::entity::direction::Direction;
-use pacman::texture::animated::AnimatedTexture;
-use pacman::texture::directional::DirectionalAnimatedTexture;
-use pacman::texture::sprite::AtlasTile;
-use sdl2::pixels::Color;
-
-fn mock_atlas_tile(id: u32) -> AtlasTile {
-    AtlasTile {
-        pos: U16Vec2::new(0, 0),
-        size: U16Vec2::new(16, 16),
-        color: Some(Color::RGB(id as u8, 0, 0)),
-    }
-}
-
-fn mock_animated_texture(id: u32) -> AnimatedTexture {
-    AnimatedTexture::new(vec![mock_atlas_tile(id)], 0.1).expect("Invalid frame duration")
-}
-
-#[test]
-fn test_directional_texture_partial_directions() {
-    let mut textures = [None, None, None, None];
-    textures[Direction::Up.as_usize()] = Some(mock_animated_texture(1));
-
-    let texture = DirectionalAnimatedTexture::new(textures, [None, None, None, None]);
-
-    assert_eq!(texture.texture_count(), 1);
-    assert!(texture.has_direction(Direction::Up));
-    assert!(!texture.has_direction(Direction::Down));
-    assert!(!texture.has_direction(Direction::Left));
-    assert!(!texture.has_direction(Direction::Right));
-}
-
-#[test]
-fn test_directional_texture_all_directions() {
-    let mut textures = [None, None, None, None];
-    let directions = [
-        (Direction::Up, 1),
-        (Direction::Down, 2),
-        (Direction::Left, 3),
-        (Direction::Right, 4),
-    ];
-
-    for (direction, id) in directions {
-        textures[direction.as_usize()] = Some(mock_animated_texture(id));
-    }
-
-    let texture = DirectionalAnimatedTexture::new(textures, [None, None, None, None]);
-
-    assert_eq!(texture.texture_count(), 4);
-    for direction in &[Direction::Up, Direction::Down, Direction::Left, Direction::Right] {
-        assert!(texture.has_direction(*direction));
-    }
-}
-
-#[test]
-fn test_directional_texture_stopped() {
-    let mut stopped_textures = [None, None, None, None];
-    stopped_textures[Direction::Up.as_usize()] = Some(mock_animated_texture(1));
-
-    let texture = DirectionalAnimatedTexture::new([None, None, None, None], stopped_textures);
-
-    assert_eq!(texture.stopped_texture_count(), 1);
-    assert!(texture.has_stopped_direction(Direction::Up));
-    assert!(!texture.has_stopped_direction(Direction::Down));
-}
-
-#[test]
-fn test_directional_texture_tick() {
-    let mut textures = [None, None, None, None];
-    textures[Direction::Up.as_usize()] = Some(mock_animated_texture(1));
-    let mut texture = DirectionalAnimatedTexture::new(textures, [None, None, None, None]);
-
-    // This is a bit of a placeholder, since we can't inspect the inner state easily.
-    // We're just ensuring the tick method runs without panicking.
-    texture.tick(0.1);
-}

tests/error.rs

@@ -0,0 +1,66 @@
+use pacman::error::{GameError, GameResult, IntoGameError, OptionExt, ResultExt};
+use speculoos::prelude::*;
+use std::io;
+
+#[test]
+fn test_into_game_error_trait() {
+    let result: Result<i32, io::Error> = Err(io::Error::new(io::ErrorKind::Other, "test error"));
+    let game_result: GameResult<i32> = result.into_game_error();
+
+    assert_that(&game_result.is_err()).is_true();
+    if let Err(GameError::InvalidState(msg)) = game_result {
+        assert_that(&msg.contains("test error")).is_true();
+    } else {
+        panic!("Expected InvalidState error");
+    }
+}
+
+#[test]
+fn test_into_game_error_trait_success() {
+    let result: Result<i32, io::Error> = Ok(42);
+    let game_result: GameResult<i32> = result.into_game_error();
+
+    assert_that(&game_result.unwrap()).is_equal_to(42);
+}
+
+#[test]
+fn test_option_ext_some() {
+    let option: Option<i32> = Some(42);
+    let result: GameResult<i32> = option.ok_or_game_error(|| GameError::InvalidState("Not found".to_string()));
+
+    assert_that(&result.unwrap()).is_equal_to(42);
+}
+
+#[test]
+fn test_option_ext_none() {
+    let option: Option<i32> = None;
+    let result: GameResult<i32> = option.ok_or_game_error(|| GameError::InvalidState("Not found".to_string()));
+
+    assert_that(&result.is_err()).is_true();
+    if let Err(GameError::InvalidState(msg)) = result {
+        assert_that(&msg).is_equal_to("Not found".to_string());
+    } else {
+        panic!("Expected InvalidState error");
+    }
+}
+
+#[test]
+fn test_result_ext_success() {
+    let result: Result<i32, io::Error> = Ok(42);
+    let game_result: GameResult<i32> = result.with_context(|_| GameError::InvalidState("Context".to_string()));
+
+    assert_that(&game_result.unwrap()).is_equal_to(42);
+}
+
+#[test]
+fn test_result_ext_error() {
+    let result: Result<i32, io::Error> = Err(io::Error::new(io::ErrorKind::Other, "original error"));
+    let game_result: GameResult<i32> = result.with_context(|_| GameError::InvalidState("Context error".to_string()));
+
+    assert_that(&game_result.is_err()).is_true();
+    if let Err(GameError::InvalidState(msg)) = game_result {
+        assert_that(&msg).is_equal_to("Context error".to_string());
+    } else {
+        panic!("Expected InvalidState error");
+    }
+}

tests/formatting.rs

@@ -0,0 +1,141 @@
+use pacman::systems::profiling::format_timing_display;
+use speculoos::prelude::*;
+use std::time::Duration;
+
+fn get_timing_data() -> Vec<(String, Duration, Duration)> {
+    vec![
+        ("total".to_string(), Duration::from_micros(1234), Duration::from_micros(570)),
+        ("input".to_string(), Duration::from_micros(120), Duration::from_micros(45)),
+        ("player".to_string(), Duration::from_micros(456), Duration::from_micros(123)),
+        ("movement".to_string(), Duration::from_micros(789), Duration::from_micros(234)),
+        ("render".to_string(), Duration::from_micros(12), Duration::from_micros(3)),
+        ("debug".to_string(), Duration::from_nanos(460), Duration::from_nanos(557)),
+    ]
+}
+
+fn get_formatted_output() -> impl IntoIterator<Item = String> {
+    format_timing_display(get_timing_data())
+}
+
+#[test]
+fn test_complex_formatting_alignment() {
+    let mut colon_positions = vec![];
+    let mut first_decimal_positions = vec![];
+    let mut second_decimal_positions = vec![];
+    let mut first_unit_positions = vec![];
+    let mut second_unit_positions = vec![];
+
+    get_formatted_output().into_iter().for_each(|line| {
+        let (mut got_decimal, mut got_unit) = (false, false);
+        for (i, char) in line.chars().enumerate() {
+            match char {
+                ':' => colon_positions.push(i),
+                '.' => {
+                    if got_decimal {
+                        second_decimal_positions.push(i);
+                    } else {
+                        first_decimal_positions.push(i);
+                    }
+                    got_decimal = true;
+                }
+                's' => {
+                    if got_unit {
+                        first_unit_positions.push(i);
+                    } else {
+                        second_unit_positions.push(i);
+                        got_unit = true;
+                    }
+                }
+                _ => {}
+            }
+        }
+    });
+
+    // Assert that all positions were found
+    assert_that(
+        &[
+            &colon_positions,
+            &first_decimal_positions,
+            &second_decimal_positions,
+            &first_unit_positions,
+            &second_unit_positions,
+        ]
+        .iter()
+        .all(|p| p.len() == 6),
+    )
+    .is_true();
+
+    // Assert that all positions are the same
+    assert_that(&colon_positions.iter().all(|&p| p == colon_positions[0])).is_true();
+    assert_that(&first_decimal_positions.iter().all(|&p| p == first_decimal_positions[0])).is_true();
+    assert_that(&second_decimal_positions.iter().all(|&p| p == second_decimal_positions[0])).is_true();
+    assert_that(&first_unit_positions.iter().all(|&p| p == first_unit_positions[0])).is_true();
+    assert_that(&second_unit_positions.iter().all(|&p| p == second_unit_positions[0])).is_true();
+}
+
+#[test]
+fn test_format_timing_display_basic() {
+    let timing_data = vec![
+        ("render".to_string(), Duration::from_micros(1500), Duration::from_micros(200)),
+        ("input".to_string(), Duration::from_micros(300), Duration::from_micros(50)),
+        ("physics".to_string(), Duration::from_nanos(750), Duration::from_nanos(100)),
+    ];
+
+    let formatted = format_timing_display(timing_data);
+
+    // Should have 3 lines (one for each system)
+    assert_that(&formatted.len()).is_equal_to(3);
+
+    // Each line should contain the system name
+    assert_that(&formatted.iter().any(|line| line.contains("render"))).is_true();
+    assert_that(&formatted.iter().any(|line| line.contains("input"))).is_true();
+    assert_that(&formatted.iter().any(|line| line.contains("physics"))).is_true();
+
+    // Each line should contain timing information with proper units
+    for line in formatted.iter() {
+        assert_that(&line.contains(":")).is_true();
+        assert_that(&line.contains("±")).is_true();
+    }
+}
+
+#[test]
+fn test_format_timing_display_units() {
+    let timing_data = vec![
+        ("seconds".to_string(), Duration::from_secs(2), Duration::from_millis(100)),
+        ("millis".to_string(), Duration::from_millis(15), Duration::from_micros(200)),
+        ("micros".to_string(), Duration::from_micros(500), Duration::from_nanos(50)),
+        ("nanos".to_string(), Duration::from_nanos(250), Duration::from_nanos(25)),
+    ];
+
+    let formatted = format_timing_display(timing_data);
+
+    // Check that appropriate units are used
+    let all_lines = formatted.join(" ");
+    assert_that(&all_lines.contains("s")).is_true();
+    assert_that(&all_lines.contains("ms")).is_true();
+    assert_that(&all_lines.contains("µs")).is_true();
+    assert_that(&all_lines.contains("ns")).is_true();
+}
+
+#[test]
+fn test_format_timing_display_alignment() {
+    let timing_data = vec![
+        ("short".to_string(), Duration::from_micros(100), Duration::from_micros(10)),
+        (
+            "very_long_name".to_string(),
+            Duration::from_micros(200),
+            Duration::from_micros(20),
+        ),
+    ];
+
+    let formatted = format_timing_display(timing_data);
+
+    // Find colon positions - they should be aligned
+    let colon_positions: Vec<usize> = formatted.iter().map(|line| line.find(':').unwrap_or(0)).collect();
+
+    // All colons should be at the same position (aligned)
+    if colon_positions.len() > 1 {
+        let first_pos = colon_positions[0];
+        assert_that(&colon_positions.iter().all(|&pos| pos == first_pos)).is_true();
+    }
+}

tests/game.rs

@@ -1,13 +1,79 @@
-use pacman::constants::RAW_BOARD;
-use pacman::map::Map;
+use pacman::error::{GameError, GameResult};
+use pacman::game::Game;
+use speculoos::prelude::*;
 
-mod collision;
-mod item;
+mod common;
+
+use common::setup_sdl;
 
 #[test]
-fn test_game_map_creation() {
-    let map = Map::new(RAW_BOARD).unwrap();
+fn test_game_30_seconds_60fps() -> GameResult<()> {
+    let (canvas, texture_creator, _sdl_context) = setup_sdl().map_err(GameError::Sdl)?;
+    let ttf_context = sdl2::ttf::init().map_err(GameError::Sdl)?;
+    let event_pump = _sdl_context
+        .event_pump()
+        .map_err(|e| pacman::error::GameError::Sdl(e.to_string()))?;
 
-    assert!(map.graph.node_count() > 0);
-    assert!(!map.grid_to_node.is_empty());
+    let mut game = Game::new(canvas, ttf_context, texture_creator, event_pump)?;
+
+    // Run for 30 seconds at 60 FPS = 1800 frames
+    let frame_time = 1.0 / 60.0;
+    let total_frames = 1800;
+    let mut frame_count = 0;
+
+    for _ in 0..total_frames {
+        let should_exit = game.tick(frame_time);
+
+        if should_exit {
+            break;
+        }
+
+        frame_count += 1;
+    }
+
+    assert_eq!(
+        frame_count, total_frames,
+        "Should have processed exactly {} frames",
+        total_frames
+    );
+    Ok(())
+}
+
+/// Test that runs the game for 30 seconds with variable frame timing
+#[test]
+fn test_game_30_seconds_variable_timing() -> GameResult<()> {
+    let (canvas, texture_creator, _sdl_context) = setup_sdl().map_err(GameError::Sdl)?;
+    let ttf_context = sdl2::ttf::init().map_err(|e| GameError::Sdl(e.to_string()))?;
+    let event_pump = _sdl_context
+        .event_pump()
+        .map_err(|e| pacman::error::GameError::Sdl(e.to_string()))?;
+
+    let mut game = Game::new(canvas, ttf_context, texture_creator, event_pump)?;
+
+    // Simulate 30 seconds with variable frame timing
+    let mut total_time = 0.0;
+    let target_time = 30.0;
+    let mut frame_count = 0;
+
+    while total_time < target_time {
+        // Alternate between different frame rates to simulate real gameplay
+        let frame_time = match frame_count % 4 {
+            0 => 1.0 / 60.0,  // 60 FPS
+            1 => 1.0 / 30.0,  // 30 FPS (lag spike)
+            2 => 1.0 / 120.0, // 120 FPS (very fast)
+            _ => 1.0 / 60.0,  // 60 FPS
+        };
+
+        let should_exit = game.tick(frame_time);
+
+        if should_exit {
+            break;
+        }
+
+        total_time += frame_time;
+        frame_count += 1;
+    }
+
+    assert_that(&total_time).is_greater_than_or_equal_to(target_time);
+    Ok(())
 }

tests/ghost.rs

@@ -1,48 +0,0 @@
-use pacman::entity::ghost::{Ghost, GhostType};
-use pacman::entity::graph::Graph;
-use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
-use std::collections::HashMap;
-
-fn create_test_atlas() -> SpriteAtlas {
-    let mut frames = HashMap::new();
-    let directions = ["up", "down", "left", "right"];
-    let ghost_types = ["blinky", "pinky", "inky", "clyde"];
-
-    for ghost_type in &ghost_types {
-        for (i, dir) in directions.iter().enumerate() {
-            frames.insert(
-                format!("ghost/{}/{}_{}.png", ghost_type, dir, "a"),
-                MapperFrame {
-                    x: i as u16 * 16,
-                    y: 0,
-                    width: 16,
-                    height: 16,
-                },
-            );
-            frames.insert(
-                format!("ghost/{}/{}_{}.png", ghost_type, dir, "b"),
-                MapperFrame {
-                    x: i as u16 * 16,
-                    y: 16,
-                    width: 16,
-                    height: 16,
-                },
-            );
-        }
-    }
-
-    let mapper = AtlasMapper { frames };
-    let dummy_texture = unsafe { std::mem::zeroed() };
-    SpriteAtlas::new(dummy_texture, mapper)
-}
-
-#[test]
-fn test_ghost_creation() {
-    let graph = Graph::new();
-    let atlas = create_test_atlas();
-
-    let ghost = Ghost::new(&graph, 0, GhostType::Blinky, &atlas).unwrap();
-
-    assert_eq!(ghost.ghost_type, GhostType::Blinky);
-    assert_eq!(ghost.traverser.position.from_node_id(), 0);
-}

tests/graph.rs

@@ -1,24 +1,8 @@
-use pacman::entity::direction::Direction;
-use pacman::entity::graph::{EdgePermissions, Graph, Node};
-use pacman::entity::traversal::{Position, Traverser};
+use pacman::map::direction::Direction;
+use pacman::map::graph::{Graph, Node, TraversalFlags};
+use speculoos::prelude::*;
 
-fn create_test_graph() -> Graph {
-    let mut graph = Graph::new();
-    let node1 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 0.0),
-    });
-    let node2 = graph.add_node(Node {
-        position: glam::Vec2::new(16.0, 0.0),
-    });
-    let node3 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 16.0),
-    });
-
-    graph.connect(node1, node2, false, None, Direction::Right).unwrap();
-    graph.connect(node1, node3, false, None, Direction::Down).unwrap();
-
-    graph
-}
+mod common;
 
 #[test]
 fn test_graph_basic_operations() {
@@ -30,10 +14,10 @@ fn test_graph_basic_operations() {
         position: glam::Vec2::new(16.0, 0.0),
     });
 
-    assert_eq!(graph.node_count(), 2);
-    assert!(graph.get_node(node1).is_some());
-    assert!(graph.get_node(node2).is_some());
-    assert!(graph.get_node(999).is_none());
+    assert_that(&graph.nodes().count()).is_equal_to(2);
+    assert_that(&graph.get_node(node1).is_some()).is_true();
+    assert_that(&graph.get_node(node2).is_some()).is_true();
+    assert_that(&graph.get_node(999).is_none()).is_true();
 }
 
 #[test]
@@ -46,15 +30,15 @@ fn test_graph_connect() {
         position: glam::Vec2::new(16.0, 0.0),
     });
 
-    assert!(graph.connect(node1, node2, false, None, Direction::Right).is_ok());
+    assert_that(&graph.connect(node1, node2, false, None, Direction::Right).is_ok()).is_true();
 
     let edge1 = graph.find_edge_in_direction(node1, Direction::Right);
     let edge2 = graph.find_edge_in_direction(node2, Direction::Left);
 
-    assert!(edge1.is_some());
-    assert!(edge2.is_some());
-    assert_eq!(edge1.unwrap().target, node2);
-    assert_eq!(edge2.unwrap().target, node1);
+    assert_that(&edge1.is_some()).is_true();
+    assert_that(&edge2.is_some()).is_true();
+    assert_that(&edge1.unwrap().target).is_equal_to(node2);
+    assert_that(&edge2.unwrap().target).is_equal_to(node1);
 }
 
 #[test]
@@ -64,8 +48,8 @@ fn test_graph_connect_errors() {
         position: glam::Vec2::new(0.0, 0.0),
     });
 
-    assert!(graph.connect(node1, 999, false, None, Direction::Right).is_err());
-    assert!(graph.connect(999, node1, false, None, Direction::Right).is_err());
+    assert_that(&graph.connect(node1, 999, false, None, Direction::Right).is_err()).is_true();
+    assert_that(&graph.connect(999, node1, false, None, Direction::Right).is_err()).is_true();
 }
 
 #[test]
@@ -79,11 +63,11 @@ fn test_graph_edge_permissions() {
     });
 
     graph
-        .add_edge(node1, node2, false, None, Direction::Right, EdgePermissions::GhostsOnly)
+        .add_edge(node1, node2, false, None, Direction::Right, TraversalFlags::GHOST)
         .unwrap();
 
     let edge = graph.find_edge_in_direction(node1, Direction::Right).unwrap();
-    assert_eq!(edge.permissions, EdgePermissions::GhostsOnly);
+    assert_that(&edge.traversal_flags).is_equal_to(TraversalFlags::GHOST);
 }
 
 #[test]
@@ -103,10 +87,10 @@ fn should_add_connected_node() {
         )
         .unwrap();
 
-    assert_eq!(graph.node_count(), 2);
+    assert_that(&graph.nodes().count()).is_equal_to(2);
     let edge = graph.find_edge(node1, node2);
-    assert!(edge.is_some());
-    assert_eq!(edge.unwrap().direction, Direction::Right);
+    assert_that(&edge.is_some()).is_true();
+    assert_that(&edge.unwrap().direction).is_equal_to(Direction::Right);
 }
 
 #[test]
@@ -119,99 +103,34 @@ fn should_error_on_negative_edge_distance() {
         position: glam::Vec2::new(16.0, 0.0),
     });
 
-    let result = graph.add_edge(node1, node2, false, Some(-1.0), Direction::Right, EdgePermissions::All);
-    assert!(result.is_err());
+    let result = graph.add_edge(node1, node2, false, Some(-1.0), Direction::Right, TraversalFlags::ALL);
+    assert_that(&result.is_err()).is_true();
 }
 
 #[test]
 fn should_error_on_duplicate_edge_without_replace() {
-    let mut graph = create_test_graph();
-    let result = graph.add_edge(0, 1, false, None, Direction::Right, EdgePermissions::All);
-    assert!(result.is_err());
+    let mut graph = common::create_test_graph();
+    let result = graph.add_edge(0, 1, false, None, Direction::Right, TraversalFlags::ALL);
+    assert_that(&result.is_err()).is_true();
 }
 
 #[test]
 fn should_allow_replacing_an_edge() {
-    let mut graph = create_test_graph();
-    let result = graph.add_edge(0, 1, true, Some(42.0), Direction::Right, EdgePermissions::All);
-    assert!(result.is_ok());
+    let mut graph = common::create_test_graph();
+    let result = graph.add_edge(0, 1, true, Some(42.0), Direction::Right, TraversalFlags::ALL);
+    assert_that(&result.is_ok()).is_true();
 
     let edge = graph.find_edge(0, 1).unwrap();
-    assert_eq!(edge.distance, 42.0);
+    assert_that(&edge.distance).is_equal_to(42.0);
 }
 
 #[test]
 fn should_find_edge_between_nodes() {
-    let graph = create_test_graph();
+    let graph = common::create_test_graph();
     let edge = graph.find_edge(0, 1);
-    assert!(edge.is_some());
-    assert_eq!(edge.unwrap().target, 1);
+    assert_that(&edge.is_some()).is_true();
+    assert_that(&edge.unwrap().target).is_equal_to(1);
 
     let non_existent_edge = graph.find_edge(0, 99);
-    assert!(non_existent_edge.is_none());
-}
-
-#[test]
-fn test_traverser_basic() {
-    let graph = create_test_graph();
-    let mut traverser = Traverser::new(&graph, 0, Direction::Left, &|_| true);
-
-    traverser.set_next_direction(Direction::Up);
-    assert!(traverser.next_direction.is_some());
-    assert_eq!(traverser.next_direction.unwrap().0, Direction::Up);
-}
-
-#[test]
-fn test_traverser_advance() {
-    let graph = create_test_graph();
-    let mut traverser = Traverser::new(&graph, 0, Direction::Right, &|_| true);
-
-    traverser.advance(&graph, 5.0, &|_| true).unwrap();
-
-    match traverser.position {
-        Position::BetweenNodes { from, to, traversed } => {
-            assert_eq!(from, 0);
-            assert_eq!(to, 1);
-            assert_eq!(traversed, 5.0);
-        }
-        _ => panic!("Expected to be between nodes"),
-    }
-
-    traverser.advance(&graph, 3.0, &|_| true).unwrap();
-
-    match traverser.position {
-        Position::BetweenNodes { from, to, traversed } => {
-            assert_eq!(from, 0);
-            assert_eq!(to, 1);
-            assert_eq!(traversed, 8.0);
-        }
-        _ => panic!("Expected to be between nodes"),
-    }
-}
-
-#[test]
-fn test_traverser_with_permissions() {
-    let mut graph = Graph::new();
-    let node1 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 0.0),
-    });
-    let node2 = graph.add_node(Node {
-        position: glam::Vec2::new(16.0, 0.0),
-    });
-
-    graph
-        .add_edge(node1, node2, false, None, Direction::Right, EdgePermissions::GhostsOnly)
-        .unwrap();
-
-    // Pacman can't traverse ghost-only edges
-    let mut traverser = Traverser::new(&graph, node1, Direction::Right, &|edge| {
-        matches!(edge.permissions, EdgePermissions::All)
-    });
-
-    traverser
-        .advance(&graph, 5.0, &|edge| matches!(edge.permissions, EdgePermissions::All))
-        .unwrap();
-
-    // Should still be at the node since it can't traverse
-    assert!(traverser.position.is_at_node());
+    assert_that(&non_existent_edge.is_none()).is_true();
 }

tests/helpers.rs

@@ -1,19 +0,0 @@
-use glam::{IVec2, UVec2};
-use pacman::helpers::centered_with_size;
-
-#[test]
-fn test_centered_with_size() {
-    let test_cases = [
-        ((100, 100), (50, 30), (75, 85)),
-        ((50, 50), (51, 31), (25, 35)),
-        ((0, 0), (100, 100), (-50, -50)),
-        ((-100, -50), (80, 40), (-140, -70)),
-        ((1000, 1000), (1000, 1000), (500, 500)),
-    ];
-
-    for ((pos_x, pos_y), (size_x, size_y), (expected_x, expected_y)) in test_cases {
-        let rect = centered_with_size(IVec2::new(pos_x, pos_y), UVec2::new(size_x, size_y));
-        assert_eq!(rect.origin(), (expected_x, expected_y));
-        assert_eq!(rect.size(), (size_x, size_y));
-    }
-}

tests/input.rs

@@ -0,0 +1,321 @@
+use glam::Vec2;
+use pacman::events::{GameCommand, GameEvent};
+use pacman::map::direction::Direction;
+use pacman::systems::input::{
+    calculate_direction_from_delta, process_simple_key_events, update_touch_reference_position, Bindings, CursorPosition,
+    SimpleKeyEvent, TouchData, TouchState, TOUCH_DIRECTION_THRESHOLD, TOUCH_EASING_DISTANCE_THRESHOLD,
+};
+use sdl2::keyboard::Keycode;
+use speculoos::prelude::*;
+
+// Test modules for better organization
+mod keyboard_tests {
+    use super::*;
+
+    #[test]
+    fn key_down_emits_bound_command() {
+        let mut bindings = Bindings::default();
+        let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::W)]);
+        assert_that(&events).contains(GameEvent::Command(GameCommand::MovePlayer(Direction::Up)));
+    }
+
+    #[test]
+    fn key_down_emits_non_movement_commands() {
+        let mut bindings = Bindings::default();
+        let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::P)]);
+        assert_that(&events).contains(GameEvent::Command(GameCommand::TogglePause));
+    }
+
+    #[test]
+    fn unbound_key_emits_nothing() {
+        let mut bindings = Bindings::default();
+        let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::Z)]);
+        assert_that(&events).is_empty();
+    }
+
+    #[test]
+    fn movement_key_held_continues_across_frames() {
+        let mut bindings = Bindings::default();
+        process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::Left)]);
+        let events = process_simple_key_events(&mut bindings, &[]);
+        assert_that(&events).contains(GameEvent::Command(GameCommand::MovePlayer(Direction::Left)));
+    }
+
+    #[test]
+    fn releasing_movement_key_stops_continuation() {
+        let mut bindings = Bindings::default();
+        process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::Up)]);
+        let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyUp(Keycode::Up)]);
+        assert_that(&events).is_empty();
+    }
+
+    #[test]
+    fn multiple_movement_keys_resumes_previous_when_current_released() {
+        let mut bindings = Bindings::default();
+        process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::W)]);
+        process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyDown(Keycode::D)]);
+        let events = process_simple_key_events(&mut bindings, &[SimpleKeyEvent::KeyUp(Keycode::D)]);
+        assert_that(&events).contains(GameEvent::Command(GameCommand::MovePlayer(Direction::Up)));
+    }
+}
+
+mod direction_calculation_tests {
+    use super::*;
+
+    #[test]
+    fn prioritizes_horizontal_movement() {
+        let test_cases = vec![
+            (Vec2::new(6.0, 5.0), Direction::Right),
+            (Vec2::new(-6.0, 5.0), Direction::Left),
+        ];
+
+        for (delta, expected) in test_cases {
+            assert_that(&calculate_direction_from_delta(delta)).is_equal_to(expected);
+        }
+    }
+
+    #[test]
+    fn uses_vertical_when_dominant() {
+        let test_cases = vec![
+            (Vec2::new(3.0, 10.0), Direction::Down),
+            (Vec2::new(3.0, -10.0), Direction::Up),
+        ];
+
+        for (delta, expected) in test_cases {
+            assert_that(&calculate_direction_from_delta(delta)).is_equal_to(expected);
+        }
+    }
+
+    #[test]
+    fn handles_zero_delta() {
+        let delta = Vec2::ZERO;
+        // Should default to Up when both components are zero
+        assert_that(&calculate_direction_from_delta(delta)).is_equal_to(Direction::Up);
+    }
+
+    #[test]
+    fn handles_equal_magnitudes() {
+        // When x and y have equal absolute values, should prioritize vertical
+        let delta = Vec2::new(5.0, 5.0);
+        assert_that(&calculate_direction_from_delta(delta)).is_equal_to(Direction::Down);
+
+        let delta = Vec2::new(-5.0, 5.0);
+        assert_that(&calculate_direction_from_delta(delta)).is_equal_to(Direction::Down);
+    }
+}
+
+mod touch_easing_tests {
+    use super::*;
+
+    #[test]
+    fn easing_within_threshold_does_nothing() {
+        let mut touch_data = TouchData::new(0, Vec2::new(100.0, 100.0));
+        touch_data.current_pos = Vec2::new(100.0 + TOUCH_EASING_DISTANCE_THRESHOLD - 0.1, 100.0);
+
+        let (_delta, distance) = update_touch_reference_position(&mut touch_data, 0.016);
+
+        assert_that(&distance).is_less_than(TOUCH_EASING_DISTANCE_THRESHOLD);
+        assert_that(&touch_data.start_pos).is_equal_to(Vec2::new(100.0, 100.0));
+    }
+
+    #[test]
+    fn easing_beyond_threshold_moves_towards_target() {
+        let mut touch_data = TouchData::new(0, Vec2::new(100.0, 100.0));
+        touch_data.current_pos = Vec2::new(150.0, 100.0);
+
+        let original_start_pos = touch_data.start_pos;
+        let (_delta, distance) = update_touch_reference_position(&mut touch_data, 0.016);
+
+        assert_that(&distance).is_greater_than(TOUCH_EASING_DISTANCE_THRESHOLD);
+        assert_that(&touch_data.start_pos.x).is_greater_than(original_start_pos.x);
+        assert_that(&touch_data.start_pos.x).is_less_than(touch_data.current_pos.x);
+    }
+
+    #[test]
+    fn easing_overshoot_sets_to_target() {
+        let mut touch_data = TouchData::new(0, Vec2::new(100.0, 100.0));
+        touch_data.current_pos = Vec2::new(101.0, 100.0);
+
+        let (_delta, _distance) = update_touch_reference_position(&mut touch_data, 10.0);
+
+        assert_that(&touch_data.start_pos).is_equal_to(touch_data.current_pos);
+    }
+
+    #[test]
+    fn easing_returns_correct_delta() {
+        let mut touch_data = TouchData::new(0, Vec2::new(100.0, 100.0));
+        touch_data.current_pos = Vec2::new(120.0, 110.0);
+
+        let (delta, distance) = update_touch_reference_position(&mut touch_data, 0.016);
+
+        let expected_delta = Vec2::new(20.0, 10.0);
+        let expected_distance = expected_delta.length();
+
+        assert_that(&delta).is_equal_to(expected_delta);
+        assert_that(&distance).is_equal_to(expected_distance);
+    }
+}
+
+// Integration tests for the full input system
+mod integration_tests {
+    use super::*;
+
+    fn mouse_motion_event(x: i32, y: i32) -> sdl2::event::Event {
+        sdl2::event::Event::MouseMotion {
+            x,
+            y,
+            xrel: 0,
+            yrel: 0,
+            mousestate: sdl2::mouse::MouseState::from_sdl_state(0),
+            which: 0,
+            window_id: 0,
+            timestamp: 0,
+        }
+    }
+
+    fn mouse_button_down_event(x: i32, y: i32) -> sdl2::event::Event {
+        sdl2::event::Event::MouseButtonDown {
+            x,
+            y,
+            mouse_btn: sdl2::mouse::MouseButton::Left,
+            clicks: 1,
+            which: 0,
+            window_id: 0,
+            timestamp: 0,
+        }
+    }
+
+    fn mouse_button_up_event(x: i32, y: i32) -> sdl2::event::Event {
+        sdl2::event::Event::MouseButtonUp {
+            x,
+            y,
+            mouse_btn: sdl2::mouse::MouseButton::Left,
+            clicks: 1,
+            which: 0,
+            window_id: 0,
+            timestamp: 0,
+        }
+    }
+
+    // Simplified helper for testing SDL integration
+    fn run_input_system_with_events(events: Vec<sdl2::event::Event>, delta_time: f32) -> (CursorPosition, TouchState) {
+        use bevy_ecs::{event::Events, system::RunSystemOnce, world::World};
+        use pacman::systems::components::DeltaTime;
+        use pacman::systems::input::input_system;
+
+        let sdl_context = sdl2::init().expect("Failed to initialize SDL");
+        let event_subsystem = sdl_context.event().expect("Failed to get event subsystem");
+        let event_pump = sdl_context.event_pump().expect("Failed to create event pump");
+
+        let mut world = World::new();
+        world.insert_resource(Events::<GameEvent>::default());
+        world.insert_resource(DeltaTime {
+            seconds: delta_time,
+            ticks: 1,
+        });
+        world.insert_resource(Bindings::default());
+        world.insert_resource(CursorPosition::None);
+        world.insert_resource(TouchState::default());
+        world.insert_non_send_resource(event_pump);
+
+        // Inject events into SDL's event queue
+        for event in events {
+            event_subsystem.push_event(event).expect("Failed to push event");
+        }
+
+        // Run the real input system
+        world
+            .run_system_once(input_system)
+            .expect("Input system should run successfully");
+
+        let cursor = *world.resource::<CursorPosition>();
+        let touch_state = world.resource::<TouchState>().clone();
+
+        (cursor, touch_state)
+    }
+
+    #[test]
+    fn mouse_motion_updates_cursor_position() {
+        let events = vec![mouse_motion_event(100, 200)];
+        let (cursor, _touch_state) = run_input_system_with_events(events, 0.016);
+
+        match cursor {
+            CursorPosition::Some {
+                position,
+                remaining_time,
+            } => {
+                assert_that(&position).is_equal_to(Vec2::new(100.0, 200.0));
+                assert_that(&remaining_time).is_equal_to(0.20);
+            }
+            CursorPosition::None => panic!("Expected cursor position to be set"),
+        }
+    }
+
+    #[test]
+    fn mouse_button_down_starts_touch() {
+        let events = vec![mouse_button_down_event(150, 250)];
+        let (_cursor, touch_state) = run_input_system_with_events(events, 0.016);
+
+        assert_that(&touch_state.active_touch).is_some();
+        if let Some(touch_data) = &touch_state.active_touch {
+            assert_that(&touch_data.finger_id).is_equal_to(0);
+            assert_that(&touch_data.start_pos).is_equal_to(Vec2::new(150.0, 250.0));
+        }
+    }
+
+    #[test]
+    fn mouse_button_up_ends_touch() {
+        let events = vec![mouse_button_down_event(150, 250), mouse_button_up_event(150, 250)];
+        let (_cursor, touch_state) = run_input_system_with_events(events, 0.016);
+
+        assert_that(&touch_state.active_touch).is_none();
+    }
+}
+
+// Touch direction tests
+mod touch_direction_tests {
+    use super::*;
+
+    #[test]
+    fn movement_above_threshold_emits_direction() {
+        let mut touch_data = TouchData::new(1, Vec2::new(100.0, 100.0));
+        touch_data.current_pos = Vec2::new(100.0 + TOUCH_DIRECTION_THRESHOLD + 5.0, 100.0);
+
+        let (delta, distance) = update_touch_reference_position(&mut touch_data, 0.016);
+
+        assert_that(&distance).is_greater_than_or_equal_to(TOUCH_DIRECTION_THRESHOLD);
+        let direction = calculate_direction_from_delta(delta);
+        assert_that(&direction).is_equal_to(Direction::Right);
+    }
+
+    #[test]
+    fn movement_below_threshold_no_direction() {
+        let mut touch_data = TouchData::new(1, Vec2::new(100.0, 100.0));
+        touch_data.current_pos = Vec2::new(100.0 + TOUCH_DIRECTION_THRESHOLD - 1.0, 100.0);
+
+        let (_delta, distance) = update_touch_reference_position(&mut touch_data, 0.016);
+
+        assert_that(&distance).is_less_than(TOUCH_DIRECTION_THRESHOLD);
+    }
+
+    #[test]
+    fn all_directions_work_correctly() {
+        let test_cases = vec![
+            (Vec2::new(TOUCH_DIRECTION_THRESHOLD + 5.0, 0.0), Direction::Right),
+            (Vec2::new(-TOUCH_DIRECTION_THRESHOLD - 5.0, 0.0), Direction::Left),
+            (Vec2::new(0.0, TOUCH_DIRECTION_THRESHOLD + 5.0), Direction::Down),
+            (Vec2::new(0.0, -TOUCH_DIRECTION_THRESHOLD - 5.0), Direction::Up),
+        ];
+
+        for (offset, expected_direction) in test_cases {
+            let mut touch_data = TouchData::new(1, Vec2::new(100.0, 100.0));
+            touch_data.current_pos = Vec2::new(100.0, 100.0) + offset;
+
+            let (delta, distance) = update_touch_reference_position(&mut touch_data, 0.016);
+
+            assert_that(&distance).is_greater_than_or_equal_to(TOUCH_DIRECTION_THRESHOLD);
+            let direction = calculate_direction_from_delta(delta);
+            assert_that(&direction).is_equal_to(expected_direction);
+        }
+    }
+}

tests/item.rs

@@ -1,53 +1,249 @@
-use glam::U16Vec2;
-use pacman::{
-    entity::{
-        collision::Collidable,
-        item::{FruitKind, Item, ItemType},
-    },
-    texture::sprite::{AtlasTile, Sprite},
-};
-use strum::{EnumCount, IntoEnumIterator};
+use bevy_ecs::{entity::Entity, system::RunSystemOnce};
+use pacman::systems::{is_valid_item_collision, item_system, EntityType, GhostState, Position, ScoreResource};
+use speculoos::prelude::*;
+
+mod common;
 
 #[test]
-fn test_item_type_get_score() {
-    assert_eq!(ItemType::Pellet.get_score(), 10);
-    assert_eq!(ItemType::Energizer.get_score(), 50);
-
-    let fruit = ItemType::Fruit { kind: FruitKind::Apple };
-    assert_eq!(fruit.get_score(), 100);
+fn test_calculate_score_for_item() {
+    assert_that(&(EntityType::Pellet.score_value() < EntityType::PowerPellet.score_value())).is_true();
+    assert_that(&EntityType::Pellet.score_value().is_some()).is_true();
+    assert_that(&EntityType::PowerPellet.score_value().is_some()).is_true();
+    assert_that(&EntityType::Player.score_value().is_none()).is_true();
+    assert_that(&EntityType::Ghost.score_value().is_none()).is_true();
 }
 
 #[test]
-fn test_fruit_kind_increasing_score() {
-    // Build a list of fruit kinds, sorted by their index
-    let mut kinds = FruitKind::iter()
-        .map(|kind| (kind.index(), kind.get_score()))
-        .collect::<Vec<_>>();
-    kinds.sort_unstable_by_key(|(index, _)| *index);
+fn test_is_collectible_item() {
+    // Collectible
+    assert_that(&EntityType::Pellet.is_collectible()).is_true();
+    assert_that(&EntityType::PowerPellet.is_collectible()).is_true();
 
-    assert_eq!(kinds.len(), FruitKind::COUNT);
-
-    // Check that the score increases as expected
-    for window in kinds.windows(2) {
-        let ((_, prev), (_, next)) = (window[0], window[1]);
-        assert!(prev < next, "Fruits should have increasing scores, but {prev:?} < {next:?}");
-    }
+    // Non-collectible
+    assert_that(&EntityType::Player.is_collectible()).is_false();
+    assert_that(&EntityType::Ghost.is_collectible()).is_false();
 }
 
 #[test]
-fn test_item_creation_and_collection() {
-    let atlas_tile = AtlasTile {
-        pos: U16Vec2::new(0, 0),
-        size: U16Vec2::new(16, 16),
-        color: None,
-    };
-    let sprite = Sprite::new(atlas_tile);
-    let mut item = Item::new(0, ItemType::Pellet, sprite);
+fn test_is_valid_item_collision() {
+    // Player-item collisions should be valid
+    assert_that(&is_valid_item_collision(EntityType::Player, EntityType::Pellet)).is_true();
+    assert_that(&is_valid_item_collision(EntityType::Player, EntityType::PowerPellet)).is_true();
+    assert_that(&is_valid_item_collision(EntityType::Pellet, EntityType::Player)).is_true();
+    assert_that(&is_valid_item_collision(EntityType::PowerPellet, EntityType::Player)).is_true();
 
-    assert!(!item.is_collected());
-    assert_eq!(item.get_score(), 10);
-    assert_eq!(item.position().from_node_id(), 0);
-
-    item.collect();
-    assert!(item.is_collected());
+    // Non-player-item collisions should be invalid
+    assert_that(&is_valid_item_collision(EntityType::Player, EntityType::Ghost)).is_false();
+    assert_that(&is_valid_item_collision(EntityType::Ghost, EntityType::Pellet)).is_false();
+    assert_that(&is_valid_item_collision(EntityType::Pellet, EntityType::PowerPellet)).is_false();
+    assert_that(&is_valid_item_collision(EntityType::Player, EntityType::Player)).is_false();
+}
+
+#[test]
+fn test_item_system_pellet_collection() {
+    let mut world = common::create_test_world();
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+    let pellet = common::spawn_test_item(&mut world, 1, EntityType::Pellet);
+
+    // Send collision event
+    common::send_collision_event(&mut world, pacman, pellet);
+
+    // Run the item system
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check that score was updated
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(10);
+
+    // Check that the pellet was despawned (query should return empty)
+    let item_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Pellet))
+        .count();
+    assert_that(&item_count).is_equal_to(0);
+}
+
+#[test]
+fn test_item_system_power_pellet_collection() {
+    let mut world = common::create_test_world();
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+    let power_pellet = common::spawn_test_item(&mut world, 1, EntityType::PowerPellet);
+
+    common::send_collision_event(&mut world, pacman, power_pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check that score was updated with power pellet value
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(50);
+
+    // Check that the power pellet was despawned (query should return empty)
+    let item_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::PowerPellet))
+        .count();
+    assert_that(&item_count).is_equal_to(0);
+}
+
+#[test]
+fn test_item_system_multiple_collections() {
+    let mut world = common::create_test_world();
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+    let pellet1 = common::spawn_test_item(&mut world, 1, EntityType::Pellet);
+    let pellet2 = common::spawn_test_item(&mut world, 2, EntityType::Pellet);
+    let power_pellet = common::spawn_test_item(&mut world, 3, EntityType::PowerPellet);
+
+    // Send multiple collision events
+    common::send_collision_event(&mut world, pacman, pellet1);
+    common::send_collision_event(&mut world, pacman, pellet2);
+    common::send_collision_event(&mut world, pacman, power_pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check final score: 2 pellets (20) + 1 power pellet (50) = 70
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(70);
+
+    // Check that all items were despawned
+    let pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Pellet))
+        .count();
+    let power_pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::PowerPellet))
+        .count();
+    assert_that(&pellet_count).is_equal_to(0);
+    assert_that(&power_pellet_count).is_equal_to(0);
+}
+
+#[test]
+fn test_item_system_ignores_non_item_collisions() {
+    let mut world = common::create_test_world();
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+
+    // Create a ghost entity (not an item)
+    let ghost = world.spawn((Position::Stopped { node: 2 }, EntityType::Ghost)).id();
+
+    // Initial score
+    let initial_score = world.resource::<ScoreResource>().0;
+
+    // Send collision event between pacman and ghost
+    common::send_collision_event(&mut world, pacman, ghost);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Score should remain unchanged
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(initial_score);
+
+    // Ghost should still exist (not despawned)
+    let ghost_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Ghost))
+        .count();
+    assert_that(&ghost_count).is_equal_to(1);
+}
+
+#[test]
+fn test_item_system_no_collision_events() {
+    let mut world = common::create_test_world();
+    let _pacman = common::spawn_test_pacman(&mut world, 0);
+    let _pellet = common::spawn_test_item(&mut world, 1, EntityType::Pellet);
+
+    let initial_score = world.resource::<ScoreResource>().0;
+
+    // Run system without any collision events
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Nothing should change
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(initial_score);
+    let pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::Pellet))
+        .count();
+    assert_that(&pellet_count).is_equal_to(1);
+}
+
+#[test]
+fn test_item_system_collision_with_missing_entity() {
+    let mut world = common::create_test_world();
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+
+    // Create a fake entity ID that doesn't exist
+    let fake_entity = Entity::from_raw(999);
+
+    common::send_collision_event(&mut world, pacman, fake_entity);
+
+    // System should handle gracefully and not crash
+    world
+        .run_system_once(item_system)
+        .expect("System should handle missing entities gracefully");
+
+    // Score should remain unchanged
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(0);
+}
+
+#[test]
+fn test_item_system_preserves_existing_score() {
+    let mut world = common::create_test_world();
+
+    // Set initial score
+    world.insert_resource(ScoreResource(100));
+
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+    let pellet = common::spawn_test_item(&mut world, 1, EntityType::Pellet);
+
+    common::send_collision_event(&mut world, pacman, pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Score should be initial + pellet value
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(110);
+}
+
+#[test]
+fn test_power_pellet_does_not_affect_ghosts_in_eyes_state() {
+    let mut world = common::create_test_world();
+    let pacman = common::spawn_test_pacman(&mut world, 0);
+    let power_pellet = common::spawn_test_item(&mut world, 1, EntityType::PowerPellet);
+
+    // Spawn a ghost in Eyes state (returning to ghost house)
+    let eyes_ghost = common::spawn_test_ghost(&mut world, 2, GhostState::Eyes);
+
+    // Spawn a ghost in Normal state
+    let normal_ghost = common::spawn_test_ghost(&mut world, 3, GhostState::Normal);
+
+    common::send_collision_event(&mut world, pacman, power_pellet);
+
+    world.run_system_once(item_system).expect("System should run successfully");
+
+    // Check that the power pellet was collected and score updated
+    let score = world.resource::<ScoreResource>();
+    assert_that(&score.0).is_equal_to(50);
+
+    // Check that the power pellet was despawned
+    let power_pellet_count = world
+        .query::<&EntityType>()
+        .iter(&world)
+        .filter(|&entity_type| matches!(entity_type, EntityType::PowerPellet))
+        .count();
+    assert_that(&power_pellet_count).is_equal_to(0);
+
+    // Check that the Eyes ghost state was not changed
+    let eyes_ghost_state = world.entity(eyes_ghost).get::<GhostState>().unwrap();
+    assert_that(&matches!(*eyes_ghost_state, GhostState::Eyes)).is_true();
+
+    // Check that the Normal ghost state was changed to Frightened
+    let normal_ghost_state = world.entity(normal_ghost).get::<GhostState>().unwrap();
+    assert_that(&matches!(*normal_ghost_state, GhostState::Frightened { .. })).is_true();
 }

tests/map_builder.rs

@@ -1,14 +1,15 @@
 use glam::Vec2;
 use pacman::constants::{CELL_SIZE, RAW_BOARD};
-use pacman::map::Map;
-use sdl2::render::Texture;
+use pacman::map::builder::Map;
+use pacman::map::graph::TraversalFlags;
+use speculoos::prelude::*;
 
 #[test]
-fn test_map_creation() {
+fn test_map_creation_success() {
     let map = Map::new(RAW_BOARD).unwrap();
 
-    assert!(map.graph.node_count() > 0);
-    assert!(!map.grid_to_node.is_empty());
+    assert_that(&map.graph.nodes().count()).is_greater_than(0);
+    assert_that(&map.grid_to_node.is_empty()).is_false();
 
     // Check that some connections were made
     let mut has_connections = false;
@@ -18,76 +19,71 @@ fn test_map_creation() {
             break;
         }
     }
-    assert!(has_connections);
+    assert_that(&has_connections).is_true();
 }
 
 #[test]
-fn test_map_node_positions() {
+fn test_map_node_positions_accuracy() {
     let map = Map::new(RAW_BOARD).unwrap();
 
     for (grid_pos, &node_id) in &map.grid_to_node {
         let node = map.graph.get_node(node_id).unwrap();
-        let expected_pos = Vec2::new((grid_pos.x * CELL_SIZE as i32) as f32, (grid_pos.y * CELL_SIZE as i32) as f32)
-            + Vec2::splat(CELL_SIZE as f32 / 2.0);
+        let expected_pos = Vec2::new(
+            (grid_pos.x as i32 * CELL_SIZE as i32) as f32,
+            (grid_pos.y as i32 * CELL_SIZE as i32) as f32,
+        ) + Vec2::splat(CELL_SIZE as f32 / 2.0);
 
-        assert_eq!(node.position, expected_pos);
+        assert_that(&node.position).is_equal_to(expected_pos);
     }
 }
 
 #[test]
-fn test_generate_items() {
-    use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
-    use std::collections::HashMap;
+fn test_start_positions_are_valid() {
+    let map = Map::new(RAW_BOARD).unwrap();
+    let positions = &map.start_positions;
 
+    // All start positions should exist in the graph
+    assert_that(&map.graph.get_node(positions.pacman)).is_some();
+    assert_that(&map.graph.get_node(positions.blinky)).is_some();
+    assert_that(&map.graph.get_node(positions.pinky)).is_some();
+    assert_that(&map.graph.get_node(positions.inky)).is_some();
+    assert_that(&map.graph.get_node(positions.clyde)).is_some();
+}
+
+#[test]
+fn test_ghost_house_has_ghost_only_entrance() {
     let map = Map::new(RAW_BOARD).unwrap();
 
-    // Create a minimal atlas for testing
-    let mut frames = HashMap::new();
-    frames.insert(
-        "maze/pellet.png".to_string(),
-        MapperFrame {
-            x: 0,
-            y: 0,
-            width: 8,
-            height: 8,
-        },
-    );
-    frames.insert(
-        "maze/energizer.png".to_string(),
-        MapperFrame {
-            x: 8,
-            y: 0,
-            width: 8,
-            height: 8,
-        },
-    );
+    // Find the house entrance node
+    let house_entrance = map.start_positions.blinky;
 
-    let mapper = AtlasMapper { frames };
-    let texture = unsafe { std::mem::transmute::<usize, Texture<'static>>(0usize) };
-    let atlas = SpriteAtlas::new(texture, mapper);
-
-    let items = map.generate_items(&atlas).unwrap();
-
-    // Verify we have items
-    assert!(!items.is_empty());
-
-    // Count different types
-    let pellet_count = items
-        .iter()
-        .filter(|item| matches!(item.item_type, pacman::entity::item::ItemType::Pellet))
-        .count();
-    let energizer_count = items
-        .iter()
-        .filter(|item| matches!(item.item_type, pacman::entity::item::ItemType::Energizer))
-        .count();
-
-    // Should have both types
-    assert_eq!(pellet_count, 240);
-    assert_eq!(energizer_count, 4);
-
-    // All items should be uncollected initially
-    assert!(items.iter().all(|item| !item.is_collected()));
-
-    // All items should have valid node indices
-    assert!(items.iter().all(|item| item.node_index < map.graph.node_count()));
+    // Check that there's a ghost-only connection from the house entrance
+    let mut has_ghost_only_connection = false;
+    for edge in map.graph.adjacency_list[house_entrance as usize].edges() {
+        if edge.traversal_flags == TraversalFlags::GHOST {
+            has_ghost_only_connection = true;
+            break;
+        }
+    }
+    assert_that(&has_ghost_only_connection).is_true();
+}
+
+#[test]
+fn test_tunnel_connections_exist() {
+    let map = Map::new(RAW_BOARD).unwrap();
+
+    // Find tunnel nodes by looking for nodes with zero-distance connections
+    let mut has_tunnel_connection = false;
+    for intersection in &map.graph.adjacency_list {
+        for edge in intersection.edges() {
+            if edge.distance == 0.0f32 {
+                has_tunnel_connection = true;
+                break;
+            }
+        }
+        if has_tunnel_connection {
+            break;
+        }
+    }
+    assert_that(&has_tunnel_connection).is_true();
 }

tests/movement.rs

@@ -0,0 +1,170 @@
+use glam::Vec2;
+use pacman::map::direction::Direction;
+use pacman::systems::movement::{BufferedDirection, Position, Velocity};
+use speculoos::prelude::*;
+
+mod common;
+
+#[test]
+fn test_position_is_at_node() {
+    let stopped_pos = Position::Stopped { node: 0 };
+    let moving_pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 8.0,
+    };
+
+    assert_that(&stopped_pos.is_at_node()).is_true();
+    assert_that(&moving_pos.is_at_node()).is_false();
+}
+
+#[test]
+fn test_position_current_node() {
+    let stopped_pos = Position::Stopped { node: 5 };
+    let moving_pos = Position::Moving {
+        from: 3,
+        to: 7,
+        remaining_distance: 12.0,
+    };
+
+    assert_that(&stopped_pos.current_node()).is_equal_to(5);
+    assert_that(&moving_pos.current_node()).is_equal_to(3);
+}
+
+#[test]
+fn test_position_tick_no_movement_when_stopped() {
+    let mut pos = Position::Stopped { node: 0 };
+    let result = pos.tick(5.0);
+
+    assert_that(&result.is_none()).is_true();
+    assert_that(&pos).is_equal_to(Position::Stopped { node: 0 });
+}
+
+#[test]
+fn test_position_tick_no_movement_when_zero_distance() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 10.0,
+    };
+    let result = pos.tick(0.0);
+
+    assert_that(&result.is_none()).is_true();
+    assert_that(&pos).is_equal_to(Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 10.0,
+    });
+}
+
+#[test]
+fn test_position_tick_partial_movement() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 10.0,
+    };
+    let result = pos.tick(3.0);
+
+    assert_that(&result.is_none()).is_true();
+    assert_that(&pos).is_equal_to(Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 7.0,
+    });
+}
+
+#[test]
+fn test_position_tick_exact_arrival() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 5.0,
+    };
+    let result = pos.tick(5.0);
+
+    assert_that(&result.is_none()).is_true();
+    assert_that(&pos).is_equal_to(Position::Stopped { node: 1 });
+}
+
+#[test]
+fn test_position_tick_overshoot_with_overflow() {
+    let mut pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 3.0,
+    };
+    let result = pos.tick(8.0);
+
+    assert_that(&result).is_equal_to(Some(5.0));
+    assert_that(&pos).is_equal_to(Position::Stopped { node: 1 });
+}
+
+#[test]
+fn test_position_get_pixel_position_stopped() {
+    let graph = common::create_test_graph();
+    let pos = Position::Stopped { node: 0 };
+
+    let pixel_pos = pos.get_pixel_position(&graph).unwrap();
+    let expected = Vec2::new(
+        0.0 + pacman::constants::BOARD_PIXEL_OFFSET.x as f32,
+        0.0 + pacman::constants::BOARD_PIXEL_OFFSET.y as f32,
+    );
+
+    assert_that(&pixel_pos).is_equal_to(expected);
+}
+
+#[test]
+fn test_position_get_pixel_position_moving() {
+    let graph = common::create_test_graph();
+    let pos = Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 8.0, // Halfway through a 16-unit edge
+    };
+
+    let pixel_pos = pos.get_pixel_position(&graph).unwrap();
+    // Should be halfway between (0,0) and (16,0), so at (8,0) plus offset
+    let expected = Vec2::new(
+        8.0 + pacman::constants::BOARD_PIXEL_OFFSET.x as f32,
+        0.0 + pacman::constants::BOARD_PIXEL_OFFSET.y as f32,
+    );
+
+    assert_that(&pixel_pos).is_equal_to(expected);
+}
+
+#[test]
+fn test_velocity_basic_properties() {
+    let velocity = Velocity {
+        speed: 2.5,
+        direction: Direction::Up,
+    };
+
+    assert_that(&velocity.speed).is_equal_to(2.5);
+    assert_that(&velocity.direction).is_equal_to(Direction::Up);
+}
+
+#[test]
+fn test_buffered_direction_none() {
+    let buffered = BufferedDirection::None;
+    assert_that(&buffered).is_equal_to(BufferedDirection::None);
+}
+
+#[test]
+fn test_buffered_direction_some() {
+    let buffered = BufferedDirection::Some {
+        direction: Direction::Left,
+        remaining_time: 0.5,
+    };
+
+    if let BufferedDirection::Some {
+        direction,
+        remaining_time,
+    } = buffered
+    {
+        assert_that(&direction).is_equal_to(Direction::Left);
+        assert_that(&remaining_time).is_equal_to(0.5);
+    } else {
+        panic!("Expected BufferedDirection::Some");
+    }
+}

tests/pacman.rs

@@ -1,107 +0,0 @@
-use pacman::entity::direction::Direction;
-use pacman::entity::graph::{Graph, Node};
-use pacman::entity::pacman::Pacman;
-use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
-use sdl2::keyboard::Keycode;
-use std::collections::HashMap;
-
-fn create_test_graph() -> Graph {
-    let mut graph = Graph::new();
-    let node1 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 0.0),
-    });
-    let node2 = graph.add_node(Node {
-        position: glam::Vec2::new(16.0, 0.0),
-    });
-    let node3 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 16.0),
-    });
-
-    graph.connect(node1, node2, false, None, Direction::Right).unwrap();
-    graph.connect(node1, node3, false, None, Direction::Down).unwrap();
-
-    graph
-}
-
-fn create_test_atlas() -> SpriteAtlas {
-    let mut frames = HashMap::new();
-    let directions = ["up", "down", "left", "right"];
-
-    for (i, dir) in directions.iter().enumerate() {
-        frames.insert(
-            format!("pacman/{dir}_a.png"),
-            MapperFrame {
-                x: i as u16 * 16,
-                y: 0,
-                width: 16,
-                height: 16,
-            },
-        );
-        frames.insert(
-            format!("pacman/{dir}_b.png"),
-            MapperFrame {
-                x: i as u16 * 16,
-                y: 16,
-                width: 16,
-                height: 16,
-            },
-        );
-    }
-
-    frames.insert(
-        "pacman/full.png".to_string(),
-        MapperFrame {
-            x: 64,
-            y: 0,
-            width: 16,
-            height: 16,
-        },
-    );
-
-    let mapper = AtlasMapper { frames };
-    let dummy_texture = unsafe { std::mem::zeroed() };
-    SpriteAtlas::new(dummy_texture, mapper)
-}
-
-#[test]
-fn test_pacman_creation() {
-    let graph = create_test_graph();
-    let atlas = create_test_atlas();
-    let pacman = Pacman::new(&graph, 0, &atlas).unwrap();
-
-    assert!(pacman.traverser.position.is_at_node());
-    assert_eq!(pacman.traverser.direction, Direction::Left);
-}
-
-#[test]
-fn test_pacman_key_handling() {
-    let graph = create_test_graph();
-    let atlas = create_test_atlas();
-    let mut pacman = Pacman::new(&graph, 0, &atlas).unwrap();
-
-    let test_cases = [
-        (Keycode::Up, Direction::Up),
-        (Keycode::Down, Direction::Down),
-        (Keycode::Left, Direction::Left),
-        (Keycode::Right, Direction::Right),
-    ];
-
-    for (key, expected_direction) in test_cases {
-        pacman.handle_key(key);
-        assert!(pacman.traverser.next_direction.is_some() || pacman.traverser.direction == expected_direction);
-    }
-}
-
-#[test]
-fn test_pacman_invalid_key() {
-    let graph = create_test_graph();
-    let atlas = create_test_atlas();
-    let mut pacman = Pacman::new(&graph, 0, &atlas).unwrap();
-
-    let original_direction = pacman.traverser.direction;
-    let original_next_direction = pacman.traverser.next_direction;
-
-    pacman.handle_key(Keycode::Space);
-    assert_eq!(pacman.traverser.direction, original_direction);
-    assert_eq!(pacman.traverser.next_direction, original_next_direction);
-}

tests/parser.rs

@@ -1,6 +1,7 @@
 use pacman::constants::{BOARD_CELL_SIZE, RAW_BOARD};
 use pacman::error::ParseError;
 use pacman::map::parser::MapTileParser;
+use speculoos::prelude::*;
 
 #[test]
 fn test_parse_character() {
@@ -15,25 +16,25 @@ fn test_parse_character() {
     ];
 
     for (char, _expected) in test_cases {
-        assert!(matches!(MapTileParser::parse_character(char).unwrap(), _expected));
+        assert_that(&matches!(MapTileParser::parse_character(char).unwrap(), _expected)).is_true();
     }
 
-    assert!(MapTileParser::parse_character('Z').is_err());
+    assert_that(&MapTileParser::parse_character('Z').is_err()).is_true();
 }
 
 #[test]
 fn test_parse_board() {
     let result = MapTileParser::parse_board(RAW_BOARD);
-    assert!(result.is_ok());
+    assert_that(&result.is_ok()).is_true();
 
     let parsed = result.unwrap();
-    assert_eq!(parsed.tiles.len(), BOARD_CELL_SIZE.x as usize);
-    assert_eq!(parsed.tiles[0].len(), BOARD_CELL_SIZE.y as usize);
-    assert!(parsed.house_door[0].is_some());
-    assert!(parsed.house_door[1].is_some());
-    assert!(parsed.tunnel_ends[0].is_some());
-    assert!(parsed.tunnel_ends[1].is_some());
-    assert!(parsed.pacman_start.is_some());
+    assert_that(&parsed.tiles.len()).is_equal_to(BOARD_CELL_SIZE.x as usize);
+    assert_that(&parsed.tiles[0].len()).is_equal_to(BOARD_CELL_SIZE.y as usize);
+    assert_that(&parsed.house_door[0].is_some()).is_true();
+    assert_that(&parsed.house_door[1].is_some()).is_true();
+    assert_that(&parsed.tunnel_ends[0].is_some()).is_true();
+    assert_that(&parsed.tunnel_ends[1].is_some()).is_true();
+    assert_that(&parsed.pacman_start.is_some()).is_true();
 }
 
 #[test]
@@ -42,6 +43,6 @@ fn test_parse_board_invalid_character() {
     invalid_board[0] = "###########################Z".to_string();
 
     let result = MapTileParser::parse_board(invalid_board.each_ref().map(|s| s.as_str()));
-    assert!(result.is_err());
-    assert!(matches!(result.unwrap_err(), ParseError::UnknownCharacter('Z')));
+    assert_that(&result.is_err()).is_true();
+    assert_that(&matches!(result.unwrap_err(), ParseError::UnknownCharacter('Z'))).is_true();
 }

tests/pathfinding.rs

@@ -1,120 +0,0 @@
-use pacman::entity::direction::Direction;
-use pacman::entity::ghost::{Ghost, GhostType};
-use pacman::entity::graph::{Graph, Node};
-use pacman::texture::sprite::{AtlasMapper, MapperFrame, SpriteAtlas};
-use std::collections::HashMap;
-
-fn create_test_atlas() -> SpriteAtlas {
-    let mut frames = HashMap::new();
-    let directions = ["up", "down", "left", "right"];
-    let ghost_types = ["blinky", "pinky", "inky", "clyde"];
-
-    for ghost_type in &ghost_types {
-        for (i, dir) in directions.iter().enumerate() {
-            frames.insert(
-                format!("ghost/{}/{}_{}.png", ghost_type, dir, "a"),
-                MapperFrame {
-                    x: i as u16 * 16,
-                    y: 0,
-                    width: 16,
-                    height: 16,
-                },
-            );
-            frames.insert(
-                format!("ghost/{}/{}_{}.png", ghost_type, dir, "b"),
-                MapperFrame {
-                    x: i as u16 * 16,
-                    y: 16,
-                    width: 16,
-                    height: 16,
-                },
-            );
-        }
-    }
-
-    let mapper = AtlasMapper { frames };
-    let dummy_texture = unsafe { std::mem::zeroed() };
-    SpriteAtlas::new(dummy_texture, mapper)
-}
-
-#[test]
-fn test_ghost_pathfinding() {
-    // Create a simple test graph
-    let mut graph = Graph::new();
-
-    // Add nodes in a simple line: 0 -> 1 -> 2
-    let node0 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 0.0),
-    });
-    let node1 = graph.add_node(Node {
-        position: glam::Vec2::new(10.0, 0.0),
-    });
-    let node2 = graph.add_node(Node {
-        position: glam::Vec2::new(20.0, 0.0),
-    });
-
-    // Connect the nodes
-    graph.connect(node0, node1, false, None, Direction::Right).unwrap();
-    graph.connect(node1, node2, false, None, Direction::Right).unwrap();
-
-    // Create a test atlas for the ghost
-    let atlas = create_test_atlas();
-
-    // Create a ghost at node 0
-    let ghost = Ghost::new(&graph, node0, GhostType::Blinky, &atlas).unwrap();
-
-    // Test pathfinding from node 0 to node 2
-    let path = ghost.calculate_path_to_target(&graph, node2);
-
-    assert!(path.is_ok());
-    let path = path.unwrap();
-    assert!(
-        path == vec![node0, node1, node2] || path == vec![node2, node1, node0],
-        "Path was not what was expected"
-    );
-}
-
-#[test]
-fn test_ghost_pathfinding_no_path() {
-    // Create a test graph with disconnected components
-    let mut graph = Graph::new();
-
-    let node0 = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 0.0),
-    });
-    let node1 = graph.add_node(Node {
-        position: glam::Vec2::new(10.0, 0.0),
-    });
-
-    // Don't connect the nodes
-    let atlas = create_test_atlas();
-    let ghost = Ghost::new(&graph, node0, GhostType::Blinky, &atlas).unwrap();
-
-    // Test pathfinding when no path exists
-    let path = ghost.calculate_path_to_target(&graph, node1);
-
-    assert!(path.is_err());
-}
-
-#[test]
-fn test_ghost_debug_colors() {
-    let atlas = create_test_atlas();
-    let mut graph = Graph::new();
-    let node = graph.add_node(Node {
-        position: glam::Vec2::new(0.0, 0.0),
-    });
-
-    let blinky = Ghost::new(&graph, node, GhostType::Blinky, &atlas).unwrap();
-    let pinky = Ghost::new(&graph, node, GhostType::Pinky, &atlas).unwrap();
-    let inky = Ghost::new(&graph, node, GhostType::Inky, &atlas).unwrap();
-    let clyde = Ghost::new(&graph, node, GhostType::Clyde, &atlas).unwrap();
-
-    // Test that each ghost has a different debug color
-    let colors = std::collections::HashSet::from([
-        blinky.debug_color(),
-        pinky.debug_color(),
-        inky.debug_color(),
-        clyde.debug_color(),
-    ]);
-    assert_eq!(colors.len(), 4, "All ghost colors should be unique");
-}

tests/player.rs

@@ -0,0 +1,519 @@
+use bevy_ecs::{event::Events, system::RunSystemOnce};
+use pacman::{
+    events::{GameCommand, GameEvent},
+    map::{
+        direction::Direction,
+        graph::{Edge, TraversalFlags},
+    },
+    systems::{
+        can_traverse, player_control_system, player_movement_system, AudioState, BufferedDirection, DebugState, DeltaTime,
+        EntityType, GlobalState, Position, Velocity,
+    },
+};
+use speculoos::prelude::*;
+
+mod common;
+
+#[test]
+fn test_can_traverse_player_on_all_edges() {
+    let edge = Edge {
+        target: 1,
+        distance: 10.0,
+        direction: Direction::Up,
+        traversal_flags: TraversalFlags::ALL,
+    };
+
+    assert_that(&can_traverse(EntityType::Player, edge)).is_true();
+}
+
+#[test]
+fn test_can_traverse_player_on_pacman_only_edges() {
+    let edge = Edge {
+        target: 1,
+        distance: 10.0,
+        direction: Direction::Right,
+        traversal_flags: TraversalFlags::PACMAN,
+    };
+
+    assert_that(&can_traverse(EntityType::Player, edge)).is_true();
+}
+
+#[test]
+fn test_can_traverse_player_blocked_on_ghost_only_edges() {
+    let edge = Edge {
+        target: 1,
+        distance: 10.0,
+        direction: Direction::Left,
+        traversal_flags: TraversalFlags::GHOST,
+    };
+
+    assert_that(&can_traverse(EntityType::Player, edge)).is_false();
+}
+
+#[test]
+fn test_can_traverse_ghost_on_all_edges() {
+    let edge = Edge {
+        target: 2,
+        distance: 15.0,
+        direction: Direction::Down,
+        traversal_flags: TraversalFlags::ALL,
+    };
+
+    assert_that(&can_traverse(EntityType::Ghost, edge)).is_true();
+}
+
+#[test]
+fn test_can_traverse_ghost_on_ghost_only_edges() {
+    let edge = Edge {
+        target: 2,
+        distance: 15.0,
+        direction: Direction::Up,
+        traversal_flags: TraversalFlags::GHOST,
+    };
+
+    assert_that(&can_traverse(EntityType::Ghost, edge)).is_true();
+}
+
+#[test]
+fn test_can_traverse_ghost_blocked_on_pacman_only_edges() {
+    let edge = Edge {
+        target: 2,
+        distance: 15.0,
+        direction: Direction::Right,
+        traversal_flags: TraversalFlags::PACMAN,
+    };
+
+    assert_that(&can_traverse(EntityType::Ghost, edge)).is_false();
+}
+
+#[test]
+fn test_can_traverse_static_entities_flags() {
+    let edge = Edge {
+        target: 3,
+        distance: 8.0,
+        direction: Direction::Left,
+        traversal_flags: TraversalFlags::ALL,
+    };
+
+    // Static entities have empty traversal flags but can still "traverse"
+    // in the sense that empty flags are contained in any flag set
+    // This is the expected behavior since empty ⊆ any set
+    assert_that(&can_traverse(EntityType::Pellet, edge)).is_true();
+    assert_that(&can_traverse(EntityType::PowerPellet, edge)).is_true();
+}
+
+#[test]
+fn test_entity_type_traversal_flags() {
+    assert_that(&EntityType::Player.traversal_flags()).is_equal_to(TraversalFlags::PACMAN);
+    assert_that(&EntityType::Ghost.traversal_flags()).is_equal_to(TraversalFlags::GHOST);
+    assert_that(&EntityType::Pellet.traversal_flags()).is_equal_to(TraversalFlags::empty());
+    assert_that(&EntityType::PowerPellet.traversal_flags()).is_equal_to(TraversalFlags::empty());
+}
+
+#[test]
+fn test_player_control_system_move_command() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send move command
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Up)));
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that buffered direction was updated
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+
+    match *buffered_direction {
+        BufferedDirection::Some {
+            direction,
+            remaining_time,
+        } => {
+            assert_that(&direction).is_equal_to(Direction::Up);
+            assert_that(&remaining_time).is_equal_to(0.25);
+        }
+        BufferedDirection::None => panic!("Expected buffered direction to be set"),
+    }
+}
+
+#[test]
+fn test_player_control_system_exit_command() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send exit command
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::Exit));
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that exit flag was set
+    let state = world.resource::<GlobalState>();
+    assert_that(&state.exit).is_true();
+}
+
+#[test]
+fn test_player_control_system_toggle_debug() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send toggle debug command
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::ToggleDebug));
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that debug state changed
+    let debug_state = world.resource::<DebugState>();
+    assert_that(&debug_state.enabled).is_true();
+}
+
+#[test]
+fn test_player_control_system_mute_audio() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send mute audio command
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MuteAudio));
+
+    // Run the system
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that audio was muted
+    let audio_state = world.resource::<AudioState>();
+    assert_that(&audio_state.muted).is_true();
+
+    // Send mute audio command again to unmute - need fresh events
+    world.resource_mut::<Events<GameEvent>>().clear(); // Clear previous events
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MuteAudio));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that audio was unmuted
+    let audio_state = world.resource::<AudioState>();
+    assert_that(&audio_state.muted).is_false();
+}
+
+#[test]
+fn test_player_control_system_no_player_entity() {
+    let mut world = common::create_test_world();
+    // Don't spawn a player entity
+
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Up)));
+
+    // Run the system - should write an error
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Check that an error was written (we can't easily check Events without manual management,
+    // so for this test we just verify the system ran without panicking)
+    // In a real implementation, you might expose error checking through the ECS world
+}
+
+#[test]
+fn test_player_movement_system_buffered_direction_expires() {
+    let mut world = common::create_test_world();
+    let player = common::spawn_test_player(&mut world, 0);
+
+    // Set a buffered direction with short time
+    world.entity_mut(player).insert(BufferedDirection::Some {
+        direction: Direction::Up,
+        remaining_time: 0.01, // Very short time
+    });
+
+    // Set delta time to expire the buffered direction
+    world.insert_resource(DeltaTime::from_seconds(0.02));
+
+    // Run the system
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that buffered direction expired or remaining time decreased significantly
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+    match *buffered_direction {
+        BufferedDirection::None => {} // Expected - fully expired
+        BufferedDirection::Some { remaining_time, .. } => {
+            assert_that(&(remaining_time <= 0.0)).is_true();
+        }
+    }
+}
+
+#[test]
+fn test_player_movement_system_start_moving_from_stopped() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Player starts at node 0, facing right (towards node 1)
+    // Should start moving when system runs
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that player started moving
+    let mut query = world.query::<&Position>();
+    let position = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { from, .. } => {
+            assert_that(&from).is_equal_to(0);
+            // Don't assert exact target node since the real map has different connectivity
+        }
+        Position::Stopped { .. } => {} // May stay stopped if no valid edge in current direction
+    }
+}
+
+#[test]
+fn test_player_movement_system_buffered_direction_change() {
+    let mut world = common::create_test_world();
+    let player = common::spawn_test_player(&mut world, 0);
+
+    // Set a buffered direction to go down (towards node 2)
+    world.entity_mut(player).insert(BufferedDirection::Some {
+        direction: Direction::Down,
+        remaining_time: 1.0,
+    });
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that player started moving down instead of right
+    let mut query = world.query::<(&Position, &Velocity, &BufferedDirection)>();
+    let (position, _velocity, _buffered_direction) = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { from, to, .. } => {
+            assert_that(&from).is_equal_to(0);
+            assert_that(&to).is_equal_to(2); // Should be moving to node 2 (down)
+        }
+        Position::Stopped { .. } => panic!("Player should have started moving"),
+    }
+
+    // Check if the movement actually happened based on the real map connectivity
+    // The buffered direction might not be consumed if there's no valid edge in that direction
+}
+
+#[test]
+fn test_player_movement_system_no_valid_edge() {
+    let mut world = common::create_test_world();
+    let player = common::spawn_test_player(&mut world, 0);
+
+    // Set velocity to direction with no edge
+    world.entity_mut(player).insert(Velocity {
+        speed: 1.0,
+        direction: Direction::Up, // No edge up from node 0
+    });
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Player should remain stopped
+    let mut query = world.query::<&Position>();
+    let position = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Stopped { node } => assert_that(&node).is_equal_to(0),
+        Position::Moving { .. } => panic!("Player shouldn't be able to move without valid edge"),
+    }
+}
+
+#[test]
+fn test_player_movement_system_continue_moving() {
+    let mut world = common::create_test_world();
+    let player = common::spawn_test_player(&mut world, 0);
+
+    // Set player to already be moving
+    world.entity_mut(player).insert(Position::Moving {
+        from: 0,
+        to: 1,
+        remaining_distance: 50.0,
+    });
+
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that player continued moving and distance decreased
+    let mut query = world.query::<&Position>();
+    let position = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { remaining_distance, .. } => {
+            assert_that(&(remaining_distance < 50.0)).is_true(); // Should have moved
+        }
+        Position::Stopped { .. } => {
+            // If player reached destination, that's also valid
+        }
+    }
+}
+
+#[test]
+fn test_full_player_input_to_movement_flow() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send move command
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Down)));
+
+    // Run control system to process input
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Run movement system to execute movement
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check final state - player should be moving down
+    let mut query = world.query::<(&Position, &Velocity, &BufferedDirection)>();
+    let (position, _velocity, _buffered_direction) = query.single(&world).expect("Player should exist");
+
+    match *position {
+        Position::Moving { from, to, .. } => {
+            assert_that(&from).is_equal_to(0);
+            assert_that(&to).is_equal_to(2); // Moving to node 2 (down)
+        }
+        Position::Stopped { .. } => panic!("Player should be moving"),
+    }
+
+    // Check that player moved in the buffered direction if possible
+    // In the real map, the buffered direction may not be consumable if there's no valid edge
+}
+
+#[test]
+fn test_buffered_direction_timing() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send move command
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Up)));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Run movement system multiple times with small delta times
+    world.insert_resource(DeltaTime::from_seconds(0.1)); // 0.1 seconds
+
+    // First run - buffered direction should still be active
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+
+    match *buffered_direction {
+        BufferedDirection::Some { remaining_time, .. } => {
+            assert_that(&(remaining_time > 0.0)).is_true();
+            assert_that(&(remaining_time < 0.25)).is_true();
+        }
+        BufferedDirection::None => panic!("Buffered direction should still be active"),
+    }
+
+    // Run again to fully expire the buffered direction
+    world.insert_resource(DeltaTime::from_seconds(0.2)); // Total 0.3 seconds, should expire
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    let buffered_direction = query.single(&world).expect("Player should exist");
+    assert_that(buffered_direction).is_equal_to(BufferedDirection::None);
+}
+
+#[test]
+fn test_multiple_rapid_direction_changes() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Send multiple rapid direction changes
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Up)));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Down)));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Left)));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+
+    // Only the last direction should be buffered
+    let mut query = world.query::<&BufferedDirection>();
+    let buffered_direction = query.single(&world).expect("Player should exist");
+
+    match *buffered_direction {
+        BufferedDirection::Some { direction, .. } => {
+            assert_that(&direction).is_equal_to(Direction::Left);
+        }
+        BufferedDirection::None => panic!("Expected buffered direction"),
+    }
+}
+
+#[test]
+fn test_player_state_persistence_across_systems() {
+    let mut world = common::create_test_world();
+    let _player = common::spawn_test_player(&mut world, 0);
+
+    // Test that multiple commands can be processed - but need to handle events properly
+    // Clear any existing events first
+    world.resource_mut::<Events<GameEvent>>().clear();
+
+    // Toggle debug mode
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::ToggleDebug));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+    let debug_state_after_toggle = *world.resource::<DebugState>();
+
+    // Clear events and mute audio
+    world.resource_mut::<Events<GameEvent>>().clear();
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MuteAudio));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+    let audio_muted_after_toggle = world.resource::<AudioState>().muted;
+
+    // Clear events and move player
+    world.resource_mut::<Events<GameEvent>>().clear();
+    common::send_game_event(&mut world, GameEvent::Command(GameCommand::MovePlayer(Direction::Down)));
+    world
+        .run_system_once(player_control_system)
+        .expect("System should run successfully");
+    world
+        .run_system_once(player_movement_system)
+        .expect("System should run successfully");
+
+    // Check that all state changes persisted
+    // Variables already captured above during individual tests
+    let mut query = world.query::<&Position>();
+    let position = *query.single(&world).expect("Player should exist");
+
+    // Check that the state changes persisted individually
+    assert_that(&debug_state_after_toggle.enabled).is_true();
+    assert_that(&audio_muted_after_toggle).is_true();
+
+    // Player position depends on actual map connectivity
+    match position {
+        Position::Moving { .. } => {}  // Good - player is moving
+        Position::Stopped { .. } => {} // Also ok - might not have valid edge in that direction
+    }
+}

tests/profiling.rs

@@ -0,0 +1,92 @@
+use pacman::systems::profiling::{SystemId, SystemTimings};
+use speculoos::prelude::*;
+use std::time::Duration;
+use strum::IntoEnumIterator;
+
+macro_rules! assert_close {
+    ($actual:expr, $expected:expr, $concern:expr) => {
+        let tolerance = Duration::from_micros(500);
+        let diff = $actual.abs_diff($expected);
+        assert_that(&(diff < tolerance)).is_true();
+    };
+}
+
+#[test]
+fn test_timing_statistics() {
+    let timings = SystemTimings::default();
+
+    // Add consecutive timing measurements (no skipped ticks to avoid zero padding)
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(10), 1);
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(12), 2);
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(8), 3);
+
+    // Add consecutive timing measurements for another system
+    timings.add_timing(SystemId::Blinking, Duration::from_millis(3), 1);
+    timings.add_timing(SystemId::Blinking, Duration::from_millis(2), 2);
+    timings.add_timing(SystemId::Blinking, Duration::from_millis(1), 3);
+
+    {
+        let stats = timings.get_stats(3);
+        let (avg, std_dev) = stats.get(&SystemId::PlayerControls).unwrap();
+
+        assert_close!(*avg, Duration::from_millis(10), "PlayerControls average timing");
+        assert_close!(*std_dev, Duration::from_millis(2), "PlayerControls standard deviation timing");
+    }
+
+    // Note: get_total_stats() was removed as we now use the Total system directly
+    // This test now focuses on individual system statistics
+}
+
+#[test]
+fn test_default_zero_timing_for_unused_systems() {
+    let timings = SystemTimings::default();
+
+    // Add timing data for only one system
+    timings.add_timing(SystemId::PlayerControls, Duration::from_millis(5), 1);
+
+    let stats = timings.get_stats(1);
+
+    // Verify all SystemId variants are present in the stats
+    let expected_count = SystemId::iter().count();
+    assert_that(&stats.len()).is_equal_to(expected_count);
+
+    // Verify that the system with data has non-zero timing
+    let (avg, std_dev) = stats.get(&SystemId::PlayerControls).unwrap();
+    assert_close!(*avg, Duration::from_millis(5), "System with data should have correct timing");
+    assert_close!(*std_dev, Duration::ZERO, "Single measurement should have zero std dev");
+
+    // Verify that all other systems have zero timing (excluding Total which is special)
+    for id in SystemId::iter() {
+        if id != SystemId::PlayerControls && id != SystemId::Total {
+            let (avg, std_dev) = stats.get(&id).unwrap();
+            assert_close!(
+                *avg,
+                Duration::ZERO,
+                format!("Unused system {:?} should have zero avg timing", id)
+            );
+            assert_close!(
+                *std_dev,
+                Duration::ZERO,
+                format!("Unused system {:?} should have zero std dev", id)
+            );
+        }
+    }
+}
+
+#[test]
+fn test_total_system_timing() {
+    let timings = SystemTimings::default();
+
+    // Add some timing data to the Total system
+    timings.add_total_timing(Duration::from_millis(16), 1);
+    timings.add_total_timing(Duration::from_millis(18), 2);
+    timings.add_total_timing(Duration::from_millis(14), 3);
+
+    let stats = timings.get_stats(3);
+    let (avg, std_dev) = stats.get(&SystemId::Total).unwrap();
+
+    // Should have 16ms average (16+18+14)/3 = 16ms
+    assert_close!(*avg, Duration::from_millis(16), "Total system average timing");
+    // Should have some standard deviation
+    assert_that(&(*std_dev > Duration::ZERO)).is_true();
+}

tests/sprite.rs

@@ -1,81 +1,57 @@
 use glam::U16Vec2;
-use pacman::texture::sprite::{AtlasMapper, AtlasTile, MapperFrame, Sprite, SpriteAtlas};
+use pacman::texture::sprite::{AtlasMapper, AtlasTile, MapperFrame};
 use sdl2::pixels::Color;
+use speculoos::prelude::*;
 use std::collections::HashMap;
 
-fn mock_texture() -> sdl2::render::Texture<'static> {
-    unsafe { std::mem::transmute(0usize) }
-}
+mod common;
 
 #[test]
-fn test_sprite_atlas_basic() {
+fn test_atlas_mapper_frame_lookup() {
     let mut frames = HashMap::new();
     frames.insert(
         "test".to_string(),
         MapperFrame {
-            x: 10,
-            y: 20,
-            width: 32,
-            height: 64,
+            pos: U16Vec2::new(10, 20),
+            size: U16Vec2::new(32, 64),
         },
     );
 
     let mapper = AtlasMapper { frames };
-    let texture = mock_texture();
-    let atlas = SpriteAtlas::new(texture, mapper);
 
-    let tile = atlas.get_tile("test");
-    assert!(tile.is_some());
-    let tile = tile.unwrap();
-    assert_eq!(tile.pos, glam::U16Vec2::new(10, 20));
-    assert_eq!(tile.size, glam::U16Vec2::new(32, 64));
-    assert_eq!(tile.color, None);
+    // Test direct frame lookup
+    let frame = mapper.frames.get("test");
+    assert_that(&frame.is_some()).is_true();
+    let frame = frame.unwrap();
+    assert_that(&frame.pos).is_equal_to(U16Vec2::new(10, 20));
+    assert_that(&frame.size).is_equal_to(U16Vec2::new(32, 64));
 }
 
 #[test]
-fn test_sprite_atlas_multiple_tiles() {
+fn test_atlas_mapper_multiple_frames() {
     let mut frames = HashMap::new();
     frames.insert(
         "tile1".to_string(),
         MapperFrame {
-            x: 0,
-            y: 0,
-            width: 32,
-            height: 32,
+            pos: U16Vec2::new(0, 0),
+            size: U16Vec2::new(32, 32),
         },
     );
     frames.insert(
         "tile2".to_string(),
         MapperFrame {
-            x: 32,
-            y: 0,
-            width: 64,
-            height: 64,
+            pos: U16Vec2::new(32, 0),
+            size: U16Vec2::new(64, 64),
         },
     );
 
     let mapper = AtlasMapper { frames };
-    let texture = mock_texture();
-    let atlas = SpriteAtlas::new(texture, mapper);
 
-    assert_eq!(atlas.tiles_count(), 2);
-    assert!(atlas.has_tile("tile1"));
-    assert!(atlas.has_tile("tile2"));
-    assert!(!atlas.has_tile("tile3"));
-    assert!(atlas.get_tile("nonexistent").is_none());
-}
-
-#[test]
-fn test_sprite_atlas_color() {
-    let mapper = AtlasMapper { frames: HashMap::new() };
-    let texture = mock_texture();
-    let mut atlas = SpriteAtlas::new(texture, mapper);
-
-    assert_eq!(atlas.default_color(), None);
-
-    let color = Color::RGB(255, 0, 0);
-    atlas.set_color(color);
-    assert_eq!(atlas.default_color(), Some(color));
+    assert_that(&mapper.frames.len()).is_equal_to(2);
+    assert_that(&mapper.frames.contains_key("tile1")).is_true();
+    assert_that(&mapper.frames.contains_key("tile2")).is_true();
+    assert_that(&mapper.frames.contains_key("tile3")).is_false();
+    assert_that(&mapper.frames.contains_key("nonexistent")).is_false();
 }
 
 #[test]
@@ -85,19 +61,10 @@ fn test_atlas_tile_new_and_with_color() {
     let color = Color::RGB(100, 150, 200);
 
     let tile = AtlasTile::new(pos, size, None);
-    assert_eq!(tile.pos, pos);
-    assert_eq!(tile.size, size);
-    assert_eq!(tile.color, None);
+    assert_that(&tile.pos).is_equal_to(pos);
+    assert_that(&tile.size).is_equal_to(size);
+    assert_that(&tile.color).is_equal_to(None);
 
     let tile_with_color = tile.with_color(color);
-    assert_eq!(tile_with_color.color, Some(color));
-}
-
-#[test]
-fn test_sprite_new() {
-    let atlas_tile = AtlasTile::new(U16Vec2::new(0, 0), U16Vec2::new(16, 16), None);
-    let sprite = Sprite::new(atlas_tile);
-
-    assert_eq!(sprite.atlas_tile.pos, atlas_tile.pos);
-    assert_eq!(sprite.atlas_tile.size, atlas_tile.size);
+    assert_that(&tile_with_color.color).is_equal_to(Some(color));
 }

tests/sprites.rs

@@ -0,0 +1,73 @@
+//! Tests for the sprite path generation.
+use pacman::{
+    game::ATLAS_FRAMES,
+    map::direction::Direction,
+    systems::components::Ghost,
+    texture::sprites::{FrightenedColor, GameSprite, GhostSprite, MazeSprite, PacmanSprite},
+};
+
+#[test]
+fn test_all_sprite_paths_exist() {
+    let mut sprites_to_test = Vec::new();
+
+    // Pac-Man sprites
+    for &dir in &[Direction::Up, Direction::Down, Direction::Left, Direction::Right] {
+        for frame in 0..2 {
+            sprites_to_test.push(GameSprite::Pacman(PacmanSprite::Moving(dir, frame)));
+        }
+    }
+    sprites_to_test.push(GameSprite::Pacman(PacmanSprite::Full));
+    for frame in 0..=10 {
+        sprites_to_test.push(GameSprite::Pacman(PacmanSprite::Dying(frame)));
+    }
+
+    // Ghost sprites
+    for &ghost in &[Ghost::Blinky, Ghost::Pinky, Ghost::Inky, Ghost::Clyde] {
+        for &dir in &[Direction::Up, Direction::Down, Direction::Left, Direction::Right] {
+            for frame in 0..2 {
+                sprites_to_test.push(GameSprite::Ghost(GhostSprite::Normal(ghost, dir, frame)));
+            }
+            sprites_to_test.push(GameSprite::Ghost(GhostSprite::Eyes(dir)));
+        }
+    }
+    for &color in &[FrightenedColor::Blue, FrightenedColor::White] {
+        for frame in 0..2 {
+            sprites_to_test.push(GameSprite::Ghost(GhostSprite::Frightened(color, frame)));
+        }
+    }
+
+    // Maze sprites
+    for i in 0..=34 {
+        sprites_to_test.push(GameSprite::Maze(MazeSprite::Tile(i)));
+    }
+    sprites_to_test.push(GameSprite::Maze(MazeSprite::Pellet));
+    sprites_to_test.push(GameSprite::Maze(MazeSprite::Energizer));
+
+    for sprite in sprites_to_test {
+        let path = sprite.to_path();
+        assert!(
+            ATLAS_FRAMES.contains_key(&path),
+            "Sprite path '{}' does not exist in the atlas.",
+            path
+        );
+    }
+}
+
+#[test]
+fn test_invalid_sprite_paths_do_not_exist() {
+    let invalid_sprites = vec![
+        // An invalid Pac-Man dying frame
+        GameSprite::Pacman(PacmanSprite::Dying(99)),
+        // An invalid maze tile
+        GameSprite::Maze(MazeSprite::Tile(99)),
+    ];
+
+    for sprite in invalid_sprites {
+        let path = sprite.to_path();
+        assert!(
+            !ATLAS_FRAMES.contains_key(&path),
+            "Invalid sprite path '{}' was found in the atlas, but it should not exist.",
+            path
+        );
+    }
+}

tests/text.rs

@@ -1,9 +1,10 @@
 use pacman::texture::{sprite::SpriteAtlas, text::TextTexture};
-
-use crate::common::create_atlas;
+use speculoos::prelude::*;
 
 mod common;
 
+use common::create_atlas;
+
 /// Helper function to get all characters that should be in the atlas
 fn get_all_chars() -> String {
     let mut chars = Vec::new();
@@ -16,22 +17,16 @@ fn get_all_chars() -> String {
 /// Helper function to check if a character is in the atlas and char_map
 fn check_char(text_texture: &mut TextTexture, atlas: &mut SpriteAtlas, c: char) {
     // Check that the character is not in the char_map yet
-    assert!(
-        !text_texture.get_char_map().contains_key(&c),
-        "Character {c} should not yet be in char_map"
-    );
+    assert_that(&text_texture.get_char_map().contains_key(&c)).is_false();
 
     // Get the tile from the atlas, which caches the tile in the char_map
     let tile = text_texture.get_tile(c, atlas);
 
-    assert!(tile.is_ok(), "Failed to get tile for character {c}");
-    assert!(tile.unwrap().is_some(), "Tile for character {c} not found in atlas");
+    assert_that(&tile.is_ok()).is_true();
+    assert_that(&tile.unwrap().is_some()).is_true();
 
     // Check that the tile is now cached in the char_map
-    assert!(
-        text_texture.get_char_map().contains_key(&c),
-        "Tile for character {c} was not cached in char_map"
-    );
+    assert_that(&text_texture.get_char_map().contains_key(&c)).is_true();
 }
 
 #[test]
@@ -74,8 +69,8 @@ fn test_text_width() -> Result<(), String> {
         let width = text_texture.text_width(&string);
         let height = text_texture.text_height();
 
-        assert!(width > 0, "Width for string {string} should be greater than 0");
-        assert!(height > 0, "Height for string {string} should be greater than 0");
+        assert_that(&(width > 0)).is_true();
+        assert_that(&(height > 0)).is_true();
     }
 
     Ok(())
@@ -88,22 +83,42 @@ fn test_text_scale() -> Result<(), String> {
 
     let mut text_texture = TextTexture::new(0.5);
 
-    assert_eq!(text_texture.scale(), 0.5);
-    assert_eq!(text_texture.text_height(), 4);
-    assert_eq!(text_texture.text_width(""), 0);
-    assert_eq!(text_texture.text_width(string), base_width / 2);
+    assert_that(&text_texture.scale()).is_equal_to(0.5);
+    assert_that(&text_texture.text_height()).is_equal_to(4);
+    assert_that(&text_texture.text_width("")).is_equal_to(0);
+    assert_that(&text_texture.text_width(string)).is_equal_to(base_width / 2);
 
     text_texture.set_scale(2.0);
-    assert_eq!(text_texture.scale(), 2.0);
-    assert_eq!(text_texture.text_height(), 16);
-    assert_eq!(text_texture.text_width(string), base_width * 2);
-    assert_eq!(text_texture.text_width(""), 0);
+    assert_that(&text_texture.scale()).is_equal_to(2.0);
+    assert_that(&text_texture.text_height()).is_equal_to(16);
+    assert_that(&text_texture.text_width(string)).is_equal_to(base_width * 2);
+    assert_that(&text_texture.text_width("")).is_equal_to(0);
 
     text_texture.set_scale(1.0);
-    assert_eq!(text_texture.scale(), 1.0);
-    assert_eq!(text_texture.text_height(), 8);
-    assert_eq!(text_texture.text_width(string), base_width);
-    assert_eq!(text_texture.text_width(""), 0);
+    assert_that(&text_texture.scale()).is_equal_to(1.0);
+    assert_that(&text_texture.text_height()).is_equal_to(8);
+    assert_that(&text_texture.text_width(string)).is_equal_to(base_width);
+    assert_that(&text_texture.text_width("")).is_equal_to(0);
+
+    Ok(())
+}
+
+#[test]
+fn test_text_color() -> Result<(), String> {
+    let mut text_texture = TextTexture::new(1.0);
+
+    // Test default color (should be None initially)
+    assert_that(&text_texture.color()).is_equal_to(None);
+
+    // Test setting color
+    let test_color = sdl2::pixels::Color::YELLOW;
+    text_texture.set_color(test_color);
+    assert_that(&text_texture.color()).is_equal_to(Some(test_color));
+
+    // Test changing color
+    let new_color = sdl2::pixels::Color::RED;
+    text_texture.set_color(new_color);
+    assert_that(&text_texture.color()).is_equal_to(Some(new_color));
 
     Ok(())
 }

tests/ttf.rs

@@ -0,0 +1,115 @@
+use pacman::texture::ttf::{TtfAtlas, TtfRenderer};
+use sdl2::pixels::Color;
+
+mod common;
+
+#[test]
+fn text_width_calculates_correctly_for_empty_string() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer = TtfRenderer::new(1.0);
+    let width = renderer.text_width(&atlas, "");
+
+    assert_eq!(width, 0);
+}
+
+#[test]
+fn text_width_calculates_correctly_for_single_character() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer = TtfRenderer::new(1.0);
+    let width = renderer.text_width(&atlas, "A");
+
+    assert!(width > 0);
+}
+
+#[test]
+fn text_width_scales_correctly() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer1 = TtfRenderer::new(1.0);
+    let renderer2 = TtfRenderer::new(2.0);
+
+    let width1 = renderer1.text_width(&atlas, "Test");
+    let width2 = renderer2.text_width(&atlas, "Test");
+
+    assert_eq!(width2, width1 * 2);
+}
+
+#[test]
+fn text_height_returns_non_zero_for_valid_atlas() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer = TtfRenderer::new(1.0);
+    let height = renderer.text_height(&atlas);
+
+    assert!(height > 0);
+}
+
+#[test]
+fn text_height_scales_correctly() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer1 = TtfRenderer::new(1.0);
+    let renderer2 = TtfRenderer::new(2.0);
+
+    let height1 = renderer1.text_height(&atlas);
+    let height2 = renderer2.text_height(&atlas);
+
+    assert_eq!(height2, height1 * 2);
+}
+
+#[test]
+fn render_text_handles_empty_string() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer = TtfRenderer::new(1.0);
+    let result = renderer.render_text(&mut canvas, &mut atlas, "", glam::Vec2::new(0.0, 0.0), Color::WHITE);
+
+    assert!(result.is_ok());
+}
+
+#[test]
+fn render_text_handles_single_character() {
+    let (mut canvas, texture_creator, _sdl) = common::setup_sdl().unwrap();
+    let _ttf_context = sdl2::ttf::init().unwrap();
+    let font = _ttf_context.load_font("assets/game/TerminalVector.ttf", 16).unwrap();
+
+    let mut atlas = TtfAtlas::new(&texture_creator, &font).unwrap();
+    atlas.populate_atlas(&mut canvas, &texture_creator, &font).unwrap();
+
+    let renderer = TtfRenderer::new(1.0);
+    let result = renderer.render_text(&mut canvas, &mut atlas, "A", glam::Vec2::new(10.0, 10.0), Color::RED);
+
+    assert!(result.is_ok());
+}

web.build.ts

@@ -1,7 +1,7 @@
 import { $ } from "bun";
 import { existsSync, promises as fs } from "fs";
 import { platform } from "os";
-import { dirname, join, relative, resolve } from "path";
+import { basename, dirname, join, relative, resolve } from "path";
 import { match, P } from "ts-pattern";
 import { configure, getConsoleSink, getLogger } from "@logtape/logtape";
 
@@ -79,16 +79,19 @@ async function build(release: boolean, env: Record<string, string> | null) {
 
   // The files to copy into 'dist'
   const files = [
-    ...["index.html", "favicon.ico", "build.css", "TerminalVector.ttf"].map(
-      (file) => ({
-        src: join(siteFolder, file),
-        dest: join(dist, file),
-        optional: false,
-      })
-    ),
+    ...[
+      "index.html",
+      "favicon.ico",
+      "build.css",
+      "../game/TerminalVector.ttf",
+    ].map((file) => ({
+      src: resolve(join(siteFolder, file)),
+      dest: join(dist, basename(file)),
+      optional: false,
+    })),
     ...["pacman.wasm", "pacman.js", "deps/pacman.data"].map((file) => ({
       src: join(outputFolder, file),
-      dest: join(dist, file.split("/").pop() || file),
+      dest: join(dist, basename(file)),
       optional: false,
     })),
     {
@@ -498,7 +501,6 @@ async function activateEmsdk(
 
   return { vars };
 }
-
 async function main() {
   // Print the OS detected
   logger.debug(
@@ -512,7 +514,19 @@ async function main() {
         .exhaustive()
   );
 
-  const release = process.env.RELEASE !== "0";
+  // Parse command line args for build mode
+  const args = process.argv.slice(2);
+  let release = true; // Default to release mode
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-d" || arg === "--debug") {
+      release = false;
+    } else if (arg === "-r" || arg === "--release") {
+      release = true;
+    }
+  }
+
   const emsdkDir = resolve("./emsdk");
 
   // Activate the Emscripten SDK (returns null if already activated)