CSE 142 Spring 2002

Homework #3

Pinball (Minus a Few Things)

Due: Electronically, 11:00pm, Sun., April 21;
written report due in lecture, Monday April 22.

Tuesday, 4/16, 2:45PM: New versions of hw3.jar and hw3.zip have been installed. These fix a bug reported on the class discussion list, and have a few other changes solely to help you diagnose problems you might have in getting the code to run. If you haven't already modified the code, get new copies (i.e., re-fetch hw3.jar or hw3.zip and start from there). If you have already modified the code, the patch is basically one line of java, and is described here.

00:49:00, 4/16/02: New section, Running the Starter Code of the Box, added to this page.

Homework 3 Frequently Asked Questions
This misnamed page really contains some information about the kinds of things that might be going wrong for you trying to obtain or use the skeleton code files. It is not mandatory reading, but is worth a look if you're having trouble setting up your system (as contrasted with issues like understanding what the assignment is asking you to do, or the code itself, neither of which is talked about in the FAQ).

Purpose

The purpose of this assignment is to

Gain more experience with instance variables, constructors, and methods
Learn about conditional (if) statements
Learn to work with code written by others.
Learn to debug by reconciling the behavior you're seeing with your understanding of what the code is doing, so that when you change the code you are with very high probability making progress towards a final solution.

This assignment involves much (much) more reading of code than writing. You will be given an incomplete implementation of a program that bounces balls inside a closed container, and be asked to complete it. The assignment has a number of phases. You will save time by completing each entirely before moving on to the next, rather than trying to do them all at once.

Getting Started

Alternative J
Download the file hw3.jar, and put it in a folder (none of the folders in the path name to these files should have a space or any special character (such as '#') in them). Then expand the jar file using the command jar -xvf hw3.jar. When you've done that, you should find files BallGame.java, Player.java and a number of .jpg files in that directory.
Alternative Z
Download the file hw3.zip, and put it in a folder (none of the folders in the path name to these files should have a space or any special character (such as '#') in them). Then expand the zip file however you do that normally (often just double-clicking does something good). When you've done that, you should find files BallGame.java, Player.java and a number of .jpg files in that directory.

