Animating with Purpose: How to Document and Plan Game Animations

Why Animation Documentation Is the Most Underrated Part of Game Production

Game animation documentation is the work that happens before an animator opens their software. It is the difference between an animator understanding exactly what they need to create and an animator guessing — and guessing wrong — at what the game requires. It is the difference between a technical designer building a state machine that matches the animation library and one that breaks two days before ship because an expected animation does not exist.

Most small studios skip animation documentation entirely. They operate on verbal agreements, ad hoc requests, and shared intuition that breaks down the moment a team member is on vacation or the project grows beyond a single animator's mental model. The result is a game animation list that exists only in one person's head, animation assets that are named inconsistently, and a state machine that references animation clips that may or may not exist in the current build.

This guide covers everything you need to build a professional animation documentation system — from the initial animation list through briefs, style guides, state machine specs, naming conventions, and handoff documentation.

Building Your Game Animation List

The animation list is the master inventory of every animation your game requires. It is the single source of truth for what needs to be created, what exists, and what state each asset is in. It is not glamorous work, but it is the foundation on which every subsequent animation decision depends.

What Goes in an Animation List

A complete animation list entry should capture:

• Animation ID: A unique identifier used throughout the project (e.g., PLR_LOC_RUN_FWD_01)
• Display name: Human-readable description ("Player Run Forward")
• Character/rig: Which character or rig this animation belongs to
• Category: Locomotion, Combat, Interaction, Cinematic, UI, etc.
• State machine state: The state in which this animation plays
• Transition dependencies: What animations this one transitions to and from
• Priority: Critical path, important, or nice-to-have
• Source: In-house keyframe, mocap capture, pre-made pack, AI-generated
• Status: Not started / In progress / Needs review / Approved / Integrated
• Notes: Special requirements, known issues, reference videos

States and Transitions

Document the animation list alongside the state machine logic, not separately from it. Every animation state should map to an entry in the animation list, and every transition condition should be documented alongside the states it connects. When a technical designer builds the state machine, they should be able to reference the animation list and find every clip they need — already created, named, and in the correct location.

Animation Priorities

Categorize animations into three priority tiers from the start:

• Critical path: Animations without which the game cannot be played. Locomotion, core combat actions, death. These must be done first and done well.
• Important: Animations that are expected and will be noticed if absent. Secondary combat moves, interaction animations, hit reactions for all damage types.
• Polish: Animations that elevate the game but are not required for function. Idle variations, environmental reactions, rare contextual events.

In any schedule crunch, the priority tier determines what gets cut and in what order. Making this explicit at the start of production prevents painful arguments at the end.

Writing an Animation Brief

An animation brief is the document you give to an animator — in-house, freelance, or a mocap performer — that tells them everything they need to know to create a specific animation correctly. A good brief eliminates the most expensive communication in game animation: the rework cycle caused by an animator building the wrong thing.

What to Include in an Animation Brief

• Animation ID and name
• Context: Where does this animation play? What is the character doing? What has just happened? What happens next?
• Duration: Target frame count and frame rate (e.g., 30 frames at 30fps)
• Entry pose: What pose should the animation start from? Is it a continuation of another animation?
• Exit pose: What pose does the animation end on? What will it transition to?
• Key actions: A beat-by-beat breakdown of what happens in the animation (e.g., "Frame 0–5: windup / Frame 6–12: strike contact / Frame 13–30: recovery")
• Reference footage: Links to video references — film clips, sports footage, previous animations in the game that establish the style
• Technical constraints: Root motion or in-place? Specific contact points that need to align with gameplay geometry? Blend in/out requirements?
• Performance notes: What emotion or character quality should the animation convey? This is especially important for a mocap actor who is performing the motion live.

Briefs for Mocap Sessions

When briefing a mocap performer, the brief needs additional practical detail:

• Props required and their approximate size/weight
• Whether the performer is working alone or with another performer
• The sequence in which takes will be captured (group related animations together for performer efficiency)
• Any safety considerations for physically demanding actions
• Number of takes expected per animation

A mocap session brief doubles as the session shotlist — the document the director uses to manage the capture day and ensure all required animations are captured before the performers leave.

Creating an Animation Style Guide

The animation style guide defines the visual and performance language of your game's animation. It answers the question: "Does this animation fit in this game?" without requiring a senior animator to review every asset.

Core Sections of an Animation Style Guide

Animation philosophy: One or two sentences describing the overall feel. "Weighty and grounded — every action has momentum and consequence" versus "Fluid and expressive — character animation prioritizes readability over physical realism." This is the north star for every animation decision.

