CMPM171, Winter 2015, Section 01: Technical Design Document

At the beginning of every release in the agile Scrum process, and especially during the very first sprint for a project, a team must think through the software design implications of the work they will be performing during the release. For the very first sprint, the team needs to create a software design that will ideally act as a scaffolding for the implementation effort in remaining sprints. For subsequent releases (and sometimes for individual sprints), the team needs to determine what changes they will make to the existing design to accommodate the specific changes that will occur in that release/sprint. This may involve changing aspects of the existing design.

The purpose of this document is to describe the internal structure of your code at the class level, and give an overview of how the code behaves at runtime. This is accomplished by creating UML class diagrams to represent the static structure of the code, and UML sequence diagrams to represent important aspects of its dynamic behavior. These diagrams represent the detailed technical design of your project.

One aspect of software design is the use of software design patterns, where they are appropriate. Computer games often make use of the Strategy (implementation examples), Chain of Responsibility, and Composite design patterns.

A complete technical design document will contain a static structural description and a dynamic description, detailed below.

Static structural description. In one or more UML class diagrams, represent all of the classes and interfaces that your team will develop in your project. Where you create subclasses of existing game engine or game framework classes (e.g., SFML), you should also indicate these classes as well on the UML diagram, though not to the same level of detail. Each class should describe the class variables, and all of the methods in the class. Ideally you will also provide method parameter lists, though this is not strictly necessary. Diagrams should represent all inheritance and containment relationships among classes.

There will generally be two broad categories of UML class diagram structures, depending on whether your team is creating its own game engine, or is building off an existing game engine. Teams that are building their own engine will tend to have many classes that are highly interconnected. Teams building off of game engines will tend to have a series of mostly isolated class clusters that subclass off of various leaf nodes in the game engine.

For teams developing their own game engine, the class diagram typically needs to describe the following game elements:

  • input handling
  • representation of game levels, if present
  • player class
  • enemy classes, including a container holding active enemies
  • game object classes, including a container to hold them
  • collision detection
  • classes for drawing player, enemies, other game objects
  • classes for handling audio
  • menu system classes

Your game may also include other elements above and beyond this list.

For teams using a game engine, the elements that need to be represented will vary depending on the services provided by the game engine, but will typically include game-specific enemy AI, game-specific animation routines, non-standard collision behavior, code that is executed by in-game triggers, etc.

Dynamic description. In a series of UML sequence diagrams, describe the most important code sequences in your game.

As with the class diagrams, the most interesting and relevant code sequences will vary, depending on whether your team is developing a game engine from scratch, or is using a game engine (and hence mostly subclassing off of existing classes).

For a team developing its own game engine, modeled sequences should include at least the following:

  • Initialization. What happens when the game first starts running? This involves creating model and view objects, loading levels, playing background music, displaying an initial menu, etc.
  • Menu system. If the game has a series of menus, what is the sequence of selecting one menu item?
  • Main game loop. What methods are called, in which order, during each clock tick of the game during normal operation? Typical operations include gathering input, updating state, collision detection, checking for end-of-level conditions, drawing objects, and updating particle systems.
  • Player collision. What happens when the player has a collision, such as with a wall, a bullet, an enemy, or other? This involves updating object state, visually representing the collision, and often playing some kind of sound.
  • Enemy collision. What happens when the enemy has a collision?
  • End of level. What happens in the game when there is a transition to a new level?

For a team using an existing game engine, it may make sense to model the sequences above, at least in how they affect the code that your team is developing. Other sequences may also be important, depending on how the game engine works, and how it makes calls off into your code.

Common pitfalls. A common error is lack of consistency between UML class and sequence diagrams. For example, if a method is given in a sequence diagram, it should also be defined on a class in a UML class diagram. This error often occurs when class diagrams are created by one team member, sequence diagrams by another, without having a meeting to make them consistent. It is also common for the UML sequence diagrams to omit some of the relationships among classes. Other common errors include not including audio handling, or having inconsistent handling of input between class and sequence diagrams. Another common source of error is inconsistency between the game design document and the technical design document. Are the game aspects described in the game design document also present in the technical design document?