T-Th 9:05
or
T-Th 11:15
in Olin 155

CS 1110: Introduction to Computing Using Python

Fall 2014

Assignment 7:
Breakout

Due to CMS by Wednesday, December 10th at 11:59 pm.

Despite any difficulties you might have had with previous assignments, we know that this assignment is easily within your grasp. You just have to start early, break the problem up into manageable pieces, and program/test incrementally. Below, we discuss stages of implementation and give suggestions for staying on top of the project. If you follow our advice and test each piece thoroughly before proceeding to the next, you should be successful.

Our bare minimum solution is about 700 lines of code. This is ~230 lines in breakout.py (including the ~140 lines already there), ~200 lines in gameplay.py (including the ~70 lines already there), and ~220 lines in models.py (including the ~100 lines already there). So you should expect to be write around 500 lines of code for the bare minimum solution. While this may seem intimidating, a good amount of that is headers and specification. Our minimum solution has 20 methods across all four classes, not including getters and setters.

Learning Objectives

This final assignment has several important objectives.

• It gives you practice with reading official class documentation and APIs.
• It gives you experience using stateful controllers to handle a complex, interactive application.
• It gives you experience with designing helper functions to structure your code properly.
• It gives you experience with using constants to make your code more readable.
• It gives you experience with programming animation and simple physics.
• It gives you experience with an open-ended project that is not fully-specified.
• It brings together everything you have learned in this class in one final assignment.

Table of Contents

Authors: W. White, D. Gries, E. Roberts

• Academic Integrity and Collaboration
• Organization and Scope
• Breakout
• The Basic Game
• Create a Welcome Screen
• Set up the Bricks
• Create (and Animate) the Paddle
• Create a Ball and Make it Bounce
• Check for Collisions
• Finish the Game
• Extending the Game
• Finishing the Assignment
• Appendix: Frequently Asked Questions

Academic Integrity and Collaboration

Academic Integrity

This is a classic assignment that we are giving again because students really like it. You might even find some old solutions out there if you look really hard. There are some major modifications made in the assignment this year, however. We are always making changes to the architecture to make the assignment a little more interesting.

Even though this assignment is different, please do not look up the old solution. That is still a violation of academic integrity, and copying code (without attribution) from that solution is an instance of plagiarism. The program Moss checks for similarity in parts of the code, not just all of it. If you copy code from the old solution (even though it is different) we will know. The code is too complex for accidental similarities to happen.

Code Attribution

There is a lot of code available for you to use in in the Lecture on OO Design. The animation, subcontroller, and etch-a-sketch examples are particularly useful. You are permitted to copy whatever code you want from these (or other samples).

However, if you copy code you must cite the source. This is no different than quoting a book or article in an essay or research paper. In the function specification, you should add a paragraph citing the source module and the original authors (likely the CS 1110 instructors). You must cite your source even if you make changes; that is no different than paraphrasing a quote in an essay or research paper.

Unless you make drastic changes, Moss will catch any copying of the demo code from lecture. Do it right; cite the source.

Copyrighted Material

There is another Academic Integrity issue with this assignment: copyrighted material. You do not own the rights to Pokémon. Pokémon is owned by Nintendo. The president of Nintendo America is a Cornell alum. Please do not encourage our alums to sue us by using Pokémon artwork in your game.

In general, you are only allowed to use copyrighted material if you have a license to do so. For example, many of the songs and sound effects in the NewGrounds library are available for you to use under an Attribution License. That means you are free to use it so long as you cite the source in your documentation (e.g. your header comments). This is okay. A license where you have to pay is not okay.

If you are in doubt as to whether you have a license to use something, ask us on Piazza.

Collaboration Policy

You may do this assignment with one other person. If you are going to work together, then form your group on CMS as soon as possible. If you do this assignment with another person, you must work together. It is against the rules for one person to do some programming on this assignment without the other person sitting nearby and helping.