Timing and spacing: What is the target frame rate? How is anticipation used? Are animations slow and deliberate or fast and snappy? Reference specific games or films that exemplify the desired feel.

Weight and physicality: Does the character feel heavy or light? How do they respond to impact? How does secondary motion behave?

Transition style: Fast cuts between states or smooth blends? What is the standard blend time for locomotion? For combat?

Character personality in animation: How does personality manifest in idle variation, locomotion style, and reaction animations?

Reference wall: A curated set of video references that define the target quality and style. This is the most useful section for a new animator onboarding to the project.

Working with Technical Designers on State Machine Specs

The animation state machine is the bridge between the animation list and the game's runtime behavior. It needs to be documented collaboratively between the animator who owns the animation assets and the technical designer who implements the logic.

State Machine Documentation Format

Each state in the state machine should have a corresponding spec document covering:

• State name and ID: Must match the implementation exactly
• Animation clip(s): Which clips play in this state (single, looping, or blend tree)
• Blend parameters: What gameplay variables drive blend weights (speed, direction, stance)
• Entry conditions: What must be true for this state to be entered
• Exit conditions: What triggers the transition out, and to which state
• Interrupts: Which transitions can interrupt this state mid-play
• Events: Any animation events that fire during this state (sound cues, VFX triggers, gameplay hitbox enable/disable)

Using a spreadsheet or Notion database for this allows the technical designer and animator to work in the same document simultaneously and keeps the spec as a living reference throughout production.

Documentation Tools: Notion, Confluence, and Spreadsheets

The right tool for animation documentation depends on your team size, existing infrastructure, and how the documentation needs to be accessed during production.

Spreadsheets (Google Sheets / Excel)

Best for: Animation lists, status tracking, naming convention reference, session shotlists. Spreadsheets are universally accessible, easy to filter and sort, and require no setup.

Limitations: Not great for rich text, embedded video references, or hierarchical documentation. Large animation lists in spreadsheets become hard to navigate.

Recommended structure: One sheet for the master animation list, one for state machine specs, one for the naming convention dictionary.

Notion

Best for: Animation style guides, briefs, and reference libraries. Notion's database features allow you to build a relational animation library where each animation entry links to its brief, reference videos, state machine spec, and current asset file.

Limitations: Requires setup investment. Works best when the whole team uses Notion for project documentation rather than as an isolated animation tool.

Confluence

Best for: Larger teams already in the Atlassian ecosystem (Jira + Confluence). Strong templating, good search, and integration with Jira bug tracking.

Limitations: Overkill for small teams. Requires Atlassian licensing.

Recommendations by Team Size

• Solo developer: A well-organized spreadsheet is enough. One tab per documentation category.
• 2–5 person team: Notion with a dedicated animation database. Free tier is sufficient.
• 6–20 person team: Notion or Confluence, with explicit ownership of each documentation section.
• 20+ person team: Confluence with Jira integration, or a production tracking tool like Shotgrid.

Reference Video Organization

Reference video is the most important creative input in animation production and the most consistently disorganized. Reference footage gets saved to personal drives, sent in Slack messages, and forgotten. A simple reference organization system saves hours of re-searching for the same footage multiple times across a production.

Reference Folder Structure

/reference
  /locomotion
    /walk
    /run
    /crouch
  /combat
    /melee
    /ranged
    /special-attacks
  /interaction
  /cinematics
  /style-reference
    /game-references
    /film-references

Each reference folder should contain a brief text file naming the source and why the reference is useful. "clip01.mp4 — The Last of Us Part II — excellent weight in the tackle animation, study the follow-through frame 0:23."

For teams using Notion, embed reference videos directly in animation brief pages so the reference is always next to the brief it supports.

Animation Asset Naming Conventions

Consistent naming is not optional — it is load-bearing infrastructure. A state machine that references PLR_RUN_FWD will break silently if the animator delivered the file as Player_RunForward_V2_FINAL.fbx. Every hour spent searching for misnamed animation files is an hour not spent making the game better.

Recommended Naming Format

[CHARACTER]_[CATEGORY]_[ACTION]_[VARIANT]_[VERSION]

Examples:

• PLR_LOC_RUN_FWD_01 — Player / Locomotion / Run / Forward / Version 1
• ENM_CMB_ATTACK_OVERHEAD_01 — Enemy / Combat / Attack / Overhead / Version 1
• NPC_IDLE_VARIATION_02 — NPC / Idle / Variation / Version 2

