Pacai

An AI educational project disguised as Pac-Man!

This project was inspired by and originally based off of the Pacman educational project from the Berkeley AI Lab. It has since been completely rewritten.

Some notable changes from the original Berkeley project:

• Upgraded to Python 3.10.
• All code is typed.
• TK/tkinter is now optional.
• The default UI is web/browser based.
• Agents can be isolated from the core game engine to prevent cheating.
• Games can be saved as gifs/webps.
• The graphical engine has been optimized.
• Substantial testing infrastructure has been added.
• Agent speed is now configurable.

Documentation

API documentation for all releases is available at edulinq.github.io/pacai.

Installation / Requirements

This project requires Python >= 3.10.

The project can be installed from PyPi with:

pip3 install edq-pacai

Standard Python requirements are listed in pyproject.toml. The project and Python dependencies can be installed from source with:

pip3 install .

Tk

Optional

If you want to run any Pac-Man code in a system window (instead of a browser window), then you will need to install a library called Tk. There is a version for pretty much all operating system, and you should be able to follow the simple installation instructions.

You may already have Tk installed, and can skip this step! To test, run the following command:

python3 -c 'import tkinter ; tkinter._test()'

If a window pops up, then you should be all set!

You can now run Pac-Man commands with --ui tk to use a Tk window instead of a browser window.

Using Pacai

Once installed, you can play a game of Pac-Man with:

python3 -m pacai.pacman

To see all the available options, use the --help flag:

python3 -m pacai.pacman --help

Boards

You can change the board that you are playing on with the --board option. Pacai comes with several different boards in the pacai/resources/boards directory. For example:

python3 -m pacai.pacman --board classic-original

You can also specify a path to a board file if you want to use a custom board:

python3 -m pacai.pacman --board pacai/resources/boards/classic-small.board

UIs

You can change the user interface (UI) you are using with the --ui option. The provided UIs are:

• null -- Do not show any ui/graphics (best if you want to run fast and just need the result).
• text -- Use stdin/stdout from the terminal.
• tk -- Use Tk/tkinter (must already be installed) to open a window.
• web -- Launch a browser window (default).

For example if you just want to run a game without seeing anything, you can do:

python3 -m pacai.pacman --ui null

This is the quickest way to run a game, and can be very useful when testing out agents.

You can also run using TK (if you already have it installed) with:

python3 -m pacai.pacman --ui tk

Choosing an Agent

In Pac-Man, you can choose which agent you use with the --agent option. The --help flag will list all the agent's available by default. Agents may be specialized and not work on every board.

For example, you can use a random agent with:

python3 -m pacai.pacman --board classic-small --pacman agent-random

You can also use --agent to point to any importable module or file/class.

# Use an importable module name.
python3 -m pacai.pacman --pacman pacai.agents.random.RandomAgent

# Point to an agent class inside of a file.
python3 -m pacai.pacman --pacman pacai/agents/random.py:RandomAgent

Agent Arguments

Many agents will accept arguments that can be used to tweak that agent's behavior. These arguments can be passed using the --agent-arg options (which can be specified as many times as you wish). The argument to --agent-arg is formatted as: <agent index>::<option name>=<option value>.

For example, by default the agent-search-problem agent uses a random search to solve its search problems. It should be able to eventually solve the maze, but with a suboptimal path:

python3 -m pacai.pacman --board maze-tiny --pacman agent-search-problem

We can pass this agent (which has an index of 0) an argument telling it to use a search specialized for this board instead of a random search:

python3 -m pacai.pacman --board maze-tiny --pacman agent-search-problem --agent-arg 0::solver=search-solver-maze-tiny

Note that the agent now finds the optimal path much faster.

For Students

Students who are working on this project as part of a class should note a few things:

1. Never share your solutions or implemented code. In many courses, this would be considered cheating.
2. Make sure that your version of this repo is private. Having a public repo may be indirectly sharing code. You can follow GitHub's directions on creating a repo from a template. Pay close attention to make the repository private.
3. All or most of the code you will implement will be in the pacai/student directory.

Acknowledgements

This project has been built up from the work of many people. Here are just a few that we know about:

• The Berkeley AI Lab for starting this project. Primarily John Denero (denero@cs.berkeley.edu) and Dan Klein (klein@cs.berkeley.edu).
• Barak Michener for providing the original graphics and debugging help.
• Ed Karuna for providing the original graphics and debugging help.
• Jeremy Cowles for implementing an initial tournament infrastructure.
• LiveWires for providing some code from a Pacman implementation (used / modified with permission).
• The LINQS lab from UCSC for updating the code to Python 3 and various other improvements.
• Connor Pryor for various development and design efforts.
• Eriq Augustine and EduLinq for rewriting the project from scratch.
• TAs, grader, and graduates of UCSC's CMPS/CSE 140 class who have helped pave the way for future classes (their identities are immortalized in the git history).

Licensing

See LICENSE.

The majority of this project is licensed under an MIT license. Non-code portions of the code (e.g., images) under the pacai/resources directory are license under a CC BY-SA 4.0 license.

Additionally, solutions (implementations (full or partial) of the code in the pacai/student directory) should never be published or distributed.

This notice should always be retained.

Licensing for the original UC Berkeley project (not applicable as of release v2.0.0) can be found in release v1.0.0.