# Pacai
An AI educational project disguised as [Pac-Man](https://en.wikipedia.org/wiki/Pac-Man)!
This project was inspired by and originally based off of the Pacman educational project from the
[Berkeley AI Lab](https://www-inst.eecs.berkeley.edu/project_overview.html).
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](https://edulinq.github.io/pacai).
## Installation / Requirements
This project requires [Python](https://www.python.org/) >= 3.10.
The project can be installed from PyPi with:
```sh
pip3 install edq-pacai
```
Standard Python requirements are listed in `pyproject.toml`.
The project and Python dependencies can be installed from source with:
```sh
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](https://tkdocs.com/tutorial/install.html).
There is a version for pretty much all operating system,
and you should be able to follow the simple [installation instructions](https://tkdocs.com/tutorial/install.html).
You may already have Tk installed,
and can skip this step!
To test, run the following command:
```sh
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:
```sh
python3 -m pacai.pacman
```
To see all the available options, use the `--help` flag:
```sh
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](pacai/resources/boards).
For example:
```sh
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:
```sh
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:
```sh
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:
```sh
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:
```sh
python3 -m pacai.pacman --board classic-small --pacman agent-random
```
You can also use `--agent` to point to any importable module or file/class.
```sh
# 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:
```sh
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:
```sh
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](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-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](pacai/student).
## 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](http://ai.berkeley.edu/) for starting
[this project](https://www-inst.eecs.berkeley.edu/project_overview.html).
Primarily John Denero ([denero@cs.berkeley.edu](mailto:denero@cs.berkeley.edu))
and Dan Klein ([klein@cs.berkeley.edu](mailto: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](LICENSE).
The majority of this project is licensed under an [MIT license](LICENSE-code).
Non-code portions of the code (e.g., images) under the [pacai/resources directory](/pacai/resources)
are license under a [CC BY-SA 4.0 license](LICENSE-noncode).
Additionally, solutions (implementations (full or partial) of the code in the [pacai/student directory](/pacai/student))
should never be published or distributed.
[This notice](LICENSE) 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`](https://github.com/edulinq/pacai/blob/v1.0.0/LICENSE.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "edq-pacai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "AI, Artificial Intelligence, Education, Teaching",
"author": null,
"author_email": "Eriq Augustine <eriq@edulinq.org>, Connor Pryor <cfpryor@ucsc.edu>, LINQS <linqs.edu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/98/25d0773a3cedf1abcf6eccc507a9dfdcd7b9baab7da0e4d6ce4fe9a1ba15/edq_pacai-2.0.1.tar.gz",
"platform": null,
"description": "# Pacai\n\nAn AI educational project disguised as [Pac-Man](https://en.wikipedia.org/wiki/Pac-Man)!\n\nThis project was inspired by and originally based off of the Pacman educational project from the\n[Berkeley AI Lab](https://www-inst.eecs.berkeley.edu/project_overview.html).\nIt has since been completely rewritten.\n\nSome notable changes from the original Berkeley project:\n - Upgraded to Python 3.10.\n - All code is typed.\n - TK/tkinter is now optional.\n - The default UI is web/browser based.\n - Agents can be isolated from the core game engine to prevent cheating.\n - Games can be saved as gifs/webps.\n - The graphical engine has been optimized.\n - Substantial testing infrastructure has been added.\n - Agent speed is now configurable.\n\n## Documentation\n\nAPI documentation for all releases is available at [edulinq.github.io/pacai](https://edulinq.github.io/pacai).\n\n## Installation / Requirements\n\nThis project requires [Python](https://www.python.org/) >= 3.10.\n\nThe project can be installed from PyPi with:\n```sh\npip3 install edq-pacai\n```\n\nStandard Python requirements are listed in `pyproject.toml`.\nThe project and Python dependencies can be installed from source with:\n```sh\npip3 install .\n```\n\n### Tk\n\n*Optional*\n\nIf you want to run any Pac-Man code in a system window (instead of a browser window),\nthen you will need to install a library called [Tk](https://tkdocs.com/tutorial/install.html).\nThere is a version for pretty much all operating system,\nand you should be able to follow the simple [installation instructions](https://tkdocs.com/tutorial/install.html).\n\nYou may already have Tk installed,\nand can skip this step!\nTo test, run the following command:\n```sh\npython3 -c 'import tkinter ; tkinter._test()'\n```\n\nIf a window pops up, then you should be all set!\n\nYou can now run Pac-Man commands with `--ui tk` to use a Tk window instead of a browser window.\n\n## Using Pacai\n\nOnce installed, you can play a game of Pac-Man with:\n```sh\npython3 -m pacai.pacman\n```\n\nTo see all the available options, use the `--help` flag:\n```sh\npython3 -m pacai.pacman --help\n```\n\n### Boards\n\nYou can change the board that you are playing on with the `--board` option.\nPacai comes with several different boards in the [pacai/resources/boards directory](pacai/resources/boards).\nFor example:\n```sh\npython3 -m pacai.pacman --board classic-original\n```\n\nYou can also specify a path to a board file if you want to use a custom board:\n```sh\npython3 -m pacai.pacman --board pacai/resources/boards/classic-small.board\n```\n\n### UIs\n\nYou can change the user interface (UI) you are using with the `--ui` option.\nThe provided UIs are:\n - `null` -- Do not show any ui/graphics (best if you want to run fast and just need the result).\n - `text` -- Use stdin/stdout from the terminal.\n - `tk` -- Use Tk/tkinter (must already be installed) to open a window.\n - `web` -- Launch a browser window (default).\n\nFor example if you just want to run a game without seeing anything,\nyou can do:\n```sh\npython3 -m pacai.pacman --ui null\n```\n\nThis is the quickest way to run a game,\nand can be very useful when testing out agents.\n\nYou can also run using TK (if you already have it installed) with:\n```sh\npython3 -m pacai.pacman --ui tk\n```\n\n### Choosing an Agent\n\nIn Pac-Man, you can choose which agent you use with the `--agent` option.\nThe `--help` flag will list all the agent's available by default.\nAgents may be specialized and not work on every board.\n\nFor example, you can use a random agent with:\n```sh\npython3 -m pacai.pacman --board classic-small --pacman agent-random\n```\n\nYou can also use `--agent` to point to any importable module or file/class.\n```sh\n# Use an importable module name.\npython3 -m pacai.pacman --pacman pacai.agents.random.RandomAgent\n\n# Point to an agent class inside of a file.\npython3 -m pacai.pacman --pacman pacai/agents/random.py:RandomAgent\n```\n\n#### Agent Arguments\n\nMany agents will accept arguments that can be used to tweak that agent's behavior.\nThese arguments can be passed using the `--agent-arg` options\n(which can be specified as many times as you wish).\nThe argument to `--agent-arg` is formatted as: `<agent index>::<option name>=<option value>`.\n\nFor example, by default the `agent-search-problem` agent uses a random search to solve its search problems.\nIt should be able to eventually solve the maze, but with a suboptimal path:\n```sh\npython3 -m pacai.pacman --board maze-tiny --pacman agent-search-problem\n```\n\nWe can pass this agent (which has an index of 0)\nan argument telling it to use a search specialized for this board instead of a random search:\n```sh\npython3 -m pacai.pacman --board maze-tiny --pacman agent-search-problem --agent-arg 0::solver=search-solver-maze-tiny\n```\n\nNote that the agent now finds the optimal path much faster.\n\n## For Students\n\nStudents who are working on this project as part of a class should note a few things:\n 1. Never share your solutions or implemented code.\n In many courses, this would be considered cheating.\n 2. Make sure that your version of this repo is private.\n Having a public repo may be indirectly sharing code.\n You can follow GitHub's directions on\n [creating a repo from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).\n Pay close attention to make the repository private.\n 3. All or most of the code you will implement will be in the [pacai/student directory](pacai/student).\n\n## Acknowledgements\n\nThis project has been built up from the work of many people.\nHere are just a few that we know about:\n - The [Berkeley AI Lab](http://ai.berkeley.edu/) for starting\n [this project](https://www-inst.eecs.berkeley.edu/project_overview.html).\n Primarily John Denero ([denero@cs.berkeley.edu](mailto:denero@cs.berkeley.edu))\n and Dan Klein ([klein@cs.berkeley.edu](mailto:klein@cs.berkeley.edu)).\n - Barak Michener for providing the original graphics and debugging help.\n - Ed Karuna for providing the original graphics and debugging help.\n - Jeremy Cowles for implementing an initial tournament infrastructure.\n - LiveWires for providing some code from a Pacman implementation (used / modified with permission).\n - The LINQS lab from UCSC for updating the code to Python 3 and various other improvements.\n - Connor Pryor for various development and design efforts.\n - Eriq Augustine and EduLinq for rewriting the project from scratch.\n - TAs, grader, and graduates of UCSC's CMPS/CSE 140 class who have helped pave the way for future classes\n (their identities are immortalized in the git history).\n\n## Licensing\n\nSee [LICENSE](LICENSE).\n\nThe majority of this project is licensed under an [MIT license](LICENSE-code).\nNon-code portions of the code (e.g., images) under the [pacai/resources directory](/pacai/resources)\nare license under a [CC BY-SA 4.0 license](LICENSE-noncode).\n\nAdditionally, solutions (implementations (full or partial) of the code in the [pacai/student directory](/pacai/student))\nshould never be published or distributed.\n\n[This notice](LICENSE) should always be retained.\n\nLicensing for the original UC Berkeley project\n(not applicable as of release `v2.0.0`)\ncan be found [in release `v1.0.0`](https://github.com/edulinq/pacai/blob/v1.0.0/LICENSE.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "An AI educational project disguised as Pac-Man.",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://github.com/linqs/pacman",
"Repository": "https://github.com/linqs/pacman"
},
"split_keywords": [
"ai",
" artificial intelligence",
" education",
" teaching"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb5472e6fbc9b033ae914e3473b22d186443435f4b8931559ce56444da799c19",
"md5": "99b6634aa5b1a0e51b5eb73a0b740907",
"sha256": "2211c43340076acf671777dd64792a7190a5db9ae8f292119ca1036e9cf6fedc"
},
"downloads": -1,
"filename": "edq_pacai-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99b6634aa5b1a0e51b5eb73a0b740907",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 308821,
"upload_time": "2025-10-25T20:10:33",
"upload_time_iso_8601": "2025-10-25T20:10:33.486049Z",
"url": "https://files.pythonhosted.org/packages/bb/54/72e6fbc9b033ae914e3473b22d186443435f4b8931559ce56444da799c19/edq_pacai-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e49825d0773a3cedf1abcf6eccc507a9dfdcd7b9baab7da0e4d6ce4fe9a1ba15",
"md5": "a09631baa88a3ae340ecf06d10296332",
"sha256": "4d4523d8493d9b7a75e162297eeec70d3ed73e300aee065da63058a52ba80186"
},
"downloads": -1,
"filename": "edq_pacai-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a09631baa88a3ae340ecf06d10296332",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2229806,
"upload_time": "2025-10-25T20:10:34",
"upload_time_iso_8601": "2025-10-25T20:10:34.963226Z",
"url": "https://files.pythonhosted.org/packages/e4/98/25d0773a3cedf1abcf6eccc507a9dfdcd7b9baab7da0e4d6ce4fe9a1ba15/edq_pacai-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 20:10:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "linqs",
"github_project": "pacman",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Pillow",
"specs": [
[
">=",
"8.3.2"
]
]
},
{
"name": "edq-utils",
"specs": [
[
">=",
"0.0.5"
]
]
}
],
"lcname": "edq-pacai"
}
JSON
