# warhorst/pacman architecture

> Architecture diagram of the GitHub repository warhorst/pacman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/warhorst/pacman
- Repository: https://github.com/warhorst/pacman

## Overview

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.

Main entry points: [`src/game/mod.rs`](https://github.com/warhorst/pacman/blob/master/src/game/mod.rs) (Game layer), [`src/spawn/mod.rs`](https://github.com/warhorst/pacman/blob/master/src/spawn/mod.rs) (Spawn pipeline), [`assets/maps/map.scn.ron`](https://github.com/warhorst/pacman/blob/master/assets/maps/map.scn.ron) (Assets), [`src/main.rs`](https://github.com/warhorst/pacman/blob/master/src/main.rs) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core rules"]
  node_node_core_mod["Core<br/>domain<br/>[mod.rs]"]
  node_node_core_state(("Game state<br/>[game_state.rs]"))
  node_node_core_map["Map model<br/>map data<br/>[map.rs]"]
  node_node_core_actor["Actors<br/>entity state<br/>[pacman.rs]"]
  node_node_core_ghost["Ghost rules<br/>ghost logic<br/>[ghosts.rs]"]
  node_node_core_progress["Progress<br/>score/lives<br/>[score.rs]"]
  node_node_core_rules["Interactions<br/>rules<br/>[interactions.rs]"]
end

subgraph group_group_game["Bevy runtime"]
  node_node_main["Main<br/>entry<br/>[main.rs]"]
  node_node_spawn["Spawn pipeline<br/>map setup<br/>[mod.rs]"]
  node_node_game_mod["Game layer<br/>ecs systems<br/>[mod.rs]"]
  node_node_pacman["Pac-Man<br/>runtime subsystem<br/>[mod.rs]"]
  node_node_ghosts["Ghosts<br/>runtime subsystem<br/>[mod.rs]"]
  node_node_target["Targeting<br/>ghost AI<br/>[mod.rs]"]
  node_node_edibles["Edibles<br/>collectibles<br/>[mod.rs]"]
  node_node_ui["UI<br/>hud/overlays<br/>[mod.rs]"]
  node_node_audio["Audio<br/>music/sfx<br/>[music.rs]"]
  node_node_state(("State flow<br/>transition systems<br/>[state.rs]"))
end

subgraph group_group_content["Assets"]
  node_node_sprite["Sprites<br/>asset loading<br/>[sprite_sheet.rs]"]
  node_node_assets["Assets<br/>content<br/>[map.scn.ron]"]
end

subgraph group_group_build["Build pipeline"]
  node_node_loader["Loader<br/>preload crate<br/>[lib.rs]"]
  node_node_build["Build<br/>[build.rs]"]
end

node_node_main -->|"boots"| node_node_game_mod
node_node_main -->|"uses"| node_node_core_mod
node_node_game_mod -->|"orchestrates"| node_node_state
node_node_game_mod -->|"spawns map"| node_node_spawn
node_node_spawn -->|"loads scene"| node_node_assets
node_node_spawn -->|"builds"| node_node_core_map
node_node_game_mod -->|"updates"| node_node_pacman
node_node_game_mod -->|"updates"| node_node_ghosts
node_node_game_mod -->|"updates"| node_node_edibles
node_node_game_mod -->|"updates"| node_node_target
node_node_game_mod -->|"renders"| node_node_ui
node_node_game_mod -->|"plays"| node_node_audio
node_node_pacman -->|"reads/writes"| node_node_core_actor
node_node_ghosts -->|"reads/writes"| node_node_core_ghost
node_node_target -->|"drives"| node_node_core_ghost
node_node_edibles -->|"feeds"| node_node_core_rules
node_node_game_mod -->|"updates"| node_node_core_progress
node_node_game_mod -->|"transitions"| node_node_core_state
node_node_sprite -->|"loads from"| node_node_assets
node_node_loader -->|"supports"| node_node_sprite
node_node_build -->|"invokes"| node_node_loader
node_node_audio -->|"uses"| node_node_assets
node_node_ui -->|"displays"| node_node_core_progress

click node_node_main "https://github.com/warhorst/pacman/blob/master/src/main.rs"
click node_node_core_mod "https://github.com/warhorst/pacman/blob/master/src/core/mod.rs"
click node_node_core_state "https://github.com/warhorst/pacman/blob/master/src/core/game_state.rs"
click node_node_core_map "https://github.com/warhorst/pacman/blob/master/src/core/map.rs"
click node_node_core_actor "https://github.com/warhorst/pacman/blob/master/src/core/pacman.rs"
click node_node_core_ghost "https://github.com/warhorst/pacman/blob/master/src/core/ghosts.rs"
click node_node_core_progress "https://github.com/warhorst/pacman/blob/master/src/core/score.rs"
click node_node_core_rules "https://github.com/warhorst/pacman/blob/master/src/core/interactions.rs"
click node_node_spawn "https://github.com/warhorst/pacman/blob/master/src/spawn/mod.rs"
click node_node_game_mod "https://github.com/warhorst/pacman/blob/master/src/game/mod.rs"
click node_node_pacman "https://github.com/warhorst/pacman/blob/master/src/game/pacman/mod.rs"
click node_node_ghosts "https://github.com/warhorst/pacman/blob/master/src/game/ghosts/mod.rs"
click node_node_target "https://github.com/warhorst/pacman/blob/master/src/game/target/mod.rs"
click node_node_edibles "https://github.com/warhorst/pacman/blob/master/src/game/edibles/mod.rs"
click node_node_ui "https://github.com/warhorst/pacman/blob/master/src/game/ui/mod.rs"
click node_node_audio "https://github.com/warhorst/pacman/blob/master/src/game/music.rs"
click node_node_state "https://github.com/warhorst/pacman/blob/master/src/game/state.rs"
click node_node_sprite "https://github.com/warhorst/pacman/blob/master/src/sprite_sheet.rs"
click node_node_assets "https://github.com/warhorst/pacman/blob/master/assets/maps/map.scn.ron"
click node_node_loader "https://github.com/warhorst/pacman/blob/master/load_assets/src/lib.rs"
click node_node_build "https://github.com/warhorst/pacman/blob/master/build.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_core_mod,node_node_core_state,node_node_core_map,node_node_core_actor,node_node_core_ghost,node_node_core_progress,node_node_core_rules toneBlue
class node_node_main,node_node_spawn,node_node_game_mod,node_node_pacman,node_node_ghosts,node_node_target,node_node_edibles,node_node_ui,node_node_audio,node_node_state toneAmber
class node_node_sprite,node_node_assets toneMint
class node_node_loader,node_node_build toneRose
```

## Components

### Core rules

Authoritative Pac-Man domain state and rules.

- [Core](https://github.com/warhorst/pacman/blob/master/src/core/mod.rs): domain · Shared game rules and state model. · `src/core/mod.rs`
- [Game state](https://github.com/warhorst/pacman/blob/master/src/core/game_state.rs): state · High-level game flow and restart logic. · `src/core/game_state.rs`
- [Map model](https://github.com/warhorst/pacman/blob/master/src/core/map.rs): map data · Maze, level, and scene-derived world data. · `src/core/map.rs`
- [Actors](https://github.com/warhorst/pacman/blob/master/src/core/pacman.rs): entity state · Pac-Man and ghost state, directions, positions, and targets. · `src/core/pacman.rs`
- [Ghost rules](https://github.com/warhorst/pacman/blob/master/src/core/ghosts.rs): ghost logic · Ghost modes, schedules, house gate, and targeting. · `src/core/ghosts.rs`
- [Progress](https://github.com/warhorst/pacman/blob/master/src/core/score.rs): score/lives · Score, lives, level, speed, and per-level specs. · `src/core/score.rs`
- [Interactions](https://github.com/warhorst/pacman/blob/master/src/core/interactions.rs): rules · Collision and edible interaction rules. · `src/core/interactions.rs`

### Bevy runtime

ECS systems that run the game and render it.

- [Main](https://github.com/warhorst/pacman/blob/master/src/main.rs): entry · Starts the Bevy app and wires plugins. · `src/main.rs`
- [Spawn pipeline](https://github.com/warhorst/pacman/blob/master/src/spawn/mod.rs): map setup · Imports and enriches the map scene into gameplay structures. · `src/spawn/mod.rs`
- [Game layer](https://github.com/warhorst/pacman/blob/master/src/game/mod.rs): ecs systems · Bevy integration boundary for runtime systems. · `src/game/mod.rs`
- [Pac-Man](https://github.com/warhorst/pacman/blob/master/src/game/pacman/mod.rs): runtime subsystem · Spawn, movement, edible reactions, and textures for Pac-Man. · `src/game/pacman/mod.rs`
- [Ghosts](https://github.com/warhorst/pacman/blob/master/src/game/ghosts/mod.rs): runtime subsystem · Ghost spawn, movement, and textures. · `src/game/ghosts/mod.rs`
- [Targeting](https://github.com/warhorst/pacman/blob/master/src/game/target/mod.rs): ghost AI · Ghost target selection and eaten/spawned transitions. · `src/game/target/mod.rs`
- [Edibles](https://github.com/warhorst/pacman/blob/master/src/game/edibles/mod.rs): collectibles · Dots, energizers, and fruit behavior. · `src/game/edibles/mod.rs`
- [UI](https://github.com/warhorst/pacman/blob/master/src/game/ui/mod.rs): hud/overlays · Top/bottom HUD plus ready and game-over screens. · `src/game/ui/mod.rs`
- [Audio](https://github.com/warhorst/pacman/blob/master/src/game/music.rs): music/sfx · Music and sound effect playback driven by game state. · `src/game/music.rs`
- [State flow](https://github.com/warhorst/pacman/blob/master/src/game/state.rs): transition systems · Game-state transitions and restart handling in the runtime. · `src/game/state.rs`

### Assets

Scene, textures, sound, and generated asset data.

- [Sprites](https://github.com/warhorst/pacman/blob/master/src/sprite_sheet.rs): asset loading · Sprite-sheet registration and asset preloading coordination. · `src/sprite_sheet.rs`
- [Assets](https://github.com/warhorst/pacman/blob/master/assets/maps/map.scn.ron): content · Imported scene, generated textures, sounds, and source art. · `assets/maps/map.scn.ron`

### Build pipeline

Asset-preload and WASM-oriented build support.

- [Loader](https://github.com/warhorst/pacman/blob/master/load_assets/src/lib.rs): preload crate · Auxiliary crate used for asset loading/preload workflows. · `load_assets/src/lib.rs`
- [Build](https://github.com/warhorst/pacman/blob/master/build.rs): build scripts · Build-time and WASM packaging support. · `build.rs`

## Connections

- Main → Game layer: boots · Main initializes the runtime layer.
- Main → Core: uses · Main pulls in shared game rules.
- Game layer → State flow: orchestrates · Runtime systems manage game-state transitions.
- Game layer → Spawn pipeline: spawns map · Game layer turns map data into entities.
- Spawn pipeline → Assets: loads scene · Spawn pipeline starts from scene/content data.
- Spawn pipeline → Map model: builds · Enhances imported scene into maze structures.
- Game layer → Pac-Man: updates · Pac-Man systems run inside the Bevy loop.
- Game layer → Ghosts: updates · Ghost systems run inside the Bevy loop.
- Game layer → Edibles: updates · Collectibles are managed as runtime systems.
- Game layer → Targeting: updates · Ghost AI target logic is executed at runtime.
- Game layer → UI: renders · HUD and overlays reflect current game state.
- Game layer → Audio: plays · Audio responds to gameplay events and state.
- Pac-Man → Actors: reads/writes · Pac-Man systems manipulate core actor state.
- Ghosts → Ghost rules: reads/writes · Ghost systems manipulate ghost rule state.
- Targeting → Ghost rules: drives · Targeting depends on ghost-mode and schedule rules.
- Edibles → Interactions: feeds · Eating collectibles triggers interaction rules.
- Game layer → Progress: updates · Score, lives, level, and speed are updated by systems.
- Game layer → Game state: transitions · Runtime advances the overall game flow.
- Sprites → Assets: loads from · Sprite metadata and art live in the asset tree.
- Loader → Sprites: supports · Loader crate supports preload/registration workflow.
- Build → Loader: invokes · Build scripts support the auxiliary loader workflow.
- Audio → Assets: uses · Music and sound effects are asset-backed.
- UI → Progress: displays · HUD reads score, lives, and level resources.