Your mission in this assignment is to write a simple text-based adventure game in the tradition of Will Crowthers pioneering Adventure program of the early 1970s. In games of this sort, the player wanders around from one location to another, picking up objects, and solving simple puzzles. The program you will create for this assignment is considerably less elaborate than Crowthers original game and it therefore limited in terms of the type of puzzles one can construct for it. Even so, you can still write a program that captures much of the spirit and flavor of the original game.

Because this assignment is large and detailed, it takes quite a bit of writing to describe it all. This handout contains everything you need to complete the assignment, along with a considerable number of hints and strategic suggestions. To make it easier to read, the document is divided into the following sections:

1. Overview of the adventure game

2. The Adventure class

3. The AdvRoom and AdvMotionTableEntry classes

4. The AdvObject class

5. The AdvCommand class and its subclasses

6. Strategy and tactics

Section 1

Overview of the Adventure Game

The adventure game you will implement for this assignmentlike any of the text-based adventure games that were the dominant genre before the advent of more sophisticated graphical adventures like the Myst/Riven/Exile seriestakes place in a virtual world in which you, as the player, move about from one location to another. The locations, which are traditionally called rooms even though they may be outside, are described to you through a written textual description that gives you a sense of the geography. You move about in the game by giving commands, most of which are simply an indication of the direction of motion. For example, in the classic adventure game developed by Willie Crowther, you might move about as follows:

In this example, you started outside the building, followed the road up the hill by typing WEST, and arrived at a new room on the top of the hill. Having no obvious places to go once you got there, you went back toward the east and ended up outside the building again. As is typical in such games, the complete description of a location appears only the first time you enter it; the second time you come to the building, the program displays a much shorter identifying tag, although you can get the complete description by typing LOOK, as follows:

From here, you might choose to go inside the building by typing IN, which brings you to another room, as follows:

In addition to the new room description, the inside of the building reveals that the adventure game also contains objects: there is a set of keys here. You can pick up the keys by using the TAKE command, which requires that you specify what object youre taking, like this:

The keys will, as it turns out, enable you to get through a grating at the bottom of the stream bed that opens the door to Colossal Cave and the magic it contains.

Overview of the data files

Like the teaching machine program, the adventure program you will create for this assignment is entirely data driven. The program itself doesnt know the details of the game geography, the objects that are distributed among the various rooms, or even the words used to move from place to place. All such information is supplied in the form of data files, which the program uses to control its own operation. If you run the program with different data files, the same program will guide its players through different adventure games.

To indicate which data files you would like to use, the adventure program begins by asking you for the name of an adventure. To get the adventure game illustrated above, you would begin by typing Crowther, which selects the collection of files associated with a relatively sizable subset of Will Crowthers original adventure game. For each adventure, there are three associated data files that contain the name of the adventure as a prefix. For the Crowther adventure, for example, these files are

CrowtherRooms.txt, which defines the rooms and the connections between them. In these examples, you have visited three rooms: outside of the building, the top of the hill, and the inside of the well house.

CrowtherObjects.txt, which specifies the descriptions and initial locations of the objects in the game, such as the set of keys.

CrowtherSynonyms.txt, which defines several words as synonyms of other words so you can use the game more easily. For example, the compass points N, E, S, and W are defined to be equivalent to NORTH, EAST, SOUTH, and WEST.

Similarly, if it makes sense to refer to an object by more than one word, this file can define the two as synonyms. As you explore the Crowther cave, for example, you will encounter a gold nugget, and it makes sense to allow players to refer to that object using either of the words GOLD or NUGGET.

These data files are not Java programs, but are instead text files that describe the structure of a particular adventure game in a form that is easy for game designers to write. The adventure program reads these files into an internal data structure, which it then uses to guide the player through the game.

Your program must be able to work with any set of data files that adhere to the rules outlined in this handout. In addition to the three files with the Crowther prefix, the starter folder also contains file named TinyRooms.txt that contains only three rooms with no objects and no synonyms and a set of three files with the prefix Small that define a much smaller part of the Crowther cave. Your program should work correctly with any of these files, as well as other adventure games that you design yourself.

