EECS110 Course Project Option 1, Spring 2009

vPool Project

Overview

For this project, you will be writing a fully interactive 3D "pool-like" game using vPython. We say "pool-like" because the game need not satisfy the official rules of pool and the game may be substantially less complicated than a full pool game. Moreover, you are welcome to make the table more "interesting" than a normal pool table and you can make the physics arbitrarily wacky.

Starting with vPython

Documentation on vPython is available at the vPython website.

On your own PC

If you're on your own PC, starting with vPython is not too hard. Download it from the downloads page of vpython.org and install it on your computer. Although some Vista users have reported some strange behavior, they have gotten it working, and other PC users have found it works "out of the box".

Start IDLE by doubleclicking the "IDLE for Python" shortcut on the desktop.
Open an example program -- for example, bounce2.py ( available at C:\Python25\Lib\site-packages\visual\examples ).
Press F5 to run (or use the Run menu).
Every time you run, your files are automatically saved (if you have changed them).
Choose Visual on the Help menu for documentation.

You can also start IDLE from the "Python 2.5: IDLE (Python GUI)" entry on the Programs portion of the Windows Start menu, then open an example program in C:\Python25\Lib\site-packages\visual\examples.

On your own Mac

It is possible to install vPython on a Mac, but the setup is involved and time-consuming. We encourage you to use vPython on the Wilkinson Lab machines instead.

If you still choose to install vPython on your Mac, note the following:

Once you're in vPython, if you have a one or two button mouse (as the Macs have), go to the X11 icon at the upper left of the window. From there, click on "Preferences". From there select "Input". Finally, select "Emulate 3-button mouse". Now, you can zoom in your 3D graphics window by holding the OPTION button and clicking the mouse button (left button on a 2-button mouse) while moving the mouse. You can rotate the scene by holding the APPLE button down with the mouse click while moving the mouse.

To stop a vPython program, click on the red button in the upper left of the graphics window. Then, save the file, as pr1_final.py or pr1_milestone.py to the Desktop. This is somewhat tricky! When you choose "Save As...," the default directory will be some place deep within a nested set of folders far from the Desktop. Use the pull-down menu to ascend all the way up to the directory named / (forward slash). Then, double-click on home and after a few seconds, double-click on your login name. Underneath that will be a folder named Desktop. That's where you want to save your file.

When you open the file from scratch, you need to start vPython in the way explained above (using the vPython icon). Double-clicking on the desktop .py file will NOT bring up vPython, but the standard Python we've been using throughout this term.

On the Wilkinson Lab machines

Install vPython on the Lab machine you are using by following the steps above. Start IDLE by doubleclicking the "IDLE for Python" shortcut on the desktop.
Open an example program -- for example, bounce2.py ( available at C:\Python25\Lib\site-packages\visual\examples ).
Press F5 to run (or use the Run menu).
Every time you run, your files are automatically saved (if you have changed them).
Choose Visual on the Help menu for documentation.

You can also start IDLE from the "Python 2.5: IDLE (Python GUI)" entry on the Programs portion of the Windows Start menu, then open an example program in C:\Python25\Lib\site-packages\visual\examples.

Requirements

Here are the requirements (and a few "non-requirements") for your game:

• When the game is started, a 3-dimensional pool table appears along with a collection of balls. There should be a cue ball (the ball that the player can strike directly), at least 2 additional balls, and optionally some holes in the table where the balls can fall (the holes are not required!)
• There must be a defined game objective with clearly specified win conditions. This can be a one-person game, a two-person game, or a game against the computer opponent. That's totally up to you!
• Your program should somehow alert the user when he/she has won the game.
• Your program must have an easy-to-use interface (any combination of mouse and keyboard interface) that allows the user to hit the cue ball in different directions (and optionally with varying velocity). You do not need to have an actual pool cue ("stick"). There are lots of other ways to handle the interface and this is entirely up to you.
• Your program must handle ball collisions and bounces in some way. In any case, balls should not be able to pass through one another nor pass through walls. A ball that hits a wall should use the "angle of incidence equals angle of reflection" rule. It's nice to simulate the physics of ball-on-ball collisions accurately as well, but you can use "wacky physics" if you prefer for ball-on-ball collisions (just don't tell your physics professors that we used the words "wacky" and "physics" in the same sentence!).
• It must be possible for multiple balls to move "simultaneously". For example, if ball X hits ball Y then ball X presumably continues moving (in some direction) and ball Y begins moving. Both of these balls should be moving for awhile. Moreover, ball X and ball Y may now hit other balls and these other balls may all need to move for some time as well. In other words, it is not acceptable for your program to always have at most one ball moving at a time.
• Your milestone and final project documentation must describe exactly the objective of the game and how to use the user interface. This should also be summarized as a comment in the code itself.

Feel free to add additional features as you wish.

Here are a few tips that may be helpful to you:

• First, remember that the vPython reference page is a self-contained resource for vPython.
• The vPython arrow object can be used instead of drawing a pool cue to indicate the direction in which you will strike the cue ball. For example, the user might use the mouse or keyboard to rotate an arrow centered at the cue ball. Then another user input could be used to cause the cue ball to move.
• See the vPython reference page for information on how to get keyboard and mouse input from the user. It's not hard!
• Notice that vPython also has a built-in class called vector (take a look at the vPython documentation). The pos that defines the position of a vPython object is actually a vector! This means that you can do the following kind of thing to animate the movement of an object:

mySphere = sphere(pos=(0, 0, 0), ...)

movement = vector(0.1, 0.1 , 0)

while True:

mySphere.pos = mySphere.pos + movement # addition here is overloaded to add movement to pos!

Using a vector to keep track of the direction of movement of a ball allows for easy animation. Moreover, if the ball collides with another object then you need only update the vector appropriately.

What to Submit for the Milestone and Final Project

The milestone is due on Sunday, May 31 at 11:59 PM. For this milestone, you should submit the following:

• A text document called pr1_milestone.txt with your name and the name of your partner (if any), the project that you've chosen, and a brief description of what your game will look like (one paragraph will suffice for the description) and the objective of the game. In addition, the document must give instructions for playing the game (e.g. "Pressing the "g" key will do blah blah blah, the mouse will allow the user to blah blah blah".)
• A list of the function signatures (functions and the names of the arguments that they take) with a docstring for each one.
• Implementation of enough of the functions that the game does something interesting (even if it is far short of the complete implementation) in a file called pr1_milestone.py.
• Submit all of your files (your pr1_milestone.txt, pr1_milestone.py, and any other files that are required to play your game) on the submission site as milestone support files, e.g., pr1_milestone_sup1.py, pr1_milestone_sup2.py, etc.

The final project is due on Friday, June 5 at 5 PM. For the final project, you should submit the following:

• A text document called pr1_final.txt that provides a description of the game and its objectives and complete instructions for how to play the game.
• The full game in a file called pr1_final.py.
• Submit all of your files (your pr1_final.txt, pr1_final.py, and any other files that are required to play your game) on the submission site as final support files, e.g., pr1_final_sup1.py, pr1_final_sup2.py, etc.

Submission: submit your solutions at the submissions server