The Anatomy of a Design Document, Part 2: Documentation Guidelines for the Functional and Technical Specifications
by Tim Ryan
Guidelines for the Technical Specification
While the functional specification explains what is going into the product, the technical specification explains how. The technical specification (or tech spec) is a working blueprint for the game.
It turns conjecture into reality by forcing the programmers to think through how the game will be implemented, by reducing implementation/integration headaches, and by delineating the program areas and tasks for the schedule.
Many companies will skip this step, as it is time consuming and seemingly benefits only the programmers. However, time spent working on a tech spec is less than the time lost from pitfalls that come with not writing one. The primary author is the lead programmer or technical director, though it is often more timely and useful if the programmers responsible for implementing the various program areas be responsible for documenting them. In its compiled form, it should present a plan that any programmer can understand and work from.
The target audience is the lead programmer on the project and the technical director of the company. Therefore it will generally be written from the system perspective as opposed to the user perspective. It will be boring and Greek to the producer and any other non-technical readers. By asking for one, the producer is just making sure the technical staff thinks everything through, even if he or she doesn’t understand it. To the lead programmer, it’s a way of organizing his or her thoughts and creating an accurate picture of the work involved. The process of writing it will flag any of the uncertainties on the programming side and any of the holes, ambiguities or absurdities in the functional spec.
Many good technical specifications vary from the form described here. This form mirrors the functional specification to ensure that all areas of the functional specification are covered. Sometimes it’s easier for a team writing this spec to organize it differently, if only because they are splitting the work differently or because of the organization of the underlying system. If they do, I’d recommend going through every line of the functional specification and do a correlation with a highlighter to make sure nothing has been overlooked. An overlooked detail can lead to undesirable results in the product, project and team dynamic.
These guidelines will not tell you how to implement your game. It’s assumed that you are a technically competent, experienced game programmer. An inexperienced or untrained game programmer should not attempt this task. These guidelines are the result of what I’ve come to expect in a good technical specification, though I certainly couldn’t tell you how to program your game. These guidelines force you to define the most common elements one finds in all games. Some may not be applicable, but each should be considered carefully. It may spark a question you haven’t asked yourself yet; which is sort of the whole point of writing this spec.
This is certainly the bulk of the document. Right away you’ll see that any attempt to match up specific subsections with the game mechanics section of the functional spec is totally ludicrous. The perspective must be from the system out as opposed to the designers’ or users’ perspective. This starts with the hardware platform and the operating system, the use of externally provided code objects (DLLs, EXEs, drivers), and the delineation of internally generated code objects (if any). Then it breaks down the specific mechanics of game code stemming from the control loop.
Platform and OS: Indicate the hardware platform and the operating system and the versions supported. For PC/Mac games, mention the minimum system requirements and the target machine. If distributed on something other than a CD like a cartridge, indicate the target ROM.
External Code: Describe the source and purpose of all the code used but not developed by the project team. This includes OS code and preprocessing tools of the various game platforms, drivers and code libraries like DirectX, any acquired 3D API, or any other off-the-shelf solution.
Code Objects: Break down the purpose and scope of the various code objects coded, compiled and built into the EXE. If any out-of-process or in-process code libraries (DLLs) are used, break them down as well, but be sure to explain the use of object instancing and their persistence (like Direct Draw objects).
Control Loop: Every game has one. Be specific about how control is transferred from the start-up code to the shell and down into the main game code. Spell out the names of the functions in the core loop and what they will do, like the collision, movement and rendering routines. Explain the use of multi-threading, drivers, DLLs and memory management. Of course further details on the likes of multi-threading and memory management will be covered in the areas that they will be used most, like the rendering or sprite engine, sound code and AI.
This subsection summarizes the system and underlying framework that supports the core game play and game flow described in the functional specification.
Game Object Data: Read carefully over the functional spec at all the character/unit descriptions and game play elements. Then list and formulate all the data structures and their identifiers that are required to support the described attributes, functions and behaviors. To a certain extent, these will not be complete until the game physics and statistics and AI subsections are completely thought through and documented. Add statistics for user interface or any other area of the game that have unit or game play object specific data (i.e. icons, HUD displays, animation or special effect references, etc.).
If using object oriented programming methods, show the class inheritance tree and each class’ interface properties and functions. Describe the use of collections. Identify any variables that could possibly be made into global variables to increase performance, such as any objects variables that may be referenced multiple times during critical game routines such as collision, movement or rendering. Again, I’m not telling you how to program your game. I’m just trying to get you thinking about common technical issues, specifically in regard to optimizing data structures for neatness, versatility or speed.
Data Flow: Explain how data is stored, loaded, transferred, processed, saved and restored. While references should be made to data entry or processing tools, separate functional and technical specifications should be made for any complex or user intensive tools.
Game Physics and Statistics: This is the nitty gritty – movement, collision, combat – and probably the most fun to document and implement. However, it can also be the code that gets altered more than any other part of the program. Designers like to change things. It’s often only after they can play it for a while before they can really decide what is right. For this reason, you should plan to implement things as modular and flexible as possible. Put all the factors that control behavior into data files read at run-time, so the designers can change and balance things at their leisure without involving coding changes and new builds. The specification should clearly identify the modularity and divisions between code and the data that controls it.
Define each function or procedure. Describe its purpose. Define what statistics control its behavior (constants, variables etc.) and how they can be modified. Include the function prototype listing all the parameters. If using function pointers and function overloading, specify where the different versions of the function will be used. For example, you may have multiple functions that handle movement for the various unit types – one for land movement, one for air, one for water, etc. Briefly describe how the function will work. For complex functions, use pseudo code to specify exactly how you will code it. This is especially important for CPU intensive functions that do a lot of number crunching or are just called very often. Think about how they can be optimized to increase performance. Perhaps bit-shifting or macros could speed things up.
Artificial Intelligence: This often grows to a major section unto itself and is then scaled back when the schedule dictates the necessity to keep it simple. This shows a growing enthusiasm for complex AI, but a lack of time and resources to make AI anything more than simulated intelligence or scripted behaviors. Be mindful of this when you design the AI scheme. Try to accomplish the behaviors and decision making described in the functional specification without adding a huge layer of unnoticed and therefore unappreciated realism to the process. The basic rule of production applies here. If something that costs less and takes less time to build does the job, then don’t spend more time and money creating something else.
Of course, there are exceptions that should be mentioned. Sometimes something might take longer to build, but it saves the designers a lot of time working on their levels. Also, creating something more flexible or powerful may make it a valuable asset to the company for other projects or just make it more capable of handling design changes should they occur. Discuss these with your producer and director of development before making a decision.
Be sure to include the methods of manipulating the AI as dictated by the functional spec, i.e. whether it’s data driven or embedded into compiled code, and whether it’s a scripted language or a fixed set of variables or a combination of both.
AI should include path finding, target selection, tests and events to attach reactionary behaviors to, and other decisions made by characters, units or intelligent game elements involving game situations and unit statistics.
DO NOT include the actual scripts or data driving the AI. That’s production work. Merely be specific enough to explain how the decisions and behaviors will be derived. Break down the statistics used to control the behavior.
Multiplayer: It’s extremely important that the implementation plan is reviewed from a multiplayer perspective. This subsection should break down all the multiplayer considerations in game mechanics and all the multiplayer specific requirements specified in the functional spec.
Multiplayer over multiple PCs (as opposed to console sharing or hotseat) has a lot of unique requirements that should be addressed. What connection methods and protocols are supported? Is it client-server or peer-to-peer? What are the packet sizes and how often are they sent? What is the structure of the packet? How are missed packets and latency issues handled? What messages are broadcast and what are sent to specific hosts? How many different messages are there and when are they used?
Look and feel is one area of the design that undergoes the most changes during development. Therefore, its necessary that the programming for the GUI be as flexible as possible, separating game purpose from GUI function, so that changes that occur to the user interaction methods will not affect other areas of the game or require significant reprogramming. Create a variety of GUI objects (controls) using inheritance to maintain a consistent code interface to the events and the values. This way a slider bar can be exchanged with a text box or radial buttons with little or no changes to the calling functions. Assume that any of the GUI objects can be exchanged at any point in the project.
To this end, your documentation should be flexible and generic. While it should break down the GUI into the screens, windows and menus, it should not go any further into the specific interaction.
Instead, document how the various GUI objects will work, wherever they are used.
Make references to functions in the game mechanics documented in the previous section, but anything that’s interface related should go here. Explanation of the drawing and clipping routines of the graphics engine should be left for the Art and Video section, but certainly they should be referenced here in terms of view ports and HUD attachments and anything the player can interact with.
Document the names for any of the global variables, constants, macros, function names or interface properties, so that other programmers can refer to the documentation without having to dig through code. This also avoids replication and inconsistency and increases clarity.
Game Shell: List all the screens that make up the game shell – all the screens and windows other than the main play screens. These are derived from the flowchart in the functional specification, but may include some additional screens that the lead designer may have overlooked or brushed over (like installation or setup screens). Each item listed should be its own subsection with a description of its purpose, its scope (i.e. before or after level specific data is loaded), the pertinent values it will be accessing and setting, and what functions it will call.
Main Play Screen(s): These are the one or more screens in which the core of the game is played. Though many people think from the GUI perspective down to the complexities of what’s under the hood, this should be written from the low-level mechanics perspective (the engine and rotors) out to the GUI (the hood and the dash). This keeps it consistent even if the outward appearance of the GUI should change.
Art and Video
While this section in the functional spec pretty much just listed the art and video, the technical spec has to explain how the art and video will be stored, loaded, processed and displayed in the game. This includes the animation system, whether it’s 2D or 3D, and the video decompression and streaming system. Of course some of these might be off the shelf solutions, especially the video code. But all the interfacing should be mentioned here.
Graphics Engine: Whether you are using sprites, voxels or 3D-polygon rendering or a combination, break down their functions in very specific detail. While it’s only 2 sentences of description here, it will likely prove to be a very meaty piece of the spec. Describe areas like view ports, clipping, special effects, and the connection to the collision and movement functions described in the game mechanics.
Artist Instructions: Break out the details important to the artists, like resolutions, bit depth, palettes, file formats, compression, configuration file definitions and any other data the artists need to define to fold in the art. Consider what tools can be created to streamline the art pipeline, and indicate their specifications here or create separate specifications for the more complex or user intensive tools.
Sound and Music
Describe how sound will be loaded and played. Be specific about the use of mixing, DMA, multiple channels, 3D sound, and methods of determining priority. If using third party drivers, describe their interface and purpose. Be sure to address all of the requirements specified in the functional spec.
Sound Engineering Instructions: Break out the details important to the sound engineers and composers, like sample rates, the use of multiple channels, 3D sound definitions, sample length etc. If using MIDI, indicate the version to use and the number and type of instruments that can be used and possibly stored. Indicate the data path and file requirements including any specific configuration files that need to be created. Consider what tools can be created to streamline the sound pipeline, and indicate their specifications here or create separate specifications for the more complex or user intensive tools.
Level Specific Code
Based on the level design seeds in the functional specification, describe how code specific to those levels will be implemented and how it will accomplish the desired effect. Also describe how any other level specific code can be interfaced to the game code should the need arise to add more. In general, you should try to make any of the level specific code as generic and as flexible as possible so that it may be freely used to accommodate similar needs for other levels or new ideas.
Here are some common mistakes to look out for:
•Hand waving: It’s very tempting to just list the functions and not fill in all the details that force you to really plan how you are going to implement them. Sometimes they are just glossed over, but really the hand waving should end with the functional spec. This spec is supposed to force the programmers to really think everything through ahead of time. How else are they going to estimate the task time correctly?
•While it can be very effective to assign portions of the technical spec to the individual programmers responsible for implementing it, it’s not always in the best interest of the game or indeed the programmer to do so without some supervision. An entry-level programmer should get some guidance, and all the programmers should discuss and critique their documentation before it gets all folded together. Some companies have regular code reviews where programmers critique each other’s work. That should start even sooner during the design phase.
Guidelines for Paper Level Designs
The designers should do paper versions of level designs before they begin creating the levels in the editor. Ideally, the designers will be familiar with the design palette, the level editor and game engine capabilities before they get started. Paper level designs are creating during the implementation phase, though they are based off of level design seeds expressed in the functional specification. These seeds are the core idea for the level and/or the basic requirements that may indicate what new assets are being introduced or what to limit the design to. It’s best not to do all of the paper designs at once, either, as the designers usually learn a lot while implementing each new level.
For some reason, producers often expect the cart to come before the horse, so before serious level design begins, push for a playable, prototype level to be created first. It’s often a milestone unto itself that ensures that the tools and game mechanics are working well enough to develop levels. It should also serve as a guide to what can be accomplished with the editor and engine and epitomize the vision for level design.
Following the first playable mission, level design can start in earnest. Yet even here, documentation plays an important role in saving time and ensuring quality through meticulous planning and the critical process. The process of level design that works:
Step 1: Thumbnail & Discussion
The level designer conceives of a level layout that meets the requirements laid out in the functional specification and asset revelation schedule. He or she then produces a thumbnail sketch and discusses the concept with the lead designer. The thumbnail could be on a white board or a note pad. It is a visual aid in the discussion. It does not need to convey the entire idea or all the details for the level, as these often evolve during the discussion or get tossed out altogether.
The benefit of doing a thumbnail sketch and discussion rather than forcing a designer to first think everything through and document it is that it saves time. A senior or lead designer can in a matter of minutes determine whether a proposed level design has merit and give valuable advice that can drastically alter the design. A fully detailed and documented paper version can take days or even a week to put together. Depending on the skill of the designer, a designer might get sent back to the drawing board many times. This is especially true near the beginning of the project, when the designer is still learning what the lead designer wants, and near the end of the project, when original, compelling level concepts are harder to come by.
Step 2: Detailed Paper Version
With an approved thumbnail and level concept, the level designer can work on a detailed paper version of the level design. The layout (or map) of the level should be much more detailed than the sketch and should be drawn to scale. This is best done on a large sheet of graph paper using colored pencils. Information about objectives, behaviors, buildings, enemies, events, locations etc. should either appear on the map or on a separate document with reference points on the map. Any mission specific art or code should also be listed. This amount of detail can take a few days or as long as a week to draw and document, but it saves a lot of time that would otherwise be spent “searching” or “redesigning” in the actual editor.
When completed, the lead designer, producer and any other principal decision-makers should subject the paper design to an approval process. They may approve it, throw in some changes, or kill the level right then and there.
It’s also important that someone technical, preferably a senior programmer, review the paper design from a technical standpoint. This gives the programmers a heads up on what the level designers are going to attempt to do with the tools and graphics engine. They might add some features to the tools or make some code adjustments to make the level possible or just easier to implement. They may also vote to eliminate or alter any level designs that may break the game or are similarly unfeasible.
It’s often very tempting to skip this step and jump right into the editor as it’s often faster to just build a prototype of the level than to write up the paper version. This is especially tempting in tight schedule situations. Yet, it’s these tight schedules that make documentation that much more important, because it means there’s even more reason to get it right the first time and reduce the number of surprises and time to redo the work. The benefit of a detailed paper version is that it forces a designer to think everything through and express the fun and challenges before he or she implements it. It also ensures that the details that may involve more tasks for programmers, artists and sound technicians get documented and scheduled for completion before the designer begins working on the level.
This article is focused on documentation, but for completeness to this section and to this process, here are the remaining steps to level design as I see them:
Step 3: Creating the Core of the Level
The designers should establish the core game play of the level using broad strokes. They should get it to the point that it gives them the fun and challenge they envisioned in the paper design. The designer should then get feedback from the lead designer and producer, who will determine whether the level has merit or not. It may indeed prove impossible to accomplish what the paper design suggested, or it may prove to not be as fun as was expected. This is simply a review point in the level design that saves the designer time should drastic changes need to be made or the level dropped entirely.
Step 4: Filling in the Finer Details
Once the core game play of the level is established, everything else should just make it better. These are all the things that establish the setting, flesh out the level, and liven up the fun by providing more options, solutions, or surprises.
Often new art or code assets may seem appropriate, so be sure the designers find out they can get them before putting placeholders in. Then update the paper design and task lists.
Step 5: Play Test
Have the designers play their levels and get as much feedback as possible. Again, documentation plays a role here. Be sure they keep track of all their bugs, feedback and tasks with at least a notebook and pencil. It’s very easy to lose track of issues at times (not to mention sheets of paper), so a centralized database with level specific issues and feedback is ideal.
For further guidelines for level design, I encourage you to read my articles on level design that present a background to level design and some rules to design by. The first part “Level Design Theory” can be found here. The second part “Rules to Design By and Parting Advice” is available here.
Documentation Milestones and the Development Schedule
Below is a list of the typical milestones in a schedule and where the documents described in this series serve as deliverable items. Following each milestone would be a review of that milestone, which would require approval to go on to the next. As the production schedule isn’t due until after the bulk of the documentation, then there shouldn’t be an impact on the schedule if time needs to be spent going back to the drawing board and creating specifications that everyone can agree with. It’s a recipe for disaster to race into production with iffy design documents just because of the urgency to meet an arbitrary ship date. In the end, it usually doesn’t save you any time, and in fact often leads to wasted efforts and significant delays.
•Document: Game Concept
•Document: Game Proposal
•Document: Functional Specification
•Document: Technical Specification
•Documents: Tool Specifications (if applicable)
Production Phase (sometimes called Implementation Phase)
•Technology and Art Demo
•First Playable Level
•Documents: Paper Level Designs (not always a deliverable)
•Alpha – Functionally Complete
Testing Phase (Quality Assurance)
•Beta – First Potential Code Release
•Gold Master – Code Release
There could be more milestones, as it’s often necessary for publishers to have some means of determining and ensuring that progress is being made. Sometimes there are arbitrary monthly milestones for particular art, code, and design. The ones suggested here are the most common and have the greatest significance.
Dealing with Change
It can be a beautiful thing to witness a project run smoothly following these guidelines, but what typically happens is some change to the vision due to inspiration or market trends. It’s very easy to slip into design-on-the-fly mode to try to adapt to the new vision without impacting the schedule. Of course it inevitably does anyway, because design-on-the-fly has its dangers. In these cases, the only way to make sure this doesn’t happen is to be adamant about the guidelines and the procedures they promote. This is easier if it’s spelled out in the contract. Don’t make any changes to the game without it going through the documentation. A change to the functional specification potentially invalidates the technical specification and subsequent schedule. It’s certainly grounds for reassessing the schedule. It should be very clear to the principle designers who may want these changes that when they sign-off on the functional specification and deliver it, they do so with no expectations on being able to make changes. Then, if they really want the change, the impact can be lessened with a period of updating the documentation and a reassessment of the schedule. The threat of being stuck with what you got or being late is certainly compunction enough to put as much forethought as possible into the design and produce the best possible documentation. The guidelines presented in this series of articles should help you do just that.
For more details on how to deal with change, I encourage you to read my article “Controlling Chaos in the Development Process” published here.
This concludes part 2 of a 2 part series of articles on the anatomy of a design document. （source:gamasutra)