CSCI 1321 (Principles of Algorithm Design II), Spring 2010:
Project Description

Contents

• Overview
• The game framework
• General requirements
• Assignments
• Hints and tips

Overview

The assignments for this course are all parts of a single project that spans the entire semester. For this project you will write code that integrates with code written by Dr. Lewis. His code forms a framework for arcade-style games, but is flexible enough to allow for a lot of variation, so you have considerable freedom with regard to exactly what kind of game you want to create. This page outlines the game framework and describes other requirements common to all the assignments.

The game that you will be writing is what you might call a screen-based or arcade-style game. Your game will have a ``player'' character controlled by the human player. The player moves around a playing field consisting of one or more two-dimensional ``screens''; the screens can be linked together such that when the player moves to a particular part of a screen it automatically jumps to another screen. Each screen is composed of a regular grid of blocks; blocks represent different things that the player character can interact with -- floor, walls, ladders, etc. You can have as many or as few kinds of blocks as you need for your game; blocks represent things that do not move but can change based on the player's actions (though this imposes other restrictions). In addition to the human-controlled player character, the playing field can be populated by other characters or entities. These entities can move around the playing field and interact with the player and each other. You can have as many or as few kinds of entities as you need for your game. It is simplest to make each entity (and the player) one grid cell in size, but the framework allows some flexibility in this regard. You will have access to two tools, a ``screen editor'' program program to lay out the playing field and an ``image editor'' program to create graphics for your blocks, player, and other entities. (Be advised, however, that you can also use graphics files created with other programs.)

The state of the game advances roughly 20 times each second; we'll call this interval a ``tick''. Each entity (including the player) has a method that gives the next tick in which it wants to be updated and a method that describes how it should be updated. Using these methods, on each tick the game framework identifies all the entities (player and others) that want to be updated in that tick and then updates them.

You should note that there is a lot of flexibility here, and you have significant control over exactly what you produce in the end. I encourage you to be creative, but remember that you need to be able to implement your design, and it will probably be more satisfying to finish something not too complicated than to tackle something overly ambitious and not be able to finish it. If you want to try something ambitious, try to think of a way it can be scaled back into something still playable if the original design turns out to be more difficult than anticipated. I also encourage you to focus your creativity on functionality rather than appearance; your grade will be based mostly on functionality, and I think you will learn more by making your game do interesting things than by focusing too much on the details of appearance.

The game framework

To write your game, you will need to create subclasses of several interfaces defined as part of Dr. Lewis's game framework. If you do this, your code will fit together neatly with the framework code that defines the main GUI for the program and provides the 20-updates-per-second functionality, The main interfaces for which you need to write code are as follows. Refer to the project framework API for details.

• Screen. You will probably create only one subclass of this interface; each instance represents a screen in your game and holds a two-dimensional array of blocks for the screen and a list of entities currently located on the screen.

• Block. You will probably create several subclasses of this interface. Usually they will be simple classes that represent building pieces from which you make screens -- walls, ladders, background space, etc. Blocks cannot move, but they can change appearance.

• GameEntity. This interface represents anything that is dynamic in your game -- anything that changes form or moves during the game will be some form of GameEntity. You will probably create several subclasses of this interface.

• Player. You will make one Player subclass; your program will need one object of this class to represent the player character. The Player interface is a subclass of GameEntity.

• GameSetup. You will make one GameSetup subclass; your program will need one object of this class in order for the framework to get the main pieces of information it needs (e.g., a reference to the Player object).

General requirements

Each assignment consists of two phases, design and code. For each phase, you will turn in something by e-mail, which you should just send to my regular e-mail address (bmassing@cs.trinity.edu). When you do this, please use a subject line that mentions the course number/name and which assignment you're turning in (e.g., ``csci1321 hw1 design'' or ``PAD II hw1 design''). Assignments are due at 11:59pm on the date given on the ``Lecture topics and assignments'' page; I will use the timestamp on the e-mail to determine whether they are on time.

I strongly encourage you to do the assignments using Eclipse, though you can use some other tool(s) if you prefer. I also encourage you to create a new project for each assignment, and to put your code in a package named according to the Java conventions for packages (edu.cs.trinity.yourusername.yourgame, where yourgame is something descriptive of your game -- e.g., pacmanclone). For all the assignments except the first one, once you have created a new project you can simply copy into it the package from the previous assignment.

Design

