# brandonpike/uc-berkeley-pacman architecture

> Architecture diagram of the GitHub repository brandonpike/uc-berkeley-pacman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brandonpike/uc-berkeley-pacman
- Repository: https://github.com/brandonpike/uc-berkeley-pacman

## Overview

The Pacman AI project is centered on building and testing search algorithms within a maze environment where Pacman finds paths (e.g., to dots or corners) using classic search techniques such as Depth First Search (DFS), Breadth First Search (BFS), Uniform Cost Search (UCS), and A*. The project is organized as a command-line game with both graphical and text-based displays, and it also includes components for automated grading and testing.

##### Main Components
- Main Execution and Game Engine:
- pacman.py – the central entry point that initializes the game, processes command-line arguments, and launches the game loop.
- game.py – contains the core logic for game flow and mechanics.
- Agents and Search Algorithms:
- search.py, searchAgents.py, pacmanAgents.py, and ghostAgents.py – these files encapsulate the implementation of search algorithms and handle different types of agents (Pacman, ghosts, etc.).
- keyboardAgents.py – allows interactive control via user input.
- Maze/Layouts:
- layout.py and the layouts directory (including its duplicate under the project’s root) – these contain the maze definitions (.lay files) that configure the game environments.
- Components:
- graphicsDisplay.py and graphicsUtils.py – manage the graphical interface and display.
- textDisplay.py – handles rendering of the game in a text-based format.
- Testing/Grading Infrastructure:
- autograder.py, grading.py, testClasses.py, testParser.py, and searchTestClasses.py – support automated scoring, testing, and validation of search algorithms.
- Support/Utility Components:
- util.py and projectParams.py – provide helper functions and configuration parameters.
- eightpuzzle.py – possibly supports an auxiliary puzzle challenge which may share search techniques.

##### Relationships and Data Flow
- The User invokes the program via the command line (e.g., “python pacman.py –l tinyMaze –p SearchAgent –a fn=astar,heuristic=manhattanHeuristic”). This triggers command-line argument parsing.
- pacman.py then initializes the Game Engine (central game loop in game.py) and loads a maze layout from the layout files.
- The Game Engine coordinates with the Search Algorithms (from search.py and searchAgents.py) to compute the shortest path for the Pacman agent. Different agent files (pacmanAgents.py, ghostAgents.py, keyboardAgents.py) plug into game.py based on user input.
- The Display components (either graphicsDisplay.py/graphicsUtils.py or textDisplay.py) render the current state of the game.
- Simultaneously, testing (e.g., autograder.py, testParser.py) can be invoked to validate the agent behavior and grading for educational purposes.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project distinctly divides responsibilities among modules—input handling, game logic, search algorithms, display, and testing—making it easier to track and modify each part independently.
- Modularity and Extensibility: The use of different agent types (SearchAgent, AStarCornersAgent, etc.) and easily configurable layouts (.lay files) indicates a design that supports plug-and-play extension.
- Command-line Configuration: The system heavily relies on command-line arguments to switch and test different behaviors, which is essential for experimental algorithms.

##### Final Checklist for the Principal Software Engineer
- Clear, descriptive labels for each component.
- On the modular design (separation of concerns and extensibility) in your architectural layout.
- Configuration or initialization flows pertinent to switching between different search strategies and maze layouts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U("User CLI"):::external

    %% Main Execution & Game Engine
    subgraph "Main Execution & Game Engine"
        P("pacman.py"):::core
        G("game.py"):::core
    end

    %% Agents & Search Algorithms
    subgraph "Agents & Search Algorithms"
        S1("search.py"):::core
        SA("searchAgents.py"):::core
        PA("pacmanAgents.py"):::core
        GA("ghostAgents.py"):::core
        KA("keyboardAgents.py"):::core
    end

    %% Maze/Layouts
    subgraph "Maze/Layouts"
        L("layout.py"):::layouts
        LD("layouts"):::layouts
        LR("layouts (root)"):::layouts
    end

    %% Display Components
    subgraph "Display Components"
        GD("graphicsDisplay.py"):::display
        GU("graphicsUtils.py"):::display
        TD("textDisplay.py"):::display
    end

    %% Testing & Grading Infrastructure
    subgraph "Testing & Grading Infrastructure"
        AG("autograder.py"):::testing
        GR("grading.py"):::testing
        TC("testClasses.py"):::testing
        TP("testParser.py"):::testing
        STC("searchTestClasses.py"):::testing
    end

    %% Support/Utility Components
    subgraph "Support/Utility Components"
        UTL("util.py"):::utility
        PP("projectParams.py"):::utility
        EP("eightpuzzle.py"):::utility
    end

    %% Arrows for user flow and interactions
    U -->|"initializes"| P
    P -->|"launches"| G

    %% Game Engine interactions
    G -->|"requests_search"| S1
    G -->|"requests_search"| SA
    G -->|"requests_search"| PA
    G -->|"requests_search"| GA
    G -->|"requests_search"| KA
    G -->|"loads_maze"| L
    G -->|"loads_maze"| LD
    G -->|"loads_maze"| LR
    G -->|"renders_state"| GD
    G -->|"renders_state"| GU
    G -->|"renders_state"| TD

    %% Testing interactions
    AG -->|"tests_agents"| SA
    TP -->|"parses_tests"| AG

    %% Utility Dependencies (dashed arrows)
    G -.->|"depends_on"| UTL
    G -.->|"depends_on"| PP
    G -.->|"depends_on"| EP

    %% Class Definitions for colours
    classDef core fill:#CDE7BE,stroke:#333,stroke-width:2px;
    classDef display fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef testing fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef utility fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef layouts fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#333,stroke-width:2px;

    %% Click Events
    click P "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/pacman.py"
    click G "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/game.py"
    click S1 "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/search.py"
    click SA "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/searchAgents.py"
    click PA "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/pacmanAgents.py"
    click GA "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/ghostAgents.py"
    click KA "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/keyboardAgents.py"
    click L "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/layout.py"
    click LD "https://github.com/brandonpike/uc-berkeley-pacman/tree/master/UC-Berkeley-PacMan/layouts"
    click LR "https://github.com/brandonpike/uc-berkeley-pacman/tree/master/layouts/"
    click GD "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/graphicsDisplay.py"
    click GU "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/graphicsUtils.py"
    click TD "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/textDisplay.py"
    click AG "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/autograder.py"
    click GR "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/grading.py"
    click TC "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/testClasses.py"
    click TP "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/testParser.py"
    click STC "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/searchTestClasses.py"
    click UTL "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/util.py"
    click PP "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/projectParams.py"
    click EP "https://github.com/brandonpike/uc-berkeley-pacman/blob/master/UC-Berkeley-PacMan/eightpuzzle.py"
```
