AAA Game GDD Skill

AAA Game Design Document (GDD) Skill

Path Convention: All scripts/, references/, assets/ in this file are relative to the directory containing this SKILL.md. Before running python scripts/new_gdd.py, first locate that directory (Cursor/Codex install it via install.ps1 to <project>/skills/game-dev/aaa-game-gdd/). If unsure, find the absolute path of this SKILL.md and use the absolute path to call the script; typing a relative path from the project root will result in a file-not-found error.

What This Skill Does

It turns "I have a game idea" into a complete set of documents that a team can follow directly to develop a Steam-ready, AAA-quality game. The core deliverable is a structured, quantified, reviewable set of Markdown documents (GDDs), not a vague design proposal.

Each document produced must satisfy three iron rules:

1. Actionable: Developers reading the document should not need to ask "What exactly do I do? How big? What standard?" Everything quantifiable must be given specific values (poly count, frame count, duration, resolution, frequency, delay, trigger conditions).
2. Verifiable: Every asset, system, and scene must have a Definition of Done checklist, allowing each item to be checked off upon completion.
3. Consistent: All documents share the same vision pillars, art bible, naming conventions, and performance budget; documents cross-reference each other by ID and must not contradict each other.

Document Map (Read References on Demand)

Do not read all reference documents at once. First, determine which type of document the user needs to create using the table below, then read only the corresponding reference. Each reference is structured as: what problem it solves → when to write it → chapter structure → how to write each chapter (with quantitative standards) → good/bad examples → Definition of Done checklist.

Document	When to Read This Reference	Corresponding Template (assets/templates)
00 Overall Document System	New project initiation, need to determine document list and phase plan	README.md
01 Vision & Pitch	When a game idea first emerges; need a one-pager to explain the game or pitch externally	01-vision-pitch.md
02 Art Bible	When defining art style, unifying team aesthetics, or creating art briefs	02-art-bible.md
03 Scenes & Levels	When writing scene descriptions, level flow, routes, encounters, environmental storytelling	03-scene-level.md, scene-sheet.md, level-sheet.md
04 Gameplay Systems	When designing core loops, combat, progression, economy, stat tables	04-gameplay-systems.md, system-sheet.md
05 Narrative & Dialogue	When writing story outline, chapter beats, branching, dialogue scripts, voiceover scripts	05-narrative-dialogue.md, dialogue-sheet.md
06 Interaction & UI/UX	When defining controls, interaction matrix, game feel, HUD, menus, accessibility	06-interaction-uiux.md
07 Character Specs	When detailing protagonist/enemy/NPC settings, appearance, move sets, AI, stats	07-character-spec.md, character-sheet.md
08 Prop Modeling Specs	When specifying props/weapons/environmental asset modeling, textures, LODs, naming, delivery	08-prop-modeling.md, prop-sheet.md
09 Animation Specs	When defining 3D skeletal animation, animation state machines, cutscenes, 2D sprite animation	09-animation-spec.md, animation-sheet.md
10 Audio Design	When specifying music, sound effects, voiceover, dynamic music, bus loudness	10-audio-spec.md
11 Technology & Performance	When choosing engine, rendering pipeline, frame rate/memory/package budget, platform	11-tech-performance.md
12 AAA Quality & Steam Review	When defining stage gates, QA plan, Steam store page & release, AAA benchmarking scoring	12-steam-qa-checklist.md

Workflows

Workflow A: New Project (From Idea to Complete Document System)

1. Clarify Minimum Necessary Information (ask the user in one batch, no more than 4 questions): one-sentence game genre and core gameplay, engine (Unity/Unreal/Godot/undecided), platform and target frame rate (PC 60fps? Steam Deck?), art style preference. Once asked, start working; do not ask repeatedly for completeness. Mark unknown items explicitly as [TBD] in documents.
2. Run Scaffolding: python scripts/new_gdd.py init --name "Game Name" --out <output directory> --engine <engine from step 1>, generating the complete GDD document tree. --engine must use the answer from Step 1, not always "unity" — it determines actual document content like axes, collision naming, navigation, and data asset standards.
3. Write Documents in Phase Order (see "Stage Gates" below). Each time read the corresponding reference first, then fill in the template. Order: 01 Vision → 02 Art Bible + 11 Tech Budget → 04 Core Gameplay → 07/08/09/06 Specs → 03/05 Content → 12 Review.
4. For each scene/character/prop/animation/dialogue/system, use scripts/new_gdd.py sheet to generate an individual single-page document in the GDD's corresponding subdirectory. The core document only contains an index table; do not pile hundreds of assets into one file.
5. Pass Quality Gates: At the end of each phase, use the gate table from 12-steam-qa-checklist.md to check each item. Do not proceed to the next phase until the current one passes.

