0   CS 1110 2017sp, Assignment 5: Citizen Pac

Authors: Stephen McDowell, Erik Andersen, David Gries, Lillian Lee, Steve Marschner, Eric Roberts, Walker White

Due on CMS by Wednesday May 10th, 2017, 11:59pm

As usual, we strongly recommend that you submit a preliminary version by 2pm the day of the deadline, for the usual reasons. [1]

This assignment, including some of the wording of this document, was inspired by the videogame PacMan, this year’s CS1110 mascot, and the CS1110 final assignment project Breakout, which in turn was adapted from an assignment by Professor Eric Roberts at Stanford University.

When you finish this assignment, you’ll be able to play a Pacman-like game that will look like the following. You control the bat, Citizen Pac, with keyboard presses: “A” for West, “W” for North, “S” for South, and “D” for East. When the bat hits a window boundary, it “teleports” or wraps around to the opposite window boundary. Your enemies are ghosts, and their touch is fatal, although you have three lives. You win the game by having Citizen Pac collect all the food items before losing all three lives.

screen shot of the Citizen Pac game

1   Rules (All The Same As For A4)

This assignment will receive a single grade; there is no revise-and-resubmit like there was for Assignment 1.

You may do this assignment in groups of size one or two. All previous groups have been dissolved by CMS for this assignment; if you want to work with someone (whether or not you’ve worked with them before), you need to form your group on CMS before submitting. [2]

If your partnership dissolves, see Scenario 2, ‘’group divorce’‘, on the CS1110 academic integrity page to see what to do.

Our policies are laid out in full on the CS1110 academic integrity page, but we re-state here the main rules: where ‘’you’’ means you and, if there is one, your one CMS-registered group partner,

  1. Never look at, access or possess any portion of another group’s work in any form
  2. Never show or share any portion of your work in any form to anyone except a member of the course staff.
  3. Never request solutions from outside sources such as online services like StackOverflow.
  4. Do specifically acknowledge by name at the top of your file all help you received, whether or not it was “legal” according to (1)-(3).

2   TODO by End of Day (EOD) Wed May 3: Make sure your installation is compatible with A5

Todo

By the end of Wed May 3: download and unzip the assignment files into a new directory called A5. Open a command shell and navigate to your directory A5. Using ls or dir, check that you see the directory citizen_pac.

In the command shell, enter python citizen_pac. [3]

If you get a message in the command shell that starts “There seems to be an issue with the version of python you have installed...”, then you have too advanced a version of anaconda to work with the assignment code and you will need to re-install anaconda python following the directions given in the error message.

3   Assignment Source Code

Download the source code from here: a5.zip

Of the several files needed for this assignment, you need only focus on the following. [4]

model.py
Contains a class and code for modeling a Scene and its physics.
view/actors.py
Code for displaying actors, such as CitizenPac or the food items.
constants.py

Sets variables known as constants that are used throughout the code, and whose values should never be changed outside of the constants.py file.

An important constant is constants.FULL_GAME_MODE. When False, the game runs in debug mode, and you will initially want to be in debug mode until you have completed some of your implementation tasks. To get the full game to run correctly, you’ll want to change its value to True.

Some constants you should be aware of are constants.MOVE_NORTH, constants.MOVE_SOUTH, constants.MOVE_EAST, and constants.MOVE_WEST. These values represent move directions, which you will need to detect in your code.

Other than those you can change the initialization values for some of the variables in constants.py as you like if you would like to change the corresponding game properties, but you don’t have to.

A constant you may want to change to make the game arguably more exciting is constants.USE_SPEED_BOOST; if set to True, the more food consumed, the faster all the actors move.

Note the style convention that constants, whose values should never change throughout execution of the program, are in all-caps.

3.1   Viewing code specifications and documentation: The CitizenPac Library API

We have nicely formatted displays of the source-code specifications and documentation available for you, which will be easier to read than comments in the code itself.

To view this documentation, click on the “Site” link at the top of this webpage, and select “CitizenPac Library API” [5] in the resulting pulldown menu.

3.2   Coordinate system and actor coordinates

coordinates

The x coordinates increase as one moves rightwards; the y coordinates increase as one moves downwards. But, items whose x-coordinates are not in the range [-.5*width, .5*width] or whose y-coordinates are not in the range [-.5*height, .5*height] will not show up on the board.

One can access the current coordinates of an actor a via method calls a.x() and a.y().

