Final Contest: PacPack

Student Instructions

Hello everyone! The final contest is here!

This challenge moves away from the competitive agents we have explored through topics like minimax game trees in previous parts of the course. We want to flip the script, and challenge you with a cooperative version of PacMan where you write a bot to coordinate with another bot to gather food and defeat ghosts. The contest code is available as zip archive.

You may choose to work alone or with one partner. There is room to bring your own unique ideas, and there is no single set solution. Much looking forward to seeing what you come up with!

Extra Credit

Extra credit points are earned on top of your overall score on projects. E.g. if you you earn 1 point of EC through the Final Contest, then that means you get an extra 1 % * 25 = 0.25 points on your overall grade tally for CS188. (Recall, grading scale is available on the policy page).

Your agent will be tested against staff agents on several "held-out" maps.

  1. 0.5 points for not timing out
  2. 0.5 points for average completion time with NaiveStaffBot lower than 750
  3. 0.5 points for average completion time with MediumStaffBot lower than 650
  4. 0.5 points for average completion time with SmartStaffBot lower than 550

Exact thresholds to be determined after some more calibration has been done (but we wanted you to be able to start in the meantime). Students that perform well in the final leaderboard, ranked by the "final score" metric, will receive the following:

  1. 1st place: 2 points
  2. 2nd place: 1.5 points
  3. 3rd place: 1 point


The goal of this contest is for your agent to work together with a staff-built PacMan agent to eat all but two of the pellets as quickly as possible while avoiding a single ghost. Unlike previous contests and projects, a staff bot teammate will be able to communicate with your agent by broadcasting a plan of its actions at each turn. Your agent will be able to use this plan to determine its own actions in the subsequent steps.

Key Files to Read:

File name Content The main file that runs games locally. This file also describes the gameState type and rules. Specified the agent classes that will form your team. Specification and helper methods for capture agents. This is where you will define your own agents for submission. (These are the only files that you will submit.)

Supporting Files (Do not Modify):

File name Content The logic behind how the Pacman world works. This file describes several supporting types like AgentState, Agent, Direction, and Grid. This is probably the only supporting file that you might want to read Useful data structures for implementing search algorithms. Computes shortest paths between all maze positions. Graphics for Pacman Support for Pacman graphics ASCII graphics for Pacman Keyboard interfaces to control Pacman Code for reading layout files and storing their contents

Academic Dishonesty

Although the spirit of PacPack is cooperative, we expect you to share code only with your partner and submit your own code to the best of your ability. Please don't let us down.

Getting help: You are not alone! If you find yourself stuck on something, contact the course staff for help. Office hours, section, and the discussion forum are there for your support; please use them. If you can't make our office hours, let us know and we will schedule more. We want these contests to be rewarding and instructional, not frustrating and demoralizing. But, we don't know when or how to help unless you ask.

Rules of PacPack


The Pacman agents' goal is to try to eat the food in as few timesteps as possible; A ghost agent will try to stop the Pacman agents from doing so.


