warhorst/pacman

1. This is a Bevy-based arcade game implementation of Pac-Man. The executable starts in src/main.rs, and the runtime is organized around Bevy’s ECS loop, with game behavior split into systems, resources, and component-driven entities.

2. The repository has a clear separation between “core game rules” and “game presentation/runtime.” src/core contains the rule model and domain logic: directions, positions, ghost state, pacman state, map/level data, score/lives, speed/specs per level, sound/music state, and interaction rules. These modules are the closest thing to the game engine’s authoritative state.

3. src/game is the Bevy integration layer. It turns core state into on-screen behavior: spawning entities, moving Pac-Man and ghosts, handling collisions/interactions, animating sprites and walls, switching game states, and updating UI. In an architecture diagram, this is the boundary where ECS systems read/write core resources and components.

4. The gameplay is split into focused subsystems under src/game: pacman, ghosts, edibles, target, ui, plus supporting modules such as music, sound_effect, score, lives, level, speed, and schedule. This suggests a system-oriented architecture where each subsystem owns one slice of the loop rather than a monolithic “game manager.”

5. Ghost behavior is modeled as its own subsystem rather than generic enemy AI. The tree shows ghost_schedule, ghost_state, ghost_house_gate, target, spawn, and movement, indicating a pipeline of scheduled mode changes, target selection, spawning, house gating, and path/motion updates. That mirrors classic Pac-Man behavior and is likely one of the central design boundaries.

6. Pac-Man also has a dedicated lifecycle: spawning, movement, edible interactions, textures, and state transitions such as dying or respawning. The presence of restart_game, game_state_transition, and ready_screen/game_over_screen shows that the game flow is explicitly stateful, not just continuous simulation.

7. The map and maze are treated as data-driven content. assets/maps/map.scn.ron indicates a scene-driven map definition, and src/spawn plus src/spawn/enhance_map suggest a preprocessing/spawn pipeline that enriches the imported scene into gameplay structures like maze walls, tunnels, and the ghost house before entities are activated.

8. Asset handling is a notable architectural concern. The project keeps source art in resources/aseprite and generated/runtime assets in assets/. The many .aseprite.json files imply sprite-sheet metadata generated from Aseprite exports, and src/sprite_sheet.rs plus src/asset_preload.rs likely coordinate loading and registering those assets for Bevy.

9. There is also an explicit Rust subcrate, load_assets/, plus build.rs and build_wasm.sh. That points to a build-time asset or preload workflow, especially for WebAssembly deployment where assets often need to be enumerated up front. The README confirms WASM is a first-class target and notes that asset preloading is part of that pipeline.

10. Sound is a parallel asset and runtime subsystem, not just decoration. The repository includes separate sound effects for waka, siren, frightened, fruit eaten, ghost eaten, dying, start, and high score, and src/game/music.rs / sound_effect.rs indicate that audio is driven by game state transitions and interactions rather than by ad hoc playback calls.

11. UI is lightweight but distinct from core gameplay. src/game/ui contains top/bottom HUD elements plus ready and game-over overlays, which suggests the HUD reads score/lives/level resources while the gameplay systems continue running underneath.

12. Overall data flow is: assets and scene data are loaded, the map is enhanced/spawned into entities, core state drives movement and interactions, collisions update score/lives/edible/ghost states, and Bevy systems reflect those changes through animation, audio, and UI. The architecture is intentionally modular and heavily state-driven, with a clear boundary between deterministic game rules and Bevy-facing presentation logic.