Advanced GDD Information

Page content

This page will suggest an example structure for a GDD (Game design document) and will explain why this structure is useful, it will also cover a number of tricks and how-to’s that can help to make a GDD more readable, to reduce unnecessary maintenance and to avoid duplicate information.

These concepts and examples expect that a wiki like confluence is used to create the GDD.

Some teams name their documentation after each department, but since Design will usually be the team that has the responsibility to look after the documentation this page will call it GDD and instead will feature department sections within it.

GDD style guide

Just some general rules to make each page more readable.

Start pages with a few sentences about the content of the page. If applicable contain the purpose and a user’s perspective.

Use headings to separate pages into topics

Only use typographical emphasis (bold, italics, etc) if something should grab attention.

Add a on this page section to each relevant page. This is a table of contents that lives in a fixed position on the side of the screen. This can be accomplished by using the “Easy Heading” macro.

Use info panels macro to highlight warnings and info.

Use the code snipped macro to show code.

Use the status macro to show the state of something.

For lists use Shift+Enter to add images in an extra line.

Use galleries to show multiple images at once.

External sources like youtube or Miro will generate preview links, use these previews to inspect a specific video time or board location.

Confluence tracks page updates like a version control system comment on relevant updates.

Use a Glossary macro to highlight common terms throughout the documentation. Applications should generally be avoided but adding them to the Glossary will resolve miscommunication issues that would usually be caused by them.

High-level GDD structure

This is a list of all the elements that are commonly contained within a GDD.

  • Creative overview
  • Next team meeting requests
    • A place for each team member to ask questions or recommend something to become part of the next larger team meeting
  • Starter Guide
    • The GDD wants one for each department
      • Links to GDD pages and references that are relevant for each new team member
      • Setup guides for software and tools used for the project
      • Link to the naming convention
  • Naming convention
    • Asset naming structure
    • Folder structure
    • Code naming conventions
  • Marketing
    • Marketing goals and plans for how to achieve them
    • Available and planned Trailers
    • Screenshots
    • Other relevant resources like social media or influencers
  • Production plan
    • Project roadmap
    • Relevant jira links
    • Benchmark list with descriptions
    • Milestone list with descriptions
    • Definition of feature/product quality levels
    • Team member list with contact information
    • Licenses needed and overall concerns
  • Features briefs
    • List of all implemented and proposed features
    • Some examples:
      • Character controls and abilities
      • Menus/HUD elements and other UI objects
      • Upgrades/Weapons/Tools/Mechanics/Modes the player has access to
      • Conversation tools and narrative interactions
      • Enemies and bosses
      • Inventory
      • Health/Lives
      • Scoring or how to win/lose
      • Checkpoint/Save system
      • Leaderboard/Achievement system
      • Vehicles
      • Minigames
  • Tutorialisation
    • Tutorial metrics/guidelines
    • A list naming each tutorial
    • A full step-by-step for each tutorial
    • Conditional tutorial rulings
    • Re-watch/enable/play tutorial feature
  • Design space
    • Work a lot with feature briefs
    • Breakdown of core pillars
    • Level design metrics
    • UI metrics
    • Player metrics
    • Enemy metrics
    • Level layout plans
    • Menu structures
    • Specific tech used
    • Open discussion area
    • Research area
  • Art space
    • Concept art
    • Player visual description
    • World visual description
    • NPC visual description
    • Levels visual description
    • Lighting goals + description
    • Techart guidelines
    • VFX guidelines
    • Style + tone pass principles
    • Specific tech used
    • Open discussion area
    • Research area
  •  Animation space
    • Animation guidelines
    • Specific tech used
    • Open discussion area
    • Research area
  • Audio space
    • Audio guidelines
    • Setup for Wwise/etc.
    • Setup for localisation LAMS/etc.
    • Haptics guidelines
    • Direct and environmental conversation guidelines
    • Music guidelines
    • Sound effects guidelines
    • Voice guidelines
    • Specific tech used
    • Open discussion area
    • Research area
  • Tech space
    • Work a lot with feature briefs
    • Code best practices/guidelines
    • Specific tech used
    • Open discussion area
    • Research area
  • Narrative space
    • Narrative guidelines
    • Backstories
    • Main story including description of the overall arc/structure
    • Side stories
    • Character descriptions/personalities/traits
    • World description/Narrative layers (Describe how a world came to be. Example city in Last of us 2: We have our normal everyday city, now parts get destroyed during the infection outbreak, nature reclaims parts of the city while humans are gone, humans come back to take shelter. This is the time the game plays in but the development should be recognizable in story, visuals and gameplay)
    • List of actors/voice actors for each character (Collaboration with audio)
    • Specific tech used
    • Open discussion area
    • Research area
  • Quality Assurance space
    • QA guidelines
    • List of all features with the current tested state (Depending on the project with multiple tested states sorted by milestones)
    • Test setup guides
    • Specific tech used
    • Open discussion area
    • Research area
  • Tools
    • List of all created/used tools with links to their corresponding how-to page
  • How-to’s
    • User guides for anything that would need one
  • User tests
  • Front-end game information
    • Credits list
    • Publisher
    • Licensors
    • Third-party software
    • Legal screen
  • Studio information
    • Annual leave rules + studio closing periods
    • Approved software
    • IT support guidelines
    • Studio points of contact
    • Shared software links
  • Archived content
    • Anything that is no longer part of the project

The document should also feature a revision history but if Confluence is used this is automatically created for each page separately which will usually be better anyway.

Feature Brief

This is the description of an element that is directly added to the project and it should add direct value to the final shippable product.

