Overview

Weight: The homework will count 11% of your final grade.
Assigned: April 16, 2007
Due: Thursday, May 3, 11:59:59 PM
This assignment provides experience with language features of Java that we haven't encountered in previous languages: objects, exceptions, and threads to name a few. The goal is to write a simple game that lands a vehicle on a planet. The game will be implemented in two forms: a text-based game, playable in a terminal window, and a graphics game playable as an applet in a web browser.

Turning in your project

All code should be developed in the five directory. When you are done the directory will contain your source (java) files, object (class) files, a transcript of a successful (in the sense that the program works, not necessarily in the sense of a successful landing) execution of the text-based game, and the supplied gif and html files for the applet. When you are done and certain that everything is working correctly, create a zipped or tarred, gzipped copy of the five directory. Turn in the tar or zip file using the turn-in page. The uploaded file name should be five.tar.gz or five.zip. You may turn in your assignment as many times as you like.

Getting started

A skeleton of the code for this assignment is provided. You can download the files in either five.tar.gz or five.zip. (This code has Unix/Linux line-ends so some Windows editors may not display it correctly -- Wordpad or any program editor should not have a problem.) Both a stark, monochrome planet surface and lander ({landscape,lander*}.gif) and a more colorful lunar surface and Apollo lander ({lunarSurface,apollo*}.gif) are included for use in the second part of the assignment (the applet). Choose which you'd like to use.

Compiling and running your project

I suggest putting all the java files in a single directory. On the 353 linux lab machines you can then compile the program with

   javac *.java

and run the stand-alone application with

   java Game

Grading

The assignment will be marked for good programming style (indentation and appropriate comments), as well as clean compilation and correct function.

Help with Java

There is extensive documentation on Java on the web. The resources link on the class home page has links to only a few of the many, many resources available.

Text based game - 75%

The game package contains the classes for playing a planetary lander game. You may add other methods as you see fit to the classes indicated below.

class Planet

An instance of the Planet class models the physics of a planet. Edit Planet.java to implement this class. For this program, the physics is described by the gravity and the height of the surface. You are to write the following methods.

• a constructor method
• getGravity - Accessor, returns the gravity for the planet.
• getGround - Accessor, returns the height of the surface for the planet.
• getName - Accessor, returns the name of the planet.

This is a small and simple class!

class RocketException

An instance of this class is an exception thrown when the rocket reaches an undesirable state (e.g., it is below the surface without having landed and thus has crashed!). The exception should be thrown and handled appropriately by the methods of the other classes. You don't need to add anything to this class.

class Rocket

An instance of the Rocket class models the behavior of a rocket lander in the region of a planet. Edit Rocket.java to implement this class. The rocket object maintains the state of the simulated rocket, which consists of a height, velocity, amount of fuel, engine strength, and the planet on which the rocket is landing. You may want to add additional state. I've set up the following methods for you to use.

• nextHeight - This method computes the approximate height of a rocket as it falls to the surface (in a vacuum under constant gravitational acceleration). The approximate height of the rocket at time t + dt is a function of the previous height of the rocket (at time t) and the velocity (at time t), and dt (how long ago was the previous time). During the time dt we'll approximate the distance the rocket falls as (previousVelocity * dt). The height is given by the equation:

    height(t) = height(t - dt) + (velocity(t - dt) * dt)
  

• nextVelocity - This method computes the approximate velocity of a rocket as it falls to the surface (in a vacuum under constant gravitational acceleration). We will assume that the rocket has an engine that provides an upward force which is given by the equation (engineStrength * burnRate) and the rocket is being pulled down by the gravitational force. The burnRate is how much fuel we are giving to the engine per unit time period. The velocity at time t is given by the equation:

    velocity(t) = velocity(t - dt) + 
                  ((engine_strength * burnRate) - GRAVITY)*dt
  

You will write the following methods for the Rocket class:

• a constructor method - see the Game class below to see how it is called.
• getHeight - Returns the current height.
• getVelocity - Returns the current velocity.
• getHeightString - This method has been provided for you but there is still work for you to do. It returns a string with an asterisk in representing the position of the rocket and a `|' representing the position of the planet's surface. This method also includes the current velocity at the end of the line which makes the game easier to play.
• getState - This method returns a string consisting of the height, velocity, and amount of fuel for the rocket. For example

  "HEIGHT -2.5 VELOCITY -7.5 FUEL 200"
  

  You'll want to use a formatter to make the double numbers look nice. I used the DecimalFormat class in my implementation of getHeightString.
• reachedSurface - This private method returns a boolean value indicating whether the rocket has reached the surface (or below).
• landed - This private method returns a boolean indicating whether the rocket has landed safely. The rocket has landed safely if it has reached the surface and the velocity is greater than safeVelocity (a local constant defined to be -1.0 -- downward velocity is negative!).
• nextFuel - This method computes and updates the available fuel according to

    fuel(t) = fuel(t - dt) - (burnRate*dt)
  

• move - This method changes the rocket state at time t into the new state at time t + dt. It takes two arguments, the change in time, dt, and fuel burn rate. The rocket may not have enough fuel left to be able to burn at the specified burn rate for all of dt. If there isn't enough fuel, this method should limit the burn rate so that the available fuel is exactly used up during the interval dt.

class Game

Edit Game.java to implement this class. This class actually plays the game by calling the appropriate methods in the Rocket class. The game is played by printing the position of the rocket, and the waiting for the user to input the character `b' followed by a newline character indicating a full burn or a newline character alone indicating no burn. This repeats until the rocket either lands or crashes. In this character-oriented game assume that the time between inputs (dt) is 0.5 second (regardless of how long the player actually takes before entering input). That is, the character-oriented game is not played in real time.

When the game terminates, the rocket state and an appropriate message indicating whether the rocket has landed or crashed should be printed. Here is an example output of a game.

java Game

      |                                                 *       - 0.3

      |                                                *        - 0.6

      |                                                *        - 0.9

      |                                               *         - 1.2

      |                                              *          - 1.5

      |                                            *            - 1.8

      |                                          *              - 2.1

      |                                        *                - 2.4

      |                                      *                  - 2.7

      |                                   *                     - 3

      |                                *                        - 3.3

      |                             *                           - 3.6

      |                         *                               - 3.9

      |                     *                                   - 4.2

      |                 *                                       - 4.5

      |             *                                           - 4.8

      |        *                                                - 5.1
b
      |   *                                                     - 3.4
b
      *                                                         - 1.7
b
     *|                                                           0
Landed Safely! One small step for man, one giant leap for mankind...

The above game was played on Pluto with a gravity of 0.3, the surface at 0.0 and a rocket motor strength of 2.0 with 1 second between moves so your 1/2 second move behavior will be different. Include in your tar or zip file a transcript of an interactive session in which you play the game and (hopefully) land successfully. Try playing the game with the above Planet and Rocket attributes, but if you find it too hard to land you may change them (do real rocket scientists wish for the same freedom?!). Good luck!

applet package -- 25%

Modify the code in GameApplet.java to animate the applet. To view an applet use

  appletviewer my.html

or open my.html in your browser. The applet will run the code in GameApplet.java. There are at least three important methods that you will have to modify.

• init() - This method is called when the applet is started. Use it to set up the initial state of the game.
• run() - This method is called when the applet is run. Use it to move your rocket.
• update() - This method is called to refresh the display. Use it to show the current state of the game.

Finally, you will have to write methods to listen for mouse events. The rocket should do a full burn when the mouse button is down, and no burn when the button is up. A class extending MouseInputAdapter is just what you need to handle the mouse events. Just override MouseInputAdapter's mousePressed() and mouseReleased() methods. MouseInputAdapter is in the javax.swing.event package. The MouseEvent class is java.awt.event.MouseEvent.

One thing to watch out for in this version of the game is that here you will be measuring time in milliseconds while the move method in Rocket wants the time in seconds. Easy enough to fix but your rocket will uncontrollably shoot off into space if you don't compensate correctly.

If you are into building GUIs you might want to investigate adding components to the applet display that show dials for height, velocity and remaining fuel. That would be visually more pleasant than displaying text overlaid on the gif as is now done.