You will be turning in design documentation prior to every assignment for this class. You will also turn in modified/finalized designs when you turn in each of the assignments. This sounds like it might be a lot of work, but with Java documentation comments and Eclipse it is pretty easy. When you write your code, you will include documentation comments (``Javadoc comments''); you can then use Eclipse's built-in feature or the javadoc command to turn these comments into HTML. (The API for the project framework was generated in this way.)

To make it easy for me to find everyone's documentation, I want you to put yours in a specific place in your home directory on the department's Linux file and Web server, where it can be accessed via a Web browser. (You can have Eclipse put it there directly, or you can copy it there later.) Anything you put in Local/HTML-Documents in your home directory can be accessed from the Web (assuming it is world-readable). So: Within this directory, create a subdirectory CSCI1321. Documentation for individual assignments will go in subdirectories of this directory -- HW1 for Homework 1, HW2 for Homework 2, etc. Within each of these subdirectories there should be a subdirectory Design containing documentation generated in the design phase and a subdirectory Final containing documentation generated in the code phase. (Usually these will be pretty similar, but maybe not always.) So, for example, your documentation for the design phase of Homework 1 should go in Local/HTML-Documents/CSCI1321/HW1/Design. Notice that case is significant on UNIX systems (e.g., Design and design are different).

Step-by-step instructions for each assignment

