A3: Adventure Augmented

Adventure Augmented

In this assignment you will finish developing the text adventure game (TAG) that you began in A2. Although this handout provides some requirements regarding the functionality you should implement, many of the details are up to your team. If we left something unspecified in this handout, you are empowered to make your own choices about what to do. We hope you have fun making the game your own!

Table of contents:

Getting Started

There is no starter code provided for this assignment. Rather, you should begin with the code that you submitted for A2.

This assignment will not be autograded. You will demo your game in person to a TA. Hence there is no new makefile or make check. Passing make check is not a requirement for this assignment. Instead, your submission:

You are welcome to change any and all interfaces, to add new code, to link against libraries of your choice, etc. If you do add new compilation units, you will need to list them at the top of the Makefile to ensure they (and their documentation) are built correctly. If you link against new libraries, you will need to add them to _tags and .merlin. And both new compilation units and new libraries could require you to modify .ocamlinit.

To be clear, there is no need at all to link against new libraries, and most people will not. But it is a possibility.

Step 1: Team Maintenance

Your A3 team will be the same as your A2 team. At your first team meeting about A3, please do two things:

  1. Print out one copy of the Evaluation of Progress form, and fill it out together. Do your best to have a forthright and professional conversation about any issues that surface. If something comes up that you’re not sure how to handle, please talk to your TA to get their advice. You do not need to submit your form to CMS.

  2. Assign new roles for this assignment. Make sure to give everyone a different role than they had in A2. Please note that the checker role has been updated to include additional responsibilities.

Step 2: Finish A2

If there’s anything your team didn’t finish in A2, begin A3 by finishing it now. In particular, your A3 solution must provide the “go” and “quit” verbs, and a user interface, and be capable of loading adventures from data files.

Here are a couple definitions to recall from A2 for the rest of this handout:

Step 3: Gamify

Arguably, what you built in A2 is not yet a game, because there is no notion of winning or losing, or of comparison to other players. Add functionality to your software to make it a game, as follows.

Introduce a notion of score to your game. A player’s score should be based on which rooms they have visited, and possibly other factors (which we leave up to your choice). Each room should be worth some number of points for visiting. Moreover, the adventure file should specify the number of points for each room, meaning that each room can be worth a different number of points from all other rooms. In other words, the number of points any room is worth should be data driven, not hardcoded. You should provide a “score” verb to display to the player their current score.

Implementing this will require:

We leave the exact rules for scoring up to you, as long as they satisfy the above requirements.

Step 4: Sample Adventures

Create your own adventure by constructing your own JSON file. It may not be based on any sample files we have already given you. We encourage you to create an interesting and creative adventure! But your grade won’t be based on that. Instead, we simply require that it have at least five rooms.

Then create a second sample adventure. This one may be quite small and minimal. The point of this step is to demonstrate that your game engine is data driven and does not hardcode objects (i.e., rooms or their points).

The names of both sample adventure files must end with .json.

This is the stopping point for a satisfactory solution.

Step 5: Items

Adventure games usually involve items that the adventurer can move between rooms. For example, in the Colossal Cave adventure, the player’s goal was to collect all the items and put all of them in a designated room, making it a kind of treasure hunt. In Myst, the player’s goal was to collect missing pages of books, and to put those pages into the books.

Extend your game engine and your sample adventure with the notion of items. Your main sample adventure should contain at least three items. It should be possible for the player to issue commands that cause the adventurer to move items between rooms. The interface should display helpful acknowledgments and error messages for those commands. Moreover, the player’s score should in some way be dependent upon which room each item is located in, and each item should potentially be worth a different number of points than all other items. Finally, there should be some winning condition based on the items and their room locations that causes the engine to notify the player that they have won the game. We leave the exact design of these commands and rules up to you.

The items in your game should be data driven—that is, every item should be defined by the adventure file, not by your source code. The types representing items, of course, will be defined in your source code.

On the other hand, the new commands that you introduce will involve new verbs, and those verbs—like “go” and “quit” and “score”—should be hard coded.

As a suggestion, here is one way to satisfy the above requirements:

This is the stopping point for a good solution.

Step 6: Augmentation

Thus far, the gameplay of our adventures does not involve very much adaptation to what the player does. Let’s make the gameplay more interesting by making it dependent upon the state of the game.

Pick one of the following three game augmentations, implement it, and extend your sample adventures to demonstrate it:

As before, verbs may be hardcoded, but objects should be data driven. For example, which key opens which lock would be determined by the adventure file, but verbs such as “unlock” or “use” would be hardcoded. Likewise, dialogue would be data driven, but the “say” verb would be hardcoded.

You might consider commands that have indirect objects, such as “use <object> with <other object>” or “say <phrase> to <character>”.

If you implement two of the three augmentations, you will receive a small bonus. Implementing all three will not result in any additional bonus, though you are welcome to do it.


Here’s what we consider a satisfactory, good, and excellent solution:

Regardless of the level of scope, two sample adventures should be provided that demonstrate all of the implemented functionality.

Documentation and Testing

Documentation for this assignment will be graded as in A2: the grader will look at the public and private documentation generated by make doc. If that command cannot be executed, the grader will give you a score of -1 for documentation. So be sure to test it yourself.

Testing will be graded by checking that you have unit tests for each verb that you add to the game. For efficiency, graders will not investigate each .mli to make sure you have unit tests for every function—though for your own sake, you probably should. If you do not pass your own test suite with make test, the grader will give you a score of -1 for testing.


Make sure your team’s NetIDs are in authors.mli, and update the hours_worked variable at the end of authors.ml. That should be the hours you spent after submitting A2. Please do not include the time you worked during A2. That is, the sum of your hours worked in your A2 and A3 submissions should represent the total time you spent working on the entire game.

Ensure that your solution compiles and passes your own test suite. Run make zip to create a zipfile to upload to CMS. Somewhat misleadingly, the name of that file will be a2src.zip. That’s our fault; we weren’t thinking far enough ahead when we created the makefile for A2. (You could fix the zipfile name in the makefile if you wanted, but it’s not necessary.) You’ll be just fine uploading the file to CMS regardless of whether it’s named a2src.zip or a3src.zip. Your zipfile must contain all your OCaml source files ( both .ml and .mli), your two sample adventures, and _tags and Makefile. The make zip command we provided in A2 will automatically do that for you, so please use it rather than any graphical tools.

Submit your zipfile on CMS. Double-check before the deadline that you have submitted the intended version of your file.

Demo and Grading

Schedule a one hour meeting with one of your section TAs to demo your finished game. The deadline for contacting your TA is the end of Friday night after A3 is due, the same as the deadline for late submissions, though we encourage you to contact the TA earlier than that. If you have not contacted your TA by the scheduling deadline, there will be an automatic deduction of 20 points.

We recommend having the demo over the weekend or on Monday. A minimum of two of your team members must attend the demo (though we encourage all to attend). The deadline for having the demo is the following Wednesday night, the same as the deadline for A4. If you have not had a demo by then, or if the minimum quota of team members does not attend, there will be an automatic deduction of 40 points. If no one shows up for your demo, or if you fail to ever schedule one, then the TA will proceed with grading in your absence. In that case, no regrades will be accepted on the grounds that the TA misunderstood something about your software—you missed the chance to be there to explain it.

At the demo, the TA will run through this rubric with you.

Congratulations! Your adventure is complete.