We are allowing some limited additional collaboration. If you want to talk to other people in the class about how you broke up your code -- what goes in gameplay.py and what goes in models.py -- you may do that as well. If you want ideas for method specifications, that is okay. The number 1 rule is this: with the exception of your CMS-registered partner, please do not look at anyone else's code or show your code to anyone else, in any form what-so-ever.

Organization and Scope

This is very long assignment, much like Assignment 4. However, both I and the consultants have a lot more experience with this assignment, and so it should go much smoother. Once gain, the trick is to pace yourself. While there are no unit tests this time, you should be able to figure out if everything is working simply by playing the game.

Assignment Source Code

The first thing to do in this assignment is to download the zip file A7.zip from this link. You should unzip it and put the contents in a new directory. This time, you are going to get a directory with a lot more than usual. In particular, this zip file contains the following:

breakout.py

This file contains the controller class Breakout. This is the controller that launches the application. It is one of three modules that you will modify for this assignment. While it is the primary controller class, you will note that it has no script code. For that, you will use the module __main__.py below.

gameplay.py

This file contains the secondary controller class Gameplay. This class manages a single game of breakout. It works as a subcontroller, just like the example subcontroller from class. It is another of the three modules that you will modify for this assignment, and the one that will require the most original code.

models.py

This file contains the model classes Ball and BrickWall. If you want to add other model classes (such as for your Paddle), then you add those here as well. This is the last of the three files you should modify for this assignment.

constants.py

This is a module filled with constants (global variables that should not ever change). It is used by both breakout.py, gameplay.py, and models.py to ensure that these modules agree on certain important values. It also contains code for adjusting your brick size. You should only modify this file if you are adding additional constants as part of your extended features.

game2d.py

This file contains the view class (e.g. GView) for this application. It also contains the parent classes for your models and controller. Under no circumstances should you ever modify this file!

__main__.py

This module contains the application code for this assignment. It is the module you run from the command line to start the game. However, the way that you run it is a tad unusual; see the below. Do not modify this file!

Sounds

This folder is a list of sound effects that you may wish to use as part of your extensions. You are also free to add more if you wish; just put them in this folder. All sounds must be WAV or OGG files, recorded at 16 bits and sampled at 44.1 kHz (e.g. CD quality).

Fonts

This folder is a collection of True Type Fonts, should you get tired of the default Kivy font. You can put whatever font you want in this folder, provided it is a .ttf file. Other Font formats (such as .ttc, .otf, or .dfont) are not supported.

Images

This folder is a collection of images that you may wish to use as part of your extensions. The class GImage allows you to animate images in this game, should you wish. You can also use it to provide a background; just remember to draw the background image first.

For the basic game, you will only modify the first three files listed above. The class Breakout is a subclass of the class GameApp. With the exception of BrickWall, your model classes should all be subclasses of GObject. As part of this assignment, you are expected to read the online documentation which describes how to use the basic classes.

Running the Application

Because there are so many files involved, this application is handled a little differently from previous assignments. To run the application, put all of the files in a folder, and give the folder a name like breakout. The file __main__.py turns the entire folder, not just one module, into a script. You already saw this in the WordApp application in Assignment 4.

As with that game, change the directory in your command shell to just outside of the folder breakout and type

python breakout

In this case, Python will "run the folder" by executing the application code in __main__.py. This trick only works when you run the folder breakout as a script; 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.

Assignment Organization

This assignment closely follows the model-view-controller pattern discussed in class. The modules are clearly organized so that each holds models, the view, or a controller. The organization of these files is shown below. The arrows in this diagram mean "imports". So the Breakout controller imports the view and Gameplay subcontroller. The Gameplay controller imports the view and the models. This leads to an important separation of files. Breakout is never permitted to access anything in models.py and Gameplay is never permitted to access anything in breakout.py. This cuts down on those annoying meetings.

