# hamzalaaz/pac-man architecture

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

- Interactive diagram: https://gitdiagram.com/hamzalaaz/pac-man
- Repository: https://github.com/hamzalaaz/pac-man

## Overview

Pac-Man is a Python arcade game whose main workflow runs from configuration and menu selection through generated levels, player/ghost gameplay, and a win or game-over screen. The game loop in `src/start.py` coordinates screen transitions and level progression; gameplay includes maze generation, collectible items, entity movement, ghost AI, scoring, and cheat controls. UI screens also provide instructions, pause, and highscore views. The README documents some behavior whose implementation excerpts were not shown, so those relationships are included only where documented or indexed.

Main entry points: [`src/start.py`](https://github.com/hamzalaaz/pac-man/blob/main/src/start.py) (Game loop), [`src/screens/game_screen.py`](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/game_screen.py) (Level gameplay), [`src/screens/text.py`](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/text.py) (Text drawer), [`src/screens/end_screen.py`](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/end_screen.py) (End screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game runtime"]
  node_entry["Game loop<br/>[start.py]"]
  node_mlx["MLX window<br/>[mlx_class.py]"]
end

subgraph group_gameplay["Gameplay"]
  node_game["Level gameplay<br/>[game_screen.py]"]
  node_maze["Maze generator"]
  node_pacman["Pac-Man entity<br/>[entities.py]"]
  node_collectibles["Maze collectibles<br/>[entities.py]"]
  node_ghosts["Ghost entities<br/>[entities.py]"]
  node_ai["Ghost AI<br/>[ghost_ai.py]"]
end

subgraph group_ui["Screens and UI"]
  node_menu["Main menu<br/>[main_menu.py]"]
  node_pause["Pause screen<br/>[pause_screen.py]"]
  node_instructions["Instructions screen"]
  node_end["End screen<br/>[end_screen.py]"]
  node_scores_view["Highscores screen"]
  node_text["Text drawer<br/>[text.py]"]
end

subgraph group_persistence["Configuration and scores"]
  node_config["Config loader<br/>[config.py]"]
  node_scores[("Highscore table<br/>[highscores.py]")]
end

node_player(("Player"))

node_player -->|"starts game"| node_entry
node_entry -->|"loads settings"| node_config
node_entry -->|"loads table"| node_scores
node_entry -->|"creates window"| node_mlx
node_entry -->|"dispatches input"| node_menu
node_entry -->|"creates levels"| node_game
node_entry -->|"dispatches input"| node_pause
node_entry -->|"dispatches input"| node_end
node_entry -->|"dispatches input"| node_scores_view
node_entry -->|"dispatches input"| node_instructions
node_game -->|"reads settings"| node_config
node_game -->|"generates maze"| node_maze
node_game -->|"creates entity"| node_pacman
node_game -.->|"creates items"| node_collectibles
node_game -->|"creates entities"| node_ghosts
node_game -->|"assigns behavior"| node_ai
node_ghosts -->|"requests movement"| node_ai
node_pacman -->|"eats items"| node_collectibles
node_end -->|"adds score"| node_scores
node_scores_view -->|"reads entries"| node_scores
node_entry -->|"creates drawer"| node_text
node_menu -->|"draws window"| node_mlx
node_pause -->|"renders text"| node_text
node_instructions -->|"renders text"| node_text
node_end -->|"renders text"| node_text
node_scores_view -->|"renders text"| node_text

click node_entry "https://github.com/hamzalaaz/pac-man/blob/main/src/start.py"
click node_config "https://github.com/hamzalaaz/pac-man/blob/main/src/config.py"
click node_mlx "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/mlx_class.py"
click node_game "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/game_screen.py"
click node_pacman "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/classes/entities.py"
click node_collectibles "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/classes/entities.py"
click node_ghosts "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/classes/entities.py"
click node_ai "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/ghost_ai.py"
click node_menu "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/main_menu.py"
click node_pause "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/pause_screen.py"
click node_instructions "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/instructions_screen.py"
click node_end "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/end_screen.py"
click node_scores_view "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/highscores_screen.py"
click node_text "https://github.com/hamzalaaz/pac-man/blob/main/src/screens/text.py"
click node_scores "https://github.com/hamzalaaz/pac-man/blob/main/src/highscores.py"

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_entry,node_mlx toneBlue
class node_game,node_maze,node_pacman,node_collectibles,node_ghosts,node_ai toneAmber
class node_menu,node_pause,node_instructions,node_end,node_scores_view,node_text toneMint
class node_config,node_scores toneRose
class node_player toneIndigo
```

## Components

### Game runtime

- [Game loop](https://github.com/hamzalaaz/pac-man/blob/main/src/start.py): `src/start.py`
- [MLX window](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/mlx_class.py): `src/screens/mlx_class.py`

### Gameplay

- [Level gameplay](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/game_screen.py): `src/screens/game_screen.py`
- **Maze generator**
- [Pac-Man entity](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/classes/entities.py): `src/screens/classes/entities.py`
- [Maze collectibles](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/classes/entities.py): `src/screens/classes/entities.py`
- [Ghost entities](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/classes/entities.py): `src/screens/classes/entities.py`
- [Ghost AI](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/ghost_ai.py): `src/screens/ghost_ai.py`

### Screens and UI

- [Main menu](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/main_menu.py): `src/screens/main_menu.py`
- [Pause screen](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/pause_screen.py): `src/screens/pause_screen.py`
- [Instructions screen](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/instructions_screen.py): `src/screens/instructions_screen.py`
- [End screen](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/end_screen.py): `src/screens/end_screen.py`
- [Highscores screen](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/highscores_screen.py): `src/screens/highscores_screen.py`
- [Text drawer](https://github.com/hamzalaaz/pac-man/blob/main/src/screens/text.py): `src/screens/text.py`

### Configuration and scores

- [Config loader](https://github.com/hamzalaaz/pac-man/blob/main/src/config.py): `src/config.py`
- [Highscore table](https://github.com/hamzalaaz/pac-man/blob/main/src/highscores.py): `src/highscores.py`

### Other components

- **Player**

## Connections

- Player → Game loop: starts game (evidence: `README.md`)
- Game loop → Config loader: loads settings (evidence: `src/start.py`)
- Game loop → Highscore table: loads table (evidence: `src/start.py`)
- Game loop → MLX window: creates window (evidence: `src/start.py`)
- Game loop → Main menu: dispatches input (evidence: `src/start.py`)
- Game loop → Level gameplay: creates levels (evidence: `src/start.py`)
- Game loop → Pause screen: dispatches input (evidence: `src/start.py`)
- Game loop → End screen: dispatches input (evidence: `src/start.py`)
- Game loop → Highscores screen: dispatches input (evidence: `src/start.py`)
- Game loop → Instructions screen: dispatches input (evidence: `src/start.py`)
- Level gameplay → Config loader: reads settings (evidence: `src/screens/game_screen.py`)
- Level gameplay → Maze generator: generates maze (evidence: `README.md`)
- Level gameplay → Pac-Man entity: creates entity (evidence: `src/screens/game_screen.py`)
- Level gameplay → Maze collectibles: creates items (evidence: `src/screens/game_screen.py`)
- Level gameplay → Ghost entities: creates entities (evidence: `src/screens/game_screen.py`)
- Level gameplay → Ghost AI: assigns behavior (evidence: `src/screens/game_screen.py`)
- Ghost entities → Ghost AI: requests movement (evidence: `src/screens/classes/entities.py`)
- Pac-Man entity → Maze collectibles: eats items (evidence: `src/screens/classes/entities.py`)
- End screen → Highscore table: adds score (evidence: `src/start.py`)
- Highscores screen → Highscore table: reads entries (evidence: `src/screens/highscores_screen.py`)
- Game loop → Text drawer: creates drawer (evidence: `src/start.py`)
- Main menu → MLX window: draws window (evidence: `src/screens/main_menu.py`)
- Pause screen → Text drawer: renders text (evidence: `src/screens/pause_screen.py`)
- Instructions screen → Text drawer: renders text (evidence: `src/screens/instructions_screen.py`)
- End screen → Text drawer: renders text (evidence: `src/screens/end_screen.py`)
- Highscores screen → Text drawer: renders text (evidence: `src/screens/highscores_screen.py`)
