docs

Import Format

JSON specification for importing Game Design Documents into GDD.studio. Generate with an AI, migrate from another tool, or create programmatically.

GDD.studio Import Format Guide

This document describes the JSON format used to import a complete Game Design Document into GDD.studio. This format can be used to:

  • Generate a GDD with an AI (ChatGPT, Claude, Gemini, etc.) and import it
  • Migrate data from another tool
  • Script GDD creation programmatically
  • Exchange GDD data between teams

Quick Start

Minimal valid file:

{
  "gdd_studio_version": "1.0",
  "project": {
    "title": "My Game",
    "genre": "platformer"
  },
  "sections": [
    {
      "title": "Core Concept",
      "type": "concept",
      "content": "<p>A platformer about a cat exploring a haunted mansion.</p>",
      "elements": []
    }
  ]
}

File Structure

{
  "gdd_studio_version": "1.0",        // Required, must be "1.0"
  "project": { ... },                  // Required: project metadata
  "sections": [ ... ]                  // Required: at least one section
}

Project

Field Type Required Description
title string Yes Game name (max 255 chars)
genre string Yes See Genres
pitch string No Elevator pitch
platform string[] No See Platforms
scale string No Free text (e.g. "solo", "small team")
status string No See Statuses. Default: "draft"

Sections

Sections are the main organizational units. Each section contains optional rich-text content and a list of elements. The array order determines display order.

Field Type Required Description
title string Yes Section title
type string Yes See Section Types
content string or object No Rich text content (see below)
status string No Default: "draft"
elements array No List of elements

Section Content

Content can be provided in two ways:

Simple string (auto-wrapped in HTML):

"content": "This is a description of the game concept."

Rich HTML object:

"content": {
  "html": "<h2>Overview</h2><p>This is a <strong>rich text</strong> description.</p>",
  "text": "Overview This is a rich text description."
}

The text field is optional — if omitted, it's derived by stripping HTML tags. Supported HTML: <h1>-<h6>, <p>, <ul>, <ol>, <li>, <strong>, <em>, <a>, <blockquote>, <code>, <pre>.

Elements

Elements are the building blocks of your GDD: mechanics, characters, levels, etc.

Field Type Required Description
title string Yes Element title
type string Yes See Element Types
ref_id string No Unique reference ID for linking (e.g. "jump-mechanic")
fields object No Type-specific fields (see below)
media_urls array No External URLs (YouTube, Figma, etc.)
status string No Default: "draft"
links array No Connections to other elements

ref_id (Reference IDs)

The ref_id is a human-readable identifier you assign to elements so you can create links between them. Rules:

  • Only letters, numbers, hyphens, and underscores: [a-zA-Z0-9_-]+
  • Must be unique across the entire file
  • Examples: "jump-mechanic", "main-hero", "forest-level", "combat-system"

media_urls

"media_urls": [
  { "label": "YouTube Trailer", "url": "https://youtube.com/watch?v=..." },
  { "label": "Figma Mockup", "url": "https://figma.com/file/..." },
  { "label": "Reference Art", "url": "https://imgur.com/..." }
]

links (Element Connections)

Links create a directed graph between elements. Each link uses target_ref_id to reference another element:

"links": [
  { "target_ref_id": "gravity-system", "label": "uses" },
  { "target_ref_id": "stamina-system", "label": "requires" }
]
Field Type Required Description
target_ref_id string Yes* ref_id of the target element
target_id string Yes* Alternative: ULID from GDD.studio export
label string No Relationship type. Default: "linked"

*One of target_ref_id or target_id is required.

Common link labels: uses, requires, triggers, related_to, depends_on, inspired_by, countered_by, unlocks, linked

Element Types & Fields

Each element type has its own set of fields. All fields are optional — omitted fields default to empty string or empty array.

mechanic

A game mechanic (action, rule, or system the player interacts with).

Field Type Description Example
name string Mechanic name "Double Jump"
description string How it works "Press jump while airborne for a second jump"
input string Player input "Space bar while in air"
output string Result "Character performs a second jump with reduced height"
feel string Game feel / juice "Snappy, responsive, slight hang time at apex"
related_systems string[] Related systems ["Physics", "Stamina", "Coyote Time"]

character

A game character (player, NPC, enemy, boss).

Field Type Description Example
name string Character name "Aria"
role string Role in the game "Protagonist"
backstory string Lore and backstory "A former knight who lost her memory..."
abilities string[] Abilities ["Fireball", "Shield Bash", "Heal"]
visual_ref string Visual description "Tall, silver armor, blue cloak, scar on left cheek"
personality string Personality traits "Stoic but caring, dry humor, loyal to allies"

level

A game level, area, or map.

Field Type Description Example
name string Level name "Haunted Forest"
theme string Visual/narrative theme "Dark fantasy, twisted trees, glowing mushrooms"
objectives string[] Objectives ["Find the lost key", "Defeat the Shadow Wolf"]
enemies string[] Enemies ["Shadow Wolf", "Cursed Treant", "Will-o-Wisp"]
layout_notes string Layout description "Linear path with optional side caves"
difficulty string Difficulty "Medium (3/5)"

asset

A game asset (sprite, sound, model, texture, etc.).

