Document Your Game

As a game designer, you will be primarily concerned with what is commonly called the design document, which I will explore in detail in Chapter 19. However, there are many other pieces of documentation used in the creation of modern computer games . Even though you may not work with all of these documents, it is important nonetheless to understand what each of them is supposed to contain and how the different documents are interrelated. So before delving into the nature of design documents, a survey of the different types of documents is appropriate. Different people at different companies or in different situations will invariably use a variety of different names for the documents listed below. You should realize that the naming convention I employ here is not universal, but the types of documents used are quite common throughout the game development industry.

Concept Document, Pitch Document, or Proposal

These are usually the first formal documents created for a given game. Often they are written in order to sell the idea of a game to a publisher (if the author works for a developer that does not publish its own work) or to upper management (at a company that publishes internally developed projects). In short, this document is shown to the green-light committee, the money, the suits , the decision makers , or whatever one may call them, in order to convince them to spend a lot of money on the idea, thereby funding its development. Concept documents are the seeds that have the potential to grow into a full game but all too often never get the opportunity. Concept documents are usually short in length, customarily no longer than ten pages, and in their more snazzy form include plenty of concept art. Often concept documents focus exclusively on high-level design issues, exploring the unique gameplay the title will provide, detailing the game s story, and generally pulling out all the stops to get the reader excited about the project. Writing a concept document can be quite a lot of fun, since the writer gets to focus on the most exciting parts of the game and does not have to worry about all the messy details of actually implementing the game. At the same time, it is important not to go overboard and promise the unattainable with your pitch document, since the more astute readers will quickly be able to pick up on the implausibility of your idea.

Concept documents can sometimes go a bit beyond the high-level ideas to become significantly more elaborate. In this case, they are often written by committee, typically involving the game s producer, lead designer, lead programmer, whatever marketing people may be on hand, and the lead artists who contribute a variety of sketches , conceptual pieces, and screen mockups . Concept documents discuss all aspects of the game idea in question, including how it might be positioned in the marketplace , budgets and development timelines , what technology will be used, what the art style of the game will be, mini-bios of the team members who hope to work on the game, and some broad description of the gameplay. These documents are not much use in the game s actual development, though they can be a springboard for creation of other documents, such as the design document or the art bible. Since concept documents do not apply very much to the game s actual development, I will not go into further detail about them.

Competitive Analysis

When writing a competitive analysis, you will need to include a discussion and potentially screenshots from the leaders in your title s genre . For an RTS title, you d almost certainly want to discuss WarCraft III .

The competitive analysis is another document used in trying to sell your game. Sometimes competitive analyses are written in the early stages of a game that has already been green-lit, in order to clearly show the marketing department how the game will fare in the marketplace. It typically includes a shorter, more condensed version of the pitch document, and specifically lists the unique features of the game being developed. The competitive analysis then lists a number of other games that have shipped in the recent past that are similar to the proposed game, provides a brief synopsis of the fiction and gameplay of each, and then describes how each of these games performed (via average review score, quotes from various reviews, and sales figures, if available). For each of these previously released games, the document will go on to describe how that game compares to the new game being developed. For example, if you were writing a competitive analysis for a proposed real-time strategy game, you would probably want to include the more recent games from the major RTS franchises, such as the latest addition to the Command & Conquer series, the WarCraft series, and the Age of Empires series. Competitive analysis documents typically do not help very much with development, but can provide a useful reality check to help you realize that the game you are hoping to create really is exactly the same as another title that shipped six months ago.

Design Document

In other parts of the software development industry, the equivalent of the design document is often called the functional specification. Indeed, some game developers refer to the design document as the functional specification. I prefer design document because it is the more widely used termand because it better represents the content of the document. The design document s goal is to fully describe and detail the gameplay of the game. For large team projects, the design document serves as a vital reference work for how the different aspects of the game need to function, with, ideally , team members referring to it throughout the game s development. Producers will often use the design document as a springboard from which to schedule the project. A well-written and complete document can also be of vital importance when a game is subsequently converted to another platformby a different development team. The document can serve as an ideal reference tool for this new team to understand how the game is supposed to function as they start porting it to a new system, assuming it is kept up to date over the course of the project.