Feature brief structure

A feature brief will be built with a “Master” page that contains multiple sub-pages this allows to splitting of the relevant information into different categories while still allowing to keep all feature components in one place. Not every feature will need all components and some want their own specific components.

  • [Feature Name] Master
      • Contains: Feature summary; Feature owners (for each relevant department); State of completion; Direct links to all sub-pages;
    • [Feature Name] Direction
      • Contains: Feature purpose; Related core pillars; Direction description; References; Success criteria for the feature; Confirmation that direction and feature owners are in agreement about this feature; Link to the master page;
    • [Feature Name] Description
      • Contains: Detailed step-by-step feature description; Player perspective; Link to other relevant GDD pages; Link to master;
    • [Feature Name] Implementation
      • Contains: Required assets and code work; Implementation details; File names/Folder locations; Link to master;
    • [Feature Name] User guide
      • Contains: Setup guide and how the feature can be used by the team;

Purpose of each recommended page

  • Master page
      • Landing page  for organisation; Gives a one-line summary of the feature; Contains information about how to contact; Shows the current implementation state of the feature;
    • Feature Direction
      • Gives a high-level description of the intentions of the feature and defines the expectations of what it brings to the product; Gives useful references to deepen the understanding of the feature before development starts; Defines what makes the feature a success or a failed attempt;
    • Feature Description
      • Defines how the feature should function during gameplay; Defines how the feature fits into the product; Desciptes every element of the feature in detail;
    • Feature Implementation
      • Specifies technical details; Tracks required elements for the feature; Hands team members that are supposed to work on this feature in the future the required information;
    • Feature User guide
      • Allows team members to work with the completed feature without taking too much time from the people who have created the feature; Avoids potential errors;

Starter guides

A short list of the elements that should be contained in each starter guide document page if it is available.

  • Game pillars/Unique selling points/Project Logline/Game loops
  • Latest stakeholder presentation
  • Link to latest playable demo/build (Instruction to record 1st playthrough with a microphone and to speak their thoughts out loud)
  • Selection of useful resources and references
  • Links to the guidelines and metrics pages for the corresponding department
  • Link to the naming convention
  • Link to the production maps
  • How-to’s for engine setup/jira/etc.
  • Guide to setting up a test space for the department’s relevant work
  • List of team communication tools + necessary guides
  • List of required software
  • Relevant people and contacts (Direction/Leads/Production/QA/HR)

Naming convention

Many different people work on a project to make sure that these people can communicate effectively it is required that they all talk about the same elements using the same names and that everyone can find what they are looking for in the location they look for it. Naming conventions try to ensure that this can be the case by providing guidelines for how things should be named and where they should be located. A good starting point is the Epic Naming Convention.

The length of file/folder names is relevant since most operating systems have a max file path character count. The limit on a usual Windows machine is 260 characters so shorter names are encouraged.

Each team member should update this page if new elements are required. But one team member should take responsibility to make sure that these conventions are up-to-date and practised throughout the project.

Describe the typographies used

Capitalisation should have a recommended structure.

Examples: BigDog; bigDog; big-dog;

File names

Enforce a general structure for how files should be named.

Example: [ObjectType]_[Name]_[Version] = Material_RoughMetal_03

A list of all object types featured in the project should be provided if new ones are added to the project the list needs to be updated.

Folder structure

The folder naming conventions should follow the file naming convention for anything that is reasonable to move over (Folders will rarely feature a version number).

The GDD wants a list of the project folder tree for each main category and an explanation of what type of files should be stored in each of these categories.

There should be some general guidelines on when to create sub-folders and when not to create one.

Code naming convention

The tech team will usually come up with their own preferred naming convention but if at all possible finding a common ground on the previously stated rules is encouraged.

This is a good place to start if the team needs some guidance:

Metrics

A collection of relevant values that are supposed to be consistent across a project. These should be listed with the relevant department and enforced whenever they are used. Changing these values later during development might cause issues because the team has previously relied on them so ideally these should be established early and only be changed if absolutely necessary.

These metrics can be anything that should be consistent for a given project so each project will feature different metrics, that being said there are a number that will be commonly required.

Examples of values frequently tracked as metrics:

  • Player
    • Size in each dimension
    • Move speed
    • Max jump hight
    • Max jump distance
    • Fall damage distance
    • Crouch height/speed
  • Weapons
    • Basic weapon damage/speed/range
    • Basic explosion damage/area
    • Highest weapon damage/speed/range
  • Enemies
    • Basic enemy health/speed/damage
    • Basic boss health/speed/damage
    • Highies enemy health/speed/damage
    • Might change based on level/area
  • Mantling
    • Max/Ideal vault height
    • Max/Ideal vault depth (distance to jump over)
    • Min/Ideal overhead clearance
    • Vaulable window dimensions
    • Same for climbing heights
    • Clearly unreachable height
  • Falling
    • Clearly survivable drop distance
  • Ladders
    • Sprung spacing
    • Ladder width
  • Ground decoration  objects
    • Max height for an object not to have collision
  • Camera
    • Default camera position
    • Min height for objects to be visible in front of 3ed person player
    • Min height for ceiling not to obstruct the camera
  • Card game
    • Draws per turn
    • Basic power level to cost relation

Tools/How-to’s

A short list of the elements that should be contained in each Tools/How-to document page if it is available.

  • Overview of the tool
  • Description of purpose
  • Step-by-step user guide
  • Addition information about common use cases
  • Commonly used terms + definition

Font
Off On
Size
revert
Content
Color
revert
Links
Color
revert
Scroll to top