Field Type Description Example
name string Asset name "Player Idle Spritesheet"
type string Asset type "sprite", "sound", "music", "fx", "model"
format string File format "PNG", "WAV", "OGG", "FBX"
source string Source/origin "Created in Aseprite"
license string License "CC0", "CC-BY 4.0", "Proprietary"

system

A game system (combat, economy, crafting, AI, etc.).

Field Type Description Example
name string System name "Combat System"
description string How it works "Real-time action combat with dodge and parry"
rules string Core rules "Damage = base_atk * weapon_mult - target_def"
parameters string[] Tunable params ["base_damage", "crit_chance", "dodge_window"]
balance_notes string Balance goals "Combat should feel fast but punishing"

narrative_beat

A story event or narrative moment.

Field Type Description Example
title string Beat title "The Betrayal"
description string What happens "The mentor reveals they were the villain all along"
trigger string Trigger condition "Player completes Chapter 3"
consequences string Impact "Player loses access to the mentor's shop"
branch_to string[] Story branches ["Revenge Path", "Forgiveness Path"]

ui_screen

A user interface screen or component.

Field Type Description Example
name string Screen name "Inventory"
purpose string Purpose "Equipment management and item inspection"
wireframe_url string Wireframe URL "https://figma.com/file/..."
interactions string[] Interactions ["Drag to reorder", "Right-click for details"]

sound_design

A sound effect, music track, or audio element.

Field Type Description Example
name string Sound name "Boss Theme - Phase 2"
context string When it plays "Plays when boss health drops below 50%"
mood string Mood/feeling "Intense, urgent, orchestral with choir"
reference_url string Reference URL "https://youtube.com/watch?v=..."
loop boolean Loops? true (music/ambiance) or false (one-shot)

Enums Reference

Genres

Value Label
horror Horror
roguelike Roguelike
puzzle Puzzle
platformer Platformer
rpg RPG
narrative Narrative
arcade Arcade
simulation Simulation / Tycoon

Platforms

Value Label
pc PC
mac Mac
linux Linux
web Web
mobile Mobile
ios iOS
android Android
switch Nintendo Switch
playstation PlayStation
xbox Xbox

Statuses

Value Label Description
draft Draft Work in progress, not finalized
in_progress In Progress Actively being worked on
done Done Completed and finalized
cut Cut Removed from scope but kept for reference

Section Types

Value Label Description
concept Concept High-level game concept and vision
mechanics Mechanics Core gameplay mechanics
game_loop Game Loop Core loop and progression
characters Characters Characters and NPCs
levels Levels Levels, maps, and areas
assets Assets Art, audio, and visual assets
sound Sound Sound design and music
ui_ux UI/UX User interface and experience
technical Technical Technical architecture and tools
custom Custom Custom section (any content)

Element Types

Value Label Fields
mechanic Mechanic name, description, input, output, feel, related_systems
character Character name, role, backstory, abilities, visual_ref, personality
level Level name, theme, objectives, enemies, layout_notes, difficulty
asset Asset name, type, format, source, license
system System name, description, rules, parameters, balance_notes
narrative_beat Narrative Beat title, description, trigger, consequences, branch_to
ui_screen UI Screen name, purpose, wireframe_url, interactions
sound_design Sound Design name, context, mood, reference_url, loop

Using with AI

To generate a GDD with an AI, provide this prompt along with the schema:

Generate a complete Game Design Document in GDD.studio JSON format for [your game idea]. Follow the attached JSON Schema strictly. Use ref_id on every element and create links between related elements. Fill all relevant fields for each element type.

The AI should receive either this guide or the JSON Schema file (gdd-import-schema.json) as context.

Import Behavior

When importing into GDD.studio:

  1. Title: Gets " (import)" appended
  2. Status: Project status is forced to "draft" regardless of the file
  3. IDs: New ULIDs are generated — ref_id and id values are only used to resolve links
  4. Links: Resolved via ref_id first, then id fallback. Unresolvable links are silently skipped
  5. Unknown enum values: Fall back to defaults (genre → "arcade", section type → "custom", element type → "mechanic", status → "draft")
  6. Missing fields: Filled with defaults (empty string or empty array)
  7. Media files: Only media_urls (external links) are imported. Actual file uploads must be done in the editor
  8. Content shorthand: String content is auto-wrapped in {html: value, text: stripped(value)}

Validation

Validate your file before import:

# Using ajv-cli (Node.js)
npx ajv validate -s gdd-import-schema.json -d my-game.json

# Using Python jsonschema
python -m jsonschema -i my-game.json gdd-import-schema.json

# Using check-jsonschema
check-jsonschema --schemafile gdd-import-schema.json my-game.json

Full Example

See gdd-import-example.json for a complete example with all element types, links, and media URLs.

