Writing Design Specifications

tim-cain game-design design-documents specifications production communication

Abstract

Problem: How do you write effective design specifications that can be handed to programmers and artists, and what pitfalls should you avoid?

Approach: Tim Cain walks through a concrete example — specifying a single weapon in a game — showing how the same item requires completely different specification documents for artists versus programmers, and why detail is the single most important quality.

Findings: Specifications must be extremely detailed with actual values (not vague descriptors), tailored to each discipline's needs, organized into clearly sectioned documents with cross-references, and must avoid both the trap of too little information and the trap of burying critical details in irrelevant content.

Key insight: The buzzword for design specifications is "details, details, details" — vague language like "reloads slowly" is useless; you must define what slow means (e.g., 3–5 seconds) so animators and programmers can actually do their jobs.

Source: https://www.youtube.com/watch?v=gmDX1p-WZ7g

The Core Principle: Details

Design specifications span a huge range — system mechanics, user interfaces, narrative guidelines — but they all share one thing in common: they require extreme detail. This is especially true when working with external teams (outsourced art, code, etc.), where you can't just walk over and clarify something.

Rather than covering every type of specification, Tim demonstrates by walking through a single weapon specification, showing how it splits into completely different documents for artists and programmers.

What the Artist Needs

Weapon Types and Visual Identity

The artist needs to know all the different weapon types in the game. This can be a separate reference document linked at the top of each weapon spec. The artist needs this context because they're making the weapon look like it belongs in your world — they need to understand the family of weapons.

Beyond types, you need to communicate the visual style: Is it super slick far-future sci-fi? Clunky mechanical sci-fi? Old-timey Victorian brass steampunk? There must be a standard look across all weapons.

Per-Weapon Art Details

For each specific weapon, the artist needs to know:

  • Handedness — one-handed or two-handed, which determines firing animations and hand placement
  • Reload mechanics — how is it reloaded? Magazine pops out the bottom? Break open the weapon? This affects animation design
  • Ammo appearance — what does the ammo look like? It's a separate art asset that needs to visually match the weapon
  • Wield/unwield behavior — does the weapon just appear? Do hands go down and come back up? Does the character reach behind them?
  • First-person vs. third-person — how it looks both when you see someone else do it and when you see yourself do it
  • Aiming — fired from the hip? Iron sights? Scopes that bring up a magnified view with crosshairs?
  • Timing information — how long to wield, aim, fire/recover, and reload, including ranges affected by perks or skills
  • Non-combat animations — which animations still show the weapon (walking) and which don't (lock picking)

Why Timing Matters for Artists

If an animation is too fast, it becomes impossible to execute well. If it's too long, it looks weird. Artists need to know the full timing range — including any perks that speed things up — to design animations that work across all scenarios.

What the Programmer Needs

Animation State Data

Programmers need weapon animation data, partly from designers (what states exist, timings) and partly from artists (which states can blend to/from which other states). For example: when holding a weapon, you can blend into aim or immediately into fire. Some states have idle animations; others are static poses.

Interrupt Behavior

A critical area: what happens when actions are interrupted? If a player is reloading and gets attacked:

  • Does the reload continue while taking damage?
  • Does the hit animation blend with the reload?
  • Is the reload halted entirely?
  • If halted, is the weapon partially loaded, fully loaded, or not loaded at all?
  • Is there a specific point in the animation where the reload "counts"?

Failure Cases

What happens when a player tries to reload with no ammo? Does it show a partial animation? Display a "no ammo" message? Just nothing? These edge cases must be specified.

Weapon Data and Exposure

Programmers need to know which values should be exposed to designers for tweaking (via tools or engine inspectors like Unity) and which should be hardcoded. Examples:

  • Ammo type, max capacity, weapon weight
  • Available attacks (standard fire, pistol whip, aim-down-sights, power attacks for melee)
  • Cooldown timers
  • Mouse/keyboard input mappings
  • HUD display requirements (current ammo, max ammo, cooldown displays, number digit count)

Provide Actual Values, Not Vague Descriptions

You cannot say "this reloads slowly" and "this one reloads fast." You must define what slow and fast mean: slow is 3–5 seconds, fast is under 2 seconds. Animators need these ranges to design appropriate animations, and programmers need them for timer displays and UI sizing.

The Two Pitfalls

Pitfall 1: Not Enough Information

If you don't provide enough detail, one of two bad things happens:

  • You don't get something you desperately needed — you forgot to mention a reload animation, so now reload just magically happens with no visual feedback
  • Someone else fills in the blanks for you — you get a reload animation, but it can't be interrupted because you never specified that requirement

Pitfall 2: Too Much Wrong Information

This is the internet recipe problem. If programmers have to wade through paragraphs of weapon lore just to find the cooldown timing, they'll either miss critical details or resent the document entirely.

The solution: break specifications into clearly labeled sections, and use cross-references. Information that applies to all weapons (weapon types, visual style guide) should be written once and linked, not repeated at the top of every weapon spec. Keep each section focused on what its audience needs.

Structuring Your Specifications

  • Use separate documents for shared reference material (weapon types, visual style, general UI conventions)
  • Link rather than repeat — put common information in one place and reference it
  • Organize by audience — artist specs and programmer specs for the same item look completely different
  • Section clearly — so people can jump to exactly what they need without reading the whole document
  • Give concrete values — numbers, timings, ranges, not adjectives

References