Workflow B: Single Document (User Only Needs One Type of Document)

Confirm the object and its purpose → read the corresponding reference → copy and fill the template → self-check using the "Definition of Done" at the end of the template → deliver. When the user says "write a scene for me," first ask for the scene name, its position in the flow, and the core event (ask all at once), then directly produce a complete scene-sheet; do not just give an empty template.

Scene vs. Level: by default, produce only what the user asked for. references/03 says "a scene is space, a level is time; write them separately." This refers to the division of labor when both are needed, not a requirement to always produce a level sheet with every scene.

Division is strict:

• Scene Page (SC_) = What this space provides: terrain, lines of sight, cover, height differences, escape routes, hiding spots, spatial constraints on enemies (§7), and trigger zones TZ_ (§4).
• Level Page (LV_) = What sequence the player experiences: beat table (with EV_ event IDs), pacing, consequences of encounters, checkpoints.

Therefore:

• User wants a scene → write only scene-sheet.md, no sequence; if a level page is truly not needed, add a brief line in §7 "Experience Sequence (Brief)."
• User wants a level flow, or a scene has multi-phase pacing → then produce level-sheet.md, with both using TZ_ ↔ EV_ to cross-reference.
• Do not automatically produce two documents just because 03 says "write them separately," as this would unnecessarily bloat a simple request 2-3 times.

Read a full example before filling in templates — each type of single-page sheet has a complete example. Read the appropriate one directly:

Sheet Type	Example	What to Focus On Most
Scene (Linear/Horror)	assets/examples/SC_01_SurgeryFloor2Corridor_Example.md	§7 Space Provision = line-of-sight blocking and "see first, then contact"; §10 Perception and pacing
Scene (Open/BOSS)	assets/examples/SC_07_BrokenBridgeObservatory_Example.md	§7 Space Provision = distance adjustable / line-of-sight break / risk gambles; §10 Combat solvability
Level	assets/examples/LV_01_CorridorFirstEncounter_Example.md	How beat tables reconcile with TZ_; how intensity curves and teaching moments work without pop-up tutorials
Character (Enemy)	assets/examples/EN_01_Stitcher_Example.md	§6 State machine+speed difference: why "can be outrun" matters; §7 How combat duration is calculated
Prop	assets/examples/PR_017_BrokenWheelchair_Example.md	§5 Technical spec values; §7 How to write "intentionally omitted" in DoD
Animation	assets/examples/AN_EN01_Slash_01_Example.md	§2 Three-part frame interval; §3 Event markers (preview sound as fairness baseline)
Dialogue/Cutscene	assets/examples/DL_07_NurseRecording_Example.md	How to define line ID/duration/subtitle compliance/interruption and resume playback
System	assets/examples/SYS_04_GrabBreak_Example.md	§4 Parameter table must include "design intent"; §5 No boundary omissions

All examples must reach this granularity (every item has specific numbers, IDs, and assignable content). Note: the checkbox items in examples are verification records after completion (including actual poly counts, review dates, overturned design decisions), not blanks to fill at the start. In v0.1 phase, leave those blanks; do not fabricate figures that look like actual measurements. §10 Design Risks and Hypotheses to Test is the only section that is allowed and should have no numbers.

Workflow C: Review Existing Documents / Ideas

Use the "AAA Ten-Dimensional Scoring Table" in 12-steam-qa-checklist.md to score each dimension (1-10, with evidence), list blocking issues for release, missing documentation, and prioritized modification suggestions. Scoring must quote the original document or missing items; avoid vague evaluations.