Whereas a functional specification for, say, a spreadsheet application can be extremely detailed and complete, a design document for a game is necessarily less complete because of the more organic, dynamic, and iterative nature of game development, as I discussed in Chapter 15, Getting the Gameplay Working. As a designer working on a large team project, the design document will be the primary specification with which you will need to be concerned. The guts of a design document are the detailing of game mechanics: what the players are able to do in the game-world, how they do it, and how that leads to a compelling gameplay experience. Design documents typically also include the main components of whatever story the game may tell and a detailing of the different levels or worlds the players will encounter in the game. Also included will be lists of the different characters , items, and objects the players will interact with in the game-world. One can think of the important aspects of the design document as not dissimilar from what a journalist looks for in a news story: what the players do (which actions the players can perform), where they do it (the game s setting), when they do it (at what time and in what order the players must perform different actions), why they do it (the players motivations), and how they do it (what commands are used to control the game).

The design document can also be defined by what it does not include. Most of the content contained in the other documents listed in this chapter should not be found in the design document, including the bulk of the information found in the script, the technical design document, and the art bible. In particular, a design document should not spend any time describing the game s development from a technical standpoint. Platform, system requirements, code structure, artificial intelligence algorithms, and the like are all topics that should be covered in the technical design document and therefore avoided in the design document. The design document should describe how the game will function, not how that functionality will be implemented.

Similarly, discussions about the marketing of the game, explorations of how it will be positioned compared to other games in the marketplace, and sales projections are all inappropriate in the design document. In addition, schedules, budgets, and other project management information should be left out. This information should certainly be recorded in some documents, such as the pitch document or project schedule, but it should be strictly excluded from the design document. I would think that such an exclusion would be obvious to anyone undertaking a design document, but I have seen many design documents that spent half their pages considering how the game will be sold. The design document needs to describe how the game functions so that someone working on the development team can see exactly what he needs to create. Including materials that are more about the business side of the game s development will only get in the way of more appropriate information.

The design document and its creation are discussed in more detail in Chapter 19, The Design Document. You can find sample design documents in this book s two appendixes.

Flowcharts

Flowcharts may often be included as part of the design document or as separate documents. In game development, flowcharts have two primary uses. The first is to track the players navigation of out-of-game menu options, such as those players use to start a new game or load a saved one. Flowcharts can also be used to chart the areas the players progress to and from in the game, particularly in level-based games. Beyond these most obvious applications, flowcharts can be quite useful for visually representing the results of any decisions players may get to make in your game. Flowcharts are a means for visually representing a chunk of gameplay, whether micro or macro, and can often evolve into full decision trees with lots of branches, each representing a player choice that leads to new choices or loops back to previous decisions. These visual representations can be helpful not only to a designer trying to figure out what the consequences of a player s actions will be, but also for communicating the sequence of events and choices to other members of the team. With complex scenarios involving a lot of branching, a flowchart representation will be much more effective at getting your ideas across than what you will be able to convey with text alone. Flowcharts can be either handmade or developed using various flowchart creation tools, such as Visio.

Story Bible

For games that tell stories, some amount of that story must be included in the design document. Certainly a summary of the game s overall story is essential, and a thorough description of the game-flow will need to include parts of the story, but the design document often cannot include it all. This is especially true if the game being developed involves a complex story line with a variety of characters and locations, or if the game takes place in a universe with a specific history. A story bible may be the best place to document this information. Often the author of a game s story will have in his mind a vision for the universe and its inhabitants beyond the scope of the game, such as where game characters come from and what their motivations are, and how the game-world came to be in the state it is in when players encounter it. What the players experience may be only the tip of the proverbial iceberg, with the story s author having in mind ten times more detail about the game-world than is actually communicated to the players through the gameplay. Other aspects of the universe may only be hinted at. By having a complete plan for the game s back-story, even if the players do not directly learn all of it, the story s writer will have a much better chance at keeping the game s narrative consistent and plausible.