You will notice that the models module imports the view because it needs the parent class GObject to perform any drawing. In practice, we often like to separate the model and view to cut down on the number of arrows (less meetings). However, that would make this assignment a lot harder. Fortunately, the view does not import anything (and should not be modified). This means there are no cycles in this architecture (e.g. A imports B imports C imports A). Cyclical imports are very dangerous and you have to be careful with them in large applications. Avoiding cycles is one of the reasons we draw pictures like the one above.

In addition to the four main modules, there is another module with no class or function definitions. It only has constants, which are global variables that do not change. This is imported by the model module and the two controllers; it is a way to help them share information.

Assignment Scope

As you can see from the online documentation, the class Breakout needs to implement three main methods. They are as follows:

Obviously, you are not going to put all of your code in those three methods; the result would be an unreadable mess. An important part of this assignment is developing new methods whenever you need them, so that each method is small and manageable. Your grade will depend partly on the design of your program. As one guideline, points will be deducted for methods that are more than 40 lines long. This includes the specification (though init, update, and draw are exempt from this rule)..

You will also need to add methods and attributes to the classes Gameplay, BrickWall, and Ball in model.py. These classes are completely empty, though we have given you a lot of hints in the class specification. You should read all these specifications.

As you write the assignment, you may find that you need additional attributes. Whenever you add a new attribute to a class, you must fully state the invariant in your specification. All instance attributes should be hidden. While you do not need to enforce the invariants, you must have getters and setters if the attributes are accessed by a class in another model. For example, if the Gameplay class needs to check the velocity of the ball, then you are going to need getters for the velocity in the Ball class.

When approaching this assignment, you should always be thinking about "what code goes where?" If you do not know what file to put things in, please ask on Piazza (but do not post code). In general, you should follow these guidelines:

Breakout

This controller does very little. All it does is keep track of the game state (e.g. whether or not the game is paused). Most of the time it just calls the methods of Gameplay, and Gameplay does all the work. However, if you need anything between games, like a paused message or a countdown clock, this goes here.

Gameplay

This class does all the hard work. In addition to the initializer, it needs the following three methods as a bare minimum:

• A method to serve the ball (if it is lost, or the game is starting)
• A method to move the paddle
• A method to move the ball

The last one is going to be quite complex. If you try to write it as a single method, you are going to violate the 40 line rule. So you will need to add some helpers there as well.

In general, anything that involves additional gameplay is going to go in this class.

The Models

The models just keep track of data. Most of the time, models just have attributes, with getters and setters. Think Dataset and Cluster from the previous assignment. However, sometimes models have additional methods that perform complex computation on the data, like distance and updateCentroid in class Cluster

The models in this assignment are the game objects on screen: the ball, the paddle, and the bricks. Of these three, it is more important to have a class for Ball. Ball needs additional attributes for its velocity, and you need several extra methods to perform complex calculations on this velocity. However, you do not need an extra class for the paddle, since all you are doing is changing its x and y position. The provided class GRectangle should be enough for paddle.

You also do not need a class for a brick. GRectangle is fine there as well. However, we do want a class that stores all of the bricks, called BrickWall. Again, think of Dataset. We did not make you create a class for the points, but we wanted a class to store the points in them. Why do we need BrickWall? Why cannot we use a simple list? That question is answered below when we talk about collision detection.

If your added features include power-ups, like those in Arkanoid, then you are going to need additional model classes. In that example, you are going to need a class for the paddle to keep track of what power ups it has. As a general rule, if your game object needs additional attributes that are not included in GObject, then you are going to have to create a new class.

Pacing Yourself

You should start as soon as possible. If you wait until the day before this assignment is due, you will have a hard time completing it. If you do one part of it every 2-3 days, you will enjoy it and get it done on time. We have also tried not to include your Thanksgiving Break in this assignment.

The hard part of this assignment may be "finishing up": designing the final reorganization in order to incorporate three balls in a game. We have budgeted you one day for this, but you have up to four days if you decide just to do the bare minimum and not add any extensions.

Implement the program in stages, as described in this handout. Do not try to get everything working all at once. Make sure that each stage is working before moving on to the next stage.

