Pacman Multi-Agent Project

Implementation scaffolding for the UC Berkeley Pacman multi-agent search project. The codebase ships with the full game engine (pacman.py, game.py, display utils), baseline reflex and ghost controllers, and the harness used by the course autograder. It enables the creation of adversarial, stochastic, or evaluation-driven controllers by extending multiAgents.py or by wiring up additional agent modules.

Getting Started

• Python: The project targets Python 3.8+ and only uses the standard library. The graphical display depends on tkinter, which is bundled with most Python installs; when that import fails, the ASCII display (-q) provides a fallback.
• Virtual env (optional):

  python3 -m venv .venv
  source .venv/bin/activate
  pip install --upgrade pip

• Quick sanity check:

  python pacman.py -p ReflexAgent -l testClassic

Repository Layout

• pacman.py, game.py, util.py: Core game engine, data structures, and helper routines mentioned throughout the project description.
• multiAgents.py, pacmanAgents.py, ghostAgents.py: Templates for agents extended with minimax, alpha-beta, expectimax, evaluation functions, custom ghosts, etc.
• layouts/: Maze blueprints referenced with the -l CLI flag (e.g., smallClassic, openClassic).
• graphicsDisplay.py, graphicsUtils.py, textDisplay.py: GUI and text renderers; switch between them with the -q, -g, and -t flags.
• autograder.py, test_cases/, multiagentTestClasses.py: Testing harness mirroring the original UC Berkeley autograder.

Running Pacman

The Pacman program is entirely CLI-driven. Key commands commonly used during development include:

# Human-played game on the default layout
python pacman.py

# Run the ReflexAgent on a different layout
python pacman.py -p ReflexAgent -l smallClassic

# Use a custom agent class from multiAgents.py
python pacman.py -p MinimaxAgent -a depth=4 -l mediumClassic

# Switch to the ASCII display when tkinter is unavailable
python pacman.py -p ExpectimaxAgent -l openClassic -q

Controls rely on WASD/arrow keys, and Ctrl+C ends a run early.

Debugging Tips

• The --frameTime flag (defaults to 0.1) slows the animation for easier inspection.
• Combining -q with --ghosts RandomGhost yields predictable text traces.
• python pacman.py -h lists all available CLI options.

Autograder and Tests

Progress on each assignment question is checked with the autograder. Each question (q1–q6 in the standard spec) corresponds to an agent or evaluation function implemented inside multiAgents.py.

# Run all questions
python autograder.py

# Focus on a single question
python autograder.py -q q3

# Increase verbosity when investigating failures
python autograder.py -q q5 -t

The test_cases/ directory contains the grids and scripts referenced by the grader. Additional layouts or tests can be staged beside the provided cases (ideally in separate subdirectories when maintaining a fork).

Implementing New Agents

1. multiAgents.py (or an auxiliary module) hosts subclasses of Agent that encapsulate the desired strategy.
2. The GameState API documented in pacman.py / game.py provides utilities such as GameState.getLegalActions, GameState.generateSuccessor, GameState.getPacmanPosition, and GameState.getGhostStates.
3. The -p flag selects agent classes exposed from the relevant module (e.g., multiAgents.py or imports re-exported by pacmanAgents.py).
4. The -a flag carries configuration like depth=3 or evalFn=betterEvaluationFunction to tune search depth, evaluation weights, or debugging behavior.

When adding files, keep the headers that attribute the UC Berkeley AI group intact so downstream users know the provenance of the scaffolding.

Troubleshooting

• tkinter import errors: Typically indicate missing Tk bindings; install the appropriate package or run with the ASCII display (-q).
• ModuleNotFoundError for an agent: Usually means the class name does not match the value passed to -p, or the module is not importable from the project root (either beside pacman.py or added to PYTHONPATH).
• Slow autograder: The --no-graphics flag, reduced debugging output, and smaller layouts shorten iteration cycles.

Attribution

Per the project headers, this code is adapted from the UC Berkeley CS188 Pacman AI assignments. If you redistribute work built on top of this repository, keep the original license comments and add your contribution notes alongside them.