Background
Problem
Purpose
Architecture
Specification
Tasks
Deliverables and Grading
Hints
Updates
Wiki Pages
References
Because of the proximity to the semester's end, the staff will not be able to accept late Project 6 submissions. Please plan accordingly, and start work well in advance.
As a reminder: the design document is due on Monday, May 5 by 5:00 PM; the code is due on Tuesday, May 13 by 11:59 PM; and the post-project report is due on Thursday, May 15 by 5:00 PM.
A MUD (Multi-User Domain) is a multiplayer text adventure game, in which players use a simple text-based user interface to enter commands. Traditionally, the world of a MUD consists of a graph of interconnected rooms, as well as items and characters. Players move around these rooms and interact with the world around them.
A more detailed explanation can be found on Wikipedia's article on MUDs, and you can explore some existing MUDs at Top MUD Sites.
In this project, you will design and implement a MUD as an interactive web application, which players connect to through a web browser. Your system will include both the back-end world of the MUD, and the web server that provides a text interface to clients. In addition, your world will have a graphical component, as explained below.
Each MUD will take an MIT building or a nearby location as its environment. Within your MUD, you will have to design and implement your own specifications, and there is no requirement that the environment must realistically model the building. For instance, it is possible that Stata is the backdrop of a giant zombie warfare, or that Kresge embodies the world of Zelda. However, we will connect all the MUDs geographically in order to allow users to travel across the campus, so you will also have to support some (rudimentary) central specifications.
The purpose of this project is to give you experience developing a program with a rich, relational state, and in particular:
You will also become familiar with the fundamental architecture of a web server, and with the use of XML as a machine-readable interchange format.
Your MUD will be played in a web browser, which means your game world will function as a component in a web server. The MUD game's user interface will be interactive, continually accepting the commands of clients, and dynamically updating the web page with new messages. You'll do this with AJAX (Asynchronous JavaScript And XML); JavaScript code will run in each client's browser to send and receive messages after the page has been loaded. With this technique, the user's browser becomes the interface for an interactive web application, with the web server acting as the backend.
We've provided you with the essential code for a web server infrastructure, which you have experimented with in the lab. You are free to use this code in your project, modifying it in any way you please. You may also reimplement the infrastructure if you prefer (but we do not recommend that you do).
Your project will consist of two components: a MUD game, and a web server that lets users play the game using a web browser. The design of both components is entirely unconstrained. However, an important criterion that will be used to judge your design is how well you have decoupled the game and server components so that it would be possible to reuse the game component with a different server (and perhaps not even in a web context).
You have complete freedom to determine the content and behaviour of the MUD world. To ensure that your MUD is sufficiently challenging to design and implement, it should include at least these elements:
The text interface should provide the functionality of the game to its players in a helpful and understandable manner. Players should be able easily to determine which actions apply at a given time, and should be notified of important events in an informative and entertaining way. Erroneous input should be handled gracefully.
Your text interface should support the following set of commands:
This should not be the entire repertoire of possible commands. These commands are specified so that users can experience consistency across MUDs.
The text interface should be supplemented by a graphical representation of the user's current room, such as a photograph, drawing, illustration, etc.
If you want to be more elaborate, you might find these resources helpful: HTML reference and CSS reference.
We will connect all of the MUDs geographically with the use of a central server. Each MUD will be uniquely identified by its group's two-digit number (see Project 6 Groups). MUDs will then be connected via numbered doors.
For example, a user may be playing in MUD xx and exit through that MUD's door 2, moving him to MUD yy. From there, he may make his way to another door, moving him to MUD zz.
To facilitate clients travelling across MUDs like so, every user will have a unique randomly-generated ID number, as well as a user-specified name that may not be unique. The ID number should be a Java integer, between 0 and Integer.MAX_VALUE inclusive.
In addition, your web server must support the following URIs:
Any additional parameters should be preserved. For instance, if the user comes in with some amount of "gold", you may support the gold as an item, or you may ignore it. Either way, you should pass the same "gold" parameter (with an updated value if you used it) to the central server when the user leaves.
Groups can create additional such parameters to share across MUDs through a wiki page we've made: Project 6 Properties. The page explains this concept in more detail.
When a user exits your MUD, you will need to redirect the user to our central server:
You will register your MUD's locations with the TAs (sign up at Project 6 Locations if you have not yet done so). Once all groups have registered, we will derive the geographical connections between the MUDs. We will then assign you some number of doors and let you know where these doors will lead.
Note that no central server exists yet. We will update this specification once we create it and notify you of the central server URL.
The infrastructure for your game should be decoupled from the story and content of your world. You should do this by using XML to configure your game upon initialization. The XML file should provide the majority of the textual descriptions you use, along with things like the layout of rooms and their interconnections, and an initial placement of items and bots. You should provide at least one interesting and thorough XML configuration file.
You have limited experience with XML, and might like to explore more powerful techniques. A good place to start is Wikipedia's article on XML.
The provided web server will create a new thread to handle every request it receives, meaning that if you use the provided infrastructure, multiple threads will be calling the ApplicationServer's methods and possibly also your game component's methods. In fact, you should assume not only that multiple clients may make concurrent requests, but also that a single client may make multiple simultaneous requests. (One way this might happen is if a user enters a message at the same time that the page is requesting new messages to render.) It is therefore important that your MUD application have a clearly defined and justified concurrency model.
In addition to meeting the above standards, you are to specify, design and implement TWO extensions. The two extensions must be dissimilar in nature: you may not implement two graphical add-ons, or two additional commands. Possible examples are:
Discuss your ideas with your group TA, and make sure to obtain your TA's approval before you complete your design.
The staff will award prizes to the top MUDs in four categories:
TAs will be nominating the top MUDs in their section soon after the implementation deadline. In addition, you are welcome to nominate yourself for any of these categories when you submit your final code.
On the final day of class, we will announce the winning groups and showcase their MUDs. In addition, we will try to have all MUDs up and running and connected via our central server. We encourage everyone to bring their laptops and explore each others' MUDs.
Prepare. Complete the lab.
Plan. Think of possible extension ideas that interest you, and run them by your TA before you incorporate them into your design. Discuss the division of labor among your group members.
Define. Informally describe the environment your MUD will simulate. Formally decide on the rules and elements of your MUD, and construct a problem object model that captures these rules and elements. Note that your object model should not be specific to any storyline or implementation choice (e.g. web server). As always, the object model should deal only with the problem domain, and should not include any solution components.
Design. Design a module structure for your program, and show it as a module dependency diagram (MDD). In a brief commentary, explain what key dependences your design eliminates or reduces, what design patterns you used, and what the key decision points were -- where you might have chosen differently and why you didn't. In addition, outline a testing strategy, and how you will divide implementation and testing tasks amongst team members, using the MDD as a basis.
Implement. Using your module dependency diagram, divide your MUD's functionality into sets of dependent features, implementing and testing one set at a time. Start with the most basic set of features, and move on to the next set only when the current set is complete and tested. You will likely want to review and update your design models as you refine the design.
Test. Execute your testing strategy. Ensure that your system works as a whole and as sets of dependent features. While you may find that some parts of your testing strategy cannot be automated, try to automate as much as possible.
Demonstrate. Construct at least one interesting XML configuration file that shows off the features of the MUD. Then, record an interesting and representative transcript of a user playing your MUD. Though the transcript should be from the perspective of only one player, other players can be present on the server to present a more complete view of the game. You should save the transcript as a plain text file, but you may optionally also save the transcript as an HTML file, using File > Save from your browser, if you wish to capture images and other graphical elements.
Document.
Reflect.
Wrap up. Meet with your group's TA for your last grading meeting of 6.005. Show your TA a live demo of your game, including your extensions.
There are three major deliverables for this project:
In addition, your TA may ask to meet with you one or more times to track your progress.
The grading will be broken down as follows:
All grading meetings need to be finished by Friday, May 16. We will have your grades to you shortly after.
There are some subtle and fundamental specification issues you will need to resolve. For example, what happens if a player discovers the proximity of another player or item, issues an instruction to perform an action on it, but it moves out of range before the action can be completed?
A well-designed and accurate object model can save you a lot of headache and provide a straightforward path to implementation. Use the techniques from lecture 17 to create a robust code design.
Introduce concurrency with great care, and make use of simple and robust patterns to minimize the risks of races and deadlock.
The Javascript in the sample web page doesn't just draw the incoming messages it fetches as plain text. Rather, the web page inserts the text into the HTML of the page, meaning that the server can send marked-up text, images, tables, and even Javascript of its own.
This feature can be used to help satisfy the graphical interface requirement. For example, to draw an image, the server should return an HTML snippet that includes an <img src="..." /> tag.
Complex systems can be full of bugs if there isn't adequate testing to catch them, and it can be a giant headache trying to debug them. This is a great opportunity to put into practice good testing practices in order to avoid that fate.
For example, as soon as you know your text commands, sketch out some representative scenarios using them; as your system comes together, test those scenarios. Also be sure to regularly update a regression suite with bug-causing inputs as soon as you discover any.
Similarly, it pays to make explicit a strong rep invariant for every non-trivial class you make. In addition, make liberal use of runtime assertions to check the assumptions your methods may be making.
Be sure to turn on the -ea (enable assertions) flag in the JVM so that your assert statements execute. You can do this in Eclipse by opening the "Run..." dialog, selecting your program, selecting the "Arguments" tab, and typing -ea into the VM arguments.
Especially nearing the code deadline, be sure that none of your commits break the build. Ensure that all your regression tests continue to pass before you check in any updates.
The central server for Project 6 is now running. It can be found at http://cagfarm-01.csail.mit.edu:3999/. Please make sure to use this URL in your code when users exit your MUD.
It supports the specified /move?from=xy&door=z&... command, which will attempt to actually redirect to another group's MUD, but for your testing purposes it also supports /testmove?from=xy&door=z&s..., which will send you back to your own MUD.
We have also begun automatically downloading, compiling, and running your MUDs on several CSAIL machines. Unfortunately, these machines only have Java 5, so please make sure it compiles under Java 5. The most common Java 6 feature which will not compile under Java 5 is the use of @Override for interface methods (as opposed to superclass methods), so please remove such tags.
In general, you should be able to tell if your MUD is compiling on our servers by looking at http://cagfarm-01.csail.mit.edu:3980/groupXY-ant, which is the build log for your code. The server checks your repository every 5 minutes, and if you have committed any changes, checks out and rebuilds your MUD.
Note: if your code uses any JAR files beyond the JRE and JUnit libraries, please put those jars into a top-level lib/ folder inside your project, and make sure to commit that folder and the JARs to your repository.
We've released an example MUD that meets the full spec, along with a minor extension that supports weights of items. You are free to use the MUD out here:
http://cagfarm-01.csail.mit.edu:4000/
Try moving around, conversing with each other and with bots, taking, dropping and giving items, looking around, etc. As always, you can type help to get help about each command.
We've released a set of client-side code (HTML, Javascript and CSS) that you may find useful in implementing the client-side portions of the project. You can find the files here: client.zip.
Features:
The zip file contains the following files:
You can find an example of it here: Akishore's MUD. You can also find an example server class for this new client code here: ApplicationServer.java. This ApplicationServer has functionality identical to the original lab 6 code, but uses this new client code instead of the old ChatBox.html.
To effectively use the code, you will need to take the following into consideration:
Save all the files into a directory/package inside your project folder. When retrieving a file, then, you will want to append the filename onto this directory's relative path. The example class has the files in a client/ directory/package on the same level as the server/ directory/pacakge, so the file constants.js is found at ../client/constants.js.
Provide a way for the server to return each Javascript and CSS file. The example class does this by declaring an array of known filenames, and checking against this array when handling unknown URIs. In the example ApplicationServer.java, see: FILES, isKnownFile(), serve(), serveFile().
Like before, create a random client ID when serving a new request, and replace the placeholder in the HTML with the generated ID. Unlike before, the Javascript was changed so that a placeholder ID already exists, so that the client code can be tested without a server. So the mechanism for replacing the ID has changed. The Javascript declares the ID like this:
var CLIENT_ID = /*CLIENT_ID*/ 123456789 /*CLIENT_ID*/;This means the /*CLIENT_ID*/ markers can be checked for, and the content inside the markers can be replaced by the new ID number. You can do this with a regular expression as the example class does. In the example ApplicationServer.java, see: CID_REGEXP, serveBase().
The Javascript provides the ability to change the image or redirect the user, but currently it doesn't get used. You'll probably want to create a text protocol between the client and server, like for project 5, and parse server responses in the refresh() method of model.js. When you get the appropriate responses, then, the model can raise the respective events, e.g. by calling handleNewImage(url).
If you have any questions, please post it on the Project 6 forums, and we'll try to answer it as soon as possible.