# harryfoster1812/pac-man-clone architecture

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

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

## Overview

##### Project Type and Purpose
- The project seems to be a game (a variant or clone of Pac-Man) with a clear separation between game logic, assets, and configuration.
- It is organized as a lab submission; however, the main purpose is to implement a functional game using Python.

##### Main Components
a. Game Engine / Core Module:
– The main entry point appears to be either game_solution.py or src/game.py.
– This component manages the game loop, overall flow, and integrates the different game modules.

b. Game Logic and Objects:
– Modules in src include: game.py, animate.py (for handling animations), gameImage.py (for rendering images), maze.py (for level layout), and settings.py.
– The “src/objects” directory contains modules for different game characters:
- Pac-Man (src/pacman.py and src/player.py)
- Ghosts (modules like Blinky.py, Clyde.py, Inky.py, Pinky.py, and ghost_state.py in the src/objects/ghosts folder)
- Objects (walls, movable objects in src/objects/map_objects)

c. Level and Environment Management:
– The src/levels directory (with main.txt) suggests that level configuration or maze design is handled separately.

d. Assets Management:
– This module is separate from the code – it’s used by the gameImage.py and maybe animate.py modules to render the assets correctly.

e. Leaderboard Component:
– Presence of src/leaderboard.py and src/leaderboard.json indicates that there is a subsystem managing scores or game progress.

f. Auxiliary and Debug/Configuration Files:
– Additional configuration files (like settings.py) and debugging files (e.g., VSCodeCounter directories) provide insight into development metrics or environment configurations. Though they might not be core to the in-game logic, they still support project maintenance.

##### Relationships and Data Flow
- The Game Engine (main control) interacts with the following:
– It calls the game loop and periodically updates game state.
– It uses the animation module to ensure that game objects (Pac-Man, ghosts) are displayed with dynamic behavior.
– It loads resources (assets/images/sprites) via a resource manager or gameImage module.
– It loads the maze/level structure (via maze.py and levels files).
– It integrates with the leaderboard system for score saving and retrieval.

- The object hierarchy:
– The player (Pac-Man) and the enemy objects (ghosts) are instantiated from their respective modules.
– Ghost behavior, including movement and states, is managed by modules within “src/objects/ghosts” and potentially interacts with map objects for collision detection.

- Data flows:
– Input (keyboard controls) flows into the game engine.
– The engine passes state updates to both the display/animation components and object logic modules.
– Assets are loaded from the assets directory and continuously referenced by the game image/animation subsystems.

##### Architectural Patterns and Design Principles
- You might consider that this project loosely follows an MVC-like organization:
– Model: Classes and modules representing game state (Pac-Man, ghosts, maze, leaderboard data).
– View: The asset-related modules (gameImage.py, animate.py) that wholly manage rendering.
– Controller: The game engine (game.py and game_solution.py) that coordinates all inputs and updates.
- The design also uses separation of concerns – with separate directories for assets, levels, and object definitions.

- Every component is clearly labeled and annotated with its corresponding file/directory names.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Game Engine
    subgraph "Core Game Engine"
        GE1["game_solution.py"]:::core
        GE2["src/game.py"]:::core
    end

    %% Game Logic & Settings
    subgraph "Game Logic & Settings"
        GS1["src/maze.py"]:::logic
        GS2["src/settings.py"]:::logic
    end

    %% Level Management
    subgraph "Level Management"
        LM["src/levels/main.txt"]:::logic
    end

    %% Character Modules
    subgraph "Character Modules"
        CP1["src/pacman.py"]:::char
        CP2["src/player.py"]:::char
        Ghosts["Ghosts Module: src/objects/ghosts"]:::char
        MapObjs["Map Objects: src/objects/map_objects"]:::char
    end

    %% Rendering / Animation
    subgraph "Rendering/Animation"
        RA1["src/animate.py"]:::anim
        RA2["src/gameImage.py"]:::anim
    end

    %% Assets Management
    subgraph "Assets"
        Assets["assets"]:::asset
    end

    %% Leaderboard Component
    subgraph "Leaderboard"
        LB1["src/leaderboard.py"]:::leader
        LB2["src/leaderboard.json"]:::leader
    end

    %% Connections
    GE2 -->|"loads"| GS1
    GE2 -->|"reads"| GS2
    GE2 -->|"loads_level"| LM
    GE2 -->|"controls_player"| CP1
    GE2 -->|"controls_player"| CP2
    GE2 -->|"instantiates_ghosts"| Ghosts
    GE2 -->|"handles_collisions"| MapObjs
    GE2 -->|"updates_animation"| RA1
    Assets -->|"supplies_sprites"| RA2
    GE2 -->|"updates_scores"| LB1

    %% Styles
    classDef core fill:#B3E5FC,stroke:#01579B,stroke-width:2px,color:#000;
    classDef logic fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px,color:#000;
    classDef char fill:#FFECB3,stroke:#F57F17,stroke-width:2px,color:#000;
    classDef anim fill:#D1C4E9,stroke:#512DA8,stroke-width:2px,color:#000;
    classDef asset fill:#FFE0B2,stroke:#E64A19,stroke-width:2px,color:#000;
    classDef leader fill:#F8BBD0,stroke:#C2185B,stroke-width:2px,color:#000;

    %% Click Events
    click GE1 "https://github.com/harryfoster1812/pac-man-clone/blob/main/game_solution.py"
    click GE2 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/game.py"
    click GS1 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/maze.py"
    click GS2 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/settings.py"
    click LM "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/levels/main.txt"
    click CP1 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/pacman.py"
    click CP2 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/player.py"
    click Ghosts "https://github.com/harryfoster1812/pac-man-clone/tree/main/src/objects/ghosts"
    click MapObjs "https://github.com/harryfoster1812/pac-man-clone/tree/main/src/objects/map_objects"
    click RA1 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/animate.py"
    click RA2 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/gameImage.py"
    click Assets "https://github.com/harryfoster1812/pac-man-clone/tree/main/assets"
    click LB1 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/leaderboard.py"
    click LB2 "https://github.com/harryfoster1812/pac-man-clone/blob/main/src/leaderboard.json"
```