The detailed structure of each data file is described later in this handout in conjunction with the description of the module that processes that particular type of data. For example, the rooms data file is described in conjunction with the AdvRoom class.

Overview of the class structure

The adventure game is divided into the following principal classes:

AdventureThis is the main program class and is by far the largest module in the assignment. This class is yours to write, butas will be true for all the classes you implement for this assignmentthe public methods are specified in the starter files.

AdvRoomThis class represents a single room in the cave. This class is also yours to write. The private methods that decompose parts of the operation are yours to design, but the specification of the public methods used to communicate with other modules is specified. This class is closely linked with the AdvMotionTableEntry class, which is described in the same section. That class is provided as part of the starter project.

AdvObjectThis class represents one of the objects in the cave. As with the AdvRoom class, you have to implement this class although the public methods are specified.

AdvCommandThis class is the abstract class that is the superclass of all command types in the game. Each of the built-in commands corresponds to a particular subinstance of AdvCommand. For example, there is a QuitCommand subclass that implements the command QUIT. This file is supplied for you with the exception of the HELP command described in the section on the AdvCommand class. You are asked to add that oneeven though you need to add just a few lines in various placesto make sure that you understand how the command dispatch system works. If you add any additional commands, you should make sure that they use the same basic structure.

AdvMotionCommandThis class is a subclass of AdvCommand used to implement all motion verbs such as NORTH, SOUTH, EAST, and WEST. The AdvMotionCommand is given to you, but the actual work is performed by methods in the Adventure class that you must supply.

AdvMotionTableEntryThis class defines a record type that combines a direction of travel, the room one reaches by moving in that direction, and an optional object that enables the motion. The definition of this class is extremely simple and is provided in the starter project.

The structure of each of these classes is described in detail in one of the sections that follow.

Even though the code for these components is substantial, your job is made easier by the following properties of the assignment:

1. Most of the methods used to communicate among the classes have already been designed for you. The public methods in the AdvRoom and AdvObject classes are completely specified; all you need to do is implement them.

2. The structure of the command system is provided in the design of the AdvCommand class. This design is hard to get right, and the fact that the general outline is provided should make things considerably easier.

3. The project works from the very first moment that you get it. Each of the classes you need to design is supplied to you in the starter files as a subclass of a stub that works correctly and provides all of the methods you need. Your job is simply to remove the superclasses and implement all the necessary methods yourself. Providing the stub classes, however, makes it much easier to test you code as you go because you can rely on our implementations of the classes and methods.

Section 2

The Adventure Class

The main program class is called Adventure and contains most of the code you have to write for this assignment. This is the class that opens the data files, assembles the principal data structures, maintains the list of words known by the game, interacts with the user, and implements the various commands. For the most part, you will have the opportunity to figure out how to decompose the entire operation into reasonably-sized pieces and for choosing what data structures and methods to use in the underlying implementation. The starter files do, however, include public entry points for the various commands that the user can enter, mostly because we wanted to show you how object-oriented design supports a very clean design for a command processor. Because these methods are called from instances of the AdvCommand class described in Section 5, these entries must be public rather than private. This class has several public methods that fall into two categories. The first of these is the main method, which is invoked when the program is started. The main method has the following responsibilities:

Ask the user for the name of an adventure game

Read in the data files for the game into an internal data structure

Play the game by reading and executing commands entered by the user

The last two phases of the main method reading in the data files and playing the game will certainly be broken down into subsidiary methods. In several cases, these methods will delegate part of their work to one of the subsidiary classes. For example, even though the Adventure class opens the rooms data file and maintains the corresponding data structure, the task of reading the data for a single room is implemented by a method in the AdvRoom class.

The second category of public method in the Adventure class consists of the methods used to implement the various commands, which have the following header lines:

public void executeMotionCommand(String direction)

public void executeQuitCommand()

public void executeHelpCommand()