Naming Convention Rules

• All uppercase, underscores only (no spaces, no camelCase, no hyphens)
• No special characters
• Version numbers are always two digits (01, not 1)
• Directional suffixes: FWD, BWD, LEFT, RIGHT, or compass directions (N, S, E, W, NE, NW, SE, SW)
• Variant suffixes for blend tree entries: SLOW, MID, FAST for speed; LIGHT, HEAVY for stance
• Draft versions: add _WIP suffix. Approved versions: remove _WIP

Document the full naming convention in a shared reference and enforce it with a brief review step before assets are committed to version control.

Version Control for Animation Files

Animation files are large and change frequently. Standard Git is not well-suited to binary file versioning, but several approaches work well:

Git LFS (Large File Storage)

Git LFS stores binary files (FBX, BIP, BVH) in a separate storage backend while keeping Git for the rest of the project. Works well for small-to-mid size animation libraries. Requires all contributors to have Git LFS installed.

Perforce Helix Core

The industry standard for game binary asset versioning. Handles large animation libraries natively, has good file locking (preventing simultaneous edits to the same animation file), and integrates with Unreal and Unity. Perforce offers a free tier for teams up to 5 users and 20GB.

Plastic SCM (Unity DevOps)

Now part of Unity's DevOps platform, Plastic SCM is well-integrated with Unity and handles large binary files well. If you are on Unity, this is worth evaluating before setting up Perforce.

Naming Branches for Animation Work

Use descriptive branch names that reference the animation being worked on:

anim/[animator-initials]/[animation-id]-[brief-description]
anim/jd/PLR-CMB-ATTACK-OVERHEAD-polish-pass

Handoff Documentation

When an animation is complete and ready for integration, it needs a handoff document — a brief record of what was delivered, how to use it, and any known issues.

Animation Handoff Checklist

• File location: Exact path in the project repository
• Animation ID: Matching the animation list entry
• Frame range: Start and end frames in the file
• Root motion: Is root motion present and correct?
• Events: Any animation events embedded in the file and their frame positions
• Known issues: Anything the integrator should be aware of (minor clipping in edge case, specific blend time recommended)
• Review status: Approved by whom and when

Keep handoff documentation in the same place as the animation list — one document that tracks the animation from brief through to integration. When the project ships, this document is your animation production archive.

FAQ: Game Animation Documentation

How detailed does the animation list need to be at the start of production?

It needs to be detailed enough to make scheduling decisions. At the start, you need to know the count and priority tier of every required animation. You do not need every field filled in from day one — but the more detail you can capture early, the fewer surprises appear later. Revisit and refine the list at each production milestone.

Who owns animation documentation?

The lead animator owns the animation list, style guide, and briefs. The technical designer or technical animator owns the state machine spec. They should maintain these documents collaboratively with regular cross-review. In a solo project, you own all of it — build the habit of documenting your own decisions as you make them.

How do we handle animations that change significantly after the brief is written?

Update the brief when the animation changes, and note the revision with a date and reason. Keep previous brief versions if possible — "animation brief v1 proposed a forward-charge animation; v2 changed to a leap-attack after gameplay testing showed forward charge was unfun" is valuable production history. This is where a Notion database or Confluence page is better than a flat document — revision history is automatic.

Is it worth documenting animations for a solo project?

Yes, but proportionally. For a solo project, a single well-organized spreadsheet with your animation list, status, and naming dictionary is enough. You do not need Confluence or formal state machine spec documents. The minimum viable documentation for a solo project is: know what animations you need, know which ones exist, and name them consistently.

How do pre-made motion capture packs change the documentation process?

Significantly for the better. When you license a pre-made mocap pack, you receive a library of animations with consistent naming and known characteristics. You can map pack animations directly to your animation list entries — instead of commissioning and tracking custom animations, you document which pack clip maps to which game animation ID. This reduces production risk, compresses the brief-to-asset timeline from weeks to hours, and gives you a stable reference for your state machine spec from day one.

Build On a Documented Foundation

The most productive animation documentation practice is to start with a clear inventory of what you need, and then fill it with high-quality assets that require no rework. Pre-made professional motion capture packs give you a tested, documented library of animations that you can map directly to your animation list and integrate without a custom capture and cleanup cycle.

Browse our full library at MoCap Online — All Animation Packs. Each pack is organized by category — locomotion, combat, sports, interactions, and more — making it straightforward to build your animation list around a proven foundation rather than starting from zero.