Stage Gates

Phase	Required Documents	Gate (Cannot Proceed Without Passing)
Concept	01 Vision, 04 Core Gameplay Skeleton	Core fun validated via playable paper/prototype; all 3 core pillars agreed by entire team
Vertical Slice	02, 06, 11 + at least 1 sample sheet per type (scene/character/prop/animation/dialogue)	10-15 minute flow meets final quality expectations; all core systems functional; budget meets performance target
Production	All core documents + all asset sheets	Each asset sheet directly assignable; capacity and milestones schedulable
Alpha	All content	Feature Complete: can be played from start to finish; no placeholder systems
Beta	Same as above + 12 Review Table	Content Complete; zero S/A-level bugs; playthrough complete flow ×3 configurations
RC/Release	All Steam checklist items in 12 checked	Store page, Deck verification, localization, age rating, save compatibility all passed

Scaffolding Script

# Initialize a complete GDD document tree (creates <GameName>_GDD/ in output directory)
python scripts/new_gdd.py init --name "Game Name" --out "D:/MyGame" --engine unity
#   --engine: unity | unreal | godot | agnostic (default)
#             ★ This is not decorative: choosing an engine actually writes the corresponding
#               exchange format/axes/collision naming/navigation/data assets/LOD standards
#   --genre: optional, game type description, written into the vision document
#   --dimension: 3d (default) | 2d (additionally creates sprites/ tilesets/ subdirectories)

# Generate a single-page document for one object (automatically placed in the correct subdirectory)
python scripts/new_gdd.py sheet --type scene --name "Abandoned Hospital" --out "D:/MyGame/GameName_GDD"
#   --type: scene | level | character | prop | animation | dialogue | system | sprite | tileset
#   --subtype: for character use player/enemy/npc (CH/EN/NPC); for prop use item/weapon (PR/WP)
#   Example: sheet --type character --subtype enemy --name "Stitcher" → characters/EN_01_Stitcher.md
#   Example: sheet --type sprite --name "HeroIdle" → sprites/SPR_01_HeroIdle.md

init also supports --dimension 2d: additionally creates sprites/, tilesets/ subdirectories (for 2D projects).

The script automatically replaces {{GAME_NAME}}, {{DATE}}, {{ENGINE}} placeholders. If the script is unavailable, manually copy templates from assets/templates/.

General Writing Conventions

• Document Header: Every document must start with: document ID, version number, status (Draft/In Review/Locked), last updated date, owner, and related document IDs. Asset sheets also need the engine resource name (e.g., SM_Prop_HospitalWheelchair_01).
• Quantify First: Prohibit descriptions like "feels good," "beautiful visuals," "very strong enemy" that cannot be verified. Write "8 frames (0.13s @60fps) from press to hit detection" or "Enemy HP 120, player maxed DPS 45, expected combat duration 35-45s."
• Mark Uncertainty: Write unknown values as [TBD: reason / owner / deadline]. Do not fabricate numbers and then pretend they are certain; industry standard values can be used directly and marked "industry default, adjust after first playtest."
• Visuals Required: Scenes, levels, and UI must include layout diagrams (ASCII floor plans, Mermaid flow/state diagrams, or references to concept art IDs); state machines, dialogue trees, and menu flows must be drawn using Mermaid; parameters and lists must be in tables.
• Each Document Needs a DoD: Include a Definition of Done checklist at the end (checkable - [ ] items). This is the sole basis for delivery acceptance.
• Language: Chinese for main text; technical terms, engine APIs, and resource names remain in English; dialogue scripts also reserve fields for English/other languages.
• Document Changes via Versioning: After a document is locked, any modifications must be recorded in a change log at the end, noting version, date, and what was changed.

Delivery Requirements

• Deliverables are Markdown files placed in the user's project directory (scaffolding directory + filled-in documents), not an outline in the chat.
• After each delivery, prompt the user about what document to write next and which [TBD] items they need to decide.
• Document quality standard: "A newly hired freelance artist/programmer should be able to independently produce a passable asset by reading only the corresponding single-page document."