A story bible, then, is a good place to document a game s potentially extensive back-story. Separating this information from the design document proper avoids burdening it with a lot of information that is less central to the game s creation. Weighing down a design document with a lot of back-story is an easy way to give it perceived depth and completeness, but can hide the fact that the specification fails to fully cover game mechanics and other more vital information. Nonetheless, the back-story is still important, and hence the value of its documentation in the story bible. Once a story bible has been created, when an artist wishes to learn more about the character he is modeling, he can turn to the bible and find out about that character s childhood. He can make his art better by making it fit with the back-story. When a voice actor wonders how he should play that same character, if he has read the story bible he will be working from the same information base as the artist. Properly used, a story bible can add to a game s consistency.

Should there ever be a sequel or spin-off made from the game, the game s story bible becomes all the more useful when the development team for the derivative project tries to understand what sort of new story line can be crafted. Since the story bible included more content than was actually used in the original project, it will provide the new team with plenty of unexplored areas of the game s universe. If the story bible is followed properly, the new game will fit in perfect continuity with the original. As that team creates the new game, the bible can be expanded and updated so that future projects will be just as consistent.

The format for a story bible is fairly open , and the bible s author should make the format best fit the information he is planning to include. Often the story bible consists of a number of different historical narratives of varying lengths. One narrative might describe the history of the game-world, detailing the major events that have led the world to the state it is in when the players start their game. Similarly, the document could include narratives for the different major characters the players encounter in the game. Topics discussed would include the character s childhood, how he rose to whatever position he has in the game, and what motivates the character to act as he does. By having a sense of the character s background, when it comes time to write the game s script, the game s writer will be better equipped to create compelling and believable dialog for the different characters. Of less importance but perhaps still appropriate for the story bible are the histories of the various major items or locations the players find in the world. A powerful sword might have a colorful history that NPCs may hint at when they talk of the object to players. A particular shrine might have a dark secret of its own. However, the author should always be careful to try to keep in mind how much information is actually going to be useful to the game s creation, and should not feel obligated to fully explain the lineage of every last character and object in the game. Include only the information that you think will be important to the game s creation.

The writing style of the story bible should be in more of a prose style than the bullet-point style of the design document itself. A team member using a story bible is more likely to want to sit down and read a few pages at a time, and will appreciate bible content that reads and flows nicely . Breaking the document down by character, item, or major event is still useful to the reader, so using a good quantity of appropriately titled headings is a good idea. You may also wish to include various diagrams in the document to supplement the written content, such as timelines, event flowcharts, or character-relationship trees. These charts can prove useful in allowing the reader to understand a particularly complex game-world.

On the other hand, even with a complex game-world, you may not need a story bible at all. If the author of the game s script is able to keep track of characters and their motivations in his head, and if the likelihood of a sequel worked on by another team is low, the creation of a complex story bible may not be a good use of anyone s time. It all depends on the working style of the team, particularly the lead designer and scriptwriter, who may or may not be the same person. Certainly many great authors have managed to write novels far more complex than your game is likely to be without keeping more than a few scribbled notes to themselves , if that. Many complex films have only had a script to go on for their stories, with the actors responsible for interpreting their characters motivations based only on the lines they are supposed to speak. It may be that the script s author created a story bible for his own personal use, and never saw fit to share it with anyone else. The story bible is a tool that can help in the creation of the game s story, but it may not be a tool that every scriptwriter or game designer feels the need to use.

Script

If a game has a story, it is quite likely that at some point players will be asked to listen to narration, hear characters talking, or read information about upcoming missions. This dialog and the accompanying descriptions of the situations during which the dialog occurs (stage directions) should be contained within the game s script. A game s script may be written by a variety of people: a designer, an artist, the game s producer, or someone whose only role on the project is to write the script, someone who was specifically hired for his dialog writing skills.

The script may take on different forms depending on what type of game events the dialog will accompany. For instance, if the game has film-style cut-scenes, the script may closely resemble a movie script, with descriptions of the actions the players witness and rough indications of what the camera is looking at for any given instant. Or the script for these cut-scenes may be more like that of a play, focusing primarily on the dialog. For in-game conversations, the script will focus primarily on the dialog, since players are still in control of the game and thereby in control of what direction the game s camera is pointing. But a script for the in-game cut-scenes might include stage directions or set directions along with descriptions for the accompanying character animations to assist the artist in creating the appropriate motions to accompany the dialog.