public void executeLookCommand()

public void executeInventoryCommand()

public void executeTakeCommand(AdvObject obj)

public void executeDropCommand(AdvObject obj)

You have to implement these methods just like the others; the presence of these methods, however, is required to make the command interpreter system operate correctly.

In writing the implementation of the Adventure class, you will need to engage in a significant amount of design work. Before you start in on the code, it will simplify your later work considerably if you spend some time thinking about the data structures you need and what the overall decomposition looks like. The most relevant model is the teaching machine described in class, but there are several important differences that you will have to keep in mind.

Most of this implementation will be straightforward. The only hard parts are reading in the data files and implementing the command scanner. These aspects of the code are discussed in subsequent sections.

Section 3

The AdvRoom and AdvMotionTableEntry Classes

The AdvRoom class represents an individual room in the cave. Each room in the cave is characterized by the following properties:

A room number, which must be greater than zero

Its name, which is a one-line string identifying the room

Its description, which is a multiline array describing the room (including the objects in the room).

A list of objects contained in the room

A flag indicating whether the room has been visited

A motion table specifying the exits and where they lead

The AdvRoom stores this information in its private data structure and then makes that information available to clients through the public methods exported by the class. These methods are listed in the starter file

The rooms data file

As in the teaching machine example, the information for the individual rooms is not part of the program but is instead stored in a data file. One of your responsibilities in completing the implementation of the AdvRoom class is to write the method readFromDataFile(Scanner), which initializes the contents of an AdvRoom object by reading that description from the rooms file for that adventure. At first glance, the data files for rooms look almost exactly like those for the teaching machine. For example, TinyRooms.txt looks like this:

The only obvious differences between the external file format for the teaching machine and the adventure game are

1. The title line is missing (the TeachingMachine.java program requires a course title on the first line)

2. Each of the entries for an individual room includes a short description (such as

Outside building or End of road) as well as the extended description.

These changes are in fact extremely minor. The other change, which is not quite so obvious or as easy, is that the direction indicators specified in the file (WEST, UP, and so on) need to be defined as motion commands in a dictionary. This aspect of the design is described in Section 5.

In thinking about an adventure gameparticularly as the player, but also as the implementerit is important to recognize that the directions are not as well behaved as you might like. There is no guarantee that if you move from one room to another by moving north, you will be able to get back by going south. The best way to visualize the geographic structure of an adventure game is as a collection of rooms with labeled arrows that move from one room to another, as illustrated by the following diagram of the connections defined in TinyRooms.txt:

The connections in this graph are modeled using the AdvMotionTableEntry class, which is described in a subsequent section.

Extensions to the connection structure

If the adventure program allowed nothing more than rooms and descriptions, the games would be extremely boring because it would be impossible to specify any interesting puzzles. For this assignment, you are required to make the following extensions to the data structure that provide a basis for designing simple puzzles that nonetheless add significant interest to the game:

Locked passages. The connection data structure must allow the game designer to indicate that a particular connection is available only if the player is carrying a particular object. That object then becomes the key to an otherwise locked passage. In the file format, such locked passages are specified by adding a slash and the name of an object after a room number.

Forced motion. If the player ever enters a room in which one of the connections is associated with the motion verb FORCED, the program should display the long description of that room and then immediately move the player to the specified destination without waiting for the user to enter a command. This feature makes it possible to display a message to the player and is in fact identical to the design that Willie Crowther adopted in his original adventure game.

Both of these features are illustrated by the segment of the SmallRooms.txt data file shown in the figure below. If the player is in room 6, and tries to go down, the following two lines in the connection list come into play:

DOWN 8/KEYS

DOWN 7

The first line is active only if the player is carrying the keys. In this case, the player moves into room 8 which is the beginning of the underground portion of the cave. If not, the DOWN command takes the user to room 7. Because the motion entries include the verb FORCED, the program prints out the long description for room 7 and then moves the player back to room 6, as shown in the following sample run:

It is possible for a single room to use both the locked passage and forced motion

