CSCI213
Autumn Session, 2007

Assignment 2: Simple class hierarchies

• Aims
• Objectives
• Framework
• Task
• Submission

(You should complete the exercises for laboratory exercise 2 before attempting this assignment.)

Aims

The aims of this assignment are to:

• introduce OO programming features including class hierarchies, heterogeneous collections, polymorphism, and dynamic dispatch;
• give you practice in the task of integrating your own code with code of a framework.

Objectives

The assignment involves writing a "Monster" abstract class and a set of subclasses that define specialized monster subclasses that can be used with supplied code for an "adventure" game like "Hack" or "Rogue".

On completion of this assignment you should be able to:

• define class hierarchies involving an abstract base class and a number of concrete subclasses;
• correctly use features such as protected members and mechanisms for invoking partial implementations of functions defined in a super class.
• work with code that exploits heterogeneous collections and polymorphic references.
• be able to explain standard OO concepts including "heterogeneous collection", "polymorphic reference", "dynamic binding"
• and, by reference to the lecture material, be able to explain the mechanisms used to implement dynamic binding in OO languages like C++ and Java.

Framework

Outline

You are supplied with working code for a part of a simple "adventure" game. Most of you will have played such games, or had a sibling that played such games; so lengthy explanations shouldn't be needed. All such games are based on the same simple themes:

• The player controls an avatar (player's game character) that explores a "dungeon" or some more elaborate virtual world.
• The game supplies the player with a view (graphical or, in older versions, textual) of the immediate game environment of the avatar.
• Keyboard commands allow the player to move the avatar, and to manipulate objects in the virtual world.
• While exploring the world, the avatar can discover and acquire treasure items.
• The world is populated by "monsters" - these do not welcome intrusion by the avatar and the avatar's habit of stealing treasures.
• In fact the sole purpose in life of the monsters appears to be to kill the avatar.
• There are many different species of monster with different characteristics. Although they all share the same essential behaviour:

  	if can attack player's avatar then attack avatar
  	else
  	if can detect player's avatar then advance toward avatar
  	else
  	go about own business
  

  each different species of monster has a different approach to the tasks. Some monster species rely on meleeing and can attack an adjacent player, others can use ranged attacks. Some monster species use vision to detect the presence of an avatar; others may use different senses and so be able to detect the avatar even when there are dungeon walls that block vision.
• Usually, the avatar is tougher than the monster so the player gets the joy of making a kill and indulging in a little subsequent looting of a corpse.

If you are a player, you will be using sophisticated massively multiplayer on-line games like Guild Wars, Warcraft, or Everquest, or offline single player games like NeverWinter Nights. But these games date back a long way. If you were playing in the 1970s, you would have played "Colossal Cave" (a single user game), or later "Rogue/Hack". In the 1980s, you could have played "AberMud" (a massively multiplayer on-line game with a text interface).

I didn't have the time to create a Guild Wars like framework, and you don't have the time to learn about such a framework. So the adventure game that you will complete is similar to a late 1980s version of Rogue (Hack, ...) with a simple graphical interface. By default, the game will appear something like the image shown here:

The display shows the (fixed) layout of the dungeon with walls:

that limit most movements. (The dungeon is defined via a grid of squares - a square may contain a wall or be an open square. An open square can hold one item - treasure, player, monster. Actually, as coded, a grid square can hold many treasures and monsters but only one will be displayed.)
The player avatar is (currently) represented by this image

(an alternative hero image may be used if this one is felt inappropriate). The image

represents one of the treasures.
The image:

represents one of the inhabitants of the dungeon.

The player controls movements of the avatar using the number keys - "8" moves the avatar up screen, "4" moves left, "3" moves diagonally down and right etc. The player acquires treasure items by causing the avatar to move to the same location; the player can attack a "monster" by moving the avatar to an adjacent location and then trying to move onto the monster's location.

The code that you are supplied with works. However, the dungeon has been depopulated. The classes that define the "Monster" abstraction and the concreter monster subclasses have all been removed.

Framework classes

The framework code supplied can be used essentially unchanged. Your changes (details below) can be limited to adding the names of a few more image files to the list of images of game elements (you will need images to represent instances of your different monster subclasses), and adding code that loads data defining the abilities and starting locations of individual monsters. The code for working with a collection of Monsters is already incorporated in the supplied code.
Your main work will be the definition of an abstract Monster class (that extends one of the classes supplied) and concrete subclasses. The code of the "Player" class that is supplied gives examples of how to move around the dungeon and interact with dungeon items.
Once you have completed the specified requirements of the assignment you may make further changes in the supplied framework code to enhance your own version.

The framework is supplied as a NetBeans project (in /share/cs-pub/csci213/A2). The files include a few images, a data file, and the source code files for the classes provided.

The classes in the framework are:

• DungeonGame.
  This is the main class defining the game. The main() function creates a DungeonGame object. This then loads data defining the layout of the dungeon and the initial locations of items like treasure, the player's avatar etc. The DungeonGame object then is "run" (more details below). The supplied code for loading the initial state of the dungeon requires some extensions.
• Display. Creates the GUI (a really simple one involving just one canvas) and handles the keyboard inputs that control the player's avatar.
• Images. Utility class, loads images.
• Map. Holds data defining the dungeon's layout and renders an image to screen.
• MyCanvas.
• Pt. Utility class, represents a point coordinate and supplies some auxiliary functions for checking adjacency of points and distance between points.
• DungeonItem. Abstract base class that represents anything that exists in the dungeon (treasures, player, monsters). They all have Pt locations, they all are associated with particular images etc.
• Collectable. Concrete subclass of DungeonItem; represents any type of treasure item
• ActiveItem. Abstract class extending DungeonItem, it represents common features of Player and Monsters. Players and Monsters both move, can be hit and suffer damage, can report if still "alive", and can "run". Class has some abstract methods, and some actual methods.
• Player. Concrete subclass of ActiveItem. Player's avatar. Gets to "run" every 0.5 seconds - then it checks whether any movement command entered by user, if none "run" function returns. If there was a movement command, an attempt is made to execute it - might result in attack on adjacent monster, movement to a treasure square and acquisition of treasure, simple movement, or failure (attempted movement into wall)
• Monster. Guts removed from this abstract class. You replace them.

JavaDoc documentation is available for the classes.

The following diagram shows the form of the class hierarchy for the game:

Object stuff! Polymorphism, dynamic dispatch, heterogeneous collections!!!

The following code fragment is from the DungeonGame class:

	private void showInhabitants()
	{
		for(Monster m: myCollectionOfInhabitants)
			m.show();
	}

The DungeonGame has a private data member:

	private Vector<Monster>	myCollectionOfInhabitants;

This is filled with Monster objects as these get read in the loadItems function called at startup. Of course, there are no instance of class Monster - it is an abstraction; instead there are instances of Monster subclasses ("Ghost", "Zombie", "Mugger", ...). The collection is heterogeneous (containing different types). In the showInhabitants function, the object reference variable m is polymorphic - referencing many different shaped objects. The dynamic dispatch mechanism would be invoked - though in this case all Monster classes will use the same implementation of show as defined in the base class DungeonItem.

private void moveInhabitants()
	{
		for(Monster m : myCollectionOfInhabitants) 
			m.run();
	}

The moveInhabitants function works through the collection of Monsters giving each its chance to do something. The "run" function that gets invoked here is probably the same and would be defined in abstract class Monster for it is this function that defines that common behaviour - if can attack then attack else if can detect then advance else carry on. However, the functions that define "can attack", "can detect" would be abstract in class Monster having distinct definitions in the Monster subclasses. So the functions that are invoked when run is called are specific to the type of object that is executing the run function. This is the dynamic dispatch behaviour - invoking the right behaviour for the particular object accessed via the polymorphic reference Monster m.

Task

You should be able to deploy the supplied NetBeans project and run the application. When the dungeon map is displayed, click on it with the mouse (to assign "keyboard focus"), then use numeric keys to move the player avatar. The "treasures" can be collected; when all are collected the program will terminate.

The layout of the dungeon and location of treasures is defined in the data2.txt file in the project folder.

Read the code of Images.java to see where you will have to define additional data elements for other images. Read the code of DungeonGame.loadItems to see where you will have to define additional code for loading data on monsters. Read the code of Player.java to get some ideas of how the framework code works.

Define abstract class Monster extends ActiveItem. You will have to define a run method and some other abstract methods. (You may find that you need to redefine your Monster class a couple of times as you explore different ways of factoring out code that is common to specific subclasses of class Monster).

Define at least four distinct concrete subclasses of Monster that illustrate different implementations of the "can attack", "can detect", "attack", "advance", and "go about normal business" functions. You should be able to draw on your own experience of such games for ideas as to different behaviours. However, here are some suggestions for those who have never played:

• Web spider monster - fills some adjacent squares with its web (not necessarily shown in display), if player's avatar enters a webbed square the spider detects this and responds by rapidly advancing and attacks when adjacent to the avatar (web may/may-not limit avatar motion).
• Blob monster - moves slowly and aimlessly all the time, if it moves onto square occupied by treasure/player/monster it consumes whatever was there (that feat might require some changes to supplied framework code). Does not deliberately move to attack player avatar.
• Jumping spider monster - sits still until avatar in visual range then jumps immediately to adjacent open square, attacks when adjacent.
• Ranger monster - defends one spot, uses visual detection, uses ranged attack
• Patrolling goblin monster - marches back and forth along a fixed route through dungeon until sees avatar, then either uses ranged weapon or advances to attack.
• Ghost monster - can detect avatar through walls, can advance through walls, doesn't do much damage in any attack but has own "health" rating that is so high that it cannot be killed (killed again?).
• Noisy attack monster - similar to one of the others but has extra feature of sounds playing (requires addition of code to load sounds - probably best placed as static method in DungeonGame class or in Images utility class).
• Student monster - use your imagination.

Do not create subclasses that differ only parametrically. For example, the following would count as a single class:

• Lazy student monster - sits on one spot till avatar adjacent then attacks for 2 damage each round
• Strong lazy student monster - sits on one spot till avatar adjacent then attacks for 3 damage each round

(It was OK for the Perl guys with their Animals, but here you have to do things properly!)

When there are only parametric differences, you use the same class. This is illustrated by the code and data supplied. The data include "GOLD" and "HEALTH" objects - but these are both just Collectable objects that differ merely in the image used and the values in other fields.

Add some tracer statements to your classes (and to framework classes if that is more appropriate) so that interactions between player avatar and monsters is logged.

Implement your Monster subclasses, add data to the "data2.txt" data file defining instances of your classes, run the game with an inhabited dungeon.

You will have to read the JavaDoc descriptions to find out all the functions in Player, DungeonGame etc that you may want to use. JavaDoc only documents public functions. You shouldn't need to bother about the private functions; you would only be concerned with these if you were reworking the entire framework to add features (such as Monsters that can move treasures around).

All Monster objects are given a reference to the DungeonGame object in their constructor. One of the methods of class DungeonGame returns a reference to the Player object. One of the methods of a Player object returns its current location (this method inheritted from the DungeonItem base class). So, using a couple of method calls, a Monster object can find the current location of the player's avatar.

The DungeonGame class has a utitility method clearLineOfSight; this determines whether there is a clear line of sight between two points (no intervening walls) and also fills in a supplied array with the points along such a line if one exists. A Monster could use that function to determine whether it could "see" the player. Of course, some types of monster might sense the player in some other way and have a "canSee" function that did not require a clear line of sight, instead relying simply on distance between Monster and Player locations.

The Map provides functions like accessible that a Monster could use to determine whether it could move to a particular square.

How you use these and other functions depends on the behaviours that you wish to define for your Monster classes.

Submission

You are to submit a PDF formatted report file. This report file (prepared in a word processor such as Word and "printed" to PDF file) should contain:

1. Listings of the Java code for your classes - Monster and its subclasses, modified sections of Images class, modified loadItems function (do not include unmodified code)
2. Brief commentaries on each of your Monster subclasses explaining their unique approaches to solving the thieving avatar problem.
3. Screen shots of your program in use and a listing of the data file used to create dungeon as shown in your display
4. A listing of the tracer statements from your program showing some avatar-monster interactions.
5. Listings of other changes that you chose to make to the framework code.
6. Displays of JavaDoc documentation that you compose for your Monster abstract class and its subclasses. (JavaDoc HTML documentation uses HTML "framesets"; Word, and probably most other word-processor programs, will not let you merge frameset-style HTML documents into your main report document. The easiest way of including the JavaDoc in your report is probably to grab screen shots showing the documentation in a browser and paste these into the report.)

The due date for submission will be announced in lectures; the date will probably be around the end of week 6 of session (currently set for April 6th).

turnin -c csci213 -a 2  A2.pdf

Reminders as before

1. turnin isn't chatty you don't get email back
2. you can check that your submitted file is safely submitted via turnout program.
3. turnin only works if you are logged in to banshee - use ssh if you are on a different machine or workstation. (If turnin complains that it doesn't know about the assignment, you aren't logged in on banshee!)
4. Late turnin will work, you don't need to ask. Late turnin will be valid till midnight on the following Monday at a cost in marks.
5. Medicals submitted through official university SOLS channels cancel late penalty marks