For instance, here is an excerpt of a script that could be used for a cut-scene in an adventure game:

When the PLAYER approaches PAUL and SANDY after resurrecting the TREE OF PLENTY, PAUL will be visibly thrilled at the player s arrival. He immediately bursts into effusive praise for the player s accomplishments:

PAUL: That s just the solution we have been praying for! You have saved our great Tree, and nothing we can do could ever thank you enough. Please accept this token of our appreciation ...

PAUL tosses a BAG OF FLIMFLAMS at the player s feet. SANDY steps forward:

SANDY: [Apologetically] We know it s not much, but . . .

PAUL: [Interrupting] It s all we have!

SANDY: [Cowering] Please do not hate us for our poverty. . .

The non-linear nature of games demands that the script be organized and presented differently from a play, movie, or television script. If players have branching conversations with NPCs, as they might in an RPG or an adventure game, the script will need to take on a special form conducive to the non-linear nature of the interchange. Here a script might use small amounts of pseudocode, using IF-THEN-ELSE or SWITCH-type syntax to communicate when the players would hear different pieces of dialog.

Returning to our adventure game example, here is one possible layout for a more non-linear conversation. This game uses the old keyword conversation system, where the players type in a word and the character being talked to may or may not have information about that subject:

IF the player asks about FLIMFLAM :

PAUL: A FlimFlam is a drop of dew, fallen from the morning sky, carefully wrapped in a baby leaf from the Tree of Plenty. It has special curative properties for Humanoids, when rubbed on the back of the neck.

IF the player asks about TREE OR PLENTY :

PAUL: The Tree of Plenty has been my people s source of life since before any of us can remember. Without the shade it provides, my people grow exhausted in the noonday sun. Without its leaves , we have nothing to eat. Without its strength, my people are weak.

DEFAULT , if the player asks about anything else:

PAUL: I do not know of what you speak, stranger. We are not the most intelligent of peoples; we are not as wise as a great traveler , such as yourself.

In-game dialog may be randomly varied between a number of expressions that communicate the same information but say it differently. Simple OR statements between different lines of dialog can communicate to the reader of the script that the game will randomly choose between several different lines of dialog.

Once again returning to our adventure game, here we have a sample of dialog that players might hear during actual gameplay:

When the player bumps into PAUL, he says:

Oh, excuse me, begging your pardon.

OR

Oh dear, I seem to be blocking your way.

OR

My mother always said I was born to get in her way.

There is no industry-standard syntax that dictates the formof an interactive script. It is up to the designer, producer, and scriptwriter to come up with a form that best documents the dialog they will need to use in their game. Some RPG games, such as Deus Ex , involve so much conversation and branching dialog trees that they employ fairly robust and advanced scripting languages for the designer or writer to use to implement the dialog. Designers will often want to write their interactive script to match the syntax found in such an editor, so that when it comes time to implement the dialog the process will be greatly simplified.

Games that feature a lot of branching conversations, such as Deus Ex , often include a scripting language specifically for implementing the dialog.

The game s script is also where one might find the text of what the character reads in a mission briefing or in a book they might find. Any text that is contained in the game, from signs and posters on the walls to the commands issued to the player character from an off-screen commander, is included in the game s script.

As games try to incorporate more and more story, scripts documenting all of the dialog they include have become necessary. The most important thing to remember when working on the script for your game is that people are usually playing your game not for the dialog but for the gameplay. If they had wanted to watch a movie, they would have done so. Instead they booted up your game. They may enjoy hearing some clever dialog while they are playing, but they are usually not so interested in listening to long, drawn-out cut-scenes that delve into endless back-story. If the gameplay is any good at all, players are going to want to get back to it as quickly as possible. If players find themselves more captivated by the dialog in your game than in the gameplay, you need to wonder why you are bothering to make a game at all.

Art Bible

The art bible is often composed primarily of concept sketches and other resources that artists can refer to as they are working on creating various visual assets for the game. Sometimes text accompanies these images, whether in the form of handwritten notes on concept sketches or text descriptions describing the parameters artists should follow when coming up with new elements for the game. The art bible is usually not compiled or written by the designer, but instead by the lead artist working with his team. Of course, the information contained in the art bible needs to correspond and be consistent with the story and characters described in the game s other documents, including the design document, script, and story bible. Therefore, when constructing the art bible, the artist will work closely with the designers, writers, and producers to make sure his work is going to fit with the overall vision for the game.

