CSCI 1321 (Principles of Algorithm Design II), Fall 2007:
Homework 2

Credit

Design 20 points; code 40 points.

Overview

In this assignment you will begin to construct your game following the description that you handed in for the last assignment. You will do this by creating several new classes and interfaces. classes you create will depend on the design of your particular game. What you will be constructing now is the beginning of the ``playing field'' -- the background on which the game is played. To do this, you will write what may seem like a lot of classes, but some of them can be very short, and for others you will have access to source code for the equivalent classes in Dr. Lewis's starter game.

Before reading further, review the Project Description, particularly the section ``The game framework''.

Design

The design for this assignment will include descriptions of all the classes and interfaces you will write (for this assignment) and their methods. As in the previous assignment, you will write these descriptions in the form of comments for the classes you need; they will then appear in the HTML documentation generated by Eclipse (or with the javadoc command). As before, what you turn in does not set in stone the code you write for this assignment or later assignments, but you should try to at least plan fairly carefully what you will do for this assignment.

Step-by-step instructions

• Create a new Eclipse project for this assignment. (You could skip this step and use the project you created for the previous assignment, but then you won't have a copy of what you previously turned in, which could be useful as a checkpoint of code that compiled and worked.)

• Within the project, create a package for your code. (You could skip this step, but it's good style.) A good package name is edu.trinity.cs.yourusername.yourgame, where yourgame is something descriptive of your game (e.g., pacmanclone). It can be the same as the package name you used for the previous step (and should be, unless you made a not-so-good choice then).

• Create the classes described below in ``Classes for this assignment''. In this phase, you should mostly be writing comments. However, since you will be writing documentation for methods as well as classes, you will have to provide at least minimal definitions for the methods you plan to write. A good way to approach this is to write skeleton (or stub) versions of methods. For example, here is a skeleton version of a Circle class:

  /** Class for circles. */
  public class Circle {
      /** 
       * Constructs a circle with specified radius.
       * @param r -- radius
       */
      public Circle(int r) { }
      /**
       * Gets the circle's area.
       * @return area
       */
      public double getArea() { return 0; }
  }
  

• When you're happy with your design, generate HTML documentation for your project as described in the Project Description. Notice that this time your documentation goes in a directory named HW2/Design.

• Check that the generated documentation is okay; point a browser at http://www.cs.trinity.edu/~yourusername/CSCI1321/HW2/Design and check that all the comments you wrote -- for classes and methods -- show up.

• Turn in your design by sending me mail telling me it's ready to be graded. Please use a subject line such as ``csci 1321 design 2''.

Code

For this assignment, you have to write a number of classes, described in the next section (``Classes for this assignment''). This section describes the overall procedure.

Step-by-step instructions

• Open the project you created in the design phase.

• For all the classes and methods you created in the design phase, fill in whatever code you didn't write in the design phase. (E.g., you will probably have most of the code for your block classes, but you might not have filled in the methods in your screen class.)

• Revise and debug until you're happy with how your code compiles and executes.

  When you get everything right, starting your program (by running its main class, as you did in the previous assignment) will pop up a window much like the starter game, except with a screen and blocks that you created, rather than the starter screen and blocks.

• Generate HTML documentation for your project as described in the Project Description. Check that the generated documentation is okay; point a browser at http://www.cs.trinity.edu/~yourusername/CSCI1321/HW2/Final and check that all your documentation comments show up.

• Turn in your code by sending me mail with all of your source code files (.java files) as attachments. (It's probably easiest to just use the Web interface to Outlook for now, but ask me if you want to learn about Linux mail programs.) You don't need to send me .class files or the JAR file. Please use a subject line such as ``csci 1321 code 2''.

  If you're not sure where to find your source code files: If you called your project HW2, look in subdirectory HW2 in your Eclipse workspace directory. Descend into subdirectories until you find files with extension .java and the names of your classes and interfaces. The ``General requirements'' section of the Project description has information about other approaches.

Classes for this assignment

(Read, or at least skim, all of this section before starting your design.)

As you may have noticed from browsing the API for the game framework, many classes and interfaces are generics defined in terms of two basic types, one that extends Block and one that extends GameEntity. These two interfaces are themselves generics defined in terms of Block and GameEntity, and if this sounds to you like infinite recursion -- yes, but this can be avoided by you writing your own class or interface for each of these basic types. I'll call these YourBlock and YourEntity here, but you should give them names related to your game (e.g., PacManBlock and PacManEntity). You will then use these types everywhere the framework wants types that extend Block or GameEntity. YourBlock, and all of your game entity classes will be For example: In Homework 1 you had a MainFrame<BasicBlock,BasicEntity>. In this assignment you will replace that with a MainFrame<YourBlock,YourEntity>.

To make this happen:

• YourBlock needs to be a subtype of Block. There are two ways to make this happen: It can be an interface that extends Block, or it can be a class that implements Block.

  Making YourBlock an interface involves much less code; in fact, all you need (other than the usual package and import statements) is the following line:

  public interface YourBlock extends Block<YourBlock,YourEntity> { }
  

  The idea is that all of the classes you write to represent blocks will implement this interface. So your comment describing this class could be something like ``this is an interface that all the block classes for my game will implement.''

  The alternative is to make YourBlock a class, possibly an abstract class, and make all of your other block classes subclasses of YourBlock. This is a good choice if you find yourself writing the same code over and over in your block classes, since then you could put that common code into YourBlock and have it inherited by the other block classes. You can model this class on BasicBlock, for which source code is provided as part of this assignment.

• Similarly, YourEntity needs to be a subtype of GameEntity, and again you have two choices (make it an interface, or make it a class). For this assignment I strongly recommend making it an interface; if later this turns out to be a poor choice, you can change it. The code is similar:

  public interface YourEntity extends GameEntity<YourBlock,YourEntity> { }
  

  As with YourBlock, the idea is that all the classes you write to represent entities -- including the player -- will implement this interface.

Once you have definitions for YourBlock and YourEntity, for this assignment you will write the following additional classes. (This is not as overwhelming as it might sound; for most of these classes you have starter code that you just need to modify.)

• At least one concrete (non-abstract) block class (implementing YourBlock). Since YourBlock extends Block, each block class needs to provide all the methods in Block. Some of these methods use library classes we won't talk about until later in the term, so included with this assignment is code for the blocks in Dr. Lewis's starter game, BasicBlock. You should copy the code for this class into each of your block classes and modify any parts that seem to need modifying. (If you don't understand yet what something does, leave it alone.) Be sure to change the package line so that the class belongs to your package rather than to edu.trinity.cs.gamecore.basic.

• Your own version of the player class for the starter game. (This is needed because to plug correctly into the framework the player needs to be a subtype of YourEntity, which is only possible if you have your own class for it.) You will write a better version of this class in the next assignment; for now, just copy the code for Dr. Lewis's BasicPlayer class (included with this assignment) and change its name (to something that fits in your game, e.g., PacManPlayer), the package line (to put it in your package), and all uses of BasicBlock and BasicEntity (to YourBlock and YourEntity respectively).

• A game setup class, i.e., a replacement for Dr. Lewis's BasicGameSetup. For this class you also get starter code (the code for BasicGameSetup); you should copy this code into your class (which you could call, e.g., PacManSetup) and change all uses of the starter classes (BasicBlock, BasicEntity, BasicScreen, and BasicGameSetup) to the interfaces and classes you write in this assignment (YourBlock, etc.). Over the course of the next few assignments you will probably make several changes to the methods in this class, to customize it for your game, and you can start doing this now. Comments in the code explain how all the methods fit into the game and how you might want to change them.

  Once you've written this class, you will need to use it instead of BasicGameSetup in the main method of your main class (the one you wrote for Homework 1).

• A screen class, i.e., a class implementing the Screen interface. (You could call it, e.g., PacManScreen.) This is the only class you have to write from scratch for this assignment, and it will include a number of methods, but most of them will be very short.

  To find out what methods you need in this class and what they are supposed to do, look at the project API for the Screen interface. At this point not all the methods will make sense to you; for those that don't (and the documentation should give you some hints about which ones these are), just write skeleton/stub versions, with comments that indicates you'll fill them in later. If one of these methods is supposed to return something, have it return 0 or null for now. It's up to you to decide what variables your class will need, but you will almost certainly need a two-dimensional array of blocks (i.e., a two-dimensional array of YourBlocks) and a list of game entities. For the list of game entities, for now you should use the GameEntityList class in the framework. (Later you will write your own replacement for this class.) GameEntityList is described in the project API and included in this assignment's JAR file.

For initial testing, you should write your game setup class so that it directly creates a screen and fills it with blocks. Once you're reasonably confident that your screen and block classes are working, you may want to use Dr. Lewis's screen editor (see ``Links and files'' below) to actually build screens for your game. This is a nice visual tool that allows you to build screens using your block classes and save them in a binary format that can be read into your game in the constructor of your game setup class. There is commented-out code in the starter version of this class that you can use as a model for doing this. Warning: Do not put too much effort at this point into creating elaborate screens using the screen editor; almost any change you later make to your screen or block classes will make it necessary to start over (because the saved binary-format representation will no longer be valid -- later in the semester we'll talk about why). However, do try out the screen editor, to make sure the parts of your screen and block classes that interact with it are working right.

Files and links

• The JAR file for this assignment, PAD2S08Assn2.jar. Notice that this is different from the JAR file for assignment 1; it doesn't include some of the starter classes that you should be replacing.

• Starter source code:
  • BasicPlayer.java. You should copy this code into your player class and modify as needed, as described above.

  • BasicBlock.java. You will probably want to cut and paste code from this class into your block class(es).

  • BasicGameSetup.java. You should copy this code into your game setup class and modify as needed.

  If your browser doesn't do a nice job of displaying .java files (flowing the whole file into one big paragraph rather than showing it with separate lines), you should still be able to get the above files by downloading (saving) them rather than trying to display them. (E.g., in Firefox, you right click on the link and then select ``Save link as''.)

• Project Description.

• Project API (Lewis game framework).

• Java library API.

• Help for Dr. Lewis's screen editor program. Instructions for starting the program can be found under ``Project tools'' near the end of the Project Description.