How abdulrahmanalsayedsallam/pacman-ai works
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