The art bible is the place where the look and feel of the game is comprehensively established in detail. Descriptions of the art style to be employed in the game (art deco, anim , Warner Bros. cel animation, neo- realism , and so forth) will be found in the bible accompanied by sketches that communicate the game s style better than words ever could. It is important to keep the descriptions of the game-world s art style in this document instead of in the design document in order to allow each document to stand on its own as a comprehensive reference tool. Of course, designers on a project should read over and be familiar with the art bible, if for no other reason than to make sure it is on track with the rest of the game. An art bible may also contain technical guidelines that artists need to follow to create assets that will work with the game s engine, as detailed in the technical design document. This may include polygon limitations to be followed or the duration and number of frames involved in different animations.

The Game Minute

The game minute is typically a one- to three-page document that describes in detail a short section of gameplay. These documents are often written very early in development, when what exactly the gameplay consists of is still fairly nebulous. These documents can be used to communicate to the team or to upper management what direction the game is going and to serve as a reality check to make sure everyone is fully on board with how the game s high concept will actually play out. For this reason, the gameplay described in the game minute should be representative of a relatively average gameplay experience, not a boss battle or the training mission. Since in many ways the game minute is supposed to function as a reality check, it really needs to describe your meat-and-potatoes game experience. Game minutes are written in a prose style and go into specific detail about what exactly the player is doing from moment to moment in the game. Some game minutes even go so far as to list each button or key press the players would make to accomplish the various objectives in the game.

Game minutes can be very useful, but they can also be somewhat problematic since they represent a single way of playing out a scenario. This problem can be somewhat ameliorated by writing the text in such a way that it suggests what the player might do differently in a given situation. For example, in an action-adventure game, the player might see: Rounding the corner, the player sees an intimidating Blugbatter Beast. The player contemplates charging up and attacking it with his cattle prod, but then recalls that the Blugbatter Beasts are immune to electricity, except in a weak spot at the base of their neck. Since the Beast has not yet seen the player, the player quickly backs up around the corner and waits there quietly . Knowing the Beast should soon be patrolling in this direction, the player hopes to surprise him and attack him from behind... In addition, a designer may want to consider writing up several different versions of a game minute to show how significantly different approaches to a given scenario might play out. However much the designer tries to fix this problem, he is still stuck with a narrative that only describes one particular sequence of events.

Sometimes team members who do not understand what a game minute is supposed to accomplish may even become confused when they read it, wondering, Is that all the player can do? Nevertheless, if used properly and if the team is made fully aware of the document s function, a game minute can be a very useful tool when the game is not yet in a playable state because the project is still very early in development.

Storyboards

Storyboards are an established film and television device for sketching or mocking-up shots before they are actually filmed. Storyboards may be included as part of the art bible or can stand alone as their own separate document. Storyboards are most handy for mapping out non-interactive cut-scenes, which are quite cinematic in nature and are thereby well suited to storyboarding. This allows members of the development team to provide feedback and corrections on those cut-scenes before someone goes to the trouble of filming or rendering them. Storyboards can also be used as concept sketches or mock-ups for how the game-world will appear to players if the game s engine is not yet ready to be used. Such storyboards can be useful both for making the entire team understand at an early stage where the game is heading, as well as convincing financiers to fund the project s development. Much like the game minute document described above, storyboards can be problematic because they necessarily represent a single way of playing a given area. Since they have their origins in film, traditional storyboards are completely linear and may suggest to readers that the game is more cinematic than it really should be. Indeed, when people fall in love with what they see in a storyboard they may try to limit the player s choices to doing only what has been drawn out. It may be advantageous to use some kind of branching storyboards, where the consequences of major player choices are drawn and then laid out like a flowchart or decision tree. Unfortunately, sometimes when people get overly excited by storyboarding a game it can be another case of movie envy, where developers actually wish they were filmmakers. Storyboards can be helpful, but only up to a point. In the end, they cannot replace actually prototyping gameplay on the computer, getting the game to a somewhat playable state, and then refining it until it is truly fun and all the player s choices are available for playtesters to explore.

