| CPSC 225 | Intermediate Programming | Spring 2025 |
The projects are opportunities to work on larger programs, and to bring together and apply topics from the course. This project emphasizes object-oriented analysis and design, object-oriented programming, Java Collections, and working with files.
This project puts the class design in your hands. To make sure you are on the right track with this, there is a separate (and earlier) due date for the class design, pseudocode, and plot description. There is a due date and handin for the design. The due date is at the beginning of the handout; what to do for the deadline is described in the Plan of Attack below.
The checkpoint deadline is a guideline for pacing. There isn't anything to hand in, but you should treat it like a real deadline — if you aren't on track to meet it, you run a greater risk of not completing the project on time. Where you should be for the checkpoint is also described in the Plan of Attack below.
Fixing problems is an important component of learning, and most assignments will have an opportunity for revise-and-resubmit. There will be an abbreviated resubmit for this project because the end-of-semester timeline doesn't permit something longer. (The abbreviated part here will be with respect to feedback on the initial handin.) The resubmit deadline will be announced after the initial handin is due.
Revise-and-resubmit requires there to be something to revise and feedback to act on — it is not intended as a de facto extension. To be eligible for revise-and-resubmit, there must be some effort put into the assignment (a 3 or higher) for the original handin.
Late work is generally not accepted. If circumstances beyond your control prevent you from making any progress on an assignment before it is due, you are at significant risk of falling behind in the course. Come talk to me ASAP!
In addition, no work is accepted after the end of the final exam (5/9 11:30am) except in the case of an incomplete.
You may use the course materials (slides, examples) posted on the course webpage and the course Canvas site as well as the textbook.
You are encouraged to come to office hours and Teaching Fellows for help with thinking through getting started, Java help, debugging help, or help with anything else you might be stuck on.
The use of generative AI (such as ChatGPT), homework help websites, or other resources (friends, YouTube, etc) as learning cheats is not permitted. "As a learning cheat" means generating, finding, copying, etc code that you incorporate directly or with only minor modifications into your solution. The most egregious version of this is generating the entire program, but the prohibition applies to even small sections of code as well.
Using other resources as learning aids is permitted, but you are strongly encouraged to utilize the course materials, office hours, and Teaching Fellows as your primary sources of help. "As a learning aid" is to understand concepts — e.g. getting examples of loops to understand how to write loops in general or the specific syntax for loops in Java, not their specific application to this program. ("An example of a program to play flip" is a solution, not an example, and is not a learning aid.)
For the design (program design, pseudocode, and plot description), hand in hardcopies in class.
To hand in your code:
Make sure that your name is in an @author tag at the beginning of each file that you modified, and that all of your Java files have been auto-formatted and saved.
Copy the entire adventure project directory to your handin directory. Make sure that you end up with adventure directly inside your handin directory, with the Java files themselves in a src folder inside adventure. Don't introduce extra directories or leave some out!
You are in a maze of twisty little passages, all alike...
Colossal Cave Adventure (or more commonly, just Adventure) is one of the classic computer games and pioneered an entire genre. In it, an intrepid adventurer explores a vast network of caves, braving axe-wielding dwarves, mazes, fierce green snakes, pirates, hollow voices which say "plugh", and a variety of other hazards in order to score points and win the game. If you are curious about the history of Adventure, check out http://www.rickadams.org/adventure/a_history.html.
In a typical Adventure-like game, the player interacts with the game by typing short commands such as MOVE NORTH, LOOK, TAKE LAMP, and so forth. The world that the player is moving through is made up of a series of rooms, connected by passages. Each room has a unique name/short description (e.g. "Dead end", "Building front", "NE/SW road") which identifies it, as well as a long description displayed the first time the player visits the room. There may also be additional descriptions which are applicable in different situations (e.g. a magical message might appear if you turn on a red flashlight while in the room or you may be prevented from leaving a room until a certain task is accomplished). Rooms may also contain items, which the player may pick up, carry along, use, and drop. Each item has a name (e.g. "shovel") and a description (e.g. "It is a normal shovel with a price tag attached that says $19.99"). The player earns points by completing various tasks, which might be depositing a particular item in a particular location, defeating an enemy, visiting a particular place, or solving some puzzle. The player wins by accumulating all of the possible points in the game.
If you've never played Adventure or another text adventure game, you can play it and Zork (another classic game) on the web. You may find this cheat sheet summarizing common commands helpful for getting started. (The cheat sheet is not specific to Adventure or Zork, but it gives you a starting point for the kinds of commands you can use. Also feel free to experiment!)
You can also play an Adventure-like game directly in the emacs text editor, a staple of Unix-based systems. Start up emacs (run emacs & from the commandline in a terminal window or look for it on the Applications menu), then run M-x dunnet (press and release the ESC key, then press and release x, then type dunnet and press enter).
Your task is to create a program which allows the user to play a text adventure game in the spirit of Colossal Cave Adventure. The specific elements your program must have are described in the Specifications section below.
Create a new Eclipse project named adventure.
Unlike Omino and Solitaire, you'll be identifying classes and methods yourself — there is not a predefined design to implement.
Read through the Specifications and use textual analysis as discussed in class to develop an initial class design. For each class, give it a descriptive name, briefly identify its purpose (what does it represent?), identify methods it will have, and identify information that it needs to store (instance variables).
Outline the main program's task in pseudocode. Keep a big-picture view — like an outline for a paper, cover all of the functionality of the main program (the paper's content) but at a high level (the main points) without all of the details (the actual text of the paper).
Describe the plot for your version of Adventure — what's the overall theme? What tasks must the player accomplish to win the game? Also identify the rooms and items, and draw a map showing how the rooms connect, where the items are initially, where the player starts, and where the goal room / exit is.
These three elements — the class design, the pseudocode for the main program, and the description of your plot — are due by the design deadline given at the beginning of the handout.
While you are waiting for feedback on your design, get started on several elements of the project that don't depend on the class design:
Create the rooms, items, and scoring files for your plot.
Implement file parsing — write a main program to read each of the files. For now, focus on reading and assembling the information from the files — for each room, for example, initialize local variables for the name/description; each of the north, south, east, and west rooms; and the description as read from the file, then print out each of those variables so that you can tell the right information was read.
By the checkpoint deadline, have these two elements — the files describing your world and successful file parsing — done. Being farther along is, of course, encouraged!
Once your design is on the right track, proceed with implementing the rest of the program. You could do this by implementing each of your supporting classes and then finally moving on to the main program as with Omino and Solitaire, but in this case your supporting classes are likely a lot simpler than many of the classes in Omino and Solitaire — it's not especially effective to write testers for them, but there's a lot of code to write before you get enough main program to actually run something for the first time. Instead, a better strategy in this case is use-case-driven development — instead of implementing a whole class at a time, implement a portion of the main program along with any of the class methods you need to make that work:
Write skeleton classes — for each of your classes, write the class definition with headers for the constructors and methods, declarations for the instance variables, and class and method comments. Also write the bodies for any simple methods such as getters and potentially constructors, but put just a TODO comment in the bodies of the rest. (If a method has a return value, also return something to make the compiler happy.) The TODO will help you remember that you need to come back to finish those methods, and Eclipse will display a blue marker in the margin of the editor window for each TODO, making it easier to locate unimplemented things.
Add to your file parsing code to set up the world defined by the content of your files, and implement any unimplemented class methods needed to support that. (Probably mostly constructors.) You may want to organize things better and move the file parsing and world building code out of main, perhaps to a helper function or another class.
Implement the GO command: set up the code to get commands from the user and then handle GO. Implement any unimplemented class methods needed to support that. Once GO is working, add support for the synonyms (MOVE) and alternatives (just NORTH, SOUTH, etc).
Proceed with the rest of the command handling, taking the commands one at a time and implementing any unimplemented class methods as you need them. Do easier ones and/or ones that make it easier to test other commands first — LOOK and then LOOK item might be good next. Ignore scoring and winning for now, just get the actions that each command involves working.
Add scoring and winning.
Your game must support the following commands:
GO direction, MOVE direction, or just direction, where direction is NORTH, SOUTH, EAST, or WEST — if the player can move in that direction, she should move to the new room and that room's description and contents should displayed (use the long description if the room has not been visited before and the short description if it has); if the player can't move in that direction, an appropriate error message should be displayed
TAKE item, GET item — player picks up the item named
DROP item — player drops the item named
LOOK — display the current room's long description, exit directions, and contents
LOOK item — display the item's description; should only be allowed if the item is in the current room or is being carried by the player (otherwise an appropriate message should be displayed)
INVENTORY — list the names of the items the player is currently carrying
SCORE — print out the player's current score
QUIT — end the game
Commands are shown in all caps for clarity, but your game should not be case-sensitive. Where there are synonyms listed (such as TAKE and GET), your program should support all of the versions listed. Also note that item names may consist of more than one word, but there won't be anything else on the line — i.e. for those commands that involve items, everything after the command can be taken as the item name.
Your world should be the typical Adventure-style world consisting of a collection of interconnected rooms. Each room can have exits to the north, south, east, and west though not every room will have exits in all possible directions. Each room has a unique name/short description which identifies it, as well as a longer description.
Rooms may also contain items, which the player may pick up, carry along, use, and drop. Each item has a name and a description associated with it.
You must have at least 10 different rooms, with an interesting series of routes between them. (Simply connecting the first room to the second to the third is not very interesting — there should be multiple ways you can navigate through the world.) There must be at least 5 items, which are initially placed in different rooms. (Don't put them all in one place.)
Points are earned by completing various tasks such as dropping an item in a particular location or visiting a certain room. The player wins the game by accumulating a certain number of points and then moving to a particular goal or exit room (which might represent escaping from the game's world).
Winning the game must require the completion of at least three tasks before moving to the goal/exit. At least one of those tasks must involve an item (such as picking up an item or dropping an item in a particular room), and at least one must involve visiting a certain room.
Be careful not to allow the player to accumulate points by repeating tasks — points for visiting a room should only be awarded the first time the room is visited, and points for dropping an item in the right location should be revoked if the item is picked up again.
There must be some sort of theme to your game — the rooms, items, and tasks should be tied together in some way. (For example, the original Adventure involves exploring a cave.) Be creative! You could set your game on the HWS campus, make it an exploration of an area park, create a made-up place, etc. You can be as serious or as silly as you want with the plot, rooms, items, descriptions, etc.
Good software design also includes making your code reusable where it is reasonable to do so. In particular, seeing that there are many Adventure-like games with different plots but similar elements, a good way to design this program would be to have a generic Adventure engine which handles processing commands and maintaining the player information (e.g. score, inventory) and game information (which rooms have been visited, where items are, etc). The elements specific to your plot (the particular rooms, connections, descriptions, items, scoring, etc.) should be configured via data files rather than hardcoded into the program. That way you just need to drop in a different set of data files to have a different plot — no need to rewrite any code!
Design your program to function in this manner. The easiest thing is to have separate files for each kind of information: rooms, items, and scoring. The file formats to use are described in the File Formats section below.
You can hardcode the names of the data files into your program rather than prompting the user for them. If you put the files in the top level of the project folder in Eclipse (not under src) — which you should do — you can just use the filename itself without needing to add a longer path. Do not hardcode absolute paths (starting with / or C: or similar depending on your OS)! It should be as easy as possible to locate and change those filenames if needed — use named constants.
Your program should not crash if the user does something unexpected or enters an invalid or illegal command or if a file isn't properly formatted. Problems should be handled gracefully, allowing for an opportunity to correct the problem whenever possible.
Preconditions should be identified and checked appropriately. Consider where using assertions to check internal invariants can be helpful.
Consider where there are methods which can be usefully tested individually, and create a tester class to implement test cases for them as has been done in the Omino and Solitaire projects (as well as several labs).
Most of your testing will come from running the program and entering commands like a user would. See the Implementation Notes section below for information on how to help ensure that you've tested all of your code that way. Automating this testing is an extra credit option. (see the Extra Credit section below).
For this project, unlike in the previous projects, you will need to decide on your program's design — both what the classes are and what stored information, constructors, and methods those classes will have.
Your class design should demonstrate the principles of good design, the most fundamental of which are that each class represents a distinct kind of thing (and only that thing) and that a class's instance variables and methods fit with the purpose of that class. The class name should reflect the purpose of the class.
Choose appropriate types for instance variables, parameters, and return types and appropriate data structures for storing collections of things.
Handing in a class design early in the project timeline is a required part of the assignment.
Your code should reflect good coding style:
Javadoc comments should be present for all classes and methods and comments should include necessary information (including preconditions) without also including unnecessary or inappropriate information.
Choose descriptive names.
Follow consistent and standard conventions for naming and whitespace. It is strongly recommended that you follow the 225 programming standards. Autoformat will take care of many potential whitespace-related issues, including improper indentation and too-long lines. Use blank lines for grouping and organization within longer methods.
Include a README document containing instructions on how to play the game and a description of any extra credit options or nifty/amusing features that you implemented and want me to notice. (If you don't mention them, you risk them being overlooked.) For the instructions, you should describe the setting for your game and describe anything that the player needs to know to play the game beyond what is stated in this handout. (You don't need to reveal things the player is supposed to discover for themselves as they play the game.)
The README should be a plain text file named README — create an "Untitled Text File" in your Eclipse project and then save it with the desired name. (Make sure it ends up in the top-level folder of your project, not under src.)
Extra credit features are a great way to challenge yourself. Make sure you complete the requirements of the assignment first, however, before tackling extra credit options!
More complex options and options which go farther beyond the minimum requirements will be worth more extra credit. For example, adding more rooms and items just involves adding to the game's data files and so will be worth only a small amount. Options which require more substantial thought and effort will be worth more. Extra credit will only be awarded for successfully completed options, so choose appropriate options based on your motivation and available time.
A basic room description needs to contain the room's name/short description, the room's long description, and what room you'd go to if you traveled in each of the four allowed directions (north, south, east, west). Capture this with a file containing a series of entries with the following form:
For example:
Lansing CS lab -, Lansing math/CS lounge, -, - The CS lab is full of students hunched over computers. END Lansing math/CS lounge Lansing CS lab, Lansing 3rd floor hall west, -, - The math/CS lounge in Lansing is a place with tables, full of students working. END Lansing 3rd floor hall west Lansing math/CS lounge, -, Lansing 3rd floor hall junction, - You used to be able to see a cabinet full of robots in this part of the hall. END
A comma is used to separate the rooms on line 2 because it is a character unlikely to occur in a room name. (Since room names can contain spaces, using a space to separate different rooms doesn't work very well.) If you want to allow commas in your room names, you can pick a different delimiter.
Handle items similarly to rooms, with a series of entries of the form
The scoring data file needs to contain information on the type of task (dropping an item, visiting a room, reaching a goal) as well as the particulars of that task (which item, which room) and its point value. Capture this with a file containing a series of lines of the following form: (replacing the italics item, room, points with appropriate values)
drop item, room, points visit room, points goal room, points
Lines should be allowed to occur in any order — don't assume all the drops will occur before all the visits or that the goal will be last, for example. However, there should only be one goal line.
Create your data files within Eclipse — for each, create a new "Untitled Text File" and then save it so that it ends up in the top-level folder of your project (not in src!).
All of the data files should be human-readable files (so they can be created with a text editor). Read the room and item files line by line. In the cases where you have multiple separate pieces of information on one line (such as for the list of adjacent rooms), you can use String's split method to split up the line using a comma as the delimiter. For the scoring file, the first thing on each line is the type of task (drop, visit, goal) so you might find it useful to use Scanner to read a token and then the rest of the line; the rest of the line can be split on the commas as needed.
At some point, you will probably find that you need to match the name of a room or item to the Java object in your program representing that room or item. This comes up when handling commands like TAKE and DROP, and also arises when reading in the data files to build the world. This lookup task will be much easier if you choose the right data structure...
In principle, you just read the data files and create the appropriate objects representing each thing. But there is a wrinkle when it comes to rooms, because there may be circular dependencies — for example, room A may be connected to room B which is connected to room C which is connected to room A. If a room stores references to its adjacent rooms, which one do you create first? This can be solved by making two passes through the rooms file. On the first pass, create all the room objects (with names, descriptions, etc but not which room is connected to which others) and store those objects so that you can easily look up which room object goes with which room name. On the second pass, add the neighboring rooms to the already-created room objects.
Eclipse includes a feature that can analyze code coverage by reporting what lines of code are executed during a run of the program. You can see this in action by right-clicking on a main program class in the Package Explorer and choosing Coverage As → Java Application instead of Run As → Java Application to run the program. When the program exits, the code in your Java classes is color-coded green, yellow, or red indicating whether that code was executed (green) or not (red). Yellow shows cases where some possibilities for boolean conditions were covered but not all.
To turn off the coverage color-coding, look for the Coverage view — there should be a tab called Coverage in the bottom pane below the editor window (where the Console view appears when you run a program normally). If you don't see it, you can open it with Window → Show View → Other... and then for Coverage within the little folder labelled Java. Click on the Coverage tab to make the Coverage view visible, then look for the single and double gray X icons near the right end of the pane's title bar. Click on the single gray X icon to remove the current coverage session and the double gray X icon to remove all coverage sessions (should you have more than one).