gdd-import-schema.json JSON Schema draft-2020-12
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://gdd.studio/schemas/gdd-import-v1.json",
    "title": "GDD.studio Import Format",
    "description": "Schema for importing a complete Game Design Document into GDD.studio. This file can be generated manually, by an AI, or exported from GDD.studio.",
    "type": "object",
    "required": [
        "gdd_studio_version",
        "project",
        "sections"
    ],
    "additionalProperties": false,
    "properties": {
        "$schema": {
            "type": "string",
            "description": "Optional JSON Schema reference for editor validation."
        },
        "gdd_studio_version": {
            "type": "string",
            "const": "1.0",
            "description": "Format version. Must be \"1.0\"."
        },
        "exported_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp. Optional, set automatically on export."
        },
        "project": {
            "$ref": "#/$defs/project"
        },
        "sections": {
            "type": "array",
            "description": "Ordered list of sections. The array order determines display order (index 0 = first section).",
            "items": {
                "$ref": "#/$defs/section"
            },
            "minItems": 1
        }
    },
    "$defs": {
        "project": {
            "type": "object",
            "description": "The game project metadata.",
            "required": [
                "title",
                "genre"
            ],
            "additionalProperties": false,
            "properties": {
                "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "description": "Project name. Will have \" (import)\" appended on import."
                },
                "genre": {
                    "type": "string",
                    "enum": [
                        "horror",
                        "roguelike",
                        "puzzle",
                        "platformer",
                        "rpg",
                        "narrative",
                        "arcade",
                        "simulation"
                    ],
                    "description": "Primary game genre."
                },
                "pitch": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Elevator pitch / short description of the game."
                },
                "platform": {
                    "type": [
                        "array",
                        "null"
                    ],
                    "description": "Target platforms. Null or omit if not decided yet.",
                    "items": {
                        "type": "string",
                        "enum": [
                            "pc",
                            "mac",
                            "linux",
                            "web",
                            "mobile",
                            "ios",
                            "android",
                            "switch",
                            "playstation",
                            "xbox"
                        ]
                    },
                    "uniqueItems": true
                },
                "scale": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Project scale (e.g. \"solo\", \"small team\", \"AAA\"). Free-form text."
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "draft",
                        "in_progress",
                        "done",
                        "cut"
                    ],
                    "default": "draft",
                    "description": "Project status. Defaults to \"draft\" on import."
                }
            }
        },
        "section": {
            "type": "object",
            "description": "A section groups related elements and has optional rich-text content.",
            "required": [
                "title",
                "type"
            ],
            "additionalProperties": false,
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Original ULID from export. Ignored on import, kept for compatibility."
                },
                "ref_id": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]+$",
                    "description": "Optional human-readable reference ID for this section (not used for linking, but useful for clarity)."
                },
                "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "description": "Section title displayed in the editor sidebar."
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "concept",
                        "mechanics",
                        "game_loop",
                        "characters",
                        "levels",
                        "assets",
                        "sound",
                        "ui_ux",
                        "technical",
                        "custom"
                    ],
                    "description": "Section type. Determines the icon and default guidance. Use \"custom\" for non-standard sections."
                },
                "order": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Display order. If omitted, array index is used."
                },
                "content": {
                    "oneOf": [
                        {
                            "type": "object",
                            "description": "Rich content with HTML and plain text versions.",
                            "properties": {
                                "html": {
                                    "type": "string",
                                    "description": "HTML content (TipTap-compatible). Supports standard HTML tags: h1-h6, p, ul, ol, li, strong, em, a, blockquote, code, pre."
                                },
                                "text": {
                                    "type": "string",
                                    "description": "Plain text version (used for search indexing). If omitted, will be derived from html by stripping tags."
                                }
                            },
                            "required": [
                                "html"
                            ]
                        },
                        {
                            "type": "string",
                            "description": "Shorthand: plain text or HTML string. Will be wrapped in {html: value, text: stripped(value)}."
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "description": "Section rich-text content. Can be an object {html, text}, a string (auto-wrapped), or null."
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "draft",
                        "in_progress",
                        "done",
                        "cut"
                    ],
                    "default": "draft",
                    "description": "Section status."
                },
                "elements": {
                    "type": "array",
                    "description": "Ordered list of elements in this section.",
                    "items": {
                        "$ref": "#/$defs/element"
                    }
                }
            }
        },
        "element": {
            "type": "object",
            "description": "An element is a game design building block (mechanic, character, level, etc.).",
            "required": [
                "title",
                "type"
            ],
            "additionalProperties": false,
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Original ULID from export. Used to resolve links if ref_id is not set."
                },
                "ref_id": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]+$",
                    "description": "Human-readable reference ID. Used in links.target_ref_id to create connections between elements. Must be unique across the entire file. Example: \"jump-mechanic\", \"main-hero\", \"forest-level\"."
                },
                "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "description": "Element title displayed in the editor."
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "mechanic",
                        "character",
                        "level",
                        "asset",
                        "system",
                        "narrative_beat",
                        "ui_screen",
                        "sound_design"
                    ],
                    "description": "Element type. Determines which fields are available."
                },
                "fields": {
                    "description": "Type-specific data fields. See the fields schema for each element type below.",
                    "oneOf": [
                        {
                            "$ref": "#/$defs/fields_mechanic"
                        },
                        {
                            "$ref": "#/$defs/fields_character"
                        },
                        {
                            "$ref": "#/$defs/fields_level"
                        },
                        {
                            "$ref": "#/$defs/fields_asset"
                        },
                        {
                            "$ref": "#/$defs/fields_system"
                        },
                        {
                            "$ref": "#/$defs/fields_narrative_beat"
                        },
                        {
                            "$ref": "#/$defs/fields_ui_screen"
                        },
                        {
                            "$ref": "#/$defs/fields_sound_design"
                        }
                    ]
                },
                "media_urls": {
                    "type": [
                        "array",
                        "null"
                    ],
                    "description": "External media/embed URLs (YouTube, Figma, reference images, etc.).",
                    "items": {
                        "$ref": "#/$defs/media_url"
                    }
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "draft",
                        "in_progress",
                        "done",
                        "cut"
                    ],
                    "default": "draft",
                    "description": "Element status."
                },
                "order": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Display order within the section. If omitted, array index is used."
                },
                "links": {
                    "type": "array",
                    "description": "Connections to other elements (directed graph). Defines relationships like \"uses\", \"requires\", \"triggers\".",
                    "items": {
                        "$ref": "#/$defs/element_link"
                    }
                }
            }
        },
        "element_link": {
            "type": "object",
            "description": "A directed link from this element to another element.",
            "anyOf": [
                {
                    "required": [
                        "target_ref_id"
                    ]
                },
                {
                    "required": [
                        "target_id"
                    ]
                }
            ],
            "additionalProperties": false,
            "properties": {
                "target_ref_id": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]+$",
                    "description": "Reference ID of the target element (matches a ref_id defined on another element). Preferred method for manually-created files."
                },
                "target_id": {
                    "type": "string",
                    "description": "ULID of the target element (from GDD.studio export). Used for backward compatibility."
                },
                "target_title": {
                    "type": "string",
                    "description": "Title of the target element. Informational only, not used for resolution."
                },
                "label": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Relationship label (e.g. \"uses\", \"requires\", \"triggers\", \"related_to\"). Defaults to \"linked\" if omitted.",
                    "examples": [
                        "uses",
                        "requires",
                        "triggers",
                        "related_to",
                        "depends_on",
                        "inspired_by",
                        "countered_by",
                        "unlocks",
                        "linked"
                    ]
                }
            }
        },
        "media_url": {
            "type": "object",
            "required": [
                "label",
                "url"
            ],
            "additionalProperties": false,
            "properties": {
                "label": {
                    "type": "string",
                    "description": "Display label (e.g. \"YouTube Trailer\", \"Figma Mockup\", \"Reference Art\")."
                },
                "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to external resource."
                }
            }
        },
        "fields_mechanic": {
            "type": "object",
            "description": "Fields for element type \"mechanic\". Describes a game mechanic.",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Mechanic name (e.g. \"Double Jump\", \"Crafting\")."
                },
                "description": {
                    "type": "string",
                    "description": "Detailed description of how the mechanic works."
                },
                "input": {
                    "type": "string",
                    "description": "Player input that triggers this mechanic (e.g. \"Press Space while airborne\")."
                },
                "output": {
                    "type": "string",
                    "description": "What happens when the mechanic is activated (e.g. \"Character performs a second jump\")."
                },
                "feel": {
                    "type": "string",
                    "description": "The intended game feel / juice (e.g. \"Snappy, responsive, with slight hang time at apex\")."
                },
                "related_systems": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "Tags of related game systems (e.g. [\"Physics\", \"Stamina\", \"Coyote Time\"])."
                }
            }
        },
        "fields_character": {
            "type": "object",
            "description": "Fields for element type \"character\". Describes a game character.",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Character name."
                },
                "role": {
                    "type": "string",
                    "description": "Role in the game (e.g. \"Protagonist\", \"Antagonist\", \"NPC Merchant\", \"Boss\")."
                },
                "backstory": {
                    "type": "string",
                    "description": "Character backstory and lore."
                },
                "abilities": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "List of abilities (e.g. [\"Fireball\", \"Shield Bash\", \"Heal\"])."
                },
                "visual_ref": {
                    "type": "string",
                    "description": "Visual description or reference (art style, inspirations, color palette)."
                },
                "personality": {
                    "type": "string",
                    "description": "Personality traits and behavior."
                }
            }
        },
        "fields_level": {
            "type": "object",
            "description": "Fields for element type \"level\". Describes a game level or area.",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Level name (e.g. \"Dark Forest\", \"Tutorial Island\")."
                },
                "theme": {
                    "type": "string",
                    "description": "Visual and narrative theme."
                },
                "objectives": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "Level objectives (e.g. [\"Defeat the boss\", \"Find 3 keys\", \"Survive 5 minutes\"])."
                },
                "enemies": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "Enemy types present in this level."
                },
                "layout_notes": {
                    "type": "string",
                    "description": "Level layout description, flow, and spatial notes."
                },
                "difficulty": {
                    "type": "string",
                    "description": "Difficulty rating or description (e.g. \"Easy\", \"3/10\", \"Beginner-friendly\")."
                }
            }
        },
        "fields_asset": {
            "type": "object",
            "description": "Fields for element type \"asset\". Describes a game asset (sprite, sound, model, etc.).",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Asset name."
                },
                "type": {
                    "type": "string",
                    "description": "Asset type (e.g. \"sprite\", \"sound\", \"music\", \"fx\", \"model\", \"texture\", \"animation\")."
                },
                "format": {
                    "type": "string",
                    "description": "File format (e.g. \"PNG\", \"WAV\", \"OGG\", \"FBX\")."
                },
                "source": {
                    "type": "string",
                    "description": "Source or origin (e.g. \"Created in Aseprite\", \"Freesound.org\", \"Commissioned from Artist X\")."
                },
                "license": {
                    "type": "string",
                    "description": "License type (e.g. \"CC0\", \"CC-BY 4.0\", \"Proprietary\", \"MIT\")."
                }
            }
        },
        "fields_system": {
            "type": "object",
            "description": "Fields for element type \"system\". Describes a game system (combat, economy, AI, etc.).",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "System name (e.g. \"Combat System\", \"Economy\", \"Dialogue System\")."
                },
                "description": {
                    "type": "string",
                    "description": "How the system works overall."
                },
                "rules": {
                    "type": "string",
                    "description": "Core rules and logic."
                },
                "parameters": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "Tunable parameters (e.g. [\"base_damage\", \"crit_multiplier\", \"dodge_chance\"])."
                },
                "balance_notes": {
                    "type": "string",
                    "description": "Balance considerations and design goals."
                }
            }
        },
        "fields_narrative_beat": {
            "type": "object",
            "description": "Fields for element type \"narrative_beat\". Describes a story event or narrative moment.",
            "additionalProperties": false,
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Beat title (e.g. \"Inciting Incident\", \"Boss Reveal\", \"Ending A\")."
                },
                "description": {
                    "type": "string",
                    "description": "What happens in this narrative beat."
                },
                "trigger": {
                    "type": "string",
                    "description": "What triggers this beat (e.g. \"Player enters throne room\", \"After defeating 3 bosses\")."
                },
                "consequences": {
                    "type": "string",
                    "description": "Consequences and impact on the game world."
                },
                "branch_to": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "Possible story branches from this beat (e.g. [\"Ending A\", \"Ending B\", \"Side Quest: Revenge\"])."
                }
            }
        },
        "fields_ui_screen": {
            "type": "object",
            "description": "Fields for element type \"ui_screen\". Describes a UI screen or interface.",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Screen name (e.g. \"Main Menu\", \"Inventory\", \"HUD\")."
                },
                "purpose": {
                    "type": "string",
                    "description": "What this screen is for and when the player sees it."
                },
                "wireframe_url": {
                    "type": "string",
                    "description": "URL to wireframe/mockup (Figma, image, etc.)."
                },
                "interactions": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "User interactions available (e.g. [\"Click to equip\", \"Drag to reorder\", \"Right-click for details\"])."
                }
            }
        },
        "fields_sound_design": {
            "type": "object",
            "description": "Fields for element type \"sound_design\". Describes a sound effect or music piece.",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Sound name (e.g. \"Footstep - Grass\", \"Boss Theme\", \"UI Click\")."
                },
                "context": {
                    "type": "string",
                    "description": "When/where this sound plays."
                },
                "mood": {
                    "type": "string",
                    "description": "Intended mood or feeling (e.g. \"Tense\", \"Triumphant\", \"Eerie\")."
                },
                "reference_url": {
                    "type": "string",
                    "description": "URL to a reference track or sound."
                },
                "loop": {
                    "type": "boolean",
                    "default": false,
                    "description": "Whether this sound loops. true for music/ambiance, false for one-shots."
                }
            }
        }
    }
}
gdd-import-example.json Hollow Depths — Roguelike
{
    "gdd_studio_version": "1.0",
    "project": {
        "title": "Hollow Depths",
        "genre": "roguelike",
        "pitch": "A roguelike dungeon crawler where a ghost must reclaim its stolen memories from the creatures that devoured them. Each run reshapes the dungeon based on recovered memories.",
        "platform": [
            "pc",
            "switch",
            "web"
        ],
        "scale": "solo developer",
        "status": "in_progress"
    },
    "sections": [
        {
            "title": "Game Concept",
            "type": "concept",
            "content": {
                "html": "<h2>Vision</h2><p>Hollow Depths is a <strong>top-down roguelike</strong> with a unique twist: the dungeon layout, enemies, and rewards change based on which memories the player has recovered. Each memory fragment alters the world \u2014 recovering a memory of fire unlocks flame-based areas and abilities.</p><h2>Pillars</h2><ul><li>Every run tells a different story</li><li>Memories as progression AND currency</li><li>Fast, fluid combat with meaningful choices</li></ul>",
                "text": "Vision Hollow Depths is a top-down roguelike with a unique twist: the dungeon layout, enemies, and rewards change based on which memories the player has recovered. Each memory fragment alters the world \u2014 recovering a memory of fire unlocks flame-based areas and abilities. Pillars Every run tells a different story Memories as progression AND currency Fast, fluid combat with meaningful choices"
            },
            "status": "done",
            "elements": []
        },
        {
            "title": "Core Mechanics",
            "type": "mechanics",
            "content": "<p>The game revolves around three core mechanics: memory absorption, phase shifting, and combo chaining.</p>",
            "elements": [
                {
                    "ref_id": "memory-absorb",
                    "title": "Memory Absorption",
                    "type": "mechanic",
                    "fields": {
                        "name": "Memory Absorption",
                        "description": "When an enemy is defeated, it releases a memory fragment. The player can absorb it to gain new abilities, unlock areas, or recover story pieces. Some memories conflict \u2014 absorbing one may lock out another for the current run.",
                        "input": "Walk over a memory fragment after defeating an enemy",
                        "output": "Gain ability/unlock/story piece. Conflicting memories become unavailable.",
                        "feel": "Satisfying whoosh + color burst. Brief slow-motion on important memories.",
                        "related_systems": [
                            "Progression",
                            "Combat",
                            "Narrative"
                        ]
                    },
                    "status": "done",
                    "links": [
                        {
                            "target_ref_id": "progression-system",
                            "label": "uses"
                        },
                        {
                            "target_ref_id": "phase-shift",
                            "label": "unlocks"
                        }
                    ]
                },
                {
                    "ref_id": "phase-shift",
                    "title": "Phase Shift",
                    "type": "mechanic",
                    "fields": {
                        "name": "Phase Shift",
                        "description": "The player can briefly shift into the ghost realm, becoming intangible. Passing through enemies in this state deals damage and slows them. Costs memory energy.",
                        "input": "Right mouse button / R trigger",
                        "output": "2-second intangibility, damage to phased-through enemies, 3-second cooldown",
                        "feel": "Ethereal, floaty. Screen desaturates, trails of light follow the player.",
                        "related_systems": [
                            "Combat",
                            "Stamina"
                        ]
                    },
                    "status": "in_progress",
                    "links": [
                        {
                            "target_ref_id": "combat-system",
                            "label": "uses"
                        },
                        {
                            "target_ref_id": "combo-chain",
                            "label": "triggers"
                        }
                    ]
                },
                {
                    "ref_id": "combo-chain",
                    "title": "Combo Chaining",
                    "type": "mechanic",
                    "fields": {
                        "name": "Combo Chaining",
                        "description": "Attacks build a combo meter. Higher combos increase memory fragment drop rate and quality. Taking damage resets the combo. Phase Shift through an enemy counts as a combo hit.",
                        "input": "Continuous attacks without taking damage",
                        "output": "Increasing combo multiplier (1x to 5x), visual escalation, better drops",
                        "feel": "Addictive, arcade-like. Screen shake increases, hit sounds pitch up.",
                        "related_systems": [
                            "Combat",
                            "Loot",
                            "Phase Shift"
                        ]
                    },
                    "links": [
                        {
                            "target_ref_id": "combat-system",
                            "label": "uses"
                        },
                        {
                            "target_ref_id": "memory-absorb",
                            "label": "related_to"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Game Loop",
            "type": "game_loop",
            "content": "<h2>Core Loop</h2><ol><li>Enter the dungeon</li><li>Fight enemies, absorb memories</li><li>Choose which memories to keep (limited slots)</li><li>Reach the floor boss</li><li>Die or ascend \u2014 kept memories carry over as permanent unlocks</li></ol>",
            "elements": [
                {
                    "ref_id": "progression-system",
                    "title": "Memory Progression",
                    "type": "system",
                    "fields": {
                        "name": "Memory Progression System",
                        "description": "Memories serve as both per-run power-ups and permanent meta-progression. Per-run memories are lost on death, but reaching certain thresholds converts them into permanent unlocks.",
                        "rules": "Per run: max 6 memory slots. Permanent: memories absorbed 3+ times across runs become permanent unlocks. Conflicting memories can never both be permanent.",
                        "parameters": [
                            "memory_slots_per_run",
                            "permanence_threshold",
                            "conflict_pairs",
                            "memory_quality_weights"
                        ],
                        "balance_notes": "Early runs should feel like discovery. By run 10+, players should have meaningful permanent builds. Conflict system prevents one dominant build."
                    },
                    "links": [
                        {
                            "target_ref_id": "memory-absorb",
                            "label": "depends_on"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Characters",
            "type": "characters",
            "content": "<p>The game features a small cast: the player ghost, a mysterious guide, and the memory-eating bosses.</p>",
            "elements": [
                {
                    "ref_id": "wisp",
                    "title": "The Wisp (Player)",
                    "type": "character",
                    "fields": {
                        "name": "The Wisp",
                        "role": "Protagonist",
                        "backstory": "Once a powerful mage, now a ghost with no memories. Trapped in the Hollow Depths, they must reclaim their identity fragment by fragment. Each recovered memory reveals a piece of who they were \u2014 and not all of it is heroic.",
                        "abilities": [
                            "Phase Shift",
                            "Memory Absorption",
                            "Spectral Dash",
                            "Memory Burst"
                        ],
                        "visual_ref": "A small, glowing orb of pale blue light with wispy tendrils. Grows more defined and humanoid as memories are recovered. Final form reveals the mage's silhouette.",
                        "personality": "Silent protagonist, but recovered memories show someone who was ambitious, sometimes ruthlessly so. The player decides how to interpret this."
                    },
                    "media_urls": [
                        {
                            "label": "Character Concept Art",
                            "url": "https://example.com/wisp-concept.png"
                        }
                    ],
                    "links": [
                        {
                            "target_ref_id": "phase-shift",
                            "label": "uses"
                        },
                        {
                            "target_ref_id": "memory-absorb",
                            "label": "uses"
                        }
                    ]
                },
                {
                    "ref_id": "keeper",
                    "title": "The Keeper",
                    "type": "character",
                    "fields": {
                        "name": "The Keeper",
                        "role": "NPC Guide / Ambiguous Ally",
                        "backstory": "A hooded figure found at the entrance of each floor. Claims to be a fellow ghost who has given up on recovering memories. Offers cryptic advice and trades. Their true nature is revealed in the final act.",
                        "abilities": [
                            "Memory Trading",
                            "Floor Hints",
                            "Lore Dumps"
                        ],
                        "visual_ref": "Tall hooded figure, dark purple robes, no visible face \u2014 just two dim yellow eyes. Floats slightly above the ground.",
                        "personality": "Calm, cryptic, slightly melancholic. Speaks in riddles but genuinely seems to care. Reveals more personality as the player progresses."
                    }
                },
                {
                    "ref_id": "devourer-boss",
                    "title": "The Devourer (Floor 5 Boss)",
                    "type": "character",
                    "fields": {
                        "name": "The Devourer",
                        "role": "Boss",
                        "backstory": "The first major boss. A massive creature that feeds on memories, growing stronger with each one consumed. It holds the player's memory of fire.",
                        "abilities": [
                            "Memory Drain",
                            "Shadow Slam",
                            "Devour (instant kill if combo is 0)"
                        ],
                        "visual_ref": "A swirling mass of dark energy with multiple glowing mouths. Each mouth holds a stolen memory that glows faintly inside.",
                        "personality": "Primal hunger. No dialogue, only roars and the whispers of stolen memories."
                    },
                    "links": [
                        {
                            "target_ref_id": "floor-5",
                            "label": "related_to"
                        },
                        {
                            "target_ref_id": "combat-system",
                            "label": "uses"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Levels",
            "type": "levels",
            "elements": [
                {
                    "ref_id": "floor-1",
                    "title": "The Faded Halls (Floor 1)",
                    "type": "level",
                    "fields": {
                        "name": "The Faded Halls",
                        "theme": "Crumbling stone corridors, faded tapestries, dust particles in dim light. A forgotten palace.",
                        "objectives": [
                            "Learn basic combat",
                            "Absorb first memory",
                            "Reach the exit"
                        ],
                        "enemies": [
                            "Shade",
                            "Lost Whisper"
                        ],
                        "layout_notes": "Linear with one optional side room. Tutorial area \u2014 teaches movement, combat, and memory absorption through gameplay (no text tutorials).",
                        "difficulty": "1/5 - Tutorial"
                    },
                    "links": [
                        {
                            "target_ref_id": "combat-system",
                            "label": "uses"
                        }
                    ]
                },
                {
                    "ref_id": "floor-5",
                    "title": "The Maw (Floor 5)",
                    "type": "level",
                    "fields": {
                        "name": "The Maw",
                        "theme": "Living darkness. Walls pulse like flesh, the floor shifts. Everything feels hungry.",
                        "objectives": [
                            "Navigate shifting layout",
                            "Survive ambushes",
                            "Defeat The Devourer"
                        ],
                        "enemies": [
                            "Shadow Wolf",
                            "Memory Leech",
                            "The Devourer (boss)"
                        ],
                        "layout_notes": "Procedurally generated with guaranteed boss arena at the end. Layout changes based on which memories the player holds \u2014 fire memories open magma shortcuts, ice memories reveal frozen passages.",
                        "difficulty": "3/5 - Challenging"
                    },
                    "links": [
                        {
                            "target_ref_id": "devourer-boss",
                            "label": "related_to"
                        },
                        {
                            "target_ref_id": "progression-system",
                            "label": "uses"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Game Systems",
            "type": "mechanics",
            "elements": [
                {
                    "ref_id": "combat-system",
                    "title": "Combat System",
                    "type": "system",
                    "fields": {
                        "name": "Combat System",
                        "description": "Real-time top-down combat. Light attack, heavy attack, phase shift (dodge), and memory abilities. Emphasis on positioning and combo maintenance.",
                        "rules": "Light attack: 1 damage, 0.3s. Heavy attack: 3 damage, 0.8s (can be combo finisher). Phase Shift: invuln + damage on pass-through. Memory abilities: cost memory energy, scale with combo.",
                        "parameters": [
                            "light_damage",
                            "heavy_damage",
                            "phase_damage",
                            "combo_decay_rate",
                            "memory_energy_regen"
                        ],
                        "balance_notes": "Combat should feel snappy like Hades. Heavy attacks should be risk/reward \u2014 high damage but long animation. Phase Shift should feel essential, not optional."
                    },
                    "links": [
                        {
                            "target_ref_id": "phase-shift",
                            "label": "uses"
                        },
                        {
                            "target_ref_id": "combo-chain",
                            "label": "uses"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Narrative",
            "type": "characters",
            "content": "<p>The story unfolds non-linearly through recovered memories. Key beats are fixed, but the order of discovery varies per run.</p>",
            "elements": [
                {
                    "ref_id": "beat-awakening",
                    "title": "Awakening",
                    "type": "narrative_beat",
                    "fields": {
                        "title": "Awakening",
                        "description": "The player wakes as a formless wisp in the first room of The Faded Halls. No tutorial text \u2014 the environment guides them. First enemy encounter teaches combat. First memory absorption reveals a flash: a hand reaching for a book.",
                        "trigger": "Game start (every run, but context changes as permanent memories accumulate)",
                        "consequences": "Player enters the dungeon. Sets the tone of mystery and loss.",
                        "branch_to": [
                            "First Memory Choice"
                        ]
                    },
                    "links": [
                        {
                            "target_ref_id": "floor-1",
                            "label": "triggers"
                        },
                        {
                            "target_ref_id": "wisp",
                            "label": "related_to"
                        }
                    ]
                },
                {
                    "ref_id": "beat-betrayal",
                    "title": "The Betrayal Memory",
                    "type": "narrative_beat",
                    "fields": {
                        "title": "The Betrayal Memory",
                        "description": "A critical memory reveals that the player (as the mage) betrayed someone close to gain power. This memory conflicts with the Sacrifice memory \u2014 the player can only make one permanent per save file.",
                        "trigger": "Defeat The Devourer on Floor 5",
                        "consequences": "Unlocks the Guilt path. The Keeper reacts differently. Certain enemies become sympathetic. Changes the final boss encounter.",
                        "branch_to": [
                            "Guilt Path",
                            "Denial Path"
                        ]
                    },
                    "links": [
                        {
                            "target_ref_id": "devourer-boss",
                            "label": "triggers"
                        },
                        {
                            "target_ref_id": "keeper",
                            "label": "related_to"
                        }
                    ]
                }
            ]
        },
        {
            "title": "UI/UX",
            "type": "ui_ux",
            "elements": [
                {
                    "ref_id": "hud",
                    "title": "In-Game HUD",
                    "type": "ui_screen",
                    "fields": {
                        "name": "In-Game HUD",
                        "purpose": "Minimal HUD showing health, memory energy, combo meter, and equipped memories. Fades when not in combat.",
                        "wireframe_url": "",
                        "interactions": [
                            "Combo meter pulses on hit",
                            "Memory slots glow when ability is ready",
                            "Health drains with screen vignette"
                        ]
                    }
                },
                {
                    "ref_id": "memory-select",
                    "title": "Memory Selection Screen",
                    "type": "ui_screen",
                    "fields": {
                        "name": "Memory Selection Screen",
                        "purpose": "Shown between floors. Player chooses which memories to keep (limited slots). Shows conflicts and synergies.",
                        "wireframe_url": "",
                        "interactions": [
                            "Drag memories to slots",
                            "Hover to see conflicts (red lines)",
                            "Hover to see synergies (blue lines)",
                            "Confirm button with undo"
                        ]
                    },
                    "links": [
                        {
                            "target_ref_id": "progression-system",
                            "label": "uses"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Sound Design",
            "type": "sound",
            "elements": [
                {
                    "ref_id": "sfx-memory-absorb",
                    "title": "Memory Absorption SFX",
                    "type": "sound_design",
                    "fields": {
                        "name": "Memory Absorption",
                        "context": "Plays when the player absorbs a memory fragment from a defeated enemy",
                        "mood": "Ethereal, satisfying, slightly melancholic \u2014 like remembering something beautiful and sad",
                        "reference_url": "",
                        "loop": false
                    },
                    "links": [
                        {
                            "target_ref_id": "memory-absorb",
                            "label": "related_to"
                        }
                    ]
                },
                {
                    "ref_id": "music-boss",
                    "title": "Boss Theme",
                    "type": "sound_design",
                    "fields": {
                        "name": "Boss Theme - The Devourer",
                        "context": "Plays during the Floor 5 boss fight. Intensifies in phase 2 (below 50% HP).",
                        "mood": "Intense, oppressive, with distorted whispers of stolen memories woven into the melody",
                        "reference_url": "",
                        "loop": true
                    },
                    "links": [
                        {
                            "target_ref_id": "devourer-boss",
                            "label": "related_to"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Art & Assets",
            "type": "assets",
            "elements": [
                {
                    "ref_id": "asset-player-sprite",
                    "title": "Player Sprite Sheet",
                    "type": "asset",
                    "fields": {
                        "name": "Wisp - Full Animation Set",
                        "type": "sprite",
                        "format": "PNG (spritesheet) + Aseprite source",
                        "source": "Custom - created in Aseprite",
                        "license": "Proprietary"
                    },
                    "links": [
                        {
                            "target_ref_id": "wisp",
                            "label": "related_to"
                        }
                    ]
                }
            ]
        },
        {
            "title": "Technical",
            "type": "technical",
            "content": {
                "html": "<h2>Engine</h2><p>Godot 4.3</p><h2>Target Performance</h2><ul><li>60 FPS on mid-range hardware</li><li>Web build via HTML5 export</li><li>Save system: JSON-based, cloud sync via Steam</li></ul>",
                "text": "Engine Godot 4.3 Target Performance 60 FPS on mid-range hardware Web build via HTML5 export Save system: JSON-based, cloud sync via Steam"
            },
            "elements": []
        }
    ]
}

Generate with AI

No JSON needed: ask your AI for a plain-text design brief with this prompt, then paste the answer on the import page. The JSON format below remains available for scripts.

Help me write a game design brief for [YOUR GAME IDEA]. Cover the concept and pitch, the core gameplay loop, the main mechanics, the characters, the levels or world, the art and sound direction, and the key UI screens. Write it as plain text with short headings.