# abdulrahmanalsayedsallam/pacman-ai architecture

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

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

## Overview

##### Project type and purpose
- This is an educational AI game framework built on Berkeley’s Pacman project, extended with an approximate Q-learning agent.
- It functions as both a playable game (interactive frontend + game engine) and an experiment platform (training scripts, weight storage, automated play).

##### File structure
Top‐level
- README.md — high-level overview of RL approach, usage, data, maps, rewards.
- pacman/ — original framework and all extensions.
pacman/src/
- pacman.py, game.py, util.py, layout.py — core game engine, state definitions, helpers, map loader.
- graphicsDisplay.py, graphicsUtils.py, textDisplay.py — rendering layers (GUI and ASCII).
- keyboardAgents.py, ghostAgents.py — built-in control agents.
- multiAgents.py — student’s RL agent entry point.
- autoTrain.py, autoPlay.py — orchestration scripts for batch training and evaluation.
- training/ — historical weights, alternate agent code for reproducibility.
- layouts/ — .lay files defining game maps.
- images/, commands.txt, PDFs — documentation and visuals.

##### Key insights from README
- Architecture consists of (a) the Pacman world simulator, (b) the RL agent module, and (c) auxiliary orchestration (training & playback).
- Interactions: the game engine feeds GameState → agent chooses Action → engine applies action & returns next state + reward → agent updates weights.
- Data artifacts: layout files (.lay), weight files (weights.csv & oldWeights.txt), WinRatio.txt.
- Usage scenarios: manual play, automated play, training.

a. Main components
1. Game Engine Layer
– Modules: pacman.py (orchestrator), game.py (world logic), layout.py (map parsing), util.py
2. Agent Layer
– multiAgents.py (approximate Q-learning agent), ghostAgents.py, keyboardAgents.py (others)
3. Rendering Layer
– graphicsDisplay.py + graphicsUtils.py (GUI), textDisplay.py (ASCII)
4. Orchestration Layer
– autoTrain.py (batch training driver), autoPlay.py (evaluation driver)
5. Data/Storage
– layouts/*.lay, weights.csv, training/weights.csv, WinRatio.txt, oldWeights.txt
6. External/Documentation
– commands.txt, images/, PDFs
b. Relationships & data flows
- Training flow: autoTrain.py → loads training version of multiAgents.py + starting weights.csv → loops:
Game Engine ↔ Agent (state, action, reward) → update weights → write weights.csv → record WinRatio.txt
- Playback flow: autoPlay.py → loads trained weights.csv → Game Engine ↔ Agent (no weight updates) → output performance
- Interactive flow: pacman.py + keyboardAgents.py → Game Engine → Rendering Layer → user inputs → back to engine
c. Architectural patterns & principles
- Modular separation: Game Logic vs. Agent Logic vs. Rendering vs. Orchestration
- Data-driven: layouts define environments; CSV weights define learned policy; scripts parameterize runs
- Plug-and-play agents: multiAgents.py can be swapped with ghostAgents or keyboardAgents
d. Key technologies & libraries
- Python 3.x as runtime
- Berkeley’s Pacman framework for environment
- CSV for weight persistence
- Simple file-based orchestration (no external services)

##### Essential details to capture
- Separation of concerns: environment vs. decision making vs. display
- The two distinct execution modes: interactive vs. automated training/play
- Data artifacts (layouts, weight files) and where they live
- The iterative Q-learning loop inside multiAgents.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine Layer
    subgraph "Game Engine Layer"
        direction TB
        Pcmn["pacman.py"]:::engine
        Gm["game.py"]:::engine
        Lyt["layout.py"]:::engine
        Utl["util.py"]:::engine
    end

    %% Agent Layer
    subgraph "Agent Layer"
        direction TB
        MAg["multiAgents.py"]:::agent
        GAg["ghostAgents.py"]:::agent
        KAg["keyboardAgents.py"]:::agent
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        direction TB
        GDisp["graphicsDisplay.py"]:::render
        GUtil["graphicsUtils.py"]:::render
        TDisp["textDisplay.py"]:::render
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Train["autoTrain.py"]:::orchestration
        Play["autoPlay.py"]:::orchestration
    end

    %% Data/Storage
    subgraph "Data/Storage"
        direction TB
        Layouts[".lay files"]:::data
        Weights["weights.csv"]:::data
        OldW["oldWeights.txt"]:::data
        Win["WinRatio.txt"]:::data
        TWeights["training/weights.csv"]:::data
        TMulti["training/multiAgents.py"]:::data
    end

    %% External Documentation
    subgraph "External/Documentation"
        direction TB
        Readme["README.md"]:::doc
        Commands["commands.txt"]:::doc
        Images["images/"]:::doc
        PDF["Pacman AI code explaination.pdf"]:::doc
    end

    %% Training Flow
    Train -->|loads agent & weights| MAg
    Train -->|reads| TWeights
    MAg -->|selects Action| Pcmn
    Pcmn -->|GameState,Reward| MAg
    MAg -->|update weights| TWeights
    TWeights -->|record| Win

    %% Playback Flow
    Play -->|loads agent & trained weights| MAg
    MAg -->|selects Action| Pcmn
    Pcmn -->|GameState,Reward| MAg

    %% Interactive Flow
    Pcmn -->|invokes| KAg
    Pcmn -->|renders| GDisp
    GDisp -->|draws| GUtil
    Pcmn -->|renders ASCII| TDisp
    KAg -->|user input| Pcmn

    %% Agent Plug-and-Play
    GAg -.->|alternative agent| Pcmn

    %% Data Dependencies
    Pcmn -->|loads maps| Layouts
    MAg -->|initial weights| Weights
    MAg -->|fallback weights| OldW
    MAg -->|reproducible code| TMulti

    %% Click Events
    click Pcmn "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/pacman.py"
    click Gm "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/game.py"
    click Lyt "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/layout.py"
    click Utl "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/util.py"
    click MAg "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/multiAgents.py"
    click GAg "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/ghostAgents.py"
    click KAg "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/keyboardAgents.py"
    click GDisp "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/graphicsDisplay.py"
    click GUtil "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/graphicsUtils.py"
    click Train "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/autoTrain.py"
    click Play "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/autoPlay.py"
    click Layouts "https://github.com/abdulrahmanalsayedsallam/pacman-ai/tree/main/pacman/src/layouts/"
    click Weights "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/weights.csv"
    click OldW "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/oldWeights.txt"
    click Win "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/WinRatio.txt"
    click TWeights "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/training/weights.csv"
    click TMulti "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/src/training/multiAgents.py"
    click Readme "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/README.md"
    click Commands "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/commands.txt"
    click Images "https://github.com/abdulrahmanalsayedsallam/pacman-ai/tree/main/pacman/images/"
    click PDF "https://github.com/abdulrahmanalsayedsallam/pacman-ai/blob/main/pacman/Pacman AI code explaination.pdf"

    %% Styles
    classDef engine fill:#BBDEFB,stroke:#1E88E5;
    classDef agent fill:#C8E6C9,stroke:#43A047;
    classDef render fill:#FFE0B2,stroke:#FB8C00;
    classDef orchestration fill:#E1BEE7,stroke:#8E24AA;
    classDef data fill:#E0E0E0,stroke:#757575,shape:cylinder;
    classDef doc fill:#F5F5F5,stroke:#9E9E9E,shape:rect;
```
