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
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
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
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
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:
The first is created when a player saves a game (either manually
or via a checkpoint), and the second is the output of your
- Saved game file
- Game level file
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
(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.
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
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.