Technical Design Document

A technical design document (TDD) is the sister specification to the design document. Whereas the design document focuses on how the game will function, the technical design document discusses how that functionality will be implemented. You can also think of it this way: the design document communicates how the player experiences the game, while the technical design document goes into how that experience will be implemented. Sometimes called the technical specification, the technical design document is customarily written by the lead programmer on a project, and is used as a point of reference by the programming team. Here is where the code s structure is laid out and analyzed . The technical design document is where programmers on the project can turn to figure out how they should implement a specific system. The document may include the overall code structure, what major classes will be used, descriptions of the rendering architecture, details of how the AI will function, and any amount of other implementation-side information. Pseudocode is appropriate, though not required, in the technical design document. Though the technical design document may be a good idea, in the past many projects have managed to undergo perfectly successful development cycles without a technical design document ever being created. On the other hand, with today s ever more complicated projects, escalating budgets, and the resultant increase in scrutiny placed on all titles, most all games developed now use one or more TDDs. Whether that TDD ends up being followed or not is another issue. In part to help fix the problem of useless TDDs, many developers avoid writing a massive and highly detailed TDD at the beginning of the project and write more of an outline or framework document up front. Then, as development progresses, they write smaller TDDs as each feature of the game is about to be implemented.

As I have mentioned, technical design documents are used primarily by the programming team. Nonetheless, it is very important that a designer with any sort of programming experience (or even one without any) look over technical design documents for his project, since they will certainly contain general descriptions of how AI and other algorithms will function, along with other information critical to the gameplay. Just as looking through the art bible is important for a designer to do, reading through the technical design document or documents, even if he cannot understand all of them, will give the designer a chance to make sure the programming team is on the right track.

Schedules and Business/Marketing Documents

I include these in my list of game development documents in order to emphasize that schedules, budgets, and marketing projection information does not belong in the design document. On many occasions, I ve read design documents that had whole sections about how the game might be sold. Indeed, some so-called design documents are little more than dressed-up marketing plans. Such business-oriented information is neither appropriate in the design document, nor does it belong in any of the other documents I have discussed here, except for the concept document. The design document is about the game s functional design, not how it will be advertised or sold at retail. It is best to separate out such marketing plans and business data into distinct documents, where the people concerned with such information can best review it.

When working on a large-budget project that hopes to at least recoup its capital investment, it is important to have well-thought-out marketing projections, budgets, schedules, and any number of other documents that will assist press relations people, sales representatives, and advertising artists when they are working on your project. The lead designer on a project should offer his services to help in the creation and maintenance of these documents in whatever way he can, though the writing of these documents usually falls on people more attuned to selling and managing rather than creating. Often it is the responsibility of the game s producer to develop and maintain these documents. Still, it is the designer s moral responsibility to make sure that the people funding the project know what sort of a game they are getting. This makes them less likely to become upset down the road when the game is done and it fails to match the advertisements and box art they have already spent large amounts of money creating. And when the suits understand what makes your game good, they are far less likely to demand changes or, even worse , cancel it. If the business people are really happy with the finished product, they are much more likely to be enthusiastic about promoting and selling the game, which can only mean more people will end up playing it.

No Standard Documentation

Different companies may have different standards for what documentation they create in order to assist and guide a game s development. Though they may have different names for the documents than those I have used above, I think these categories cover the vast majority of documents that companies will create. Some teams may split the design document into two documents, one containing only gameplay information and the other containing only story and level progression descriptions. Some development teams may create only a design document, having no need for a story bible. Some programming teams may find that they do not need a technical design document. Some art directors may make it through a game s development without a formal art bible. Some teams working on multimillion-dollar projects may even get through them without any documentation at all, though this is increasingly unheard of as publishers demand documentation so that they have some idea of exactly what game they are financing. Furthermore, publishers like to have some tangible proof that the development team has a good idea of what it is doing. Usually, how much documentation a publisher requires is inversely proportional to how trusted and experienced you and your team are as developers. The newer and more unproven your team, the more assurances the people funding your project will want to make sure you are not throwing money away.