270 lines
11 KiB
Markdown
270 lines
11 KiB
Markdown
# Example Session: Using /design-system to Author a GDD
|
||
|
||
**Context:** Solo indie dev, week 3 of project. `/map-systems` already ran and produced `design/gdd/systems-index.md`. The movement system is listed as MVP tier, Foundation priority.
|
||
|
||
**Starting State:**
|
||
- `design/gdd/game-concept.md` exists (survival-crafting game, 2D, Godot 4.6)
|
||
- `design/gdd/systems-index.md` exists (15 systems identified, movement is first in design order)
|
||
- No per-system GDDs written yet
|
||
- No upstream dependencies for movement (it is the foundation)
|
||
|
||
**Session Duration:** ~60 minutes
|
||
**Turns:** 14
|
||
**Outcome:** Complete `design/gdd/movement-system.md` with all 8 required sections written to file, ready for `/design-review`
|
||
|
||
---
|
||
|
||
## Turn 1: User Invokes the Skill
|
||
|
||
**User:**
|
||
> /design-system movement
|
||
|
||
## Turn 2: Agent Loads Context and Presents the Plan
|
||
|
||
**Agent (game-designer, via /design-system):**
|
||
> I'm loading context before we start:
|
||
>
|
||
> - Read `design/gdd/game-concept.md` — survival-crafting, exploration-heavy, lone survivor stranded on alien planet
|
||
> - Read `design/gdd/systems-index.md` — movement is **Foundation / MVP**, no upstream deps, downstream: combat, exploration, stamina
|
||
> - No prior GDD found for movement — starting fresh
|
||
>
|
||
> **Technical Feasibility Pre-Check:**
|
||
>
|
||
> | Domain | Signal |
|
||
> |--------|--------|
|
||
> | Engine | Godot 4.6 — CharacterBody2D with move_and_slide() is well-supported |
|
||
> | Physics | Jolt is now the default in 4.6 — 2D movement unaffected, but note for future 3D work |
|
||
> | Downstream risk | Stamina system listed as downstream dep — movement must expose a stamina callback hook |
|
||
>
|
||
> The GDD template has **8 required sections**. We'll go one at a time:
|
||
> `Overview → Player Fantasy → Detailed Rules → Formulas → Edge Cases → Dependencies → Tuning Knobs → Acceptance Criteria`
|
||
>
|
||
> I'll show you a draft of each section, you approve or revise, then I write it to the file before we move on.
|
||
>
|
||
> Creating the file skeleton now with empty section headers — may I write `design/gdd/movement-system.md` with placeholders?
|
||
|
||
**User:**
|
||
> Yes
|
||
|
||
**Agent writes** `design/gdd/movement-system.md` with 8 empty section headers.
|
||
|
||
---
|
||
|
||
## Turn 3: Section 1 — Overview
|
||
|
||
**Agent:**
|
||
> **Section 1 draft — Overview:**
|
||
>
|
||
> > The movement system is the player's primary interface with the world. It governs how the lone survivor walks, runs, rolls, and traverses alien terrain. Movement is physically grounded — the planet has heavier-than-Earth gravity, and the survivor is physically exhausted — but remains responsive enough to stay out of the player's way. The system feeds directly into exploration pacing, combat positioning, and the stamina system.
|
||
>
|
||
> Does this capture what you want?
|
||
|
||
**User:**
|
||
> Good but add something about the terrain — surfaces slow you down or have friction modifiers.
|
||
|
||
**Agent:**
|
||
> Revised:
|
||
>
|
||
> > The movement system is the player's primary interface with the world. It governs how the lone survivor walks, runs, rolls, and traverses alien terrain. Movement is physically grounded — the planet has heavier-than-Earth gravity, and the survivor is physically exhausted — but remains responsive enough to stay out of the player's way. Terrain surfaces apply friction and speed modifiers (slick rock, sand, shallow water) that make navigation a meaningful skill. The system feeds directly into exploration pacing, combat positioning, and the stamina system.
|
||
>
|
||
> May I write this to Section 1 in the file?
|
||
|
||
**User:**
|
||
> Yes
|
||
|
||
**Agent writes Section 1 to file.**
|
||
|
||
---
|
||
|
||
## Turn 4: Section 2 — Player Fantasy
|
||
|
||
**Agent:**
|
||
> **Section 2 draft — Player Fantasy:**
|
||
>
|
||
> > The player should feel like a tired but capable survivor — not a superhero, not helpless. Early game movement is deliberate and taxing; the player earns fluency over time. When traversing alien terrain, the goal is careful navigation with moments of urgency (running from threats, leaping a gap). The fantasy is "I know this terrain" — every surface type becomes readable and manageable as the player internalizes the friction system.
|
||
>
|
||
> Approve, revise, or change direction?
|
||
|
||
**User:**
|
||
> Love it. Write it.
|
||
|
||
**Agent writes Section 2 to file.**
|
||
|
||
---
|
||
|
||
## Turn 5: Section 3 — Detailed Rules
|
||
|
||
**Agent:**
|
||
> **Section 3 draft — Detailed Rules:**
|
||
>
|
||
> > **Base States:**
|
||
> > - **Walk** (default): Full directional control, moderate speed, low stamina drain
|
||
> > - **Run** (hold Shift): Faster, medium stamina drain per second — cancels automatically when stamina hits 0
|
||
> > - **Roll/Dodge** (tap Space): Quick burst in movement direction, brief invincibility frames, high stamina cost (flat)
|
||
> > - **Idle**: Zero movement input, stamina regenerates at full rate
|
||
> >
|
||
> > **Terrain Modifiers:**
|
||
> > - Normal ground: 1.0x speed multiplier, standard friction
|
||
> > - Sand/loose soil: 0.8x speed, 1.1x stamina drain (harder to move)
|
||
> > - Slick rock (wet): 1.1x speed, reduced stop friction (player overshoots)
|
||
> > - Shallow water (ankle-deep): 0.7x speed, no friction modifier
|
||
> > - Deep water: movement disabled, replaced by swimming (separate system, out of scope)
|
||
> >
|
||
> > **Collision:**
|
||
> > - CharacterBody2D + move_and_slide(); wall slide enabled
|
||
> > - Slopes up to 45° walked normally; >45° blocked
|
||
> > - One-way platforms supported (drop-through with Down + Jump)
|
||
>
|
||
> A lot here — want me to trim or expand anything?
|
||
|
||
**User:**
|
||
> Add that running is disabled when carrying a heavy object (like a large resource chunk).
|
||
|
||
**Agent:**
|
||
> Added to Run rule:
|
||
> > - **Run** (hold Shift): Faster, medium stamina drain per second — cancels automatically when stamina hits 0. **Disabled when carrying heavy objects** (signals broadcast by inventory system).
|
||
>
|
||
> Write to file?
|
||
|
||
**User:**
|
||
> Yes
|
||
|
||
**Agent writes Section 3 to file.**
|
||
|
||
---
|
||
|
||
## Turn 6: Section 4 — Formulas
|
||
|
||
**Agent:**
|
||
> **Section 4 draft — Formulas:**
|
||
>
|
||
> Let me define variables first, then the formulas:
|
||
>
|
||
> | Variable | Type | Description |
|
||
> |----------|------|-------------|
|
||
> | `base_walk_speed` | float | Base walk speed in px/s (tunable) |
|
||
> | `run_multiplier` | float | Run speed = walk × this |
|
||
> | `terrain_speed_mod` | float | Per-terrain multiplier (0.7–1.1) |
|
||
> | `stamina_drain_walk` | float | Stamina units/sec while walking |
|
||
> | `stamina_drain_run` | float | Stamina units/sec while running |
|
||
> | `stamina_cost_roll` | float | Flat stamina cost per roll |
|
||
> | `terrain_drain_mod` | float | Per-terrain stamina drain multiplier |
|
||
>
|
||
> **Effective Speed:**
|
||
> ```
|
||
> effective_speed = base_walk_speed × run_multiplier (if running, else 1.0) × terrain_speed_mod
|
||
> ```
|
||
>
|
||
> **Stamina Drain (per second):**
|
||
> ```
|
||
> drain_per_sec = stamina_drain_walk (or stamina_drain_run if running) × terrain_drain_mod
|
||
> ```
|
||
>
|
||
> **Roll Stamina Cost (flat):**
|
||
> ```
|
||
> stamina_after_roll = current_stamina - stamina_cost_roll
|
||
> (clamped to 0 — roll still executes, but player lands with 0 stamina)
|
||
> ```
|
||
>
|
||
> Approve or adjust variable names/formulas?
|
||
|
||
**User:**
|
||
> Looks right. Write it.
|
||
|
||
**Agent writes Section 4 to file.**
|
||
|
||
---
|
||
|
||
## Turn 7–9: Sections 5, 6, 7
|
||
|
||
*(These follow the same pattern — agent drafts, user approves or requests minor tweaks, agent writes each section to file before moving on. Abbreviated here.)*
|
||
|
||
**Section 5 — Edge Cases** covered:
|
||
- Player rolls into a wall (animation completes, no movement bonus)
|
||
- Stamina hits 0 mid-run (transitions to walk, no lurch)
|
||
- Two terrain types overlapping (lower multiplier wins)
|
||
- Roll on slick rock (still applies slick friction to stopping, not to the roll itself)
|
||
|
||
**Section 6 — Dependencies** covered:
|
||
- **Stamina system** (downstream): movement exposes `on_stamina_event(type: String, amount: float)` signal
|
||
- **Inventory system** (downstream): listens to `carrying_heavy_object_changed(is_heavy: bool)` signal
|
||
- **Input system**: movement direction from `InputMap` — standard Godot action names (`ui_left`, `ui_right`, etc.)
|
||
- **Terrain layer**: tile metadata drives terrain modifier lookup
|
||
|
||
**Section 7 — Tuning Knobs** covered:
|
||
- `base_walk_speed` (default: 120 px/s)
|
||
- `run_multiplier` (default: 1.7)
|
||
- Per-terrain speed and drain modifiers (table of 4 terrain types)
|
||
- `stamina_drain_walk`, `stamina_drain_run`, `stamina_cost_roll`
|
||
|
||
---
|
||
|
||
## Turn 10: Section 8 — Acceptance Criteria
|
||
|
||
**Agent:**
|
||
> **Section 8 draft — Acceptance Criteria:**
|
||
>
|
||
> These are the testable conditions that prove this system is complete:
|
||
>
|
||
> - [ ] Player walks at `base_walk_speed` on normal ground (measured with debug overlay)
|
||
> - [ ] Player runs at `base_walk_speed × run_multiplier` on normal ground
|
||
> - [ ] Run automatically cancels when stamina reaches 0, no input required
|
||
> - [ ] Roll executes with correct invincibility frames (verify via hitbox debug mode)
|
||
> - [ ] Each terrain type applies the correct speed modifier (QA table in sprint plan)
|
||
> - [ ] Carrying heavy object disables run (test with inventory integration)
|
||
> - [ ] Stamina system receives `on_stamina_event` signals during walk, run, and roll
|
||
> - [ ] All movement values come from exported variables — no hardcoded numbers in code
|
||
>
|
||
> Does this cover what "done" means to you?
|
||
|
||
**User:**
|
||
> Add one for slopes — make sure >45 degree slopes block movement.
|
||
|
||
**Agent:**
|
||
> Added:
|
||
> - [ ] Slopes ≤45° traversed normally; slopes >45° block movement (player slides back)
|
||
>
|
||
> Write to file?
|
||
|
||
**User:**
|
||
> Yes. Write it.
|
||
|
||
**Agent writes Section 8 to file.**
|
||
|
||
---
|
||
|
||
## Turn 11: Completion Summary
|
||
|
||
**Agent:**
|
||
> All 8 sections written to `design/gdd/movement-system.md`.
|
||
>
|
||
> **GDD Status:**
|
||
> - ✅ Overview
|
||
> - ✅ Player Fantasy
|
||
> - ✅ Detailed Rules
|
||
> - ✅ Formulas
|
||
> - ✅ Edge Cases
|
||
> - ✅ Dependencies (exposes 2 signals: stamina_event, carrying_heavy)
|
||
> - ✅ Tuning Knobs
|
||
> - ✅ Acceptance Criteria
|
||
>
|
||
> **Key decisions made:**
|
||
> - Terrain modifiers as tile metadata (not code constants)
|
||
> - Rolling has a flat stamina cost (not per-second)
|
||
> - Heavy carry disables run (signal-driven, not hardcoded check)
|
||
>
|
||
> **Recommended next step:** Run `/design-review design/gdd/movement-system.md` before moving to the next system in your queue (stamina is next in dependency order, per systems-index).
|
||
>
|
||
> The review will validate completeness, internal consistency, and catch anything that needs revision before you build on this GDD.
|
||
|
||
---
|
||
|
||
## What This Example Demonstrates
|
||
|
||
- **Incremental file writing**: each section written to disk immediately after approval — a session crash loses at most one in-progress section
|
||
- **Template population**: the GDD template's 8 sections become concrete content through dialogue, not bulk generation
|
||
- **Dependency signaling**: agent proactively surfaces downstream signal contracts (stamina, inventory) during the Dependencies section
|
||
- **Technical feasibility pre-check**: agent notes Jolt physics change before design starts, not after implementation breaks
|
||
- **Section-by-section cycle**: no full draft dumped at once — each section is a small, reviewable unit
|
||
- **Recovery**: if the session crashes, the agent re-reads the file on restart and resumes from the first empty section
|