Due: Saturday, March 11th 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 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
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.
Recall our discussion of
CRC cards in
the introductory class. If not remember it, reacquaint yourself with the
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 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. However, when designing your
cards, you should think about the important design patterns we talked about 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
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
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.
Third-Party Libraries (Optional)
We are not expecting you to write everything from scratch in this class. You are all
using our game engine CUGL. In addition many of you are planning to keep Box2D as your
physics engine. You may also want to add third party libraries for things that we did
not add, like pathfinding, character AI, or fluid-based physics.
In this section, list all of the third party libraries that the teams plans to use, beyond
those we provide. So you do not need to list CUGL or Box2d, but you are expected
to list Liquid Fun or
When you list a third party library, we want one CRC card for the entire library. For
the responsibilities, identify only what the library is responsible for in your game.
Functionality not used by the 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
In the introductory course, we also discussed the notion of
Activity diagrams outline the flow of the 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.
Teams should not need any more syntax than what we showed
in the introductory course.
If your team does 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.
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 you know from the introductory course, data-driven design is an important part of
game development. Much of your game content is stored externally in configuration
files, level designs, and object scripts. While this data may not be part of the team’s
software program, it is part of the game architecture. Therefore, it is important
to confirm 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.
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 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)?
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.
If the team havs 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 to specify these up to the team.
Application Restoration Plan
This last bit is necessary because you are all on mobile devices. As we discussed
mobile applications may or may not be suspended when the user returns to the home screen.
The team should have a plan for how 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, teams have to think about the App restoration restoration API as
defined in the
Provide a description of how the team is going to use this API to handle App suspension
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 all of the examples below put the dependency diagram after the CRC cards.
We are asking you to reverse this order this year. We have long used the dependency
diagram as a "table of contents" for the CRC cards, so it makes sense to do this first.
One of the most recent games on this list, Squeak & Swipe continues to be an example
of good documentation. Everything is clean and easy to read. Other than putting the
dependency diagram later, this is a good model to follow. This document is also notable
because they are using Tiled as their level editor, and this puts some contraints on
the serialization model.
Another game from 2016, Aphelion has fantastically clean diagrams. Both the dependency
diagram and the activity diagram are beautiful and easy to follow. You will also notice
that the CRC cards have a table of contents. If you put the dependency diagram first, you
will no longer need to do this.
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 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 the team does not vary the font size
of the section headers enough, so that sections start to blur together.
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.
This specification for the 2011 two-worlds game
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
The specification for the 2013 strategy game
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
Due: Saturday, March 11th at 11:59 pm
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
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.