CIS 3000: Introduction to Computer Game Design

Assignment 8
Architectural Specification

Due: Saturday, March 12th at 11:59 pm

An architectural specification is a document that roughly outlines the architecture for your software program. It is partly an API, in that it identifies some of the major classes and their methods. However, it is clearly impossible to write a complete API at the start of a project; as you continue to work on the program you will obviously add new classes, and change existing ones. It is also a "design" vision document in which out outline your major architecture goals, such as multithreaded AI or the presence of a scripting language.

This particular assignment has always been one of the most difficult; both for us and the students. As many of you have never created such a document before, it is hard to get the level of detail just right. Either you give too much detail, and then your decisions change, or you give to little detail and your programmers cannot agree on what to do.

This was motivation for the new lecture on architecture design this semester. We have introduced some new techniques to help you identify and design the major components of your architecture. Indeed, given that lecture, you have hopefully already started to think about the issues below. In that case, completing this assignment is just a matter of writing down your decisions.

The Architectural Specification

The architectural specification is a written document that describes a vision of the details of your final product, much like the gameplay specification. Indeed, these documents are very similar because they have the same audience; they are both internal documents written to allow team members to break-up and work in isolation. The primary difference is focus. The gameplay specification focused on game elements like verbs and challenges. The architectural specification focuses on software elements like classes and program flow.

Like the concept document, this file should be constructed with clear sections and subsections, and making good use of font styles, font size, and other forms of formatting to make it readable. The primary difference is what is in the sections and subsections. Following the guidelines established by the lecture on architecture design, we suggest that you organize your document as follows.

Class-Responsibility Collaboration Divisions

Remember our discussion of CRC cards in class. These represent your subsystems, or modules for those of you who have had CS 3110. These cards represent the classes that everyone on the team should know about. Anything not represented by a CRC card is unimportant, and can be "owned" by a single team member. This means that you want to keep the number of CRC cards to a minimum.

We also talked about the model-view-controller design pattern in class. This design pattern separates data from the user interface, and both of these from the input controls. The CRC Cards should respect this design pattern. In other words, each on of the classes should fall into one, and only one, of these categories. This also means that you will need a minimum of three CRC Cards: one each for the model, view, and controller.

As the architectural specification is a single written document, we are not asking for you to turn in the index cards. Instead, you should present the CRC cards in table form, just as we do in the lecture. In addition, for each table you should provide the following information.

  • A high-level, English description of what this class does.
  • Justification for why this class represents a single, coherent module.
  • Classification of the class, as either model, view, or controller.

How you format this additional information is up to you.

Finally, once you have listed all of the tables for your CRC cards, we want one last piece of information for this section. We want the collaboration graph of you classes. Draw a box for each class, and put the name of the class in the box. Then draw an edge between any two classes that collaborate. This is what we did in the second slide of the architecture design lecture. The edges can be either directed or undirected. If you choose directed edges, have the edge incoming to the class with the responsibility.

The Activity Diagram

We also discussed the notion of activity diagrams in class. Activity diagrams outline the flow of your application over time. This is key in time-critical pieces of software like games (16.7 milliseconds per animation frame).

Remember that activity diagrams work like flow charts, except that you can follow multiple paths at a time. Use synchronization bars to fork and resync your activities together. You should not need any more syntax than what we showed in the lecture notes. If you do not believe that you can express your activity diagram with this information, please contact one of the programming TAs for help.

In this section we only want one activity diagram. It does not have to be an activity diagram for the whole program. Just concentrate on the update-draw loop. Features outside this loop, like the game main menu, can be ignored.

Your activity diagram should coincide with your CRC divisions. Every single responsibility from the previous section should appear in the activity diagram, unless it is outside the main update-draw loop (e.g. menu selection). If an appropirate responsibility does not appear in the activity diagram, you should either remove it from the CRC divisions, or add it to the diagram.

The reverse is also true; every major task in the activity diagram should correspond to some class responsibility. Some of these activities may be supported by a third-party library like Box2D. But if the responsibility corresponds to a class that you have created, it belongs in the section on CRC divisions.

Class Interface Details

Once you have outlined the CRC elements, you should have all of the information that you need to make your class interfaces. The interface is just the list of methods for that class, together with some description of what the method does. Remember that each responsibility is a class method, while each collaborator is a parameter that must be passed to that method. Hence this should be pretty easy.

You should specify your interfaces like you would see in the the JavaDoc documentation of a Java class. That is, for each method, you should list

  • A short description of what the method does
  • A description of the parameters of the method
  • A description of what value the method returns (if any)
  • A description of any side effects that happen when the method is called

This section may feel a little redudant, given that a lot of this information was given in the class-responsibility-collaborators section. We are asking that you pull it out here as a separate section because it is more likely to change than the CRC divisions. Your high-level responsibilities probably will not change, but you may fiddle with the exact details of the actual methods. Doing that here in a separate section allows that flexibility.

With that said, try to keep this section brief. It may be a bit redundant, but there is no need to be completely redundant. Focus on the actual syntax of the interface.

Data Representation Model

As we discussed in class, data-driven design is an important part of game development. While the data may not be part of your software program, it is part of your game architecture. Therefore, it is important to nail down your data formats early.

At the very least, we are assuming that your game has two types of data files:

  • Saved game file
  • Game level file
The first is created when a player saves a game (either manually or via a checkpoint), and the second is the output of your level editor.

For each of these two files, you should clear describe their representation. This includes

  • The file format (e.g. XML or other)
  • The information stored in the file

In addition, if you have any other data files beyond art and music, you should describe those and explain why you need them. Examples of such files may include:

  • The physics geometry of an art file
  • A program written in a scripting language
  • A data file describing the strength/health/etc of an enemy

Third-Party Libraries (Optional)

We are not expecting you to write everything from scratch in this class. Most of you are already planning ot keep Box2D as your physics engine. There are other examples, such as the Codeplex Wii library to support the Wii Controller on PC. Are a Kinect library for the truly brave.

In this section list all of the third parties that you plan to use. You should not provide a complete class API for them. However, you should identify what the library will be responsible for in your game. This is like a CRC card, except that we only want to know how the library is used in your game, not how it is used in general. We are also not interested in the class collaborators for this section.

(Lack of) Examples

While we have examples of architectural specifications from past semesters, we do not want to show them to you. Architectural specifications have always been a problem and we are introducing new concepts this year to help improve them. Most of the old examples are bad examples, and we fear that we will just confuse you by showing them to you.

As with gaemplay specification, the upside of all this is that I will be very, very lenient with these documents. Try your best based on the instructions above. We will comment on it and you will get several opportunities to improve it. And next year, you get to be the example for everyone else.

Submission

Due Saturday, March 12th at 11:59 pm through CMS.

You should submit a PDF file called architecture.pdf containing all of the information above. We ask that the file be a PDF so that we can annotate it in order to return it to you with feedback for possible revision. It is fine if you create the document in a program like Microsoft Word, but you should convert it to PDF before submission.

As the prospect of revision implies, this is not the final draft of your specification. You will have later opportunities to revise your concept. However, as with previous revisable documents, you should take this assignment seriously.