6.170 Laboratory in Software Engineering
Fall 2003
Final Project: Gizmoball
Due: See Schedule

Handout F3

Quick links:

Contents:


Introduction

Your final project is to design, document, build, and test a program that plays Gizmoball. Gizmoball is a version of pinball, an arcade game in which the object is to keep a ball moving around in the game, without falling off the bottom of the playing area. The player controls a set of flippers that can bat at the ball as it falls.

The advantage of Gizmoball over a traditional pinball machine is that Gizmoball allows users to construct their own machine layout by placing gizmos (such as bumpers, flippers, and absorbers) on the playing field. These machine layouts may also form complicated "Rube Goldberg" contraptions that are intended to be watched rather than played. (If you don't know what a Rube Goldberg machine is, see http://www.anl.gov/OPA/rube/index.html or http://www.rube-goldberg.com/). As an optional extension (after you have designed, documented, implemented, and tested all required functionality), you may create new varieties of gizmos that can be placed on a playing field.

Gizmoball Overview

Because this project is in part a design exercise, the assignment specifies what the user should be able to do and leaves it up to you to figure out what modules and interfaces are appropriate. This section gives an overview of Gizmoball. A more detailed specification is given in Appendix 1. To enable automated testing, your implementation must support a file format (defined in Appendix 2), in addition to the loosely-specified graphical user interface.

Gizmoball has a graphical user interface with two modes, building mode and running mode.

In building mode, a user can:

In running mode, the user can play the game.


A screenshot of one implementation of Gizmoball.
Your implementation will look different (depending on your choice of user interface), and your ball motion may not match the animation given exactly.

The picture above illustrates the most important features of Gizmoball.

Grading and Schedule

Grading

You will work in teams of three or four. All members of a team will receive the same grade, except in unusual circumstances.
Stage Due date
(subject to change)
% of project grade Graded on
Preliminary design 11/12/2003
10%
Have you identified the issues?
Weekly meetings with TA 11/3/2003 - 12/5/2003
5%
Did all of the team members participate constructively?
Preliminary Release 11/24/2003
25%
Is it a good design? Is the required functionality present?
Design Critique 12/8/2003
25%
Are the tradeoffs & alternatives thoroughly analyzed?
Implementation & test 12/8/2003
35%
Does it work? Have you demonstrated that it works?

Each stage of this assignment should be handed in electronically and/or as hardcopy to your TA by 4:30 PM on its due date. All of the source and compiled code should be put online on 12/8/2003, in your team project directory.

The final report is due by 4:30 pm on 12/8/2003. Because of end of term constraints, late assignments will not be accepted.

Preliminary Design (due 11/12/2003)

The preliminary design must be submitted electronically by 4:30pm on the due date.

You should express your preliminary design in under 15 pages. Your document will be a subset of that described in the Documenting a Software System handout. It will include a revised specification, a design, and an implementation overview (possibly including code object model(s) and a module dependency diagram). You do not need to include information about your validation strategy.

The revised specification, design, and implementation overview must discuss, among other issues:

The preliminary design should also include a project plan, which lists milestones for the team and allocation of tasks to each team member. A milestone is what you expect to be done by some date, such as a tested module or a working feature -- an achievement that is objective, easy to evaluate, and significant. There must be at least two milestones in the project between the preliminary design and the final deadline. The division of labor should be equitable. (It is most useful to combine the milestones and the task allocation into a single table with "task", "who", and "when" columns, rather than making the milestones and task allocation into two separate documents which cannot be easily related.)

The preliminary design will be graded for clarity of expression and for whether you have thought rigorously about the problem, identified the major issues and challenges, and proposed a design that makes sense.

Weekly Meetings with TA (11/3/2003 - 12/8/2003)

Each team will meet with its TA once a week for half an hour. To receive full participation credit: Although the progress document must be clear, it is short and informal. This document will form the basis of discussion during the meeting, and the TA will keep it on file as a record of progress made. The team should bring multiple copies to the meeting, one for each team member and one for the TA. This progress document should include the following information:

Preliminary Release (11/24/2003)

The preliminary release has two components: a final design writeup and a demonstration of basic functionality.

Final Design

The final design document is an improved and completed version of the preliminary design document. (For instance, it should include a section on your validation/testing strategy.) You should express your final design in under 20 pages. In the project plan section, explain any milestones that you missed and give reasons why you were unable to reach them.

The final design is due two weeks before the final project due date. At this point, you should have found all major mistakes in your design. Therefore the final design will be graded on whether it is a good design, in addition to clarity of expression.

Required Functionality

At the preliminary release deadline, we will ask you to demonstrate some specific functionality.

In order to demo what you had completed by the preliminary release deadline, even if the demo is slightly later and you have made modifications in the meanwhile, you must retain a copy of your code as it existed before the deadline. You can create a snapshot of your source and/or compiled code by using a jar file. Then, you can run the demo by placing the jarfile in your classpath, or by making the jar itself executable.

It is acceptable for you to run up to four separate Java programs to demonstrate the following four features:

  1. Demonstrate key-press triggering of a flipper on the screen. When a key is pressed, the flipper should rotate 90 degrees; after the key is released, the flipper should rotate back to its original position. You should be able to trigger it a second or third time by pressing the key again after it has returned to the original position. (You need not demonstrate connecting the key to the flipper in build mode.)
  2. Demonstrate a working absorber, ball motion, gravity, and friction. In running mode, with no bumpers or flippers on the screen and the ball sitting still in the absorber, you should be able to press a key, observe the ball shoot up out of the absorber, slow down as it rises, fall back to the absorber, and return to its original position. Also demonstrate that you can shoot it out a second time. (Note that you do not yet need to support configurable gravity or friction constants.)
  3. Handle ball collisions with bumpers and the walls. Proper handling of ball-flipper collision is not required at this stage. During running mode, a ball shot out of the absorber must behave properly when it collides with bumpers or with the outer walls.
  4. Demonstrate loading files in the standard format. Given a test file, your implementation should display the gizmos specified in that file at the specified locations on the screen. You should be able to load and display all the standard gizmos.
Your animation in run mode should be smooth and adequate to demonstrate the features required above.

Handing in

You should tag the code in your cvs repository for the initial release so that we can view the source code. You must do this by midnight on 11/24/2003. Tagging the code will allow you (and us) to go back to the codebase that you submitted for the preliminary release. If you do not do this by midnight on 11/24/2003, you will not receive credit for the preliminary release.

Follow these steps to create the tag:

  1. Change to the directory of your cvs working directory: cd ~/6.170/seMMN. (This path could be different, depending on where your ran cvs co.
  2. Create the tag: cvs tag preliminary-release

Later, if you wish to go back to the tagged version, run cvs update -r preliminary-release. This will put that revision in your workspace. You will not be able to commit from that workspace. If you wish to go back to the main trunk, run cvs update -A.

You should email your TA with the following information:

  1. The location of your cvsroot.
  2. The name of the module to check out.
  3. Instructions for running each demo in the required functionality.

Your ta will run "cvs -d <your cvs root> co -r preliminary-release <your module>" and then follow your instructions to test the demo.

Amendment

Shortly after submitting the preliminary release, you will receive an amendment to the program specification. In large programming projects, the requirements often change during development. Your design should be flexible enough to adapt easily to possible changes in the specification.

Implementation and Critique (due 12/8/2003)

It should be possible for you to describe your implementation and critique your design in under 20 pages (except for the Specifications in Item 2, which may take another 5-10 pages and should be placed in an appendix). Conciseness is important. Previous teams that have won the Gizmoball design competition submitted final reports under 10 pages.

Put your code online in your team project directory. You do not need to turn in a printout of your code.

The final report includes a section on Design Changes. Detail what changes you have made to the design that was submitted on 11/24/2003. Be precise. It is vitally important that your TA have versions of the descriptive parts of the Revised Specification, Implementation Overview, and Validation Strategy that accurately describe your submitted code and what you actually did for testing or validation.

For demonstrations (as described immediately below), you must also make a jar file of your implementation named /mit/6.170/groups/seMMN/final.jar. This file must be runnable and must include all of your code in both source and compiled form.

The final implementation and report are due by 4:30 pm on 12/8/2003. Because of end of term constraints, LATE ASSIGNMENTS WILL NOT BE ACCEPTED.

Design Contest

When you submit your implementation and critique on 12/8/2003, indicate on the first page if you want it to be considered for one or more of the following prizes. These contests do not affect your overall grade. They are for FUN!
  1. Best design: Awarded for the project with the best abstraction, modularity, extensibility, simplicity, etc. The quality of the final report is also considered.
  2. Best Gizmoball game: Awarded for the project with the best game-play. Part of your submission for this prize should be an input file that sets up the playing area; the prize is for the playable game itself, not for the construction kit.
  3. Most artistic: Awarded for the project that is the most beautiful or fascinating to watch. Part of your submission for this prize should be an input file that sets up the playing area. When run with this input file, the ball or balls should bounce around forever without the user needing to press any keys.
Whether your program implements only the basic required functionality or extra gizmos etc. will not be considered when making the design award. However extra functionality that improves game-play or "Rube Goldberg" artistry will be an asset in competing for the other two awards.

Judging will be done initially by the TAs and final judgments will be made by the lecturers. One project can win multiple prizes. Winners will be announced at the last class on 12/10/2003.

What We Give You

Animations in Java are quite challenging. You will use the java.awt and javax.swing packages to construct your graphical user interface (GUI). We have provided you with a demonstration program in Example.java that shows how to animate the movement of a ball bouncing around the window. It also demonstrates how to get your program to listen to user events, such as clicking on a toolbar button, pressing a key or dragging the mouse. All members of your group should be able to compile and execute this demo GUI.

We have also provided you with a library of physics routines (see Appendix 3) for calculating the dynamics of elastic collisions. You are welcome to use this code as is, or modify it in any way that you like.

Hints

General

Coding

The syntax of Gizmoball files is designed to be easy for a program to read. The BufferedReader.readLine() method can read a command. The StringTokenizer class can decompose a command into its constituent parts.

You should acquire background knowledge about Swing before attempting to code your GUI. You can see Sun's Swing tutorial (particularly the quick tour, overview, and painting sections). For further examples you may also consult the Manning book available online.

Do not try to use the realtime clock in order to determine timing information. Instead, arrange to receive a timer event every 1/framesPerSecond and proceed to do the simulation and screen updates in response to this event. If you get behind and time slows down, so be it. A simple way to set this up is do use the javax.swing.Timer class, as in the example GUI. Using this approach will simplify the implementation of your code and will also avoid the need to deal with synchronization issues in a multi-threaded program.

If you are using Swing and wish to paint your own component, as you will need to do in order to actually draw the board, gizmos, and ball, you should extend javax.swing.JComponent and implement your own paint routines. In order to do this you will need to override the paint method of your JComponent to paint the board. The painting is done by calling methods on the supplied java.awt.Graphics object. Unless you explicitly turn it off, Swing components are automatically double-buffered to reduce flicker. If you do not understand this, do not worry about it. In addition to Graphics Java has an alternative graphics context java.awt.Graphics2D which provides more sophisticated capabilities than the traditional Graphics object. Note that the calls your components receive to paint(Graphics) will always have a Graphics2D passed as the argument, so if you want to work with Graphics2D, you may simply cast the Graphics object. You may implement Gizmoball using either style of graphics, but here are some differences which you might want to consider:

In order to respond to mouse and keyboard actions from the user you will want to create and install MouseListener, MouseMotionListener, and KeyListener all of which can be found in the java.awt.event package. Information about Java keycodes can be found in the documentation for java.awt.event.KeyEvent.

Keypress

The specifications for handling keyboard input in Gizmoball require that an object connected to a key is triggered when that key is pressed or released. This provides behavior similar to that of a real pinball game: hitting the button causes the flipper to swing upward and releasing the button causes the flipper to return to its rest position.

Keyboard events

The Java specifications for java.awt.event.KeyEvent describe three types of key events, KEY_PRESSED, KEY_TYPED, and KEY_RELEASED. The documentation suggests that KEY_PRESSED events occur when a key is actually depressed by the user and KEY_RELEASED events occur when the key is released. It would therefore seem reasonable to trigger when receiving a KEY_PRESSED or KEY_RELEASED event for a given key bound to a gizmo.

Unfortunately, most Java runtime environments fire multiple KEY_PRESSED and in some cases multiple KEY_RELEASED events when the user has only pressed the key once. Additionally, in some environments you may never receive the KEY_RELEASED events for an upstroke. This is because the behavior of KEY_PRESSED and KEY_RELEASED is system dependent. The behavior occurs through an interaction with the operating system's handling of key repeats that occur when you hold down a key for a period of time.

On Windows

On Windows, Java will produce multiple KEY_PRESSED events as the key is held down and only one KEY_RELEASED when the key is actually released. For example, holding down the 'A' key will generate these events:

PRESSED 'A'
PRESSED 'A'
...
RELEASED 'A'

On Unix

On Unix, multiple pairs of KEY_PRESSED and KEY_RELEASED are received as the key is held down:
PRESSED 'A'
RELEASED 'A'
PRESSED 'A'
RELEASED 'A'
...
PRESSED 'A'
RELEASED 'A'

Test Program

If you want to explore the behavior of your in your environment, you can use the KeypressTest class provided by the staff. The application will dump all keyboard events to the console for inspection.

The source code is available at KeypressTest.java

Solutions

You should feel free to handle this nuance of the Java API as you see fit. One easy solution is to shut off the operating system's automatic key press repeat mechanism and thereby cause the KEY_PRESSED and KEY_RELEASED events to more closely correspond to the actual actions of the user.

Asking the end user to perform settings such as these is acceptable, but should be included in your Gizmoball documentation.

An alternative solution is to take advantage of a special key listener decorator provided by the staff. The class is available in compiled form in the gb-lib.jar file as staffui.MagicKeyListener. Refer to the documentation for MagicKeyListener or use the provided source code as your own starting point.

System Administration and Computer Tools

Group Work

To make intra-group collaboration easier, each team has an AFS locker to store project work and a mailing list for posting messages within the group. Each group has a name in the format "seMMN", where MM is the team's original recitation section number, and N is the team number within that section. This name serves both as an identifier for your team's mailing list (seMMN at MIT) and as a name for the allocated project space (/mit/6.170/groups/seMMN/). We have also setup web access to your project space, using your MIT certificates. The URL for your group is of the form https://web.mit.edu/6.170/groups/seMMN/ (note the s in the https protocol).

We have initialized your lockers with cvs directory structure containing a working ant build environment to help you get started on your project. You can read more about how to get started with your locker here.

Revision Control

We require that you use the CVS revision control package to help you coordinate your work, prevent loss of code, and permit backing up to previous versions. We have initialized your cvs repository with a starter build environment. You can read more about how to access it here.

Java ARchive files

You will need to create jar files as a way of collecting all parts of your application for delivery to your TA. jar files are useful because they can store all of the source code, compiled code, and associated data files (such as images or sounds) in one centralized archive, which can then be easily distributed.

To learn more about jar files, review the jar tool manual from Sun.

As a quick reference, here are a few sample uses of the jar command:

To create gizmo.jar from classes in packages gizmo and ball:

jar cvf gizmo.jar gizmo ball
To list the contents of the jar file, use:
jar tf gizmo.jar
To create a runnable gizmo.jar
jar cvfm gizmo.jar JarMainManifest gizmo ball
In the example above, the file JarMainManifest should contain a single line which names the entry point:
Main-Class: gizmo.StartGizmoball
To run the application using the jar file, use:
java -jar gizmo.jar
Important: Note that, when using the -jar option to run an application, the CLASSPATH variable and the -cp command line switch are ignored. Therefore, to include the physics library in an application stored in a runnable jar, you will have to extract the .class files from our jar, and include them in your own. You can extract a jar file into the current directory this way:
jar xvf /mit/6.170/lib/gb-lib.jar

Using a Makefile, as described the section above, can simplify and automate the creation of jar files. Given the complexity and maintenance issues involved with merging the physics class files in with your application, we recommend the use of a Makefile to automate the process.


Appendix 1: Detailed Requirements

General

Your implementation must support two modes of execution: building and running. In building mode, the user can add gizmos to the playing area and can modify the existing ones. In running mode, a ball moves around the playing area and interacts with the gizmos.

Playing Area

To describe dimensions in the playing area, we define L be the basic distance unit, equal to the edge length of a square bumper. Corresponding to standard usage in the graphics community, the origin is in the UPPER left-hand corner with coordinates increasing to the right and DOWN.

The playing area must be at least 20 L wide by 20 L high. That is, 400 square bumpers could be placed on the playing area without overlapping. The upper left corner is (0,0) and the lower right corner is (20,20). When we say a gizmo is at a particular location, that means that the gizmo's origin is at that location. The origin of each of the standard gizmos is the upper left-hand corner of its bounding box, so the location furthest from the origin at which a gizmo may be placed is (19,19) on a 20L x 20L board. The origin of a ball is at its center.

During building mode, Gizmos should "snap" to a 1 L by 1 L grid. That is, a user may only place gizmos at locations (0,0), (0,1), (0,2), and so on.

During running mode the animation grid may be no coarser than 0.05 L by 0.05 L. Suppose that the ball is at (1,1) and is moving in the (1,0) direction -- that is, left to right -- at a rate of .05L per frame redraw. Then the ball should be displayed at least in positions (1,1), (1.05,1), (1.10,1), and can be displayed at more positions if you wish the animation to be smoother. Rotating flippers can be animated somewhat more coarsely; see the precise description of flippers below. If the ball is moving faster than the animation grid size per frame redraw, it need not be redrawn in each animation grid position.

Building Mode

In building mode the user can:

Running Mode

In running mode, the user can:

In running mode, Gizmoball should:

Standard Gizmos

There are seven standard gizmos that must be supported: bumpers (square, circular, and triangular), flippers (left and right), absorbers, and outer walls.

A coefficient of reflection of 1.0 means that the energy of the ball leaving the bumper is equal to the energy with which it hit the bumper, but the ball is traveling in a different direction. As an extension, you may support bumpers with coefficients above or below 1.0 as well.

Square Bumper

A square shape with edge length 1L
Trigger: generated whenever the ball hits it
Action: none required
Coefficient of reflection: 1.0

Circular Bumper

A circular shape with diameter 1L
Trigger: generated whenever the ball hits it
Action: none required
Coefficient of reflection: 1.0

Triangular Bumper

A right-triangular shape with sides of length 1L and hypotenuse of length Sqrt(2)L
Trigger: generated whenever the ball hits it
Action: none required
Coefficient of reflection: 1.0

Flipper

A generally rectangular rotating shape with bounding box of size 2Lx2L
Trigger: generated whenever the ball hits it
Action: rotates 90 degrees (see below)
Coefficient of reflection: 0.95 (but see below)

Flippers are required to come in two different varieties, left flippers and right flippers. A left flipper begins its rotation in a counter-clockwise and a right flipper begins its rotation in a clockwise direction.

During run mode, a flipper should never extend outside its bounding box. In edit mode the flipper should not be permitted to be placed in any way which would cause the flipper to extend outside of its bounding box during run mode, or would cause the flipper's bounding box to overlap with (the bounding box of) another gizmo.

The below pictures show flipper placements for various initial rotations. In run-mode, when a flipper is first triggered, it sweeps 90° in the direction indicated by the arrows. If triggered again, the flipper sweeps back 90° to the initial position.

In the pictures, the shape and design of the flippers are for illustrative purpose only -- your final design may differ.


Flipper initial placements and initial directions of rotation.

As with the three standard bumpers, a flipper generates a trigger whenever the ball hits it.

When a flipper's action is triggered, the flipper rotates at a constant angular velocity of 1080 degrees per second to a position 90 degrees away from its starting position. When its action is triggered a second time, the flipper rotates back to its original position at an angular velocity of 1080 degrees per second.

If its action is triggered while the flipper is rotating, the exact behavior is at your discretion. Here are some suggestions, but you are not limited to these options:

  1. Ignore triggers while the flipper is in motion. This behavior may be undesirable for the user because a single press and release of a key might not cause the flipper to return to its original position.

  2. Wait until the flipper finishes rotating (and responding to any previously-received triggers) before responding to the action. This behavior may be undesirable for the user because several quick keypresses in a row could cause the flipper to flip repeatedly for a long period of time.

  3. Queue at most one trigger during the initial forward motion and have no queue during the return motion. With this model, a keypress which generated two triggers would cause the flipper to flip and return, but quick repeated keypresses would not tie up the flipper for a long time.

  4. Respond to all triggers immediately. If a flipper is in a forward motion and is triggered, it will immediately switch to a backward motion. In this way, flippers with a key up and down as triggers will behave most like flippers in a real-world pinball game.

The standard coefficient of reflection for a flipper is 0.95. However, when computing the behavior of a ball bouncing off the flipper, you must account for the linear velocity of the part of the flipper that contacts the ball; therefore the ball may leave the flipper with a higher energy than it had when it reached it.

Absorber

A rectangle with integral-length sides
Trigger: generated whenever the ball hits it
Action: shoots out a stored ball (see below)
Coefficient of reflection: not applicable; the ball is captured

When a ball hits an absorber, the absorber stops the ball and holds it (unmoving) in the bottom right-hand corner of the absorber. The ball's center is .25L from the bottom of the absorber and .25L from the right side of the absorber.

If the absorber is holding a ball, then the action of an absorber, when it is triggered, is to shoot the ball straight upwards in the direction of the top of the playing area. By default, the initial velocity of the ball should be 50L/sec. (With the default gravity and the default values for friction, the value of 50L/sec gives the ball enough energy to lightly collide with the top wall, if the bottom of the absorber is at y=20L.) If the absorber is not holding the ball, or if the previously ejected ball has not yet left the absorber, then the absorber takes no action when it receives a trigger signal.

Absorbers cannot be rotated.

Outer Walls

Impermeable barriers surrounding the playfield.
Trigger: generated whenever the ball hits it
Action: none required
Coefficient of reflection: 1.0

A Gizmoball game supports exactly one set of outer walls. The user cannot move, delete, or rotate the outer walls. The outer walls lie just outside the playing area:

It is not required that the user be able to use the GUI to connect the trigger produced by the outer walls with any of the other gizmos. However, the standard file format does support this kind of connection.


Appendix 2: The Gizmoball File Format

Informal Description

Gizmoball files are command scripts. The syntax is, perhaps, somewhat richer than one might design for a simple game, but is also usable for debugging and testing the program independently of the GUI. That is, the file format specifies a standard interface, so that the TAs can test the functionality of your program. The files contain not just a list of gizmos and their positions, but rather commands for exercising all the Gizmoball functionality, including placing, deleting, and modifying gizmos.

Each line of a Gizmoball file contains a command. Each command consists of an opcode and zero or more arguments; these components are separated by spaces and/or tabs. For example:

        Triangle T1 0 7
This is a single command. Its opcode is "Triangle" and its arguments are "T1", "0", and "7". This command specifies that the program should create a new triangular bumper at the location (0,7), and that the triangle can later be referred to in the file by the name "T1". There are similar commands for creating square and circular bumpers and flippers.

The Triangle command places the triangle at a default rotation. If you want the triangle at a different rotation, use the "Rotate" command:

        Triangle T2 3 5
        Rotate T2
        Rotate T2
This creates a triangular bumper at position (3,5) and then rotates it twice by 90 degrees in the clockwise direction, for a total rotation of 180 degrees. Rotating a flipper does not change its bounding box but does change its pivot. Along with the Rotate command, there are also commands for moving gizmos and deleting gizmos. For example:
        Square S1 10 2
        Square S2 15 15
        Move S1 19 17
        Delete S2
This creates a square bumper at (10,2) and another at (15,15), moves first bumper to (19,17), and deletes the second, leaving one square bumper at (19,17).

There are also commands for connecting triggers to actions. For example:

        Square S3 13 13
        LeftFlipper LF1 5 18
        Connect S3 LF1
This creates a square bumper at (13,13) and a left-handed flipper at (5,18). The "Connect" command specifies that the flipper's action should be triggered whenever the ball hits the square bumper.

The KeyConnect command specifies that the action of a gizmo is associated with a particular key being pressed or released:

        RightFlipper RF1 9 18 
        KeyConnect key 32 down RF1 
        KeyConnectkey 32 up RF1
This specifies that the right-handed flipper at (9,18) should be activated whenever the space bar key is pressed or released ("32" is the number that the space bar maps to. Type man ascii and scroll down to the "Decimal" section to view all the mappings).

Because you might also want to allow the outer walls to trigger various actions, there is a special identifier reserved for it:

        Connect OuterWalls GIZ
This command would cause the ball hitting any of the outer walls trigger the action of the gizmo named by "GIZ".

The Ball command allows you to specify the position and velocity of the ball. Because the ball can be at intermediate points within a particular square, the coordinates are specified as floating point numbers:

        Ball B1 14.2 4.5 -3.4 -2.3
This places a ball with its center at (14.2,4.5) and an initial velocity of 3.4L per second to the left and 2.3L per second upward.

The Gravity and Friction commands can be used to set global properties of the game. Each takes floating point values as arguments such as:

        Gravity 16.0
        Friction 0.0 0.0
This would reduce the gravity in the game to only 16L/sec2 and remove any effects of friction. Only the last occurrence of each Gravity and Friction in the file should be used.

Here is the Gizmoball file for the example shown above. It specifies a triangular bumper in the upper right-hand corner, a bunch of circular and square bumpers, and a few flippers. The action of the upper flippers is triggered by the "space" key, the action of the lower flippers are triggered by the "q" and "w" keys, and also by hitting some of the circular bumpers. The action of the absorber is triggered both by the "delete" key and also by the absorber itself! This allows the game to run continuously. Every time the ball hits the absorber, the absorber immediately shoots it back up towards the top again.

Triangle T 19 0
Rotate T

Triangle T2 1 1

Square S02 0 2
Square S12 1 2
Square S22 2 2
Square S32 3 2
Square S42 4 2
Square S52 5 2
Square S62 6 2
Square S72 7 2
Square S82 8 2
Square S132 13 2
Square S142 14 2
Square S152 15 2
Square S162 16 2
Square S172 17 2
Square S182 18 2

Circle C43 4 3
Circle C54 5 4
Circle C65 6 5
Circle C76 7 6
Circle C99 9 9
Circle C109 10 9
Circle C1110 11 10
Circle C129 12 9
Circle C139 13 9
Circle C156 15 6
Circle C165 16 5
Circle C174 17 4
Circle C183 18 3

LeftFlipper LF92 9 2
KeyConnect key 32 down LF92
KeyConnect key 32 up LF92

RightFlipper RF112 11 2
KeyConnect key 32 down RF112
KeyConnect key 32 up RF112

LeftFlipper LF87 8 7
KeyConnect key 81 down LF87
KeyConnect key 81 up LF87
Connect C43 LF87
Connect C54 LF87
Connect C65 LF87
Connect C76 LF87
Connect C109 LF87
Connect C1110 LF87
Connect C139 LF87

RightFlipper RF137 13 7
KeyConnect key 87 down RF137
KeyConnect key 87 up RF137
Connect C99 RF137
Connect C1110 RF137
Connect C129 RF137
Connect C156 RF137
Connect C165 RF137
Connect C174 RF137
Connect C183 RF137

Absorber A 0 19 20 20
KeyConnect key 127 down A
Connect A A

Ball B 1.0 11.0 0.0 0.0

Formal Syntax

<file> ::= <commandline>*

<commandline> ::= <command>"\n" | "\n"

<command> ::= <gizmoOp> <name> <int-pair>           |
              Absorber <name> <int-pair> <int-pair> |
              Ball <name> <float-pair> <float-pair> |
              Rotate <name>                         |
              Delete <name>                         |
              Move <name> <number-pair>             |
              Connect <name> <name>                 |
              KeyConnect <keyid> <name>             |
              Gravity FLOAT                         |
              Friction FLOAT FLOAT
 

<name> ::= IDENTIFIER

<gizmoOp> ::= Square | Circle | Triangle | RightFlipper | LeftFlipper

<number-pair> ::= <int-pair> | <float-pair>

<int-pair> ::= INTEGER INTEGER

<float-pair> ::= FLOAT FLOAT

<keyid> ::= "key" KEYNUM "down" |
            "key" KEYNUM "up"

IDENTIFIER represents any string composed only from the characters {'0'..'9','A'..'Z','a..z','_'}. The identifier "OuterWalls" is a special reserved word which refers to the outer walls; no other item may use this identifier
INTEGER represents any integer number.
FLOAT represents any floating point number.
KEYNUM represents any numeric key identifier (which are integers).

Gizmoball keywords are case insensitive.

Semantics

"Square"       (IDENTIFIER name) (INTEGER x) (INTEGER y)
"Circle"       (IDENTIFIER name) (INTEGER x) (INTEGER y)
"Triangle"     (IDENTIFIER name) (INTEGER x) (INTEGER y)
"RightFlipper" (IDENTIFIER name) (INTEGER x) (INTEGER y)
"LeftFlipper " (IDENTIFIER name) (INTEGER x) (INTEGER y)
Creates the given gizmo with its upper left-corner at (x,y), in the default orientation. Within the file, the name must be unique, and may be used later to refer to this specific gizmo. The default orientation for each gizmo is:
Square
none (all orientations are equivalent)
Circle
none (all orientations are equivalent)
Triangle
One corner in the north-east, one corner in the north-west, and the last corner in the south-west. The diagonal goes from the south-west corner to north-east corner.
LeftFlipper
pivot in north-west corner, other end in south-west corner
RightFlipper
pivot in north-east corner, other end in south-east corner
"Absorber" (IDENTIFIER name) (INTEGER x1) (INTEGER y1) (INTEGER x2) (INTEGER y2)
Creates an absorber with its upper left-hand corner at (x1,y1) and its lower right-hand corner at (x2,y2). The second position must be at least 1L to the right of and at least 1L below the first position. Within the file, the name must be unique, and may be used later to refer to this specific absorber.
"Ball" (IDENTIFIER name) (FLOAT x) (FLOAT y) (FLOAT vx) (FLOAT vy)
Creates a ball whose center is (x,y) and whose velocity is (vx,vy). Within the file, the name must be unique, and may be used later to refer to this specific ball.
"Rotate" (IDENTIFIER name)
Performs a 90 degree clockwise rotation on the item named name. Note that some items (like the absorber, outer walls, or balls) can not be rotated. Rotating a flipper does not change its bounding box but does change its pivot.
"Delete" (IDENTIFIER name)
Deletes the item named name. After this operation, the item will no longer exist.
"Move" (IDENTIFIER name) (INTEGER x) (INTEGER y)
"Move" (IDENTIFIER name) (FLOAT x) (FLOAT y)
In the first form, moves the gizmo with the given name so that its upper-left corner is at (x,y). In the second form, moves the ball with the given name so that its center is at (x,y).
"Connect" (IDENTIFIER producer) (IDENTIFIER consumer)
Makes the gizmo named by consumer a consumer of the triggers produced by the gizmo described by producer. That is, every time a ball hits the producer, the consumer's action will happen.
"KeyConnect" "key" (KEYNUM num) "down" (IDENTIFIER consumer)
"KeyConnect" "key" (KEYNUM num) "up"   (IDENTIFIER consumer)
Makes the item named by consumer a consumer of the trigger produced when the key represented by num is pressed (or released, respectively).
"Gravity" (FLOAT g)
Changes the gravity of the board to be gL/sec2 in the downward direction. This command overrides any previous setting of gravity. If no Gravity command appears in the file the default value should be used.
"Friction" (FLOAT mu) (FLOAT mu2)
Changes the global friction constants to be mu and mu2 as described in the friction formula. This command overrides any previous setting of friction. If no Friction command appears in the file the default values should be used.


Appendix 3: The physics package

The provided physics library consists of immutable abstract data types such as Angle, Vect, LineSegment, and Circle, as well as a class Geometry that contains static methods to model the physics of elastic collisions between balls and other circles and line segments. You are welcome to use or not use this code as you please, and to modify it to meet your needs.

Documentation for the physics package can be found in gb-doc.
Byte-compiled .class files are stored in /mit/6.170/lib/gb-lib.jar, which should automatically be on your classpath.

Source for the physics library can be found in /mit/6.170/www/psets/gb/gb-given/. While this source is provided in the event that you wish to examine or modify it, we strongly discourage you from modifying it. In the past, students who have not used the physics library as-is have had poor results on their projects. Most groups will not need to copy the source code to their own directories, add it to their CVS repositories, or compile it, but will just use the gb-lib.jar file and examine the specifications.


Back to the problem sets page.
Back to the final project page.
For problems or questions regarding this page, contact: 6.170-webmaster@mit.edu.