Set up a schedule. We have suggested some milestones, but make up your own schedule. Leave time for learning things and asking questions. Above all, do not try to extend the program until you get the basic functionality working. If you add extensions too early, debugging may get very difficult.

Getting Help

We have tried to give you as much guidance in this document as we can. However, if you are still lost, please see someone immediately. Like the last few assignments, this is a fairly involved project, and you should get started early. To get help, you may talk to the course instructor, a TA, or a consultant. See the staff page for more information.

In addition, you should always check Piazza for student questions as the assignment progresses. We may also periodically post announcements regarding this assignment on Piazza and the course website.

Breakout

The initial configuration of the game Breakout is shown in the left-most picture below. The colored rectangles in the top part of the screen are bricks, and the slightly larger rectangle at the bottom is the paddle. The paddle is in a fixed position in the vertical dimension; it moves back and forth horizontally across the screen along with the mouse (or finger, on a touch-screen device) — unless the mouse goes past the edge of the window.

Starting Position

Hitting a Brick

A complete game consists of three turns. On each turn, a ball is launched from the center of the window toward the bottom of the screen at a random angle. The ball bounces off the paddle and the walls of the world, in accordance with the physical principle generally expressed as "the angle of incidence equals the angle of reflection" (it is easy to implement). The start of a possible trajectory, bouncing off the paddle and then off the right wall, is shown to the right. The dotted line is there only to show the ball's path and will not actually appear on the screen.

In the second diagram above, the ball is about to collide with a brick on the bottom row. When that happens, the ball bounces just as it does on any other collision, but the brick disappears. The left-most diagram below shows the game after that collision and after the player has moved the paddle to put it in line with the oncoming ball.

Intercepting the Ball

Breaking Out

The play on a turn continues in this way until one of two conditions occurs:

1. The ball hits the lower wall, which means that the player missed it with the paddle.
2. The last brick is eliminated.

In the first case, the turn ends. If the player has a turn left, the next ball is served; otherwise, the game ends in a loss. In the second case, the player wins and the game ends.

Clearing all the bricks in a particular column opens a path to the top wall. When this delightful situation occurs, the ball may bounce back and forth several times between the top wall and the upper line of bricks without the user having to worry about hitting the ball with the paddle. This condition, a reward for "breaking out", gives meaning to the name of the game. The last diagram above shows the situation shortly after the first ball has broken through the wall. The ball goes on to clear several more bricks before it comes back down the open channel.

Breaking out is an exciting part of the game, but you do not have to do anything in your program to make it happen. The game is operating by the same rules it always applies: bouncing off walls, clearing bricks, and obeying the "laws of physics".

Game State

One of the challenges with making an application like this is keeping track of the game state. In the description above, we can identity four distinct phases of Breakout.

• Before the game starts, and the bricks are not yet set up
• While the game is ongoing, and the ball is in play
• While the game is ongoing, but the player is waiting for a new ball.
• While the game is paused (e.g. to show a message), and game is waiting for a mouse click.
• After the game is over.

Keeping these phases straight is an important part of implementing the game. You need this information to implement update in Breakout correctly. For example, whenever the game is ongoing, the method update should instruct Gameplay to move the paddle. However, if the game has not started yet, the method update should create a new Gameplay object.

For your convenience, we have provided you with constants for four states.

• STATE_INACTIVE, before a new game has started
• STATE_ACTIVE, when the game is ongoing and ball is in play
• STATE_COUNTDOWN, when the player is waiting for a new ball
• STATE_PAUSED, when the game is paused to display a message
• STATE_COMPLETE, when the game is over

All of these constants are available in constants.py. The current application state should be stored in the attribute _state inside Breakout. You are free to add more states when you work on your game extensions. However, your basic game should stick to these four states.

The Basic Game

