phaser-gdd

Phaser 4 Game Design Document Generator

Generate a comprehensive Game Design Document (GDD) for a Phaser 4 game. The GDD captures every design decision — mechanics, art, audio, progression, technical constraints — in a single Markdown file so the entire team (or solo dev) has a shared reference before any code is written.

GDD Structure (13 Sections)

Every generated GDD must include all 13 sections below. If the user has not specified details for a section, provide sensible defaults based on the genre and scope, and mark assumptions with  so they are easy to find and revise.

Section 1 — Game Overview

Establish the identity of the game at a glance.

Include:

Title — Working title (can be placeholder).
Tagline — One punchy sentence that sells the hook.
Genre — Primary genre and any sub-genres (e.g., "roguelike platformer").
Target Audience — Age range, player profile, casual vs. hardcore.
Elevator Pitch — Exactly 2 sentences: what the player does and why it is fun.
Unique Selling Points (USPs) — 3-5 bullet points that differentiate the game.
Comparable Titles — 2-3 existing games the user or audience would recognize, with a brief note on what is borrowed and what is different.

Section 2 — Core Game Loop

Define the repeatable cycle that keeps the player engaged.

Include:

30-Second Loop — The smallest atomic action cycle (e.g., jump-land-collect).
5-Minute Loop — A medium arc such as completing a level or a wave.
Session Loop — What a full play session looks like (15-30 min for casual, 60+ for hardcore).

Present each loop as an ASCII flow diagram:

[Action] --> [Feedback] --> [Reward] --> [Decision] --+
   ^                                                  |
   +--------------------------------------------------+

Win Condition — What the player must achieve to "beat" the game or level.
Lose Condition — What causes failure and what happens next (restart level, lose life, game over).

Section 3 — Mechanics Deep Dive

Detail every interactive system the player touches.

Include:

Primary Mechanics — The 1-3 core verbs (e.g., jump, shoot, match). For each: input, physics behavior, edge cases.
Secondary Mechanics — Supporting systems (e.g., inventory, crafting, dialogue). Describe how they feed back into the core loop.
Control Scheme — Map inputs per platform:

Action	Keyboard	Touch	Gamepad
Move	WASD / Arrows	Virtual joystick	Left stick
Jump	Space	Tap right side	A button

Section 4 — Progression System

Describe how difficulty, content, and rewards evolve over time.

Include:

Difficulty Curve — Describe the intended ramp (linear, exponential, sawtooth). Reference specific milestones.
Unlock Sequence — What new abilities, levels, or items the player earns and when.
Scoring System — How score is calculated, combo multipliers, leaderboards if any.
Replayability Hooks — What brings the player back (new game+, daily challenges, procedural generation).
Estimated Play Time — Time to first completion and time to 100% completion.

Section 5 — Level / World Design

Plan the spatial structure of the game.

Include:

Level Count — Total number of levels, worlds, or zones.
Themes — Visual and mechanical theme per world (e.g., "World 2 — Ice Caves: slippery surfaces, breakable walls").
Flow Maps — ASCII diagram showing level progression and branching:

[Level 1] --> [Level 2] --> [Level 3]
                  |
                  +--> [Bonus Level A]

Difficulty Scaling — How enemy count, speed, puzzle complexity, or time pressure increases per level.

Section 6 — Characters & Entities

Catalog every game object with gameplay-relevant detail.

Include:

Player Character — Base stats (speed, health, jump height), abilities, state machine (idle, run, jump, hurt, dead).
Enemy Types — Table format:

Enemy	HP	Speed	Behavior	Attack	Drop
Slime	1	40px/s	Patrol left-right	Contact damage	Coin (50%)

NPCs — Role, dialogue triggers, quest associations.
Collectibles & Power-ups — Effect, duration, rarity, visual indicator.

Section 7 — UI/UX Wireframes

Define every screen the player sees.

Include:

HUD Layout — ASCII wireframe of the in-game overlay:

+---------------------------------------+
| [Lives: x3]          [Score: 00000]   |
|                                       |
|                                       |
|              GAME AREA                |
|                                       |
|                                       |
| [Item1] [Item2] [Item3]    [Pause]   |
+---------------------------------------+

