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

Credit

Design 20 points; code 40 points.

Overview

In this assignment you will begin to design and implement a class for your ``player'' -- the little character that goes running around on your screen. (If your game doesn't have something fitting that description then you should come to talk to me about what you need to do for this assignment.) For this assignment the player needs to do two things:

• Respond to keyboard or mouse input.

• Interact in a meaningful way with the other things you have implemented so far -- in particular, it should interact with your block classes in whatever way is right for your game, such as not going through walls.

You should try to take the design a little further and also think about what will be needed in your player for other aspects of the game (e.g., interacting with other game entities). You probably won't get it completely right at this point, but thinking now about all the functionality you eventually need will probably help you spot potential problems earlier.

Design

The design for this assignment will include a description of the player class you will write and its methods. The comments at the top of the class should describe (1) how your player responds to mouse or keyboard input (e.g., ``my player moves up, down, and sideways when the user presses the arrow keys'') and (2) how your player interacts with your block classes.

To fit into the game framework properly, the class needs to implement two interfaces: the ``general entity type'' (YourEntity) you wrote for the previous assignment, and also the framework's Player interface (parameterized with your block and entity types, i.e., this class should implement Player<YourBlock,YourEntity>).

As before, for the design step you can just provide skeleton or stub code for the methods. You should also look again at your descriptions of classes you wrote for previous homeworks and see if they need to be improved or updated. Remember that I want at least a short comment about every class and every method. Writing these comments before writing the code encourages you to ``think first, then code''. They also help human readers of your code understand how everything fits together.

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).

