CIS 120 Homework 2 - AdventureGame

Due Friday September 25, 2008 at 11:00am.

(Zork opening screenshot, credit Wikipedia.org)

In this homework you will be creating the core functionality of a simple text-based adventure game. The goals of this assignment are:

• working with interaction between objects of different classes
• practice with object references
• practice working with concrete inheritance and interfaces
• practice reading Javadoc documentation

Important notes:

• This assignment is significantly longer and more challenging than HW 1. Do not leave it for the last minute!
• The homework can earn a total of 100 homework points as described below.
• There is an extra credit problem. Extra credit (i.e., points over 100) is not counted as part of your ordinary homework score when calculating grades — instead, it is used subjectively at the end of the semester when the professor is calculating final grades.
• File, class, and method names should be exactly as described in the problem descriptions (otherwise the test script will not work).
• Read the Javadocs!
  

Here are the files you will need:

• hw2.jar
• javadocs (Ignore the "ItemComparator" class)
• Tester.java

Sections in this document:

1. Overview
2. Running the Tester
3. Problem 1: Basic Room Class
4. Problem 2: Maze Class
5. Problem 3: Item Class
6. Problem 4: Character Class
7. Problem 5: Adding Locked Doors
8. Extra Credit: Exits in Arbitrary Directions

Overview