• Create an Eclipse project for the assignment and add the JAR file for the assignment to the build path. (For the first assignment, you can put off this step until the code phase.) To do this, first download a copy of the file using the link on the assignment page and put it some appropriate place (such as the directory for the project, in Eclipse's workspace). Then right-click on the project name and select Build path, then Configure build path, then the Libraries tab, then Add external JARs (Add JARs seems to work too, if the JAR file is in the project directory/folder in the workspace.)

• Create or modify classes as described for the particular assignment. Notice that you don't have to have working code at this point, but you probably do need at least skeleton versions of all the methods you plan to write. By ``skeleton versions'' I mean versions with the proper names, parameters, and return types, but no code other than what is needed to compile (e.g., return 0 in a method that returns an int.).

• Generate HTML documentation. You can do this from Eclipse's Project menu. It's probably simplest to have Eclipse put it in the appropriate place in Local/HTML-Documents to start with, but you could also move/copy the files after the fact.

• Set permissions on the generated files so the department's Web server can access them; what is needed is for them to be readable to everyone. The simplest way to do this is to use the following commands (in a terminal window):

  cd ~/Local/HTML-Documents
  chmod -R go=rX CSCI1321

  (Type man chmod to read more about what this does.) Notice that if you re-generate the documentation you may need to repeat this step.

• To check that you've done everything right, point a browser at, e.g., http://www.cs.trinity.edu/~yourusername/CSCI1321/HW1/Design. You should get something that looks like the project and Java-library documentation, and it should include all the javadoc comments you wrote. (I strongly encourage you not to skip this step; it serves as a safety check that you have permissions set correctly and that the generated documentation contains everything you intended for it to contain. Notice that you should use a URL like the one above rather than one beginning file:; using a file: URL will not tell you whether permissions are set correctly.)

• Once you're happy with your documentation, send me e-mail telling me your design is ready to be graded, using a subject line that mentions the class and the assignment. Please leave the documentation files in place for the rest of the semester so I can track your progress.

Notice that unless you want your code to also be world-readable (which I think you don't at this point), you probably should not put it in Local/HTML-Documents.

A final note about the format of the documentation comments: Since they will be turned into HTML, you can use HTML tags to do any formatting. For example, if you want multiple paragraphs, you can get this by enclosing each paragraph in <p> and </p> tags. If you know more HTML, you can incorporate additional formatting such as tables, if you think that will make your meaning clearer.

Code

For the code phase of each assignment, you will be turning in code and also generating a final (for that assignment) version of your documentation. To turn in code, I want you to e-mail all the relevant files to me -- the .java files that contain your source code, plus any image or other files needed to run your game, as described below.

Step-by-step instructions for each assignment

• Open the project you created in the design phase, and fill in code as needed for the specific assignment. Of course you can add new methods or classes if you discover that you need them.

• When you're happy with how the code compiles and runs, generate a revised version of the HTML documentation, putting it in a directory Final as described above, and set permissions as described above. Check it using a browser, as described above.

• Send me mail with all your .java files as attachments and a subject line that mentions the course and the assignment.

  The .java files can be found in the directory that contains your Eclipse workspace; that directory will contain a subdirectory for every project, and each of these directories will contain a src directory containing source code. The simplest way to mail me these files is probably to just use your favorite e-mail program and attach the desired files as attachments. (Please do not try to cut and paste code into the body of a mail message; this may result in garbled code.)

  If there are so many files that this becomes tedious, you can also just send me your whole Eclipse project for an assignment. An easy way to do this under Linux (and this should work under Mac OS X too), is to (in a terminal window) cd to your Eclipse workspace directory and then use the tar command to create an archive file. If your project is called HWn,

  tar czf HWn.tgz HWn

  creates a file HWn.tgz containing everything in directory (project) HWn. (Type man tar to read more about what this does. Typing tar tzf HWn.tgz shows a list of files in the archive and may be helpful in checking that it contains the files you intended to include.)

  You can then send me the single file HWn.tgz.

  To include only the Java source files, you can do this slightly more complicated version:

  tar czf HWn.tgz `find HWn -name "*java"`

  (Notice that the outermost quotes are backquotes.)

Assignments

This section summarizes what you will do in each assignment. Follow the links for more complete descriptions.

• Homework 1 (main): For this assignment you will write a class to hold the main routine for your program. (You will use starter versions of all the other classes.) This class will have a lot of comments describing your game design but very little code; the purpose of the code phase is to give you experience in writing and running a simple Java program.

• Homework 2 (screen, blocks, game setup): In this assignment you will begin to personalize your game, by starting to write your GameSetup class and by writing your Screen class and some of your Block classes. (Starter versions of some of these classes will be provided.)

• Homework 3 (player): Here you will further personalize your game by starting to write your Player class. You will probably add to this class throughout the project; for this assignment it just has to interact with at least some of the Block classes you defined in the previous assignment.

• Homework 4 (game entities and entity list): Here you will start to write the GameEntity classes for your game and also write a class that represents a list of such entities. You will also modify your Player class to interact with the new entities. At this point the non-player entities do not need to move, just interact with your player character.

• Homework 5 (moving game entities and priority queue): For this assignment you will write additional GameEntity classes and also write a class that represents an ordered list (priority queue) of game entities. At this point some of your game entities need to be able to move or at least change (so, animated entities could work).

• Homework 6 (GUI elements): For this assignment you will write code that adds to the GUI provided by the framework. You will have several options, including adding status panels to any or all sides of the main display area for the game, adding to the menu bar for the game, and writing ``edit properties panels'' that work with the screen editor.

• Homework 7 (priority queue, revised): This assignment is a little different in that it is not really a stage in development of your game. Instead, you will be writing a different version of the priority-queue class you wrote for Homework 5, plus code that will allow you to compare the performance of the two versions.

• Homework 8 (final touches): In this assignment you will add finishing touches to your game -- finish parts that are incomplete, fix bugs, improve its functionality or appearance, etc. If all goes well, when you are done you will have something that people can enjoy playing.

Hints and tips

Eclipse

Creating a project using Eclipse was demonstrated in class. Some things to keep in mind:

• The game framework requires Java 5.0 or later. The version of Eclipse installed on the CS Linux machines this year uses Java 6 by default, but be aware that older versions of Eclipse may not. You should be able to reconfigure if needed from the Project menu, item Properties.

File transfer

If you plan to install Eclipse on your own computer and work on your game there, at some point you will need to transfer files from your computer to your home directory on the lab machines, and possibly vice versa. There are several ways to do this:

• Graphical options:
  • You should be able to access your home directory from Windows machines on campus by bringing up the Windows Run menu and typing in \\sol.cs.trinity.edu. This should show you some printers and a folder representing your home directory. Sometimes this seems not to work with Windows Vista; come talk to me if it does not work for you.

  • You should also be able to access your home directory from any computer on campus via a graphical FTP client, as long as it communicates using SSH encryption. Pointing it to any of the lab machines should work.

• Command-line options:
  • UNIX-like operating systems (including Linux and Mac OS X) should have commands for file transfer over an SSH-encrypted connection:
    • scp is ``secure copy'' and works more or less like cp, except either the source or the target can be of the form username@machine:path. You can use wildcards and/or the -r option to copy many files at once.

    • sftp is ``secure FTP'', a command-line FTP client.

    For more about these commands, look at their man pages, and/or ask me.

  • There are various possibilities for Windows; I recommend Cygwin, a free UNIX-like environment available from http://www.cygwin.com/. Once installed, it allows you to bring up something that looks and behaves more or less like a terminal window on a UNIX/Linux system, so you can use the commands described above.

If you want to be able to work on your game on your own machine and also on the lab machines, you could use any of these approaches to simply copy all needed files back and forth. The files you would need to copy are the .java files from your Eclipse workspace, plus any other files (e.g., images) needed to run your game. Or you could use CVS, described below.

CVS

As noted above, if you want to be able to work on your game on your own machine and also on the lab machines, you can just copy needed files back and forth. A less tedious and more professional approach is to use CVS; the drawback of this approach is that it is somewhat more work to set up. The idea of CVS (and other similar tools) is that you have a master copy of your files in one centralized place (a ``repository''), and then you have local copies on every machine where you want to work on them, which you ``check out'' from the repository before starting to make changes, and ``check in'' to update the master copy. Below is a short overview of using CVS with Eclipse -- far from complete or comprehensive, but perhaps enough to get you started.

• Initial setup:
  • Create a ``repository'' to hold master copies of your files. The following command creates a CVS repository in directory /users/yourusername/CVS on the lab machines:

    cvs -d /users/yourusername/CVS init

  • Tell Eclipse about this repository. From the Window menu, select Open perspective, then Other, then CVS Repository Exploring. You should get a CVS Repositories tab with some icons, one of which will start up a wizard to add a repository. You will need to fill in a hostname (any of the lab machines will do -- the Xena machines are good choices since they're usually booted into Linux), path (e.g., /users/yourusername/CVS), username, password, and connection type (extssh).

    You will need to do this for every Eclipse workspace you want to use to access the repository. Use Open perspective to go back to the Java perspective (called ``Java (default)'').

• Putting a project into the repository for the first time:

  Select the project name in the Package Explorer tab and right-click to bring up a context menu. Choose Team, then Share project. This should bring up a wizard that guides you through the process.

• Checking a project out of the repository for the first time:

  There seem to be several ways to do this. One that has worked for me is to create the project by checking something out of the repository:

  From the File menu, choose New and then Project, then look for the option Checkout Projects from CVS (it may be hidden under CVS). This should bring up a wizard that guides you through the process.

• Checking files in/out once everything is set up:

  There seem to be several ways to do this too. Local CVS expert Dr. Lewis recommends using the ``synchronize'' option:

  Select the project name in the Package Explorer tab and right-click to bring up a context menu. Choose Team, then Synchronize With Repository. This should bring up a perspective that lets you do a lot of things. In particular there are icons for ``Update all incoming changes'' (check files out of repository) and ``Commit all outgoing changes'' (check files back into the repository).

  Use Open perspective (from the Window menu) to go back to the Java default perspective.

Command-line Java tools

Remember, too, that you can compile and run Java programs and even generate HTML documentation using command-line tools, if for whatever reason you can't or don't want to use Eclipse. See Java Without an IDE for details. If you do this, the next time you open the project with Eclipse, it should pick up any changes you made with other tools. (If it doesn't seem to, right-click on the project name and select Refresh.)

Project tools

Dr. Lewis has written two programs that you may find helpful, a ``screen editor'' program program to lay out the playing field and an ``image editor'' program to create graphics for your blocks, player, and other entities. To run one of these programs, you have two options:

• From the command line. Go to the directory containing your project and type the following (all on one line):

  java -classpath .:jarfile.jar edu.trinity.cs.gamecore.ScreenEditor yourscreenclass binfile

  for the screen editor, or

  java -classpath jarfile.jar edu.trinity.cs.gamecore.ImageEditor

  for the image editor.

  jarfile.jar is the JAR file for the assignment, yourscreenclass is the fully-qualified name of your screen class (e.g., edu.trinity.cs.yourusername.YourScreen), and binfile is the file where you want to store the results (for the screen editor only).

  (Of course you won't want to type this in often; if you want to take this approach, ask me how to make a small script or alias so you don't have to type the whole command every time.)

• From Eclipse: There are probably several ways to do this. Probably the best way in the long term is to create a run configuration. From the Run menu, select Open Run Dialog. Create a new configuration, and fill in the Main tab (give your project name, and then either edu.trinity.cs.gamecore.ScreenEditor or edu.trinity.cs.gamecore.ImageEditor as the class) and (for the screen editor only) the Arguments tab (give as program arguments yourscreenclass and binfile as described above).