CS/INFO 4152: Advanced Topics in Computer Game Development

Assignment 8
Architecture Specification

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

An architecture 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/modules and their functionality. 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/modules, and change existing ones. Hence this 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 is also a document that we are continually tweaking within this class. As most of you have worked on such a document before (in the introductory course), you know that it is hard to get the level of detail just right. You give too much detail, and then your decisions change. Or you give too little detail and your programmers cannot agree on what to do.

This is why our philosophy is to stick with some simple tools and not to go full-on with complex tools like UML. UML is very expressive, but if you go into too much detail, then your spending more time programming in UML (for an architecture that might change) than working on creating your game. Instead, your goal should focus more on understanding how your team members work together and less on all of the fine details of your class structure.


The Architecture Specification

The architecture 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 mechanics and challenges. The architecture specification focuses on software elements like classes and program flow.

Like the gameplay specification, this file should be constructed with clear sections and subsections. You should make good use of font styles, font size, and other forms of formatting to make it readable. We suggest that you organize your document as follows.


Class-Responsibility Collaboration Divisions

Hopefully, you remember our discussion of CRC cards in the introductory class. If not, you should reacquaint yourself with the appropriate lecture. CRC cards represent your modules (or classes, depending on how you look at things). More importantly, these cards represent the interfaces that everyone on the team must agree upon. 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 architecture 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 cards 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.

Finally, we talked a lot about the entity-component pattern in class. If you elect to use this architecture, then we leave it up to you on how to categorize the components/roles. You may even categorize them as a fourth category, if you wish.

As the architecture specification is a single written document, we are not asking for you to turn in a set of index cards. Instead, you should present the CRC cards in table form, as shown in several of the examples below. In addition, for each table you should provide the following information.

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

How you format this additional information is up to you.


Third-Party Libraries (Optional)

We are not expecting you to write everything from scratch in this class. You are all using our variation of Cocos2d-X. In addition many of you are planning ot keep Box2D as your physics engine. Libraries for custom gesture recognition are another common resource for mobile games.

In this section list all of the third party libraries that you plan to use, beyond those we provide for you. So you do not need to list Cocos2d-x or Box2d, but you are expected to list Liquid Fun or Gesture Extensions.

Even though you are not implementing any of these libraries yourself, we want CRC cards for each one of them. Identify only what the libary is responsible for in your game; functionality not used by your game can be left out. The collaborators for these CRC cards are typically trivial (e.g. the library only collaborates with itself). However, some third party libraries provide you with an interface that you must subclass or implement in order to use the library. If any of the classes or modules designed in the previous section fit that decription, then you should list them as collaborators on the CRC card.


Dependency Diagram

Once you have listed all of the tables for your CRC cards, we want the dependency graph or diagram of your modules. Draw a box for each module/card, and put the name of the module in the box. Then draw an edge between any two modules that collaborate. Again, see the examples below for more information. The edges can be either directed or undirected. If you choose directed edges, have the edge incoming to the class with the responsibility.

The dependency diagram should include both your own classes and the third-party libraries. We need to see how everything fits together.


Activity Diagram

In the introductory course, we also discussed the notion of activity diagrams. 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 introductory course. If you do not believe that you can express your activity diagram with this information, please contact one of the course staff for help, or post on Piazza.

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 loop. Features outside this loop, like the main game menu or initialization 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 loop (e.g. menu selection). If an appropriate 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.

With that said, we are not asking for a separate activity box for each responsibility. It is okay to collapse multiple responsibilities into a single activity to make this diagram easier to read.


Data Representation Model

As you know from the introductory course, data-driven design is an important part of game development. A lot of your game content is stored externally in configuration files, level designs, and object scripts. While this 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.

You should create a separate subsection for each type of data file in your game. We are assuming that your game has at least two types of data files: the saved game file, and the level file. You may have more (like an asset directory file), in which case you should include those in this document as well.

For each file type in your game, you should clearly describe the file representation. This includes

  • The file format (e.g. JSON, XML, or other)
  • The information stored in the file
  • How this information is stored (e.g. the JSON or XML keys)

What files you are going to have is up to you. However, we recommend that you organize it as follows:

Saved Game File

If you are using a checkpoint save model, this could be as simple as player progress. If you are doing anything more complicated, you will need to list all of the state that you store. What must be stored and what can be recomputed (or reset)?

Level File

The level file is always the most complicated file in the game, typically much more so than your saved game file. It has to contain all of your world geometry, any trigger or script references (these may be separate files), and so on.

This document is also always in flux. We are not expecting you to get it 100% correct on the first draft. We just ask that you make a reasonable attempt at the document.

Other Files

If you have any other files that we may have missed, please let us know. These may include

  • Asset directory (a list of all assets and default settings)
  • Triggers or behavior scripts
  • Character statistics (e.g. health, strength, etc.)
  • Physics geometry for an art file

We leave the format for how you specify these up to you.


Application Restoration Plan

This last bit is necessary because you are all on mobile devices. As we discussed in class mobile applications may or may not be suspended when the user returns to the home screen. You should have a plan for how you intended to suspend the application. Is all data lost, and the user reloads? Or can you at least recover some of the previous state.

This problem is very similar to that of the previous section, but it is not serialization per se. Instead you have to think about the App restoration restoration API for your current platform (iOS or Android). Provide a description of how you are going to use these APIs to handle App suspension and restoration.


Examples

This document is perhaps the hardest one to "get right" in this course. We have never found an architecture specification that we are 100% happy with. However, each of the specifications below are notable in some way. They are either very strong (but not perfect), or did one part of the specification very well.

We are continually changing the format of this document. In particular, you will note that some of the documents below include an API/functional specification for all the classes. We are no longer asking for that feature. We understand that this information changes, and we leave it up to you to arrange your interface parties to make sure that everything fits together.

Over the Arctic Hills

The 2014 game Over the Arctic Hills continues to be a great source of examples for this course. This document covers all of the requirements that we listed above, and presents everything with the right amount of detail. None of its sections stand out as the best that we have ever seen, but it is one of the best "complete packages" that we have. This is the type of document that you should emulate.

Beam

Beam was the winner of the Most Polished Game in the mobile division at the 2014 Showcase. Like Over the Arctic Hills, it is an example of a solid, complete document with no serious flaws. In fact, the only issue with this document is that they do not vary the font size of the section headers enough, so that sections start to blur together.

Aquavoyant

The 2015 game Aquavoyant went through a lot of design changes, but they had a fairly solid architecture specification. It has a fantastic CRC section and great dependency diagram. There are some minor issues with the activity diagram (e.g. branches that do not come back together properly). But it is a good example over all.

Fenestra

This specification for the 2011 two-worlds game Fenestra has an fairly good dependency diagram. However, it gets the dependency direction wrong on the physics engine (how can Farseer know about the game objects?). The best thing about this document is the activity diagram. This is the right level of detail that we are looking for.

Exodus Protocol

The specification for the 2013 strategy game Exodus Protocol is one of the best examples of data representation that we have seen in this class. It goes into detail about the tags, instead of just providing and example that we have to decode. On the other hand, it does not overwhelm us with tags, only focusing on the most important ones.


Submission

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

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.