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\sitepackages\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\sitepackages\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 selfcontained 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
here is overloaded to add movement to pos!
# addition
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