options. The CrowtherRooms.txt file, for example, contains the following entry for the room just north of the curtain in the building:

Excerpt from SmallRooms.txt

The effect of this set of motion rules is to force the user to room 71 if that user is carrying the nugget and to room 76 otherwise.

The AdvMotionTableEntry class

There are several possible strategies one might have chosen to represent the table of connections in each room to its neighbors. In this assignment, you should store the room connections as a list of objects each of which is an instance of the class AdvMotionTableEntry. The complete definition of this class is included with the starter file. You could easily have designed this class yourself, but its implementation is so simple that doing so would not have helped you learn anything important. Because the class appears as the result type of a public method, it seemed easier simply to provide it to you directly.

Section 4

The AdvObject Class

The AdvObject class keeps track of the information about an object in the game. The amount of information you need to maintain for a given object is considerably less than you need for rooms, which makes both the internal structure and its external representation as a data file much simpler. The entries in the object file consist of three lines indicating the word used to refer to the object, the description of the object that appears when you encounter it, and the room number in which the object is initially located. For example, the data file SmallObjects.txt looks like this:

This file indicates that the keys start out in room 3 (inside the building), the lamp initially resides in room 8 (beneath the grating), and the rod can be found in room 12 (the debris room). The entries in the file may be separated with blank lines for readability, as these are here; your implementation should work equally well if these blank lines are omitted.

The objects, of course, will move around in the game as the player picks them up or drops them. Your implementation must therefore provide a facility for storing objects in a room or in the users inventory of objects. The easiest approach is to use an ArrayList, which makes it easy to add and remove objects.

The complete definition of the AdvObject is included in the starter file. The implementation of these methods should be quite straightfoward, particularly in comparison to those in the AdvRoom class, which is significantly more complicated.

Section 5

The AdvCommand Class

Almost of the code for the AdvCommand class is given to you for the following

reasons:

1. It is important for you to see how this type of command dispatch table is usually implemented in an object-oriented language like Java. The ability to define a general class for which the detailed behavior is specified in a set of subclasses is a critically important technique in object-oriented design.

2. It will be difficult to convince you that the inheritance model is better in the context of a program at the scale of the Adventure game. Although Adventure may seem large to you, it is still a very small program in the general scheme of things, and the advantages of using the proposed structure will not always be clear at this scale.

In the code youre given, the command module defines all of the required commands except HELP. Your only job with respect to this module is to add the various pieces necessary to implement the HELP command, using the other commands as a model.

The code for the AdvCommand.java file is given in the starter file, lacking only the HELP command definitions. Unlike the source files youve seen so far, the AdvCommand.java file contains several different classes. The publicly accessible class is AdvCommand, which is the abstract superclass for all command types. In addition, this file contains definitions for specific subclasses that define each individual command. Thus, the AdvCommand.java file contains a definition of an AdvQuitCommand class that represents the QUIT command, an AdvLookCommand class that represents the LOOK command, and so on. These classes are not defined as public, so they will not be accessible outside of the package. The other files gain access to them through a set of constant definitions in AdvCommand that define the standard entries for each of these command types.

The abstract AdvCommand class defines a single execute method that each of the subclasses must implement. The header line for this method looks like this:

public void execute(Adventure game, AdvObject obj)

The definition for each of the specific subclasses defines only that method. In each case, the definition is simply a method call to the appropriate method in the Adventure class that implements the command. The definition of the command that implements TAKE, for example, looks like this:

class TakeCommand extends AdvCommand {

public void execute(Adventure game, AdvObject obj) {

game.executeTakeCommand(obj);

}

}

An object of the TakeCommand class is part of the general framework of the AdvCommand hierarchy but has its own definition of execute.

When you read a command as part of the implementation of the game, you will need to perform the following steps:

1. Read in the command line.

2. Break the command line up into a verb representing the action and an object (if specified) indicating the target of that action. In the game you have to write, these objects are relevant only for the TAKE and DROP commands, but your extensions might add other verbs that take objects as well.