We have divided these instructions into two parts. The first part covers the basic things that you must implement just to get the game running. Once you do that, the assignment gets more interesting. You should try to finish everything in this part of the assignment by Monday, December 8 (after the last week of class). If you do that, you will be in good shape to add extensions (though you will not lose any points if you do not have extensions; they are a form of extra credit).

Before You Do Anything

The very first thing that you should do is read the file constants.py. If you ever need a value like the size of the paddle, the size of the game window, or so on, this is where you go. When writing code, you should always use the constants, not raw numbers (or "magic numbers," as we call them). Magic numbers make your code hard to debug. And if you make a change (e.g. to make the ball bigger), you have no idea about all of the locations in your code that need to be changed.

With that said, you are welcome to change any of these numbers if you wish. You are also encouraged to add more constants if you think of other numeric values that you need. Anytime that you find yourself putting a number in your code, ask yourself whether or not it would make sense as a constant.

Create a Welcome Screen

We start with a simple warm-up to get you used to defining state and drawing graphics elements. When the player starts the application, they should be greeted by a welcome screen. When you work on your extensions, you can embellish your welcome screen to be as fancy as you wish. But for now, keep it simple. Your initial welcome screen is going to consist of a text message.

Because the welcome message is before any game has started, it belongs in the Breakout class, not the Gameplay class. You are already seeing how we separate what goes where.

The text message will look something like the one shown to the above. It does not need to say "Press to Play". It could say something else, as long as it is clear that the user needs to click the mouse (or press the screen) to continue. You also do not have to use the dreaded Comic Sans font like we have.

To create a text message, you need to create a GLabel and store in it an attribute. If you read the specification for class Breakout, you will not see any attributes for the text message. That means it is your responsibility to add one. You should add the description of your attribute to the class specification. For now, we will assume that you named the attribute _message, but you could name it anything you like.

Since the welcome message should appear as soon as you start the game, it should be created in the method init, the first important method of the class Breakout. When creating your message, you will want to set things like the font size and position of the text. As you can see from the documentation for GLabel and GObject, graphics objects have a lot of attributes to specify things such as position, size, color, font style, and so on. You should experiment with these attributes to get the welcome screen that you want. The key thing to remember is that, in Kivy, that screen coordinates start from the bottom-left corner of the window (and not the top right as with most graphics applications).

Simply adding this code to init is not enough. If you were to run the application right now, all you would see is a blank white window. You have to tell Python what to draw. To do this, simply add the line

    self._message.draw(self.view)

to the method draw in Breakout. The (non-hidden) attribute view is a reference to the window; this instructs Python to draw this text label in the window. Now run the application and check if you see your welcome message.

Initializing Game State

The other thing that you have to do in the beginning is initialize the game state. The attribute _state (included in the class specification) should start out as STATE_INACTIVE. That way we know that the game is not ongoing, and that the program should (not yet) be attempting to animate anything on the screen. In addition, the other attributes listed (particularly _game) should be None; we have not done anything yet!

The _state attribute is an important part of many of the invariants in this game. In particular, we want your new attribute for the welcome message to have the following invariant:

• If the state is STATE_INACTIVE, then there is a welcome message
• If the state is not STATE_INACTIVE, the welcome message is None.

Does your definition of init satisfy this invariant?

Dismissing the Welcome Screen

The welcome screen should not show up forever. The player should be able to dismiss the welcome screen (and start a new game) when he or she clicks the mouse or touches the screen. You track this with the attribute touch which is part of GView. This attribute is a GPoint if the mouse button is currently down, and None if it is not.

When looking at the value touch, remember the issues that we discussed in class. The method update is called every 16 millisecond. If you hold the mouse down, then you see a lot of touches. You just want the first touch! That means you need an attribute _last (included for you in the specification) that keeps track of what touch was in the last call to update. You know that a press is brand new if _last is None, but touch is not None.

If you detect a mouse press, then you should change the state STATE_INACTIVE to STATE_COUNTDOWN. The game has now started (but there is no ball, or even bricks yet). You are not ready to actually write the code for the game, but switching states is an important first activity.

