# realabidhasnine/pacman_evolution architecture

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

- Interactive diagram: https://gitdiagram.com/realabidhasnine/pacman_evolution
- Repository: https://github.com/realabidhasnine/pacman_evolution

## Overview

Pac-Man Evolution is a desktop maze game built with Python’s turtle graphics. The player uses keyboard controls to navigate a wrapping maze, collect pellets and power pellets, and avoid four ghosts; the game tracks score and lives and presents win/loss restart screens. The main loop coordinates input, movement, collection, collisions, and redraws. Maze construction, actor movement and ghost decisions, and rendering are distinct supporting layers. Ghost behavior is documented more fully than the sampled actor excerpt, so those AI details are represented as documented capabilities.

Main entry points: [`main.py`](https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py) (Game setup), [`mazes.py`](https://github.com/realabidhasnine/pacman_evolution/blob/main/mazes.py) (Maze model), [`actors.py`](https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py) (Ghost movement), [`renderer.py`](https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py) (Pellet renderers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Game flow"]
  node_game_loop["Game loop<br/>[main.py]"]
  node_controls["Keyboard controls<br/>[main.py]"]
  node_game_setup["Game setup<br/>[main.py]"]
  node_game_outcomes["Win and restart<br/>[main.py]"]
end

subgraph group_world["Maze world"]
  node_maze_data["Maze layout<br/>[mazes.py]"]
  node_maze["Maze model<br/>[mazes.py]"]
  node_settings["Game settings<br/>[constants.py]"]
end

subgraph group_actors["Actors and AI"]
  node_player["Player<br/>[actors.py]"]
  node_ghosts["Ghost movement<br/>[actors.py]"]
  node_ghost_ai["Ghost strategies<br/>[actors.py]"]
end

subgraph group_display["Rendering"]
  node_wall_render["Wall renderer<br/>[renderer.py]"]
  node_pellet_render["Pellet renderers<br/>[renderer.py]"]
  node_ui["Score and lives UI<br/>[renderer.py]"]
  node_screen["Turtle screen<br/>[main.py]"]
end

node_user(("Player"))

node_game_setup -->|"selects level"| node_maze_data
node_game_setup -->|"builds"| node_maze
node_maze -->|"reads layout"| node_maze_data
node_maze -->|"uses dimensions"| node_settings
node_game_setup -->|"creates"| node_player
node_game_setup -->|"creates"| node_ghosts
node_game_setup -->|"creates"| node_wall_render
node_game_setup -->|"creates"| node_pellet_render
node_game_setup -->|"creates"| node_ui
node_game_setup -->|"initializes"| node_screen
node_user -->|"presses keys"| node_controls
node_controls -->|"queues direction"| node_player
node_game_loop -->|"moves"| node_player
node_game_loop -->|"moves and checks"| node_ghosts
node_ghosts -->|"chooses targets"| node_ghost_ai
node_ghosts -->|"checks paths"| node_maze
node_player -->|"checks collisions"| node_maze
node_wall_render -->|"draws walls"| node_maze
node_pellet_render -->|"draws pellets"| node_maze
node_game_loop -->|"collects stamps"| node_pellet_render
node_game_loop -->|"updates score and speed"| node_player
node_game_loop -->|"writes score and lives"| node_ui
node_game_loop -->|"shows win or loss"| node_game_outcomes
node_game_outcomes -->|"restarts game"| node_game_setup
node_game_loop -->|"schedules redraw"| node_screen
node_game_setup -->|"uses dimensions"| node_settings
node_ghost_ai -.->|"defines four styles"| node_ghosts

click node_player "https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py"
click node_ghosts "https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py"
click node_ghost_ai "https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py"
click node_maze_data "https://github.com/realabidhasnine/pacman_evolution/blob/main/mazes.py"
click node_maze "https://github.com/realabidhasnine/pacman_evolution/blob/main/mazes.py"
click node_game_loop "https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py"
click node_controls "https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py"
click node_game_setup "https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py"
click node_game_outcomes "https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py"
click node_settings "https://github.com/realabidhasnine/pacman_evolution/blob/main/constants.py"
click node_wall_render "https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py"
click node_pellet_render "https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py"
click node_ui "https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py"
click node_screen "https://github.com/realabidhasnine/pacman_evolution/blob/main/main.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_game_loop,node_controls,node_game_setup,node_game_outcomes toneBlue
class node_maze_data,node_maze,node_settings toneAmber
class node_player,node_ghosts,node_ghost_ai toneMint
class node_wall_render,node_pellet_render,node_ui,node_screen toneRose
class node_user toneIndigo
```

## Components

### Game flow

- [Game loop](https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py): `main.py`
- [Keyboard controls](https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py): `main.py`
- [Game setup](https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py): `main.py`
- [Win and restart](https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py): `main.py`

### Maze world

- [Maze layout](https://github.com/realabidhasnine/pacman_evolution/blob/main/mazes.py): `mazes.py`
- [Maze model](https://github.com/realabidhasnine/pacman_evolution/blob/main/mazes.py): `mazes.py`
- [Game settings](https://github.com/realabidhasnine/pacman_evolution/blob/main/constants.py): `constants.py`

### Actors and AI

- [Player](https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py): `actors.py`
- [Ghost movement](https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py): `actors.py`
- [Ghost strategies](https://github.com/realabidhasnine/pacman_evolution/blob/main/actors.py): `actors.py`

### Rendering

- [Wall renderer](https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py): `renderer.py`
- [Pellet renderers](https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py): `renderer.py`
- [Score and lives UI](https://github.com/realabidhasnine/pacman_evolution/blob/main/renderer.py): `renderer.py`
- [Turtle screen](https://github.com/realabidhasnine/pacman_evolution/blob/main/main.py): `main.py`

### Other components

- **Player**

## Connections

- Game setup → Maze layout: selects level (evidence: `main.py`)
- Game setup → Maze model: builds (evidence: `main.py`)
- Maze model → Maze layout: reads layout (evidence: `mazes.py`)
- Maze model → Game settings: uses dimensions (evidence: `mazes.py`)
- Game setup → Player: creates (evidence: `main.py`)
- Game setup → Ghost movement: creates (evidence: `main.py`)
- Game setup → Wall renderer: creates (evidence: `main.py`)
- Game setup → Pellet renderers: creates (evidence: `main.py`)
- Game setup → Score and lives UI: creates (evidence: `main.py`)
- Game setup → Turtle screen: initializes (evidence: `main.py`)
- Player → Keyboard controls: presses keys (evidence: `README.md`)
- Keyboard controls → Player: queues direction (evidence: `main.py`)
- Game loop → Player: moves (evidence: `main.py`)
- Game loop → Ghost movement: moves and checks (evidence: `main.py`)
- Ghost movement → Ghost strategies: chooses targets (evidence: `actors.py`)
- Ghost movement → Maze model: checks paths (evidence: `actors.py`)
- Player → Maze model: checks collisions (evidence: `README.md`)
- Wall renderer → Maze model: draws walls (evidence: `renderer.py`)
- Pellet renderers → Maze model: draws pellets (evidence: `renderer.py`)
- Game loop → Pellet renderers: collects stamps (evidence: `main.py`)
- Game loop → Player: updates score and speed (evidence: `main.py`)
- Game loop → Score and lives UI: writes score and lives (evidence: `main.py`)
- Game loop → Win and restart: shows win or loss (evidence: `main.py`)
- Win and restart → Game setup: restarts game (evidence: `main.py`)
- Game loop → Turtle screen: schedules redraw (evidence: `main.py`)
- Game setup → Game settings: uses dimensions (evidence: `main.py`)
- Ghost strategies → Ghost movement: defines four styles (evidence: `README.md`)
