CSCI 1321 (Principles of Algorithm Design II), Fall 2003:
Homework 1

Credit:

Design 40 points; code 20 points.

Contents

• Overview
• Details
• Hints and tips

Overview

This assignment is less about you writing code and more about thinking about what you are going to do for the project and getting used to Java and Together. As with all of the assignments, there are two distinct due dates. On the first one you will turn in your design documents; on the second one you will submit the code itself. In this assignment, the code is very short and simple; you will likely write far more comments (describing your design) than code.

Before reading further, be sure you have read the Project Description giving the overall description of the project and general requirements.

Design

Ideally you will write your design in the form of comments for the class that will contain your main program; they will then appear in the HTML documentation generated by Together. (If you can't make this work by the due date, just send an e-mail with a text description.) This documentation will not necessarily set in stone every detail of the game you will write, but you should be as specific as you can. In particular, you should first give a general description of the game and roughly how the user will play it, and then explain how you will implement this using Dr. Lewis's framework (i.e., what kinds of Block, and GameEntity classes do you think you will need?) For example, in a very simple Pacman-style game you might need two kinds of blocks, one for walls (obstacles) and one for the rest of the playing field, and two kinds of game entities, one for enemies and one for things you pick up to score points.

Code

For this assignment, all you have to write is a class with a main method that does the following:

• calls GameSetup.constructVariables()

• instantiates a MainFrame object and calls its show method. (You won't find a description of show in the documentation for MainFrame; it's inherited from the Java library class JFrame.)

When you compile this program and run it, it should bring up a window for a very simple ``starter'' game.

Details

What files do I need?

You will need the JAR file for this assignment, PAD2Assn1.jar. You will probably find the project API and the Java 1.4 API (linked from the course ``Useful links'' page) useful.

Creating a project using Together

See the course ``Useful links'' page for information on running Together on one of the lab machines or on your own machine. Once you have started Together, do the following to create a new project and set it up for this assignment.

• In the File menu, select New Project to create a project. You will be prompted to choose a name for the project and a folder (directory) for its location. If you are doing this under Linux on one of the lab machines, this folder should be somewhere in your home directory. (Notice that the top-level file-selection menu should have a choice ``Home'' that takes you to your home directory.) You probably should not put the code and its documentation in the same directory. A reasonable approach would be to create a directory PAD2 (or CS1321, or whatever appeals to you) in your home directory and then make a subdirectory for each assignment.

• Download the JAR file for this assignment (PAD2Assn1.jar); put it in the same directory/folder as the project you just created.

• Add the JAR file to the project's classpath, so that the classes you write will be able to use the classes in the JAR file: In the Project menu, select Project Properties. Select the Search/Classpath tab, click Add Path, Library, or Archive, and select the JAR file you just downloaded. Notice that the classes in the JAR file will not show up in your project's diagram. On the whole this is probably a good thing. Caution: If you mistakenly add the JAR file to the Project Paths tab, the classes inside will show up in your project's diagram, but the Java runtime will not be able to find them. If this happens, remove the JAR file from the Project Paths tab and add it to the Search/Classpath tab. One would think there would be a way to have the JAR file appear on both tabs, but this appears not to work.

• Create a ``main'' class for your game using the Designer panel or by starting with the File menu and selecting first New and then Class. Right-click on the UML diagram for the new class and select Properties. This should bring up the class's properties in the Inspector panel. The Properties tab shows the class's name, among other things. Change it to something meaningful for your game.

Completing the design step

Once you have your project set up as described above, do the following steps to finish the design part of this assignment.

• Add comments to your main class describing your game: Bring up your main class's properties in the Inspector panel as described earlier (right-click on the class's UML diagram and then choose Properties). Select the Description tab. Type your description of the game in the Description panel that comes up.

• Generate HTML documentation for your project: In the Project menu, select Documentation, then Generate HTML. You will prompted for the location of the folder (directory) in which to put the generated documentation. Follow the directions in the overall ``Project Description'' document.

Turn in your design as described in the ``Project Description'' document.

Completing the code step

For this step, you are to add a main() method to your main game class. The parameters, return type, etc. of this method should be the same as in the examples we have done in class; what the code should do is described earlier. You will be making use of Dr. Lewis's GameSetup and MainFrame classes; to find out how to use these classes, read the project API documentation.

Once you have written your code, compile it and test it. Here are some tips on writing, compiling, and testing your code using Together. They assume that you have followed the preceding steps for creating a project and documentation for your main class.

• To add code (a main() method) to your main class, you can open it in the Editor panel (by double-clicking on its class diagram in the Designer panel) and type the code in directly. (There are other ways of creating code with Together, but this is probably the simplest at this point.) When you have it typed it, save it (by starting with the File menu and selecting Save). You can actually change things in your class using the Editor panel, the Inspector panel, and the Designer panel. Changes you make in one panel show up in the other one(s) when you save them.

• Try compiling your code: In the Project menu, select Make Project. (Or find the Make Project icon on the toolbar.) You will see any error messages in the Message Pane panel at the bottom.

• Once you get code that compiles without errors, try running it: In the Run menu, select Run. (Or find the Run icon on the toolbar.) This pops up a window with more prompts. Choose the Application tab and fill in the box labeled Select class for 'main' with the name of your main class.

• If you have done everything right, you will now get a little window that allows you to play a very simple game (solid black screen, player that moves around in response to the arrow keys). You will probably want to make the window bigger, and to make the player move you may need to hold the arrow keys down longer than you might think. If you don't get such a window, the Message Pane panel should contain error messages indicating what went wrong.

When you are happy with how your code works, generate a final version of your documentation and turn in the code as described in the ``Project Description'' document. For this assignment, you will be turning in a single file, the one containing the source code for your main class. (For example, if your main class is called MyGame, this file will be MyGame.java.)

Hints and tips

Notice that you can do everything except generate HTML documentation using command-line tools, if you need to work on your project on a computer that doesn't have Together installed or doesn't have enough memory to run it with acceptable performance (or if you just decide you prefer editing code with vim!). See Java Without an IDE for details. If you do this, the next time you open the project with Together, it should pick up any changes you made with other tools; you can use the Synchronize with External Changes option from the File menu if it doesn't seem to be doing so.