Lab 1: Creating Simple Pac-Man Agents
Due Jan. 29 by midnight

The Pac-Man code was developed by John DeNero and Dan Klein at UC Berkeley.

Starting point code

This lab my be done alone or with a partner of your choice. Go through the following steps to setup your directory for this lab.

  1. First you need to run setup63 to create a git repository for the lab. If you want to work alone do:
    setup63 labs/01 none
    If you want to work with a partner, then one of you needs to run the following while the other one waits until it finishes.
    setup63 labs/01 partnerUsername
    Once the script finishes, the other partner should run it on their account.

  2. For the next step only one partner should copy over the starting point code.
    cd ~/cs63/labs/01
    cp -r ~meeden/public/cs63/labs/01/* ./
    
    This will copy over a large number of files within two different directories. One directory, called tutorial, contains small programs to help you practice with Python. The other directory, called pacman, contains all of the files you need to run the Pac-Man game.

  3. Whether you are working alone or with a partner, you should now add all of the files to your git repo, commit, and push them as shown below.
    git add pacman tutorial
    git commit -m "lab1 start"
    git push
    

  4. If you are working with a partner, your partner can now pull the changes in.
    cd ~/cs63/labs/01
    git pull
    

Python tutorial

If you are new to Python or it has been awhile since you've used Python, you should start with this Python tutorial.

Introduction

In this lab you will create simple Pac-Man agents that are reflex-based or state-based to try to collect food.

The Pac-Mac code consists of a number of Python files, some of which you will need to read and understand in order to complete the assignment, and some of which you can ignore.

Files you'll edit:
myAgents.py Where you will define your agents.
layouts/myLayout.lay Where you will define a Pac-Man layout.
Files you should look at:
pacman.py The main file that runs Pac-Man games. This file describes a Pac-Man GameState type, which you use in this lab.
game.py The logic behind how the Pac-Man world works. This file describes several supporting types like AgentState, Agent, Direction, and Grid.
util.py Useful data structures which you can use if you'd like to.
Supporting files you can ignore:
graphicsDisplay.py Graphics for Pac-Man
graphicsUtils.py Support for Pac-Man graphics
textDisplay.py ASCII graphics for Pac-Man
ghostAgents.py Agents to control ghosts
keyboardAgents.py Keyboard interfaces to control Pac-Man
layout.py Code for reading layout files and storing their contents

Welcome to Pac-Man

You can play a game of Pac-Man by typing the following at the command line:
python pacman.py
In this case you are the agent that is controlling Pac-Man. Use the arrow keys to move Pac-Man around in his environment. The smaller white dots represent food. The goal of the game is to eat all of the food while avoiding the ghosts that are trying to thwart Pac-Man. If Pac-Man runs into a ghost, he dies. However, the larger white dots are special capsules that when eaten by Pac-Man make the ghosts safe to contact. The ghosts will only be safe for a short time, while they are colored white, but they eventually become dangerous again.

Layouts

In your pacman directory you'll see that you have a sub-directory called layouts. When you invoke the pacman game, by default it chooses the mediumClassic.lay layout. However you can use command-line arguments to choose other layouts. For example:
python pacman.py -l openSearch
Try other other layouts in the directory. Notice that these layouts are simply text files that follow a convention for designating the locations of walls, food, capsules, ghosts and pacman.

Exercise 1: Create a simple layout of your own in this directory called myLayout.lay. Your layout should not include ghosts, but should have some inner walls and lots of food. Play a game with your layout by doing:

python pacman.py -l myLayout

Command-line arguments

Note that pacman.py supports a number of options that can each be expressed in a long way (e.g., --layout) or a short way (e.g., -l). You can see the list of all options and their default values via:
python pacman.py -h
If you ever want to end a game early, you can exit the game by typing CTRL-C into your terminal window.

The Pac-Man Agent

Pac-Man agents are defined as a class that inherit from a base Agent class and must have one method called getAction that takes the current state as a parameter and returns the action to take. The format of an agent is shown below:
class NameOfAgent(Agent):
  def registerInitialState(self, state):
    """
    THIS METHOD IS OPTIONAL it can be used to maintain additional
    state information
    Parameters: Current state
    Returns: None
    """
  def getAction(self, state):
    """
    Parameters: Current state
    Returns: Action to take
    """
The getAction method will automatically be called on every time step of the game and must return a valid action.

Based on Russell and Norvig's definition, an agent perceives its environment and acts upon its environment. Let's examine what Pac-Man agent can do and sense.

Actions

The Pac-Man agent can execute the following five actions: Open up the file myAgents.py in an editor. It already has one very simple agent defined, called RandomAgent. This agent gets all of the possible legal actions it could take from the current state, and then randomly chooses one of them. Notice that this agent completely ignores its percepts, and acts blindly.

To test this agent do:

python pacman.py -l openSearch -p RandomAgent
If you are willing to wait long enough, this agent will eventually manage to eat all of the food. One of the reasons it is so slow is because it is sometimes randomly choosing to 'Stop' as its action. The 'Stop' action is useful when trying to evade ghosts, but for now we are just focusing on grabbing food.

Exercise 2: Modify the RandomAgent so that it will never choose 'Stop' as its action. Then re-test the agent.

Percepts

What the Pac-Man agent can perceive is based on the methods of the GameState class which is defined in the file pacman.py. Open up this file and let's look through the options.

It is important to recognize that the game has a number of different agents (Pac-Man and the ghosts). Each agent in the game has a unique index; Pac-Man is always index 0, with ghosts starting at index 1.

Pac-Man can perceive:

In addition, Pac-Man can also determine given the action he chooses what the next state of the environment will be, by using the method generatePacmanSuccessor. It is clear from the methods available here that Pac-Man's environment is fully observable. Pac-Man's environment is also static because until he decides what to do and takes an action, the ghosts do not move.

Exercise 3: In the file myAgents.py create a new agent called ReflexAgent. This agent should look at the possible legal actions, and if one of these actions would cause a food pellet to be eaten, it should choose that action. If none of the immediate actions lead to food, it should choose randomly from the possibilities (excluding 'Stop'). Test your agent in the openSearch layout.

python pacman.py -l openSearch -p ReflexAgent

Exercise 4: In the file myAgents.py create a new agent called StateAgent. This agent should try to eat any food that is immediately accessible, as in the ReflexAgent, but rather than moving randomly when no food is directly available, it should instead try to move in one direction repeatedly until food is located or it reaches a wall. Test your agent in the openSearch layout.

python pacman.py -l openSearch -p StateAgent

Submitting your code

To submit your code, you need to use git to add, commit, and push your files. You will only be changing two files for this lab.
cd ~/cs63/labs/01
git add myAgents.py layouts/myLayout.lay
git commit -m "final version"
git push