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:
- Title: Gets " (import)" appended
- Status: Project status is forced to "draft" regardless of the file
- IDs: New ULIDs are generated — ref_id and id values are only used to resolve links
- Links: Resolved via ref_id first, then id fallback. Unresolvable links are silently skipped
- Unknown enum values: Fall back to defaults (genre → "arcade", section type → "custom", element type → "mechanic", status → "draft")
- Missing fields: Filled with defaults (empty string or empty array)
- Media files: Only
media_urls(external links) are imported. Actual file uploads must be done in the editor - 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.
{
"$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_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.