Menu Flow Diagram — ASCII showing navigation between screens:

[Title Screen] --> [Main Menu] --> [Play] --> [Level Select] --> [Game]
                       |                                           |
                       +--> [Settings]                     [Pause Menu]
                       +--> [Credits]                          |
                                                         [Game Over] --> [Main Menu]

Screen Mockups — Brief description of each unique screen (title, main menu, settings, game over, win).
Accessibility Considerations — Color-blind modes, font size options, remappable controls, screen reader hints.

Section 8 — Art Direction

Establish the visual identity and asset pipeline.

Include:

Visual Style — Describe in 1-2 sentences (e.g., "16-bit pixel art with modern lighting effects").
Color Palette — 5-8 hex codes with role labels:

Role	Hex	Usage
Primary	#3A86FF	Player, UI highlights
Secondary	#FF006E	Enemies, danger
Background	#1B1B2F	Sky, menus

Resolution & Scaling — Game resolution (e.g., 800x600), scale mode (Phaser FIT, RESIZE, etc.), pixel-perfect flag.
Animation Guidelines — Frame counts, FPS per animation type (idle: 4 frames @ 8fps, run: 6 frames @ 12fps).
Asset List with Specs — Table of every required asset:

Asset	Type	Size	Frames	Format
player_idle	Spritesheet	32x32	4	PNG
background_forest	Static	800x600	1	PNG

Section 9 — Audio Design Plan

Define the soundscape.

Include:

Music Mood per Scene — Table mapping each scene/level to a musical mood and tempo:

Scene	Mood	Tempo	Loop?
Main Menu	Mysterious, inviting	90 BPM	Yes
Level 1	Upbeat, adventurous	120 BPM	Yes
Boss Fight	Intense, urgent	150 BPM	Yes
Game Over	Somber, reflective	70 BPM	No

SFX List — Action-to-sound mapping:

Action	Sound Description	Priority
Player jump	Short airy whoosh	High
Coin collect	Bright chime ascending	High
Enemy hit	Soft thud + squish	Medium

Format Requirements — All audio must be provided in both MP3 and OGG for cross-browser compatibility. Phaser will select the best format at runtime.
Volume Hierarchy — Define relative volume levels: Music (0.4), SFX (0.7), UI sounds (0.5). Describe how they interact (SFX duck music briefly on major events).

Section 10 — Technical Requirements

Pin down the Phaser-specific technical decisions.

Include:

Phaser Version — phaser (v4.2.1 stable) unless the user specifies otherwise.
Physics Engine — Choose one and justify:
- Arcade — Simple AABB, best for platformers and shooters. Low CPU cost.
- Matter.js — Full rigid-body physics. Use for games needing rotation, joints, or complex collision shapes.
- None — For puzzle or card games with no physics simulation.
Performance Budgets — Target frame rate (60 FPS), max draw calls per frame, max simultaneous particles, texture atlas size limits.
Browser/Device Targets — Minimum browser versions, mobile device tier (e.g., "must run at 30+ FPS on 2020-era mid-range Android").

Section 11 — Platform Targets & Device Profiles

Specify where the game will run and how input differs.

Include:

Primary Platforms — Desktop browser, mobile browser, PWA, Electron, Capacitor/Cordova.
Input per Platform:

Platform	Primary Input	Secondary Input
Desktop	Keyboard + Mouse	Gamepad
Mobile	Touch	Gyroscope (optional)
Tablet	Touch	Bluetooth gamepad

Deployment Method — How the game is built and distributed (static hosting, itch.io, app store via Capacitor, etc.).

Section 12 — Monetization & Release Plan (Optional)

Include this section only if the user wants to discuss business aspects. Mark it optional in the output.

Include:

Business Model — Free, premium, freemium, ad-supported, or donation-ware.
Milestones — Key dates or phases:

Milestone	Target Date	Deliverable
Prototype	Week 2	Core loop playable
Alpha	Week 6	All levels blocked out
Beta	Week 10	Feature-complete, playtesting
Launch	Week 14	Polished, deployed

Distribution — Where the game will be published (itch.io, GitHub Pages, Steam, app stores).

Section 13 — Acceptance Criteria