Each actor also has attributes cx and cy representing its start \(x\) and \(y\) coordinates: when an actor is reset, it is placed back at this start location. More information in the documentation of the class view.actors.Actor.

4   TODO: The Functions You Must Complete

You have several functions to complete, but they all require just a few lines of code altogether!

4.1   view.actors.Actor.advance()

Todo

In order to facilitate incremental coding and testing, you will want to have the game in “debug” mode when you implement the first function. That is, make sure you’ve set constants.FULL_GAME_MODE (in the file constants.py) to False while you test your implementation of this function.

Moves an actor according to its current move direction, which can be determined by calling its isMoveDirection() method (documentation here: view.actors.Actor.isMoveDirection()). We discussed how moves are represented in Section 3   Assignment Source Code above.

Click on the method name to go to its complete documentation.

When testing, notice that debugging information is printed in the command shell.

Tip

If you hold down both the “A” and “D” keys, you should see printed out in the command shell that (1) it is True that Citizen Pac has received directives to go both East and West, but (2) the amount the bat actually moves is 0, because trying to go both East and West cancels out.

Note that the class Food, which is a subclass of class Actor, overrides the advance() method of Actor, because food isn’t supposed to wander around the scene, [6] in contrast to the ghosts and the bat.

4.2   model.generateFoodGrid()

Computes where food should be placed.

Click on the method name to go to its complete documentation.

Todo

Change constants.FULL_GAME_MODE in constants.py to True when implementing this function and the rest.

One potential source of errors to watch out for: Our 3.2   Coordinate system and actor coordinates implies that if you placed food only at locations with, say, non-negative x coordinates, then you would only place the food on the right half of the window (and about half of the food would be hidden from view past the right edge of the window).

placement without translation correction

But you can translate (that is, shift) locations with only positive coordinates by subtracting tx and ty, which are variables we compute for you, from x and y coordinates.

4.3   model.Scene.reset()

Resets the scene, and is meant to be called when CitizenPac loses a life. All the food becomes visible and uneaten, and the ghosts and CitizenPac all have their pre-written reset methods called.

Click on the method name to go to its complete documentation.

4.4   model.Scene.wrapActor()

Causes actors to “teleport” to the opposite side of the window when it hits a window boundary.

Click on the method name to go to its complete documentation.

5   Screenshots of Game Stages

If you are running with the most updated code, then the game stages below are what you should see. Note that the speed boost and score should be reset every time a life is lost.

Regular Mode (“Fancy Graphics”) Simple Graphics Mode
game start fancy

The start screen in regular mode.
game start simple

The start screen in simple mode.
one life lost fancy

Paused after one life lost in regular mode.
one life lost simple

Paused after one life lost in simple mode.
game over fancy

The game lost screen in regular mode.
game over simple

The game lost screen in simple graphics mode.
game won fancy

The game won screen in regular mode.
game won simple

The game won screen in simple graphics mode.

Note

The final score of 5439 depends on the various constants declared that control the game.

6   Submitting

You will just have to submit model.py and actors.py from the view subdirectory. (Although you’ve made changes to constants.py, you do not submit it.)

Put your (and your partner’s, if you have one) name and netid(s) at the top of the submitted file(s).

Todo

Acknowledge by name all help you received in comments at the top of your submitted file(s).

7   Footnotes

[1]Reminders: you can replace older submissions with improved ones up to the actual deadline. Since you’ve been warned to submit early, do not expect that we will accept work that doesn’t make it onto CMS on time — by CMS’s definition of time, which may differ from your watch’s or your computer’s — for whatever reason, including server delays stemming from many other students trying to submit at the same time.
[2]Reminder: Grouping requires actions on the part of both parties. Brief instructions for how to form a CMS group are given as Step 4 on the Course Assignments page.
[3]Because citizen_pac is a directory, the __main__.py file turns the entire folder, not just one module. Python “runs the folder” by executing the application code in __main__.py. (This only happens when you run the folder citizen_pac as a application; you cannot import the folder. If you wanted to “import a folder” (which, for this assignment, you don’t), you would create a file called __init__.py.)
[4]

If you are curious about the entire set of files: the three components represented by the file model.py, the file controller.py, and the directory view are what make up the model-view-controller code pattern typical for graphical applications. Here is a summary diagram:

the model view controller
[5]“API” stands for “Application Program Interface”; an “interface” in this case is between humans, who want to understand code without reading all the source, and the code itself.
[6]On your own time, you could make the food ambulatory if you liked. It’s your code and your world!