W06 CS349|SE382 : Assignment 1

Due Date

Thursday, Feb. 2, 2006 at 23:59
Lates accepted until Sunday, Feb. 5, 2006 at 23:59.

Goals

To demonstrate your:

• understanding of the low-level operation of event loops.
• abilities to read and apply documentation for a new toolkit (X windows) to implement 2D graphics.
• management of the sequence of things that occur in the user interface.
• ability to tune the speed of a game.

Change Log

• 2006-01-27: Clarified the due time. Extended late period to include the weekend. Changed the files to be submitted to be more general. See below.
• 2006-01-17: Minor modifications to the README.txt template file.
• 2006-01-13: Added a Hints section, below. The entire level is in view at one time (no scrolling required).

Program Description

One of my favourite early computer games was LodeRunner. In this game a runner is under the control of the user. It's goal is to collect all of the bags of gold in its environment. The environment consists of floors, ladders, and horizontal bars. The environment is divided into an arbitrary number of levels, only one of which is visible (in its entirety) at any given time. The runner begins with, say, five lives.

Screen shot of a downloaded version of LodeRunner.

Screen shot of Byron's sample solution.

The runner can:

1. Move left and right on top of the floors.
2. Climb up and down ladders.
3. Move hand-over-hand below the bars.
4. Fall off the end of a floor or bar, and move off the side of a ladder; in such cases the runner falls straight down until it encounters a floor, ladder, or bar.
5. Drop off a bar, falling as above.
6. Climb up a ladder to the next level in the environment.
7. Pick up a bag of gold, simply by running into it.

Unfortunately, the environment is also populated by one or more goons. A goon has the same capabilities as the runner, but with the following differences:

1. Goons are not under the user's control.
2. Goons also pick up bags of gold, but put them down again a little while later at a different location (runners never put down the bags of gold they collect).
3. In general, goons move towards the runner.

When the runner and a goon collide, the runner dies. If it has no lives left, the game is over.

The above seems like a reaonable goal for your implementation of the game. Additional features of the original game include:

1. The runner is able to blast a hole in the floor beside itself. The hole exists for several seconds, during which time a goon (or the runner!) may fall into it. Once in a hole, neither goons nor the runner can get up out of the hole. Within a few seconds the hole begins to fill in. When it has completely filled in, a goon reincarnates at the top of the environment. A runner caught in such a situation dies. The runner may blast a series of holes (blast, move, blast, move, etc) and then jump into the large hole, blasting away another level. This can be repeated a number of times to blast through several layers of floors.
2. Some floors cannot be blasted. These are shown as solid floors; blastable floors appears as interlocked brick.
3. Some floors do not support the weight of the runner or goons; they fall through.
4. There are several varieties of goons. Some are constrained to certain regions of the environment while others may have other strategies for determining their movements.
5. The ladder to the next level only becomes available after all the gold in the current level has been collected by the runner.

Googling "lode runner" or "loderunner" reveals many pages referring to the game. One free download that captures the look and feel of the game I knew years ago is at http://www.gamehippo.com/download2/download2_1937.shtml. It's for Windows and has only two levels. The "readme" file is in German. Use the arrow keys to move the runner; n and m to blast holes in the floor. I couldn't find a way to end the program without simply killing it.

Requirements

Your program must meet the following requirements. (Please note that the "sample solution" referenced below is a proof of concept and should not be taken in any way as a definitive implementation. In particular, there are a number of requirements that it does not meet and if turned in it would earn a poor mark.)

Required to receive a non-zero mark