3. Look up the action verb in a HashMap containing all of the possible action verbs. The value you get back will be an AdvCommand, which means that it will actually be one of the individual subclasses although you wont know which.

4. If an object is specified, look that up as well in a separate HashMap that converts the name of an object to the AdvObject that represents it. If no object is specified, use null in place of any specific direct object.

5. Call the execute method of the command, passing in a reference to the Adventure game and the direct object. This method call will presumably look something like this, although the variables may change if youve used different names:

command.execute(this, obj);

Calls of this form, which are initiated by a particular class and then make calls back into that class to perform some operation are referred to as callback methods, and play a significant role in modern programming.

Note that the motion names can also be implemented as AdvCommand objects. The code for AdvCommand in the starter file shows how this command class fits into the general command structure. When you encounter a command like WEST in the data file, you can create a motion command for that word by calling the AdvMotionCommand constructor. When you execute this command in the course of playing the game, it will automatically trigger a call to executeMotionCommand in the Adventure class, passing in the name of the direction as a parameter. Your implementation of that method will need to consult the motion table for the current room, see if that direction exists, make sure any necessary key object is available, and then move to the specified destination room.

As discussed earlier in this section, the code for the Adventure class will need to maintain two HashMap structures that serve as dictionaries. The first contains all of the command words, which includes all the motion verbs included in the travel table along with the built in commands like QUIT, TAKE, and DROP. The second maps the names of objects into the corresponding AdvObject values. Part of your job in writing the Adventure class is to create these HashMaps, which will require you to add the necessary entries as they become available. The built-in commands can be added as soon as you set up the HashMap; the other words, however, can only be added as you read in the data files. Thus, as soon you read in the data for a room, you will need to go through the motion table for each room and add a new entry for any new motion verbs you encounter. Similarly, when you read in an object, you will need to define its name in the HashMap for the objects. This part of the code is not very hard, but you have to remember to do it or your code will not respond correctly to any commands.

This discussion of commands finally makes it possible to discuss the handling of the last of the three data files, which is the synonym file. The synonym file consists of a list of lines in which one word is defined to be equal to another. The SmallSynonyms.txt file looks like this:

Your code for the Adventure class should read through this file and make entries in each of the two HashMap structures to ensure that the word on the left of the equal sign is interpreted in the same way as the word on the right.

Section 6

Strategy and Tactics

Even though the adventure program is big, the good news is that you do not have to start from scratch. You instead get to start with a complete program that solves the entire assignment because each of the classes you need to write is implemented as a subclass of a library stub that performs all of the necessary functions. Your job is simply to replace all of the stubs with code of your own. In your final version, the implementations of the Adventure, the AdvRoom and AdvObject classes should not specify a superclass at all. You must use generics throughout the entire program. A quick way to check that that is the case is to load your program into Eclipse and verify that none of your files has any warning.

The following suggestions should enable you to complete the program with relatively little trouble:

Start as soon as possible. If you wait until the day before this assignment is due, it will be impossible to finish.

Get each class working before you start writing the next one. Because the starter project supplies the stub classes, you should focus on the individual classes rather than the entire program. Do not try to write all the implementations ahead of time and then see if you can get the program working as a whole. Write one class and debug it thoroughly before moving on to the next. A suggestion is to start with AdvObject and AdvRoom, and then to move on to the more difficult implementation of Adventure itself.

Use the smaller data files for most of your testing. Dont try to test your code on the Crowther data files. These files take a long time to read in and are complicated only because of their scale. The Tiny data files are appropriate for the basic functionality, and the Small data files have examples of every required feature. At the end, it makes sense to try the larger data files just to make sure everything continues to work in the larger context.

Test your program thoroughly against the handout and the sample application. When you think youve finished, go back through the handout and make sure that your program meets the requirements stated in the assignment. Look for special cases in the assignment description and make sure that your program handles them correctly. If youre unsure about how some case should be handled, play with the sample application and make sure that your program operates in the same way.