• Copy over all your code from the previous assignments. (You should be able to do this with cut-and-paste in Eclipse. Drag-and-drop seems to do a move rather than a copy, so you probably don't want to use that.)

• Edit the player class you wrote for the previous assignment. You need to make two kinds of changes at this point:
  • Put in comments describing how your player responds to input and interacts with blocks.

  • Change the class declaration so that the class implements the two interfaces mentioned above (YourEntity and Player<YourBlock,YourEntity>), and put in skeleton/stub methods for the methods of these two interfaces. Put in comments describing what these methods do. You can cut and paste these from the project API. (If you do this, notice that the project API displays both one-liner comments for each method, in the ``Method Summary'' section, and longer comments below. You may find the latter more helpful.)

• 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 HW3/Design.

• Check that the generated documentation is okay; point a browser at http://www.cs.trinity.edu/~yourusername/CSCI1321/HW3/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 3''.

Code

Like the previous homework, this one will have you writing and editing a fair bit of code. the class for your player could easily be the largest class in your game. However, you don't have to write all of it now, just the beginnings of it. Over time you will probably also wind up writing other private and public methods for your player that help it get things done as well as allow it to interact with other parts of your game. Some of the key things you will write are the following.

• getUpdateTime and update methods: Your player is a game entity and as such will be added to the event queue used by the game to make sure that things get updated as the game is played. Currently this is done in the game setup class (the one that implements GameSetup) using the game framework's implementation of a priority queue. As you write additional game entities, you will add them to the priority queue as well. Later in the semester we will talk more about priority queues, and you will write your own implementation. The game framework uses this queue to move things around, as follows. The queue is kept in order by the time (in game ticks) at which the entities next want to be updated, which is based on what they return from their getUpdateTime methods, At each game tick, the framework finds every entity on the queue that wants to be updated at that tick and calls its update method, passing it the current time (in game ticks). This update method is where the game entity's state, including position, should be altered. Positions are represented using the game framework Location class and include a reference to a Screen and coordinates of a block within that screen. This allows your player to figure out what kind of block it currently occupies and what kinds of blocks are nearby. Notice that almost all of the framework classes are generics that need to be parameterized with your block and entity types. (E.g., locations have type Location<YourBlock,YourEntity > rather than just Location.)

• Methods for processing user input: Your player also needs to be able to accept and deal with inputs from the user. The game framework makes sure that when the user does something (with the keyboard or mouse) it will be passed to your player class. How it does this is something that we will discuss in more depth later. For now what you need to know is that if you want your player to respond to keyboard input you need to implement the interface java.awt.event.KeyListener, and if you want your player to respond to mouse input you need to implement java.awt.event.MouseListener and/or java.awt.event.MouseMotionListener. Look at the Java library API documentation to see what methods you need for these interfaces and what information you have to work with. For keyboard input, you probably should use keyPressed and keyReleased rather than keyTyped because this gives you more control over what is happening. For mouse input, the game framework class MainDisplay provides a nice method getClickLocation to help you convert the position as known to the Java library classes into a game-framework Location. (See me for more details if this sounds like something you want to use.) You will need to think a bit about the interaction between these methods and update, because the listener methods are called when the user does the appropriate thing with the keyboard or mouse, but you probably want all changes to the actual player to be made in update. I recommend that you have the listener methods just set variables in your player class and have update determine how to move by looking at these values. (E.g., for keyboard input, you might want a boolean for each key you want to use, representing whether it has been pressed.)

The combination of update and listener methods should give you a player class that takes input from the keyboard or mouse and uses it to move around any screens that you have built. The movement should be appropriate for the blocks that are present -- for example, if you have wall blocks or other obstacles, the player should not be able to move through them. In a side-view game the player should also fall if not supported by something, and you might want to implement some way for the user to make the player jump. If you have blocks that are supposed to change when the player moves onto them, you should implement that as well in this homework.

As mentioned above, the player's position is represented as a Location (a class in the game framework). Notice that this class is immutable. The value passed to setPartialsInWhole determines whether entities move around in whole-block units or in smaller steps. A value of 1 makes things such as collision detection easier, but a larger value gives you smoother motion. The partialMove method is useful for moving entities around without having to keep track of whether you are about to run off the edge of your screen.

This might also be a good time to start using Dr. Lewis's screen editor (links to information on starting and using it below) to lay out screen(s) for your game. (You don't have to, but the alternative is to create the layout with code in the constructor(s) of your screen class, which can get tedious for all but the simplest layouts.) This tool saves the layout you create in a file (name decided by you); commented-out code in BasicGameSetup shows how to then read from this file into your game. I recommend that you not invest a great deal of time right now making elaborate layouts; files you create may become unreadable if you make certain kinds of changes to your classes, so you should save this kind of polishing until later in the semester.

Step-by-step instructions

• Open the project you created in the design phase.

• For all the methods you created in the design phase, fill in the code to make your player behave as you described (or at least enough to make it respond to user input and interact with blocks).

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

• 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/HW3/Final and check that all your documentation comments show up.

• Turn in your code by sending me mail with all of the files I need to compile and run your game as attachments. This includes all source code (.java files), any file(s) created using the screen editor, and any file(s) containing images. (It's AOK at this stage to be using very simple block graphics, but if you're using something more complicated involving, e.g., GIF or JPEG files, you need to send me those as well). You don't need to send me .class files or the JAR file, but if it's simplest for you just to send me all the files in the directory for your Eclipse project, do that. It's better to send a bit too much than not enough!

  If you're not sure where to find your files: If you called your project HW3, look in subdirectory HW3 in your Eclipse workspace directory. Files created by the screen editor will probably be right there; source code files will be in a subdirectory based on package name. The ``General requirements'' section of the Project description has more suggestions about how to send me the needed files.

  Please use a subject line such as ``csci 1321 code 3''.

Files and links

• The JAR file for this assignment, PAD2F08Assn3.jar. Notice that this is different from the JAR files for the previous two assignments; it doesn't include the starter classes that you should be replacing.

• 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.

• Help for Dr. Lewis's image editor program. Instructions for starting the program can be found under ``Project tools'' near the end of the Project Description. This is a nice program for creating images for your blocks and entities, but if you have another favorite tool, you can probably use that. Ask me for details about loading images from files.