1. The program must be implemented in C or C++ using Xlib and an explicit event loop similar to Hello.C.
2. It must run in the undergrad computing environment on a black and white Xterm (that is, it's no use doing color; it won't help your grade at all).
3. It must be made from source using the procedure outlined in the Marking Precedure section, below.
4. It must move beyond the Hello.C program to implement some feature of the game.
5. The program must be implemented by yourself. (Actually, if it's not you will get a non-zero mark: -100%.)

Required to receive a passing mark

1. Your program must implement a runner, two or more goons. The runner must be under the user's control while the goons move independently. The movements made by the goons do not need to be smart.
2. Implement floors, which the runner and goons must react to. That is, at a minimum they must fall through space until they hit a floor and then run left or right along the floor.
3. There must be a way to tune the game to adjust its difficulty, typically by adjusting the speed at which the game moves. Your game should be tuned so that it is playable (not so easy that it's trivial; not so difficult that it's impossible). Your game should run at a constant number of frames per second, regardless of the tuning.
4. Control:
   • It must implement the following keys:

     Key	Effect on the game
     j	Move the runner left.
     l	Move the runner right.
     i	Move the runner up.
     k	Move the runner down.
     f	Make the game run faster.
     s	Make the game run slower.
     q	Quit the game.
     p	Pause the game.

     You may introduce any additional keys you feel are appropriate.
   • It must use the mouse and mouse buttons in some fashion, which is left up to you.
5. Good program design, code style, and documentation.
6. Subjective evaluation.

Required to receive a mark of 75%

1. The program must include ladders, horizontal bars, and stacked floors (that is, the possibility of a runner running into the side of a floor). The runner and goons must interact appropriately with them (not run into a floor from the side, fall off the edge of a floor, move up and down ladders as appropriate, jump off the side of a ladder, move across a bar, fall off the end of a bar, release a bar so it falls down, etc.)
2. It must include bags of gold in the environment that the runner and goons can collect. Goons, if they collect gold, must deposit it again someplace else in the level.
3. It must display at the bottom of the screen the number of gold bags that have been collected in this level and the number of bags that have yet to be collected.
4. Subjective evaluation.

Required to receive a mark of up to (and a little beyond) 100%

• Up to 12.5% is available for extending the program in ways of your own choosing. It might be to implement additional features of the original game or to add new features of your own design.
• Up to 12.5% is available for exploring new UI territory not covered by the earlier requirements and not discussed in class. The key component of this part of the assignment is figuring out some new interaction technique, not simply perfecting what you've already done.
• In recognition of the additional uncertainty of being among the first to work on an assignment, the instructor will assign up to a total of 20 bonus marks to those people who, in the instructor's opinion, ask the most helpful questions in the newsgroup. Each individual will be capped at 3 bonus marks for the assignment.

Marking Procedure

The marking procedure will consist of the following steps:

• cd to the directory containing your submission
• unzip a1.zip
• make
• ./LodeRunner

These steps will be performed in a completely standard account in the undergrad environment, using the standard paths that are provided by default. For example, which make refers to /usr/ccs/bin/make, and which gcc refers to /software/.admin/bins/bin/gcc. If in doubt, run init_home and then log in again to test your makefile.

There is a possibility that we will schedule times for you to show your program to a TA for marking. Final decision on this is pending further discussions with the TAs.

Resources

The following resources are available to you:

• Those listed on the resources page of this web site, including:
  • hello.C, a simple program using X.
  • A PDF of the Xlib programming manual and the URL of a web-based version of the manual. The PDF is particularly useful because it allows searching for commands found in hello.C to read their documentation and to learn about related commands that are typically found nearby.
• A proof-of-concept implementation by the instructor in /u/cs349/a/1/LodeRunner. It is executable, but not readable.

Handin

All of the files required to build your program. Note that one level of directiories may be included.

• makefile
• README.txt, a copy of this file with the relevant information filled in by you.
• *.[Cch]
• *.cpp
• *.cc
• *.hpp
• *.txt
• *.dat
• *.xbm
• */*.[Cch]
• */*.cpp
• */*.cc
• */*.hpp
• */*.txt
• */*.dat
• */*.xbm

Print this marksheet, fill in your part, and place it in the hand-in bins on the third floor of MC. Evaluate your program as honestly as you can. A bonus of 3% for the student(s) whose evaluations most closely match the TA's.