Updated the readme.

Author: eriq-augustine

README.md

@@ -1,71 +1,174 @@
-# Pacman
+# Pacai
 
 An AI educational project disguised as [Pac-Man](https://en.wikipedia.org/wiki/Pac-Man)!
 
-A modified version of the Pacman educational project from the [Berkeley AI Lab](http://ai.berkeley.edu/project_overview.html).
-
-Some improvements from the original project:
- - Upgraded to Python 3.
- - Organized into packages.
- - Brought up to a common style.
- - Added logging.
- - Added tests.
- - Fixed several bugs.
- - Generalized and reorganized several project elements.
- - Replaced the graphics systems.
- - Added the ability to generate gifs from any pacman or capture game.
-
-## FAQ
-
-**Q:** What version of Python does this project support?  
-**A:** Python >= 3.10.
-The original version of this project was written for Python 2, but it has since been updated.
-
-**Q:** What dependencies do I need for this project?  
-**A:** This project has very limited dependencies.
-The pure Python dependencies can be installed via pip and are all listed in the requirements file.
-These can be installed via: `pip3 install --user -r requirements.txt`.
-To use a GUI, you also need `Tk` installed.
-The process for installing Tk differs depending on your OS, instructions can be found [here](https://tkdocs.com/tutorial/install.html).
-
-**Q:** How do I run this project?  
-**A:** All the binary/executables for this project are located in the `pacai.bin` package.
-You can invoke them from this repository's root directory (where this file is located) using a command like:
+This project was inspired by and originally based off of the Pacman educational project from the
+[Berkeley AI Lab](http://ai.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.
+
+## Installation / Requirements
+
+This project requires [Python](https://www.python.org/) >= 3.10.
+
+The project can be installed from PyPi with:
+```sh
+pip3 install 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()'
 ```
-python3 -m pacai.bin.pacman
+
+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
 ```
 
-**Q:** What's with the `student` package?  
-**A:** The `student` package is for the files that students will edit to complete assignments.
-When an assignment is graded, all files will be placed in the `student` package.
-The rest will be supplied by the autograder.
-This makes it clear to the student what files they are allowed to change.
+To see all the available options, use the `--help` flag:
+```sh
+python3 -m pacai.pacman --help
+```
 
-**Q:** How do I get my own copy of repo to develop on?  
-**A:** Anyone who will be committing solutions should use this template repository to create a **private repository**.
-Directions for that can be found [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
-For anyone else, you can just [fork it](https://help.github.com/en/articles/fork-a-repo) as you normally would.
+### Boards
 
-## Pulling Changes from This Repo Into Your Fork
+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
+```
 
-Occasionally, you may need to pull changes/fixes from this repository.
-Doing so is super easy.
-Just go to your default branch and do a `git pull` command with this repository as an argument:
+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
 ```
-git pull https://github.com/linqs/pacman.git
+
+### 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 Berkley AI Lab for starting this project. Primarily John Denero and Dan Klein.
+ - The Berkeley AI Lab for starting this project.
+   Primarily John Denero and Dan Klein.
  - 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.
- - Graduates of the CMPS 140 class who have helped pave the way for future classes (their identities are immortalized in the git history).
+ - 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