Assignment 9
Architecture Specification

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

An architecture specification is a document that roughly outlines the architecture for the 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. This is why we have structured the lecture on architecture design the way we did. You 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 both the concept document and gameplay specification, this file should be constructed with clear sections and subsections. You should follow the writing guidelines and make good use of font styles, font size, and other forms of formatting to make it readable.

The specification should cover all of the major details covered in the lectures on architecture design and data-driven design. Therefore, we want you to organize your document as follows.

Dependency Diagram

Remember the in-class CRC Card exercise. 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.

You will eventually give us details on the CRC cards describing your architecture. However, we want a visual summary at the very start of this document. The dependency graph or diagram shows each of the CRC cards and their relationship to one another. 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. If you are unsure of how to do this, 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.

Class-Responsibility Collaboration Divisions

Once you have the dependency diagram summarizing everything, we want you to present more detail about the various modules. As the architecture specification is a single written document, we are not asking for teams to turn in a set of index cards. Instead, present the CRC cards in table form, as shown in several of the examples below. In addition, for each table, teams should provide the following information.

• A high-level, English description of what the module in this table does.
• Justification for why this table 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. However, when designing your cards, you should think about the important design patterns we talked about in class.

Model-View-Controller Pattern

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 one 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. While it is not required, we highly recommend that you annotate each card by the appropriate catagory.

Entity-Component Pattern

This is an optional pattern that is recommended if you find yourself wanting to use a lot of subclasses. 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 (beyond model, view, and controller), if you wish.

Wording Responsibilities

One of the things that shows up in (bad) first drafts of these documents is badly worded responsibilities. Remember, responsibilities are things that other classes depend on to do their work. They are the public aspect of the class. Do not talk about private functionality like object state. Do not say stores, holds, keeps track of, manages or anything else that describes hidden functionality. Can I get or set a value? Then that is the responsibility.

In addition, keep your responsibilities to a reasonable minimum. Model classes often have a lot of properties you can get/set. Do not list them all. But do not collapse them into a single category either. Break them up into wel-defined categories like physics-related, animation-related, combat-related, and so on.

Third-Party Libraries (Optional)

Third-party libraries include anything that you rely on that (1) you did not write yourself and (2) is not part of LibGDX. Some of the older examples below include Box2D as an example. But those are based upon older engines that did not include Box2D. Box2D is no longer considered a third-party library.

A good example of a third-party library that you might consider is LibGDX AI. This is an external add-on to LibGDX, and is not part of the core engine. It adds classes for pathfinding and state machine management. It is not the most user-friendly library in the world, so make sure you study it before adding it.

The purpose of this section is to list all of the third party libraries that you plan to use. Only include this section if you actually use third-party libraries. We do not want you to add this section and say "We do not use any third-part libraries."

Even though you are not implementing any of these libraries yourself, we want CRC cards for each one of these libraries. Identify only what the library 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.

Activity Diagram

In the architecture design lecture, we also talked about 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 mandatory activities, and use diamonds to fork optional activities. You should not need any more syntax than what is covered in the architecture design lecture. If you do not believe that you can express your activity diagram with these building blocks, 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.

The activity diagram should coincide with the 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, 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 we have mentioned several times in class, 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.

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

For each file type in the game, 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)

This last one is the trickiest to get right. It is not enough to slap an example on the page. You must describe to use what the various tags/keys are and what they represent. However, some of you have very complicated JSON files with lots of keys. So our rule of thumb is this: list on only the top-level keys and then devote a paragraph explaining the subtress under that key. The example document for Exodus Protocol below illustrates what we are asking for.

What files you are going to have can be determined within the team. However, we recommend that teams 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 the saved game file. It has to contain all of the world geometry, any trigger or script references (these may be separate files), and so on.

This document is always in flux. We are not expecting you to get it 100% correct on the first draft. We 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

• 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.

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.

You will note that some of the examples below put the dependency diagram after the CRC cards. We are asking you to reverse this order. We have long used the dependency diagram as a "table of contents" for the CRC cards, so it makes sense to do this first.

Flourish

The most recent game on this list, the architecture specification for Flourish is about as good as it gets for this course. There is ample division without overclassing, and theCRC tables are clear. The activity diagram uses branching correctly and the data representation format gives just enough detail. However, the activity diagram might be a bit too details (it does need be this fine grained). And the LevelController class feels like it collapses a model and a controller together.

Felongeist

The most innovative game at the 2017 Showcase, Felongeist also has a very strong concept document. We particularly like the section on their level save file. They break the top level tags into subsections and explain them well before showing an example. This is the level of detail we want on the data serialization model.

Squeak & Swipe

The 2016 game Squeak & Swipe was actually developed for the advanced class (which is why they have this mysterious section on App Restoration Plan). But the rest of the document is familiar and easy to read. We have included this document because they used Tiled as their level editor. They did an excellent job of describing the important parts of the Tiled data format (e.g. their custom properties) and omitting everything else. If you plan to use Tiled, look at this example.

Teddington

Teddington won Most Polished at the 2016 showcase. Their document is an example of a very well-structured architecture specification. One of the more interesting things to pay attention to is how they handle subclasses in the dependency diagram. Subclasses are represented as nested CRC cards. Once again this is an older document that puts the dependency diagram in the wrong place.

Dispossessed

We have used the 2015 game Dispossessed for several examples already (including your two week reports). That is because this group was really good at writing documents. Their architecture diagram is a solid example of what we are looking for. They just have some minor formatting issues with spacing.

Ersatz

The 2015 clone-stealth game Ersatz is another great example of an architecture specification. This was a particularly complex architecture that had a lot of custom lighting algorithms. In addition, we really like their dependency and activity diagrams. Again, they just have some minor formatting issues with spacing.

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 14th 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.