(Both approaches produces exactly the same set of files useful in this project. Alternative J is "the new-fangled Java way," meaning it is likely to fail on plenty of machines because they're not set up for it. Alternative Z is the old but servicable way, more or less guaranteed to work everywhere.)

Now you're ready to roll. You can use BlueJ, which requires creating a BlueJ project from them. (Select "open non-BlueJ from the file menu, then select the folder containing the .java files.) Or you can just compile them and run them from the command line ("java *.java" and then "java BallGame" in a DOS (command) window). Or you can compile them ("javac *.java") and then use jeva to test and run them.

Here is a brief description of the two classes involved. Complete interface documentation is available here.

BallGame

This is the main class. It's constructor creates a window and a bounding rectangle. All action takes place inside the bounding rectangle. Methods are available to create up to two balls and two obstacles, all in random locations. The obstacles are in fixed positions, but the balls move. When a ball encounters an obstacle, or the boundary rectangle, it bounces.
BallGame also "drives" the simulation - it cycles as fast as it can, asking the balls to move and then to check to see if they should bounce off anything else in the virtual world.

Player

This is the class that implements both balls and obstacles. Abstractly, the two are the same, at the level of the Java implementation. (Obstacles are just balls whose velocity is zero. The user (you) will probably be tempted to use pictures of balls for the balls, and pictures of other things for the obstacles, but what the pictures are is irrelevant to the Java code.)
A Player object knows its velocity (and so how far to move itself every time step), and it knows under what conditions it should bounce, and how to bounce. It does any of those things only when asked to do so, though, by a BallGame object.
It's important to note that a ball is actually a rectangular object, no matter what the image is that appears to be moving. That is, even though the .jpg might show a yellow, round ball, the Player object itself doesn't know anything about that. All it knows is that it's a rectangle. You don't see it because the area in the rectangle around the ball is white, just like the background. (You will see it when a corner of the ball passes through another object, though.)

What's Up

The files you will start from are what's left of a working program once a few things were removed. The total amount of code removed is very small. Reactivating each of the disabled features (described next) should take only a few lines of code. This is intentional. You will have to understand how the code works to know which few lines of code to add where. Reading code is a lot easier than writing it, because for the most part the messy little details (like "Do I have to have a '(' here?" or "Am I allowed to have a '(' here?") are irrelevant when you're reading. So, the goal is to save you time and frustration. At the same time, this program is complicated enough that trial-and-error will not work, period. Make sure to spend the time to understand what is going on before attempting to modify the code.

Things that Used to Work But Don't Any More

The working version of this program is capable of bouncing up to two balls in a world consisting of the boundary rectangle and up to two obstacles. In the version of the code you have:

For the most part balls bounce correctly to the left, but bouncing right, up, and down are all broken. (The balls simply march off the screen, in fact, rather than bouncing off most faces of the boundary rectangle.)
At most one ball can be inserted into the virtual world. No obstacles can be.
While balls mostly bounce correctly in all directions, they have some trouble at corners, where they sometimes seem to hop unnaturally as they change directions.

That's it.

Running the Starter Code of the Box

Start up whatever tool you're going to use (jeva or BlueJ). Now create a BallGame object. A window with an interior "boundary rectangle" will appear. Create a ball by invoking the createBall() method on the BallGame object. (See the documentation for parameters.) Start the ball moving using the go() method on the BallGame object.

Here's a sample sequence of method invocations:

BallGame bg = new BallGame(); (a window appears)
Player ball = bg.createBall("soccer.jpg"); (a ball appears)
bg.go(100); (the ball moves)

If the ball disappears off the screen, you can get it back with something like

ball.setPosition(50,50); (the ball puts itself at (50,50), which is visible)

You can also adjust a ball's velocity. See the documentation for Player objects.

If you're using the command line to compile ("javac *.java") and run, to do the latter just type "java BallGame." The method main() that you'll find in BallGame.java is invoked. It runs through a sequence of commands something like the example above, except that it will ask you to supply the number of time steps to give to the go() method invocation. (It will wait for you to type an integer on the keyboard, and then use that number.)

How to Proceed

Our strong advice is to do the following, in order:

Change the implementation so that the sole ball bounces as well to the right as it does to the left. (That is, it will still have its corner glitch, but it will no longer leave the screen by passing out the left edge, and will mostly look correct in a typical, non-corner bounce to the right.)
This should take about 4 or 5 lines of code.
Now change the implementation so that the ball bounces up and down as well as it does left and right.
This should take maybe nine to a dozen lines of code.
Now change the implementation of allow up to two balls to bounce around together in the virtual world. (The balls should be allowed to pass through each other.)
We're talking a couple of lines of code here.
Now change the implemenation to allow up to two obstacles to be introduced.
At this point, this should be almost trivial.

That's it. When you've done that, you're done.

In case you'd like to try more, though, for optional no-credit extra-credit, try fixing the corner bounce glitch. Or try making balls bounce off each other, as well as off the things they already bounce off. Or try figuring out how this code could have been made simpler while at the same time allowing for arbitrary numbers of balls and obstacles, up to the limits of the machine's performance. (Hint: ArrayList and its cousins.) Or, if you really want a challenge, make the program work even when the maximum distance a ball can move in a single time step is increased arbitrarily. (In the base code it can never be greater than 4 units in either dimension in a single move.)

Turning in the Completed Project

Turn-in form. (now available)

Written Report

In lecture on Monday, April 22, you must turn in a short (no more than one page) written report about your project. Include your name, section, homework number and date at the top. If you didn't get the program finished, describe what still does not work, and your best guess as to what is needed to fix it. Whether or not you finished it, describe the most important things you learned from this project, which could be new ideas that you have never seen before, or misconceptions that you had that the project helped you straighten out. Comments on the positives and negatives of reading versus writing code would also be appropriate.