The ancestor of all text-based adventure games is Bill Crowther's Adventure, developed originally in Fortran back in 1975. A popular variant was called Zork, and this spawned many sequels (and whose introductory screen can be seen above). If you are interested in experiencing this classic, check out Infocom's official Zork download page (it's free).

Our adventure game is much simpler than these. The player's character moves from room to room exploring a maze, and can pick up and drop items. We will start by building the Rooms, then the Maze, then Items, and finally Characters.

 For the complete specification of all classes in this assignment, refer to the Javadocs.

Running the Tester

For this assignment, we've created a new (hopefully simpler and more robust) way for you to run the test script and see what grade you've achieved at the moment. The hw2.jar file includes a compiled version of the Tester class that you can run yourself, on whatever machine you are using to develop your solution. Here's what you need to do to run it. (You are strongly encouraged to try this out right now, before beginning on the assignment, and to run the tester to check the parts of your solution as you finish developing them.)

• Download hw2.jar and store it in the directory where you will be developing your solution.
• Tell DrJava where to find the hw2.jar file. Under Edit -> Preferences, click the Add button under Resource Locations -> Extra Classpath and type the full path of the jar file. Reset the Interaction pane to make sure it recognizes the change.

Now there are two methods for running the tests:

• To run the tests directly in a terminal window:
1. Open a terminal window and navigate to the directory where you stored hw2.jar.
2. Type the following command:

   java -cp .:hw2.jar Tester

   You should see the test script's output in the terminal window. (Of course, it will tell you almost all the tests are failing at the moment!)

3. To test your solution as you are developing it, just run the same command as above, making sure that you compile your solution first, and that your solution and hw2.jar are in the same directory.
• To run the tests in DrJava:
  1. Go to Edit->Preferences->Miscellaneous and uncheck "Clear Console After Interactions Reset".
  2. type "java Tester" in the interactions pane.
  3. After the Tester has run, click on the "Console" tab next to the "Interactions" tab.

Problem 1 (18 Points): Basic Room Class (File to submit: Room.java)

To begin, let's set up the basic structure of the world: the Room class.

Take a look at the javadoc documentation for the Room class. Your first job is to implement this class. This should be mostly straightforward...

• Open up a new file in DrJava (or whatever IDE you prefer).
• Save it as Room.java
• Enter a class header ("public class Room", etc.)
• You'll notice that the javadocs show Room as a subclass of something called Container. You don't need to worry about what this means right now, but you should make sure your Room class header includes "extends Container" so that the Tester will work correctly.
• Now look at the javadocs for the constructor and methods of Room. For each one, you can type in a header ("public <result type> <method name> (<arguments>)...") just by looking at the javadoc to see what's needed. Then fill in its body so that it does what the javadoc describes. (This is where creativity comes in!)
• As you're working, you can compile the file to make sure there are no type errors, and you can use the Interaction pane to try some simple tests.
• When you've finished all the methods, save your file, go back to a Terminal window, and try running the Tester to see if your results agree with ours. If not, have a look at the Tester.java file and try to figure out where the discrepancy is coming from.

Here are a few more notes that should help you:

• For the moment, a room can have exits in at most four directions: "north", "south", "east", and "west". (In the extra credit part of the assignment, if you choose to do it, you'll generalize this to allow arbitrary strings as directions. But, for the non-extra-credit part of the homework, these four are the only ones you have to handle.) This means that, if you like, you can represent the exits with four instance variables of type Room, one for each direction.
• The linkRooms method is worthy of special mention (see image at right): it creates a bidirectional connection between the rooms. This ensures that if you walk north from Room 1 into Room 2, and then walk south again, you will end up back in Room 1 where you started.
• The toString method, which is used when a Room object is printed to the console, should return the room's description.
• The lockExit method is not used in question 1 and is not tested by the tester. You'll need to fill in its method header so that the tester code will work with your code, but it doesn't have to do anything yet.

Sample interactions: (problem1.hist)

> Room r1 = new Room("Ballroom")
> r1
Ballroom
> r1.getExit("north")
null
> Room r2 = new Room("Library")
> r1.linkRooms(r2, "north", "south")
> r1.getExit("north")
Library

Problem 2 (24 points): Maze Class (File to submit: Maze.java)

Creating large worlds by creating individual rooms and linking them together can be a lot of work. Let's next build a helper class that simplifies the process by taking a two-dimensional array of strings and creating a world from it all at once. For any cell in our grid, if there is a non-null String value in that cell then a room should be created with that string as its description. Exits should be automatically created for any adjacent rooms. For example, if we give it an array that looks like this...

"A"	"B"	"C"
"D"	null	"E"
"F"	"G"	"H"

...it will create a "ring" of rooms whose descriptions are "A", "B", "C", etc. where going "east" from A reaches B, going "west" from B reaches A, going "east" from B reaches C, going "south" from C reaches E, etc.

See the javadocs for full details of what your solution must provide.

Sample interactions: (problem2.hist)

> String[][] descriptions = new String[3][3]
> descriptions[1][0] = "A dusty broom closet.";
> descriptions[1][1] = "A large and dimly-lit ballroom.";
> descriptions[0][1] = "A fancy dining room";
> Maze m = new Maze(descriptions, 0, 1)
> m.getStartingRoom()
A fancy dining room.
> m.getStartingRoom().getExit("south")
A large and dimly-lit ballroom.

Problem 3 (15 points): Items (File to submit: Item.java)

Now let's enrich rooms so they can contain things. Much of the work in this part is done for you by the Container class, which is provided for you in hw2.jar. Containers hold objects of the Item class. Items are simply game elements that have a description, and can be stored in containers. For problem 3, it is your job to write the Item class.

• Start by reading the javadocs for Container and Item. Make sure you understand the relationship between them:
  • A container holds items.
  • An item holds a reference to the container its currently in.
  • Items can be moved from one container to another, but cannot be moved to the "null" container.
• Implement the Item class so that it follows the specification in the javadocs. Make sure your items interact correctly with Containers - use the sample interactions and tests.
• Finally, go back and modify the toString method of your Room class so that rooms containing items list those items in their own description (see the sample interaction below for an example of how this should look; the Tester class has some more examples). This is the only tricky bit of this question — you'll need to do a little work to make sure that rooms without any items in them continue to be described the same as they were before. HINT: To insert a newline in the middle of a string, use the special newline character '\n'.

Sample interactions: (problem3.hist)

> Room r = new Room("A large and dimly-lit ballroom.")
> r
A large and dimly-lit ballroom.
> Item i = new Item("Coin", r)
> r
A large and dimly-lit ballroom.
Contents: Coin

Problem 4 (26 points): Characters (File to submit: Character.java)

The last missing component of our adventure game is characters. For this problem you will write the Character class. Because characters are also entities in the game that will be held in Containers (in this case the Room they are in), the Character class will need to have similar functionality to the Item class (in addition to lots more specialized functionality specific to characters, like the ability to move around). In essence, you can think of a Character as a specialized type of Item that can do lots more stuff.

• Because we want characters to have all the functionality of items (plus more), it makes sense to have the Character class inherit from the Item class.
• This way, you will not have to duplicate the "container()" and "moveTo()" methods - the Character class will inherit them automatically.
• Characters are created with a description (their name) and a Room to start out in.
• A character has a Container as an instance variable that is its inventory of items it is carrying, and some methods that access what that inventory is holding.
• The pick up and drop methods move Items back and forth between the room the character is located in and its inventory.
• A character can move in a given direction from the room it is currently in to another room if there is an exit in that direction.
• Read the javadocs for a complete specification of all the methods the Character class should have.
• Again, a tricky part here is the toString method. If a character's inventory is empty, toString() should simply return the character's description. However, if the character has items in its inventory, toString should return the character's description plus a list of the items in the character's inventory. See the sample interactions and the tester to make sure the strings you are returning match exactly.

Sample interactions: (problem4.hist)

> Room r = new Room("An ancient temple.")
> Character c = new Character("Indiana Jones", r);
> c
Indiana Jones
> Item i = new Item("Fedora Hat", r)
> c.pickUp("Fedora Hat")
true
> c
Indiana Jones (carrying Fedora Hat)
> Room r2 = new Room("A small, damp stone alcove.")
> r.linkRooms(r2, "north", "south")
> c.move("west")
false
> c.move("north")
true
> c.getLocation()
A small, damp stone alcove.
Contents: Indiana Jones (carrying Fedora Hat)

Problem 5 (17 points): Locked Doors (File to submit: Room.java)

While technically we now have a fully functioning adventure game, our game isn't very interesting at the moment. To spice things up a little bit, let's now go back and add the capability for a door from one room to the next to be locked unless the character attempting to move is carrying the specific key.

• Return to your Room.java file. It's time to fill in that empty lockExit() method. Here's how it works:
• By default, exits are "unlocked". The lockExit() method locks a particular exit, requiring the given "key" (a string description of the required Item).
• A character can only move through a locked exit if it is carrying an Item whose description matches exactly the key required by the door. If the character is not carrying the necessary key, the move() should fail and return false.
• Note: calling lockExit() should only lock the exit in one direction, unless lockExit() is called again on the other room separately.
• The design of how to implement this is left to you.

Sample interactions: (problem5.hist)

> Room r = new Room("A large and dimly-lit ballroom.")
> Room r2 = new Room("A small, dusty broom closet.")
> r.linkRooms(r2, "west", "east");
> r.lockExit("west", "A small silver key");
true
> Character c = new Character("Sherlock Holmes", r);
> c.move("west")
false
> Item i = new Item("A small silver key", r)
> c.pickUp("A small silver key")
true
> c
Sherlock Holmes (carrying A small silver key)
> c.move("west")
true
> c.getLocation()
A small, dusty broom closet.
Contents: Sherlock Holmes (carrying A small silver key)

Extra Credit (10 points)

Finally (if you choose), let's make things a little more interesting by allowing rooms to have exits in "directions" with names other than the compass directions. Observe that we've already left room for this in the design — the methods of Room that deal with directions treat them as strings rather than as members of an enumerated type with just four possibilities. (This is also why the linkRooms method takes a description of the forward and backward directions when creating exits. While it may be well-defined what the opposite of "north" is, its not obvious what the opposite of the direction "a few steps to the left of the dusty old grand piano" is...) Your job is to rewrite your implementations of those methods so that they do the right thing with arbitrary strings.

One way to implement this functionality is to use a HashMap in each Room to represent the association between directions and neighboring rooms. Have a look at the documentation for HashMap (available in many places — it's a standard library class) for a detailed explanation of how it works. If you choose to use it, you'll need to put "import java.util.HashMap;" at the top of your Room.java file OUTSIDE the class definition.

This question doesn't require any new methods anywhere: just change your implementation of the preexisting framework.

Sample interactions:

> Room r = new Room("A large and dimly-lit ballroom.")
> Room r2 = new Room("A small, dusty broom closet.")
> r.linkRooms(r2, "into closet", "out of closet");
> Character c = new Character("Curious George", r);
> c.move("into closet")
true