Due: Saturday, March 19th 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.
This is a document where it is very 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. This is
why we have structured the lecture on
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 Architectural 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 both the
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
The specification should cover all of the major details covered in the lectures on
Therefore, we suggest that you organize your document as follows.
Class-Responsibility Collaboration Divisions
Remember our discussion of
CRC cards covered
in class. These 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
We also talked about the
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
We did talk about the
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 the 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 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.
Because this section of the document is the hardest to get right, this will be the
focus of a
You will have the opportunity to submit your CRC tables, and receive comments, before
turning in your complete architecture specification.
Third-Party Libraries (Optional)
We are not expecting you to write everything from scratch in this class. Most of you
are already planning to keep Box2D as your physics engine. A few of you might be using
other external libraries, such as the
AI extensions to LibGDX.
In this section list all of the third party libraries that you plan to use. In addition,
even though you are not implementing any of these libraries yourself, we want CRC cards
for each one of them. 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.
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.
If a bunch of related modules all have exactly the same edges, you might want to nest
them inside of a larger box. The modules are then submodules nested inside of this
larger module, and the dependency is between the larger module and the rest of the code.
We showed several examples of this in class.
The dependency diagram should include both your own classes and the third-party
libraries. We need to see how everything fits together.
lecture, we also talked about
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
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-draw
loop. Features outside this loop, like the main game menu or initialization can
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.
Data Representation Model
As we have mentioned several times in class,
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, in which case you should include those in this document as well.
We list some of those below.
For each file type in your game, you should clearly describe the file
representation. This includes
The file format (e.g. XML, JSON, or other)
The information stored in the file
How this information is stored (e.g. the XML or JSON tags)
Saved Game File
If you are using a checkpoint save model, this could be as simple as storing the
current 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 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.
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.
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.
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.
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.
The architecture specification of the reflection-mechanic platformer
is an excellent example of how to present CRC cards and the dependency diagram. The document
starts to look a bit "unfinished" once you reach the serialization model, but it is very
strong before that point. This document also has API implementation details that we no
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/Box2D 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
We regularly use the 2014 mobile game Over the Arctic Hills
as an example of how to write documents 4152. This document covers all of the
requirements that we listed above, and presents everything with the right amount of detail.
As a 4152 game, it has an extra section on how to handle the case when the user pauses
the game; obviously we do not want that.
Due: Saturday, March 19th 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
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.