docs(bmgd): refactor documentation using Diataxis principles
Apply Diataxis documentation framework to BMGD docs: game-types.md: - Convert to Reference format (austere, consistent structure) - Add Examples field to all 24 game types - Remove redundant Overview, GDD Section Mapping, Next Steps - Condense Hybrid Game Types to reference table - Remove Tags (no functional purpose for human readers) quick-flow-workflows.md: - Convert to How-to guide format - Remove conceptual content (Step-File Architecture, Integration) - Remove tutorial content (Examples section) - Cut redundant Reference tables (steps already in how-to) - Merge Self-Check and Adversarial Review into Validation Criteria index.md: - Fix broken link to Quick-Flow documentation Both main files: - Apply prose editorial fixes for clarity - Reduce word count while preserving comprehension
This commit is contained in:
Scott Jennings
parent
542a7429ec
commit
0089eba856
Binary file not shown.
|
After Width: | Height: | Size: 126 KiB |
|
|
@ -0,0 +1,374 @@
|
|||
---
|
||||
title: "Game Types Reference"
|
||||
---
|
||||
|
||||
BMGD supports 24 game type templates. Each adds genre-specific sections to your GDD.
|
||||
|
||||
## Game Types
|
||||
|
||||
### Action & Combat
|
||||
|
||||
#### Action Platformer
|
||||
|
||||
Side-scrolling or 3D platforming with combat mechanics.
|
||||
|
||||
**Examples:** Hollow Knight, Mega Man, Celeste
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Movement systems (jumps, dashes, wall mechanics)
|
||||
- Combat mechanics (melee/ranged, combos)
|
||||
- Level design patterns
|
||||
- Boss design
|
||||
|
||||
#### Shooter
|
||||
|
||||
Projectile combat with aiming mechanics.
|
||||
|
||||
**Examples:** Doom, Call of Duty, Splatoon
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Weapon systems
|
||||
- Aiming and accuracy
|
||||
- Enemy AI patterns
|
||||
- Level/arena design
|
||||
- Multiplayer considerations
|
||||
|
||||
#### Fighting
|
||||
|
||||
1v1 combat with combos and frame data.
|
||||
|
||||
**Examples:** Street Fighter, Tekken, Super Smash Bros.
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Frame data systems
|
||||
- Combo mechanics
|
||||
- Character movesets
|
||||
- Competitive balance
|
||||
- Netcode requirements
|
||||
|
||||
### Strategy & Tactics
|
||||
|
||||
#### Strategy
|
||||
|
||||
Resource management with tactical decisions.
|
||||
|
||||
**Examples:** StarCraft, Civilization, Europa Universalis
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Resource systems
|
||||
- Unit/building design
|
||||
- AI opponent behavior
|
||||
- Map/scenario design
|
||||
- Victory conditions
|
||||
|
||||
#### Turn-Based Tactics
|
||||
|
||||
Grid-based movement with turn order.
|
||||
|
||||
**Examples:** XCOM, Fire Emblem, Into the Breach
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Grid and movement systems
|
||||
- Turn order mechanics
|
||||
- Cover and positioning
|
||||
- Unit progression
|
||||
- Procedural mission generation
|
||||
|
||||
#### Tower Defense
|
||||
|
||||
Wave-based defense with tower placement.
|
||||
|
||||
**Examples:** Bloons TD, Kingdom Rush, Plants vs. Zombies
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Tower types and upgrades
|
||||
- Wave design and pacing
|
||||
- Economy systems
|
||||
- Map design patterns
|
||||
- Meta-progression
|
||||
|
||||
### RPG & Progression
|
||||
|
||||
#### RPG
|
||||
|
||||
Character progression with stats, inventory, and quests.
|
||||
|
||||
**Examples:** Final Fantasy, The Witcher, Baldur's Gate
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Character stats and leveling
|
||||
- Inventory and equipment
|
||||
- Quest system design
|
||||
- Combat system (action/turn-based)
|
||||
- Skill trees and builds
|
||||
|
||||
#### Roguelike
|
||||
|
||||
Procedural generation with permadeath and run-based progression.
|
||||
|
||||
**Examples:** Hades, Dead Cells, Spelunky
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Procedural generation rules
|
||||
- Permadeath and persistence
|
||||
- Run structure and pacing
|
||||
- Item/ability synergies
|
||||
- Meta-progression systems
|
||||
|
||||
#### Metroidvania
|
||||
|
||||
Interconnected world with ability gating.
|
||||
|
||||
**Examples:** Metroid, Castlevania: Symphony of the Night, Ori
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- World map connectivity
|
||||
- Ability gating design
|
||||
- Backtracking flow
|
||||
- Secret and collectible placement
|
||||
- Power-up progression
|
||||
|
||||
### Narrative & Story
|
||||
|
||||
#### Adventure
|
||||
|
||||
Story-driven exploration with puzzle elements.
|
||||
|
||||
**Examples:** Monkey Island, Myst, Life is Strange
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Puzzle design
|
||||
- Narrative delivery
|
||||
- Exploration mechanics
|
||||
- Dialogue systems
|
||||
- Story branching
|
||||
|
||||
#### Visual Novel
|
||||
|
||||
Narrative choices with branching story.
|
||||
|
||||
**Examples:** Doki Doki Literature Club, Phoenix Wright, Steins;Gate
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Branching narrative structure
|
||||
- Choice and consequence
|
||||
- Character routes
|
||||
- UI/presentation
|
||||
- Save/load states
|
||||
|
||||
#### Text-Based
|
||||
|
||||
Text input/output games with parser or choice mechanics.
|
||||
|
||||
**Examples:** Zork, 80 Days, Dwarf Fortress (adventure mode)
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Parser or choice systems
|
||||
- World model
|
||||
- Narrative structure
|
||||
- Text presentation
|
||||
- Save state management
|
||||
|
||||
### Simulation & Management
|
||||
|
||||
#### Simulation
|
||||
|
||||
Realistic systems with management and building.
|
||||
|
||||
**Examples:** SimCity, RollerCoaster Tycoon, The Sims
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Core simulation loops
|
||||
- Economy modeling
|
||||
- AI agents/citizens
|
||||
- Building/construction
|
||||
- Failure states
|
||||
|
||||
#### Sandbox
|
||||
|
||||
Creative freedom with building and minimal objectives.
|
||||
|
||||
**Examples:** Minecraft, Terraria, Garry's Mod
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Creation tools
|
||||
- Physics/interaction systems
|
||||
- Persistence and saving
|
||||
- Sharing/community features
|
||||
- Optional objectives
|
||||
|
||||
### Sports & Racing
|
||||
|
||||
#### Racing
|
||||
|
||||
Vehicle control with tracks and lap times.
|
||||
|
||||
**Examples:** Mario Kart, Forza, Need for Speed
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Vehicle physics model
|
||||
- Track design
|
||||
- AI opponents
|
||||
- Progression/career mode
|
||||
- Multiplayer racing
|
||||
|
||||
#### Sports
|
||||
|
||||
Team-based or individual sports simulation.
|
||||
|
||||
**Examples:** FIFA, NBA 2K, Tony Hawk's Pro Skater
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Sport-specific rules
|
||||
- Player/team management
|
||||
- AI opponent behavior
|
||||
- Season/career modes
|
||||
- Multiplayer modes
|
||||
|
||||
### Multiplayer
|
||||
|
||||
#### MOBA
|
||||
|
||||
Multiplayer team battles with hero selection.
|
||||
|
||||
**Examples:** League of Legends, Dota 2, Smite
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Hero/champion design
|
||||
- Lane and map design
|
||||
- Team composition
|
||||
- Matchmaking
|
||||
- Economy (gold/items)
|
||||
|
||||
#### Party Game
|
||||
|
||||
Local multiplayer with minigames.
|
||||
|
||||
**Examples:** Mario Party, Jackbox, Overcooked
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Minigame design patterns
|
||||
- Controller support
|
||||
- Round/game structure
|
||||
- Scoring systems
|
||||
- Player count flexibility
|
||||
|
||||
### Horror & Survival
|
||||
|
||||
#### Survival
|
||||
|
||||
Resource gathering with crafting and persistent threats.
|
||||
|
||||
**Examples:** Don't Starve, Subnautica, The Forest
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Resource gathering
|
||||
- Crafting systems
|
||||
- Hunger/health/needs
|
||||
- Threat systems
|
||||
- Base building
|
||||
|
||||
#### Horror
|
||||
|
||||
Atmosphere and tension with limited resources.
|
||||
|
||||
**Examples:** Resident Evil, Silent Hill, Amnesia
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Fear mechanics
|
||||
- Resource scarcity
|
||||
- Sound design
|
||||
- Lighting and visibility
|
||||
- Enemy/threat design
|
||||
|
||||
### Casual & Progression
|
||||
|
||||
#### Puzzle
|
||||
|
||||
Logic-based challenges and problem-solving.
|
||||
|
||||
**Examples:** Tetris, Portal, The Witness
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Puzzle mechanics
|
||||
- Difficulty progression
|
||||
- Hint systems
|
||||
- Level structure
|
||||
- Scoring/rating
|
||||
|
||||
#### Idle/Incremental
|
||||
|
||||
Passive progression with upgrades and automation.
|
||||
|
||||
**Examples:** Cookie Clicker, Adventure Capitalist, Clicker Heroes
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Core loop design
|
||||
- Prestige systems
|
||||
- Automation unlocks
|
||||
- Number scaling
|
||||
- Offline progress
|
||||
|
||||
#### Card Game
|
||||
|
||||
Deck building with card mechanics.
|
||||
|
||||
**Examples:** Slay the Spire, Hearthstone, Magic: The Gathering Arena
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Card design framework
|
||||
- Deck building rules
|
||||
- Mana/resource systems
|
||||
- Rarity and collection
|
||||
- Competitive balance
|
||||
|
||||
### Rhythm
|
||||
|
||||
#### Rhythm
|
||||
|
||||
Music synchronization with timing-based gameplay.
|
||||
|
||||
**Examples:** Guitar Hero, Beat Saber, Crypt of the NecroDancer
|
||||
|
||||
**GDD sections:**
|
||||
|
||||
- Note/beat mapping
|
||||
- Scoring systems
|
||||
- Difficulty levels
|
||||
- Music licensing
|
||||
- Input methods
|
||||
|
||||
## Hybrid Types
|
||||
|
||||
Multiple game types can be combined. GDD sections from all selected types are included.
|
||||
|
||||
| Hybrid | Components | Combined Sections |
|
||||
|--------|------------|-------------------|
|
||||
| Action RPG | Action Platformer + RPG | Movement, combat, stats, inventory |
|
||||
| Survival Horror | Survival + Horror | Resources, crafting, atmosphere, fear |
|
||||
| Roguelike Deckbuilder | Roguelike + Card Game | Run structure, procedural gen, cards |
|
||||
| Tactical RPG | Turn-Based Tactics + RPG | Grid movement, stats, progression |
|
||||
| Open World Survival | Sandbox + Survival | Building, crafting, exploration |
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
title: "BMGD Quick Guide"
|
||||
description: Quick reference for BMad Game Dev Studio
|
||||
---
|
||||
|
||||
|
||||
|
||||
# BMGD Quick Guide
|
||||
|
||||
BMad Game Dev Studio (BMGD) extends BMM with game-specific capabilities. Developed by game industry veterans, it guides you through product research, technical design, narrative design, and a full epic-driven production cycle.
|
||||
|
||||
## Under Construction
|
||||
|
||||
Documentation is under heavy construction catching up with the new beta release. We'll have complete documentation up as soon as possible. For now, please ask in the BMGD section of the Discord if you have any questions.
|
||||
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Install → Game Brief → GDD → (Narrative) → Architecture → Build**
|
||||
|
||||
BMGD is an optional module installed via BMAD Method: `npx bmad-method install`
|
||||
|
||||
See [How-To Reference](#how-to-reference) for commands.
|
||||
|
||||
## Development Phases
|
||||
|
||||
| Phase | Name | Key Activities |
|
||||
|-------|------|----------------|
|
||||
| 1 | **Preproduction** | Brainstorm Game, Game Brief, market research |
|
||||
| 2 | **Design** | GDD creation, Narrative Design (for story-driven games) |
|
||||
| 3 | **Technical** | Game Architecture (engine, systems, patterns) |
|
||||
| 4 | **Production** | Sprint planning, story development, code review, testing |
|
||||
|
||||
## BMGD Agents
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| Game Designer | Game mechanics, balance, player psychology |
|
||||
| Game Developer | Implementation with engine-specific patterns |
|
||||
| Game Architect | Engine selection, systems design, technical structure |
|
||||
| Game Scrum Master | Sprint planning and epic management |
|
||||
| Game QA | Playtesting, engine-specific testing, performance profiling |
|
||||
| Game Solo Dev | Full-stack game development for solo projects |
|
||||
|
||||
## Key Documents
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| **Game Brief** | Vision, market positioning, fundamentals |
|
||||
| **GDD** | Core loop, mechanics, progression, art/audio direction |
|
||||
| **Narrative Design** | Story structure, characters, world-building, dialogue |
|
||||
| **Architecture** | Engine, systems, patterns, project structure |
|
||||
|
||||
## Game Type Templates
|
||||
|
||||
BMGD includes 24 game type templates that auto-configure GDD sections:
|
||||
|
||||
Action, Adventure, Puzzle, RPG, Strategy, Simulation, Sports, Racing, Fighting, Horror, Platformer, Shooter, and more.
|
||||
|
||||
Each template provides genre-specific GDD sections, mechanics patterns, testing considerations, and common pitfalls to avoid.
|
||||
|
||||
## Explanation: BMGD vs BMM
|
||||
|
||||
### When to Use Each
|
||||
|
||||
| Use BMGD for | Use BMM for |
|
||||
|--------------|-------------|
|
||||
| Video games | Web applications |
|
||||
| Interactive experiences | APIs and services |
|
||||
| Game prototyping | Mobile apps (non-game) |
|
||||
| Game jams | General software projects |
|
||||
|
||||
### Phase Mapping
|
||||
|
||||
| BMM Phase | BMGD Phase | Key Difference |
|
||||
|-----------|------------|----------------|
|
||||
| Analysis | Preproduction | Game concepts, Game Brief instead of Product Brief |
|
||||
| Planning | Design | GDD instead of PRD; optional Narrative Design |
|
||||
| Solutioning | Technical | Focus on engine selection, game-specific patterns |
|
||||
| Implementation | Production | Game QA replaces TEA; engine-specific testing |
|
||||
|
||||
### Document Differences
|
||||
|
||||
| BMM | BMGD | Notes |
|
||||
|-----|------|-------|
|
||||
| Product Brief | Game Brief | Captures vision, market, fundamentals |
|
||||
| PRD | GDD | Includes mechanics, balance, player experience |
|
||||
| N/A | Narrative Design | Story, characters, world (story-driven games) |
|
||||
| Architecture | Architecture | BMGD version includes engine-specific patterns and considerations |
|
||||
|
||||
### Testing Differences
|
||||
|
||||
**BMM (TEA):** Web-focused testing with Playwright, Cypress, API testing, E2E for web apps.
|
||||
|
||||
**BMGD (Game QA):** Engine-specific frameworks (Unity, Unreal, Godot), gameplay testing, performance profiling, playtest planning, balance validation.
|
||||
|
||||
## How-To Reference
|
||||
|
||||
| I need to... | Action |
|
||||
|--------------|--------------------------------------------------------------------------------------------------------|
|
||||
| Install BMGD | Run `npx bmad-method install` and select BMGD during module installation |
|
||||
| Start a new game | Run `/bmad-gds-brainstorm-game`, then `/bmad:gds:create-game-brief` |
|
||||
| Design my game | Run `/bmad-gds-create-gdd`; add `/bmad:gds:narrative` if story-heavy |
|
||||
| Plan architecture | Run `/bmad-gds-game-architecture` with Game Architect |
|
||||
| Build my game | Use Phase 4 production workflows - Run `/bmad-help` to see what's next |
|
||||
| Test an idea quickly | Use [Quick-Flow](quick-flow-workflows.md) for rapid prototyping |
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Game Types Guide](game-types.md)
|
||||
- [Quick-Flow Guide](quick-flow-workflows.md)
|
||||
|
||||
|
|
@ -0,0 +1,160 @@
|
|||
---
|
||||
title: "Quick Flow Workflows"
|
||||
---
|
||||
|
||||
How to create tech specs and execute implementations with Quick Flow.
|
||||
|
||||
## Choosing a Workflow
|
||||
|
||||
| Situation | Workflow | Command |
|
||||
|-----------|----------|---------|
|
||||
| Need to document before implementing | Quick-Spec | `/bmad-gds-quick-spec` |
|
||||
| Multiple approaches to evaluate | Quick-Spec | `/bmad-gds-quick-spec` |
|
||||
| Have a completed tech-spec | Quick-Dev | `/bmad-gds-quick-dev path/to/spec.md` |
|
||||
| Have clear, direct instructions | Quick-Dev | `/bmad-gds-quick-dev` |
|
||||
| Building complete game system | Full GDS | `/bmad-gds-workflow-init` |
|
||||
| Epic-level features | Full GDS | `/bmad-gds-workflow-init` |
|
||||
|
||||
---
|
||||
|
||||
## How to Create a Tech Spec (Quick-Spec)
|
||||
|
||||
### Step 1: Start the workflow
|
||||
|
||||
```bash
|
||||
/bmad-gds-quick-spec
|
||||
```
|
||||
|
||||
### Step 2: Describe your requirement
|
||||
|
||||
Provide your feature request. The agent scans the codebase and asks clarifying questions.
|
||||
|
||||
**Checkpoint options:**
|
||||
- `[a]` Advanced Elicitation - explore requirements deeper
|
||||
- `[c]` Continue to investigation
|
||||
- `[p]` Party Mode - consult expert agents
|
||||
|
||||
### Step 3: Review investigation findings
|
||||
|
||||
The agent analyzes the codebase for patterns, constraints, and similar implementations. Review the findings.
|
||||
|
||||
**Checkpoint options:**
|
||||
- `[c]` Continue to spec generation
|
||||
- `[p]` Party Mode - get technical review
|
||||
|
||||
### Step 4: Review generated spec
|
||||
|
||||
The agent creates an ordered task list with file paths and acceptance criteria. Verify completeness.
|
||||
|
||||
**Checkpoint options:**
|
||||
- `[c]` Continue to final review
|
||||
- `[p]` Party Mode - technical review
|
||||
|
||||
### Step 5: Finalize
|
||||
|
||||
Confirm the spec meets these standards:
|
||||
- Every task has a file path and specific action
|
||||
- Tasks ordered by dependency
|
||||
- Acceptance criteria in Given/When/Then format
|
||||
- No placeholders or TBD sections
|
||||
|
||||
**Options:**
|
||||
- `[d]` Start Quick-Dev immediately
|
||||
- `[done]` Save spec and exit
|
||||
|
||||
**Output:** `{planning_artifacts}/tech-spec-{slug}.md`
|
||||
|
||||
---
|
||||
|
||||
## How to Execute Implementation (Quick-Dev)
|
||||
|
||||
### With a Tech-Spec
|
||||
|
||||
```bash
|
||||
/bmad-gds-quick-dev path/to/tech-spec-feature.md
|
||||
```
|
||||
|
||||
The agent:
|
||||
1. Captures baseline git commit
|
||||
2. Loads and validates the spec
|
||||
3. Executes tasks in order
|
||||
4. Runs self-check
|
||||
5. Performs adversarial review
|
||||
6. Resolves findings
|
||||
7. Validates against acceptance criteria
|
||||
|
||||
### With Direct Instructions
|
||||
|
||||
```bash
|
||||
/bmad-gds-quick-dev
|
||||
```
|
||||
|
||||
Then describe what you want implemented:
|
||||
1. Captures baseline git commit
|
||||
2. Evaluates complexity (may suggest planning)
|
||||
3. Gathers context from codebase
|
||||
4. Executes implementation
|
||||
5. Runs self-check and adversarial review
|
||||
6. Resolves findings
|
||||
|
||||
**Escalation:** If the agent detects complexity (multiple components, system-level scope, uncertainty), it offers:
|
||||
- `[t]` Create tech-spec first
|
||||
- `[w]` Use full GDS workflow
|
||||
- `[e]` Execute anyway
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Spec has placeholders or TBD sections
|
||||
|
||||
Return to investigation step. Complete missing research, inline all findings, re-run review.
|
||||
|
||||
### Workflow lost context mid-step
|
||||
|
||||
Check frontmatter for `stepsCompleted`. Resume from last completed step.
|
||||
|
||||
### Agent suggested planning but you want to execute
|
||||
|
||||
You can override with `[e]`, but document your assumptions. Escalation heuristics exist because planning saves time on complex tasks.
|
||||
|
||||
### Tests failing after implementation
|
||||
|
||||
Return to the resolve-findings step. Review failures, fix issues, ensure test expectations are correct, re-run full suite.
|
||||
|
||||
### Need help
|
||||
|
||||
```bash
|
||||
/bmad-help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
### File Locations
|
||||
|
||||
| File | Location |
|
||||
|------|----------|
|
||||
| Work in progress | `{implementation_artifacts}/tech-spec-wip.md` |
|
||||
| Completed specs | `{planning_artifacts}/tech-spec-{slug}.md` |
|
||||
| Archived specs | `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md` |
|
||||
| Workflow files | `_bmad/gds/workflows/gds-quick-flow/` |
|
||||
|
||||
### Validation Criteria
|
||||
|
||||
**Self-check (before adversarial review):**
|
||||
- All tasks/instructions completed
|
||||
- Tests written and passing
|
||||
- Follows existing patterns
|
||||
- No obvious bugs
|
||||
- Acceptance criteria met
|
||||
- Code is readable
|
||||
|
||||
**Adversarial review:**
|
||||
- Correctness
|
||||
- Security
|
||||
- Performance
|
||||
- Maintainability
|
||||
- Test coverage
|
||||
- Error handling
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
Loading…
Reference in New Issue