There are two numbers you want to pay attention to: the "score" displayed in the game GUI is just the number of pellets eaten, and the total number of timesteps taken to eat all pellets (but 2). The latter is what will be used for grading, and will be printed out in the console at the end of the game. Any game that does not finish in time (the pacman team doesn't eat the pellets in time) will be assigned a value of 1200 timesteps taken. This score is like golf: lower is better.

Computation Time

We will run your submissions on an Amazon EC2 Large Instance. Each agent has 1 second to return each action. Each move which does not return within one second will incur a warning. After three warnings, or any single move taking more than 3 seconds, the game is forfeit. There will be an initial start-up allowance of 15 seconds (use the registerInitialState function). If your agent times out or otherwise throws an exception, an error message will be present in the terminal output. Each game is limited to a maximum time of 1 minute.


Your teammate broadcasts its plan at each turn. This enables your agent to update their plans in response to what the other agent is doing, which lets it cooperate with the other agent to collect the food and avoid the ghost.

There are certain conventions for the broadcasting interface in this project:

  1. In the chooseAction method of the MyAgent class in, you have access to the broadcasted actions of your teammate in the self.receivedBroadcast attribute, which is updated by your staff bot teammate at each step.
  2. Your teammate will broadcast its next 400 actions to you at each time step.
  3. The broadcast must be a list containing valid action strings ("North", "West", "South", "East", "Stop") and nothing else.
  4. You should account for the possibility that the sequence of actions broadcasted to you might not be legal actions for your teammate. An example is if the agent is eaten by a ghost mid-way through executing its broadcasted plan, in which case the remaining actions in the plan could be illegal when conducted from the respawn point.

Designing Agents

File Format

You should include your agent in a file of the same format as Your agent must be completely contained in this one file.


The GameState in should look familiar, but contains new methods like getFood, which returns a grid of all food on the board. Also, note that you can list a team's indices with getPacmanTeamIndices, or test membership with isOnPacmanTeam. This is relevant for determining which agent (your agent, your teammate, or a ghost) is acting in each turn.

Distance Calculation

To facilitate agent development, we provide code in to supply shortest path maze distances.

CaptureAgent Methods

To get started designing your own agent, we recommend subclassing the CaptureAgent class. We have already done so in the starter code. This provides access to several convenience methods. Some useful methods are:

def chooseAction(self, gameState):

Override this method to make a good agent. It should return a legal action within the time limit (otherwise a random legal action will be chosen for you).

def getFood(self, gameState):

Returns a matrix where m[x][y]=True if there is food you can eat in that square.

def getOpponents(self, gameState):

Returns agent indices of your opponents. This is the list of the numbers of the agents (e.g., ghosts might be [1,3]).

def getTeam(self, gameState):

Returns agent indices of your team. This is the list of the numbers of the agents (e.g., for the pacman team it might be [1,3]).

def getScore(self, gameState):

Returns the score of the agent's team for a specific state

def getMazeDistance(self, pos1, pos2):

Returns the distance between two points; These are calculated using the provided distancer object. If distancer.getMazeDistances() has been called, then maze distances are available. Otherwise, this just returns Manhattan distance.


You are free to design any agent you want. However, you will need to respect the provided APIs. Agents which compute during another agent's turn will be disqualified. In particular, any form of multi-threading is disallowed, because we have found it very hard to ensure that no computation takes place on the opponent's turn.

Getting Started

By default, you can run a game with:


A wealth of options are available to you. To see them, run:

python --help

The Pacman team is created from the file and the ghost team is created from the To control one of the four agents with the keyboard, pass the appropriate option:

python --keys0

The arrow keys control your character. (This might not work on Windows machines. Contact us if this is the case).

Agent Teams

The team file is specified in Each Pacman team has two members, specified as default values in the signature of the function createTeam. If you want to create other agent classes, just change the signatures in the team files. Be careful to remember that your agent index is not necessarily 0 in these setups!

Note: you might have to first import your agent class at the top of


By default, all games are run on the defaultcapture layout. To test your agent on other layouts, use the -l option. In particular, you can generate random layouts by specifying RANDOM[seed]. For example, -l RANDOM13 will use a map randomly generated with seed 13.

Submission Instructions

We recommend that you test your agent against the staff bots we provide, and you can even test your agent when it cooperates with itself or other student's bots. The submission interface is slightly different than previous contests or projects. hosts a leaderboard interface that lets you run matches against staff bots or other teams.

  1. Go to and log in using your bMail credentials.
  2. Click "Create a Team" and fill in your name. If you have a partner, enter the email they used to log in at this step.
  3. Click "Upload First Bot", enter your bot name and a short description, and upload your file to the server.
  4. At the top of the page, go to the "Leaderboard" page, select a pinned staff bot or another student's submission, and click "Request Match". This will start a match with a random map layout on our EC2 instance. After the match finishes, you can see the final score. You can also observe a replay of the match to see how your bot did with the given staff bot.
  5. Leaderboard rankings will be based on your performance with the staff bots. They are updated less frequently (once a day), so don't worry if your ranking doesn't update right after you submit.

Make sure that the last bot you submit is the one you intend to be your final submission for the contest. This is the one we will use to perform the final evaluation on the test maps.

If you choose to work with a partner, whoever submits has to appropriately mark their partner at submission time.


A huge thanks to Austen Zhu, Tony Zhao, Micah Carroll, Roshan Rao, and Mesut Yang for taking charge of the initial development of this project. Thanks to the rest of the Summer 2018 CS188 staff for helping to design, tweak, debug and deploy the first iteration, and to Noah Golmant for bringing it in as a contest in the Fall. Further thanks to Barak Michener and Ed Karuna for providing improved graphics and debugging help.

Have fun! This project is very open-ended, so make sure to just spend time exploring the problem and its possible solutions. If you find any infrastructural bugs, please report them to the staff. This will ensure they are fixed promptly so we can continue to improve this contest in the future.