Invariants must be statisfied at the end of every method, so you need to assign None to the welcome message as well. This will require a simple change to method draw to keep it from crashing. Once you have done that, run the application. Does the message disappear when you click the mouse?

Important Considerations

This first part of the assignment looks relatively straightforward, but it gets you used to having to deal with controller state. In this part, you already immediately had to add attributes beyond the ones that we have provided. Whenever you a new attribute, you must add it and its corresponding invariant to the class specification. Add it just after the comment starting "ADD MORE ATTRIBUTES", to make it easier for the graders (and you) to find them. We will deduct style points for instance attributes that are not specified.

Try to finish this part by Sunday, November 23 (e.g. two days after starting the assignment). You will spend most of your time reading the online documentation. But this will give you a solid understanding of how this application works.

Create a Game and Populate it with Bricks

Technically, you are violating an invariant after the last step. When you changed the state to STATE_COUNTDOWN, the attribute _game was no longer supposed to be None. Construct a Gameplay object and assign it to this attribute.

Right now, the subcontroller Gameplay does not anything data in it. Eventually it is going to create the bricks, a ball, and a paddle. Right now, we are just going to focus on the bricks.

This is going to require that you modify two different classes in two different files. As a result, this activity will help you see how everything fits together. Read the specification for both Gameplay and BrickWall. You are going to need to add an __init__ method and a draw method to both of these classes. These are the only four methods that you need for this part of the assignment.

The __init__ for Gameplay is easy. Just construct a BrickWall object and assign it to the specified attribute _wall. The draw method is also easy: just call the (not yet implemented) draw method in BrickWall.

This means that all of the hard work is going on in class BrickWall. So go read the specification for that class again. You will see that it contains a (one dimensional) list of bricks. The initializer for this class should create this list and add the bricks (which are all just GRectangle objects). The draw method should draw these bricks.

Creating Bricks

As we mentioned before, the bricks should be instances of GRectangle. To define a rectangle, use the attributes x, y, width, height, linecolor, and fillcolor to specify how it looks on screen. Look at the sample code from lecture to see how to do this. You can either assign the attributes after the object is created, or assign them in the constructor using keywords. See the online documentation for more. When you color a brick, you should set the line color so that its outline is the same color as the interior (instead of black).

To get you started, you might want to create a single Brick object of some position and size and add it to list, just to see what happens (though you will need to finish draw first). Then think about how you can place the BRICK_ROWS rows of bricks. You will probably need a loop of some kind. We do not care if it is a for-loop or a while-loop; just get the job done.

When you are ready, you should set up the bricks as shown to the right. The number, dimensions, and spacing of the bricks, as well as the distance from the top of the window to the first line of bricks, are specified using global constants given in module constants. The only value you need to compute is the x coordinate of the first column, which should be chosen so that the bricks are centered in the window, with the leftover space divided equally on the left and right sides (Hint: the leftmost brick should be placed at x-coordinate BRICK_SEP_H/2). The colors of the bricks remain constant for two rows and run in the following sequence: RED, ORANGE, YELLOW, GREEN, CYAN. If there are more than 10 rows, you are to start over with RED, and do the sequence again. We suggest that you add a constant BRICK_COLORS to constants.py that lists these colors in an appropriate way to help with this.

Drawing Bricks

Once again, adding bricks to the model is not going to draw them on the screen. Drawing is going to involve quite a chain of events here. First, you have to to modify the method draw in Breakout, as this is where all the drawing really happens. You should note that the attribute of Breakout is _game, not _wall; _wall is an attribute of Gameplay If you are going to draw the bricks in Breakout, you have to go through Gameplay. Furthermore, writing

def _getCollidingObject(self):
    """Returns: GObject that has collided with the ball
    
    This method checks the four corners of the ball, one at a 
    time. If one of these points collides with either the paddle 
    or a brick, it stops the checking immediately and returns the 
    object involved in the collision. It returns None if no 
    collision occurred."""