Every other section describes intent. This one is the only part a machine can check, and it is what turns the GDD from a document into a specification.

Write each criterion so that it is observable, numeric, and false when the game is wrong. "The player should feel powerful" is not a criterion. "A charged attack deals 3× base damage" is.

Derive criteria directly from Sections 3 (Mechanics), 4 (Progression), and 6 (Entities) — anywhere the design commits to a number, that number is a criterion.

Criterion	Observable state	Playtest assertion
Player jumps 3 tiles (96px) high	`player.y` at apex	`player.y`, `atMost: spawnY - 96`
Basic enemy dies in 3 hits	`enemy.active`	press attack ×3, then `enemy.active`, `equals: false`
Score persists into GameOver	`registry.get('score')`	transition, then `atLeast: 10`
Coyote time is 100ms	jump succeeds after leaving ledge	walk off, wait 80ms, jump → `body.velocity.y < 0`
Wave 5 spawns 12 enemies	active enemy count	set wave, then `enemies.countActive(true)`, `equals: 12`
Holds 60fps with 50 entities	`game.loop.actualFps`	spawn 50, then `atLeast: 55`
Boot reaches menu in under 3s	scene key at t=3s	`game.scene.isActive('MainMenuScene')`, `equals: true`

Group criteria under the milestone that must satisfy them:

### Vertical Slice
- [ ] Player spawns at level start and responds to left/right/jump within 1 frame
- [ ] Falling off the map triggers respawn at the last checkpoint within 500ms
- [ ] Collecting a coin increments score by 10 and plays the pickup sound

### Alpha
- [ ] All 8 levels load without console errors
- [ ] Enemy AI pathfinds around static geometry (no wall-clipping over 30s)

Mark anything genuinely subjective as such rather than inventing a fake metric:

### Human review required (not automatable)
- Difficulty curve across levels 1-8 feels fair to a first-time player
- Art reads clearly against every background
- Audio mix is balanced at 50% volume

Save these to docs/acceptance-criteria.md alongside the GDD. The phaser-playtest skill turns each automatable criterion into a scenario assertion, which is how the design gets verified rather than merely stated.

Post-GDD Workflow

Once the GDD is finalized, guide the user to the next steps:

Scaffold the project — Use /phaser-new to generate the base project structure matching the GDD's technical requirements.
Design the architecture — Use the phaser-architect skill/agent to translate the GDD into a technical architecture: scene graph, class hierarchy, data flow, and system decomposition.
Start implementing — Use the phaser-coder skill/agent to begin coding scenes, mechanics, and entities as specified in the GDD.
Verify it runs — /phaser-playtest after each vertical slice. Section 13's automatable acceptance criteria become playtest assertions, which is how the design gets checked rather than merely stated.
Ship it — /phaser-release runs the readiness gate and prepares the store presence.
Iterate on what players say — /phaser-feedback turns their reports into failing playtest scenarios, then fixes, then regression tests.

If the user arrived here without a sharpened concept — a genre rather than a hook, or a scope that has not been sized against their available time — send them to /phaser-brainstorm first. A GDD written around an unscoped idea documents a project that will not finish.

Remind the user: the GDD is a living document. Update it as the game evolves during development.

Output Format

The generated GDD must be a single Markdown document with:

A top-level # Game Design Document: [Title] heading.
Each of the 13 sections as ## Section N — Name headings.
ASCII diagrams for all flow charts, wireframes, and level maps (no external image dependencies).
Tables for structured data (enemies, assets, audio, controls).
 comments next to any detail the generator inferred rather than received from the user.

Save the document to docs/GDD.md in the project root. If no project directory exists, print the full GDD inline in the chat.

About this skill

GDD Structure (13 Sections)

Section 1 — Game Overview

Section 2 — Core Game Loop

Section 3 — Mechanics Deep Dive

Section 4 — Progression System

Section 5 — Level / World Design

Section 6 — Characters & Entities

Section 7 — UI/UX Wireframes

Section 8 — Art Direction

Section 9 — Audio Design Plan

Section 10 — Technical Requirements

Section 11 — Platform Targets & Device Profiles

Section 12 — Monetization & Release Plan (Optional)

Section 13 — Acceptance Criteria

Post-GDD Workflow

Output Format