diff --git a/.github/workflows/bundle-latest.yaml b/.github/workflows/bundle-latest.yaml index d8a0da0e..7c49cb24 100644 --- a/.github/workflows/bundle-latest.yaml +++ b/.github/workflows/bundle-latest.yaml @@ -10,6 +10,7 @@ permissions: jobs: bundle-and-publish: + if: ${{ false }} # Temporarily disabled while web bundles are paused. runs-on: ubuntu-latest steps: - name: Checkout BMAD-METHOD diff --git a/.gitignore b/.gitignore index c644f148..c8d7f1f6 100644 --- a/.gitignore +++ b/.gitignore @@ -44,22 +44,15 @@ CLAUDE.local.md .claude/settings.local.json # Project-specific -_bmad-core -_bmad-creator-tools -flattened-codebase.xml *.stats.md -.internal-docs/ -#UAT template testing output files -tools/template-test-generator/test-scenarios/ # Bundler temporary files and generated bundles .bundler-temp/ +web-bundles/ # Generated web bundles (built by CI, not committed) src/modules/bmm/sub-modules/ src/modules/bmb/sub-modules/ -src/modules/cis/sub-modules/ -src/modules/bmgd/sub-modules/ shared-modules z*/ @@ -68,6 +61,7 @@ _bmad-output .claude .codex .github/chatmodes +.github/agents .agent .agentvibes/ .kiro/ diff --git a/docs/explanation/agents/index.md b/docs/explanation/agents/index.md index c5f02426..d8ebc323 100644 --- a/docs/explanation/agents/index.md +++ b/docs/explanation/agents/index.md @@ -7,11 +7,10 @@ Comprehensive guides to BMad's AI agents — their roles, capabilities, and how ## Agent Guides -| Agent | Description | -|-------|-------------| -| **[Agent Roles](/docs/explanation/core-concepts/agent-roles.md)** | Overview of all BMM agent roles and responsibilities | -| **[Quick Flow Solo Dev (Barry)](/docs/explanation/agents/barry-quick-flow.md)** | The dedicated agent for rapid development | -| **[Game Development Agents](/docs/explanation/game-dev/agents.md)** | Complete guide to BMGD's specialized game dev agents | +| Agent | Description | +| ------------------------------------------------------------------------------- | ---------------------------------------------------- | +| **[Agent Roles](/docs/explanation/core-concepts/agent-roles.md)** | Overview of all BMM agent roles and responsibilities | +| **[Quick Flow Solo Dev (Barry)](/docs/explanation/agents/barry-quick-flow.md)** | The dedicated agent for rapid development | ## Getting Started diff --git a/docs/explanation/core-concepts/what-are-modules.md b/docs/explanation/core-concepts/what-are-modules.md index 4527b9ba..0c4eaae0 100644 --- a/docs/explanation/core-concepts/what-are-modules.md +++ b/docs/explanation/core-concepts/what-are-modules.md @@ -13,7 +13,7 @@ A module is a self-contained package that includes: - **Configuration** - Module-specific settings - **Documentation** - Usage guides and reference -## Official Modules +## Official BMad Method and Builder Modules :::note[Core is Always Installed] The Core module is automatically included with every BMad installation. It provides the foundation that other modules build upon. @@ -37,17 +37,24 @@ Create custom solutions: - Workflow authoring tools - Module scaffolding +## Additional Official BMad Modules + +These are officially maintained modules by BMad but have their own repo's and docs. +These give a good idea also of what can be done with the BMad builder and creating your own custom modules. + ### Creative Intelligence Suite (CIS) Innovation and creativity: - Creative thinking techniques - Innovation strategy workflows - Storytelling and ideation +- [Available Here](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) ### BMad Game Dev (BMGD) Game development specialization: - Game design workflows - Narrative development - Performance testing frameworks +- [Available Here](https://github.com/bmad-code-org/bmad-module-game-dev-studio) ## Module Structure diff --git a/docs/explanation/core-concepts/what-are-workflows.md b/docs/explanation/core-concepts/what-are-workflows.md index e60d8d80..e8721da9 100644 --- a/docs/explanation/core-concepts/what-are-workflows.md +++ b/docs/explanation/core-concepts/what-are-workflows.md @@ -163,7 +163,7 @@ Before building a workflow, answer these questions: The best way to understand workflows is to study real examples. Look at the official BMad modules: -- **BMB (Module Builder)**: Workflow and agent creation workflows +- **BMB (Module Builder)**: Module, Workflow and Agent creation workflows - **BMM (Business Method Module)**: Complete software development pipeline from brainstorming through sprint planning - **BMGD (Game Development Module)**: Game design briefs, narratives, architecture - **CIS (Creativity, Innovation, Strategy)**: Brainstorming, design thinking, storytelling, innovation strategy diff --git a/docs/explanation/creative-intelligence/index.md b/docs/explanation/creative-intelligence/index.md deleted file mode 100644 index 439dc6f3..00000000 --- a/docs/explanation/creative-intelligence/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Creative Intelligence Suite (CIS)" -description: AI-powered creative facilitation with the Creative Intelligence Suite ---- - -AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains. - -## Core Capabilities - -CIS provides structured creative methodologies through distinctive agent personas who act as master facilitators, drawing out insights through strategic questioning rather than generating solutions directly. - -## Specialized Agents - -- **Carson** - Brainstorming Specialist (energetic facilitator) -- **Maya** - Design Thinking Maestro (jazz-like improviser) -- **Dr. Quinn** - Problem Solver (detective-scientist hybrid) -- **Victor** - Innovation Oracle (bold strategic precision) -- **Sophia** - Master Storyteller (whimsical narrator) - -## Interactive Workflows - -**5 Workflows** with **150+ Creative Techniques:** - -### Brainstorming - -36 techniques across 7 categories for ideation: -- Divergent/convergent thinking -- Lateral connections -- Forced associations - -### Design Thinking - -Complete 5-phase human-centered process: -- Empathize → Define → Ideate → Prototype → Test -- User journey mapping -- Rapid iteration - -### Problem Solving - -Systematic root cause analysis: -- 5 Whys, Fishbone diagrams -- Solution generation -- Impact assessment - -### Innovation Strategy - -Business model disruption: -- Blue Ocean Strategy -- Jobs-to-be-Done -- Disruptive innovation patterns - -### Storytelling - -25 narrative frameworks: -- Hero's Journey -- Story circles -- Compelling pitch structures - -## Quick Start - -### Direct Workflow - -```bash -workflow brainstorming - -workflow design-thinking --data /path/to/context.md -``` - -### Agent-Facilitated - -```bash -agent cis/brainstorming-coach - -> *brainstorm -``` - -## Key Differentiators - -- **Facilitation Over Generation** - Guides discovery through questions -- **Energy-Aware Sessions** - Adapts to engagement levels -- **Context Integration** - Domain-specific guidance support -- **Persona-Driven** - Unique communication styles -- **Rich Method Libraries** - 150+ proven techniques - -## Integration Points - -CIS workflows integrate with: - -- **BMM** - Powers project brainstorming -- **BMB** - Creative module design -- **Custom Modules** - Shared creative resource - -## Best Practices - -1. **Set clear objectives** before starting sessions -2. **Provide context documents** for domain relevance -3. **Trust the process** - Let facilitation guide you -4. **Take breaks** when energy flags -5. **Document insights** as they emerge - -:::tip[Learn More] -See [Facilitation Over Generation](/docs/explanation/philosophy/facilitation-over-generation.md) for the core philosophy behind CIS. -::: diff --git a/docs/explanation/faq/tools-faq.md b/docs/explanation/faq/tools-faq.md index 215d90e3..061f43e9 100644 --- a/docs/explanation/faq/tools-faq.md +++ b/docs/explanation/faq/tools-faq.md @@ -9,21 +9,45 @@ Quick answers to common questions about tools, IDEs, and advanced topics in the **Tools and Technical** -- [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering) -- [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools) -- [What IDEs/tools support BMM?](#what-idestools-support-bmm) -- [Can I customize agents?](#can-i-customize-agents) -- [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation) -- [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects) +- [Questions](#questions) +- [Tools and Technical](#tools-and-technical) + - [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering) + - [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools) + - [What IDEs/tools support BMM?](#what-idestools-support-bmm) + - [Can I customize agents?](#can-i-customize-agents) + - [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation) + - [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects) +- [Advanced](#advanced) + - [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3) + - [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches) + - [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint) + - [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations) + - [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project) + - [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it) +- [Getting Help](#getting-help) + - [Where do I get help if my question isn't answered here?](#where-do-i-get-help-if-my-question-isnt-answered-here) + - [How do I report a bug or request a feature?](#how-do-i-report-a-bug-or-request-a-feature) **Advanced** -- [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3) -- [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches) -- [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint) -- [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations) -- [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project) -- [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it) +- [Questions](#questions) +- [Tools and Technical](#tools-and-technical) + - [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering) + - [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools) + - [What IDEs/tools support BMM?](#what-idestools-support-bmm) + - [Can I customize agents?](#can-i-customize-agents) + - [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation) + - [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects) +- [Advanced](#advanced) + - [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3) + - [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches) + - [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint) + - [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations) + - [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project) + - [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it) +- [Getting Help](#getting-help) + - [Where do I get help if my question isn't answered here?](#where-do-i-get-help-if-my-question-isnt-answered-here) + - [How do I report a bug or request a feature?](#how-do-i-report-a-bug-or-request-a-feature) **Getting Help** @@ -199,11 +223,11 @@ Yes! But the paradigm is fundamentally different from traditional agile teams. ### What is party mode and when should I use it? -Party mode is a unique multi-agent collaboration feature where ALL your installed agents (19+ from BMM, CIS, BMB, custom modules) discuss your challenges together in real-time. +Party mode is a unique multi-agent collaboration feature where ALL your installed modules agents discuss your challenges together in real-time or have some fun with any topic you have in mind. **How it works:** -1. Run `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent) +1. Run `/bmad:core:workflows:party-mode` (or `PM or fuzzy match on party-mode` from any agent) 2. Introduce your topic 3. BMad Master selects 2-3 most relevant agents per message 4. Agents cross-talk, debate, and build on each other's ideas diff --git a/docs/explanation/game-dev/agents.md b/docs/explanation/game-dev/agents.md deleted file mode 100644 index 1dcdbb32..00000000 --- a/docs/explanation/game-dev/agents.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -title: "BMGD Agents Guide" ---- - -Complete reference for BMGD's six specialized game development agents. - -## Agent Overview - -BMGD provides six agents, each with distinct expertise: - -| Agent | Name | Role | Phase Focus | -|-------|------|------|-------------| -| **Game Designer** | Samus Shepard | Lead Game Designer + Creative Vision Architect | Phases 1-2 | -| **Game Architect** | Cloud Dragonborn | Principal Game Systems Architect + Technical Director | Phase 3 | -| **Game Developer** | Link Freeman | Senior Game Developer + Technical Implementation Specialist | Phase 4 | -| **Game Scrum Master** | Max | Game Development Scrum Master + Sprint Orchestrator | Phase 4 | -| **Game QA** | GLaDOS | Game QA Architect + Test Automation Specialist | All Phases | -| **Game Solo Dev** | Indie | Elite Indie Game Developer + Quick Flow Specialist | All Phases | - -## Game Designer (Samus Shepard) - -### Role - -Lead Game Designer + Creative Vision Architect - -### Identity - -Veteran designer with 15+ years crafting AAA and indie hits. Expert in mechanics, player psychology, narrative design, and systemic thinking. - -### Communication Style - -Talks like an excited streamer - enthusiastic, asks about player motivations, celebrates breakthroughs with "Let's GOOO!" - -### Core Principles - -- Design what players want to FEEL, not what they say they want -- Prototype fast - one hour of playtesting beats ten hours of discussion -- Every mechanic must serve the core fantasy - -### When to Use - -- Brainstorming game ideas -- Creating Game Briefs -- Designing GDDs -- Developing narrative design - -### Available Commands - -| Command | Description | -| ---------------------- | -------------------------------- | -| `workflow-status` | Check project status | -| `brainstorm-game` | Guided game ideation | -| `create-game-brief` | Create Game Brief | -| `create-gdd` | Create Game Design Document | -| `narrative` | Create Narrative Design Document | -| `quick-prototype` | Rapid prototyping (IDE only) | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -## Game Architect (Cloud Dragonborn) - -### Role - -Principal Game Systems Architect + Technical Director - -### Identity - -Master architect with 20+ years shipping 30+ titles. Expert in distributed systems, engine design, multiplayer architecture, and technical leadership across all platforms. - -### Communication Style - -Speaks like a wise sage from an RPG - calm, measured, uses architectural metaphors about building foundations and load-bearing walls. - -### Core Principles - -- Architecture is about delaying decisions until you have enough data -- Build for tomorrow without over-engineering today -- Hours of planning save weeks of refactoring hell -- Every system must handle the hot path at 60fps - -### When to Use - -- Planning technical architecture -- Making engine/framework decisions -- Designing game systems -- Course correction during development - -### Available Commands - -| Command | Description | -| ---------------------- | ------------------------------------- | -| `workflow-status` | Check project status | -| `create-architecture` | Create Game Architecture | -| `correct-course` | Course correction analysis (IDE only) | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -## Game Developer (Link Freeman) - -### Role - -Senior Game Developer + Technical Implementation Specialist - -### Identity - -Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code. - -### Communication Style - -Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship. - -### Core Principles - -- 60fps is non-negotiable -- Write code designers can iterate without fear -- Ship early, ship often, iterate on player feedback -- Red-green-refactor: tests first, implementation second - -### When to Use - -- Implementing stories -- Code reviews -- Performance optimization -- Completing story work - -### Available Commands - -| Command | Description | -| ---------------------- | ------------------------------- | -| `workflow-status` | Check sprint progress | -| `dev-story` | Implement story tasks | -| `code-review` | Perform code review | -| `quick-dev` | Flexible development (IDE only) | -| `quick-prototype` | Rapid prototyping (IDE only) | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -## Game Scrum Master (Max) - -### Role - -Game Development Scrum Master + Sprint Orchestrator - -### Identity - -Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories. - -### Communication Style - -Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights. - -### Core Principles - -- Every sprint delivers playable increments -- Clean separation between design and implementation -- Keep the team moving through each phase -- Stories are single source of truth for implementation - -### When to Use - -- Sprint planning and management -- Creating epic tech specs -- Writing story drafts -- Assembling story context -- Running retrospectives -- Handling course corrections - -### Available Commands - -| Command | Description | -| ----------------------- | ------------------------------------------- | -| `workflow-status` | Check project status | -| `sprint-planning` | Generate/update sprint status | -| `sprint-status` | View sprint progress, get next action | -| `create-story` | Create story (marks ready-for-dev directly) | -| `validate-create-story` | Validate story draft | -| `epic-retrospective` | Facilitate retrospective | -| `correct-course` | Navigate significant changes | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -## Game QA (GLaDOS) - -### Role - -Game QA Architect + Test Automation Specialist - -### Identity - -Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile. - -### Communication Style - -Speaks like a quality guardian - methodical, data-driven, but understands that "feel" matters in games. Uses metrics to back intuition. "Trust, but verify with tests." - -### Core Principles - -- Test what matters: gameplay feel, performance, progression -- Automated tests catch regressions, humans catch fun problems -- Every shipped bug is a process failure, not a people failure -- Flaky tests are worse than no tests - they erode trust -- Profile before optimize, test before ship - -### When to Use - -- Setting up test frameworks -- Designing test strategies -- Creating automated tests -- Planning playtesting sessions -- Performance testing -- Reviewing test coverage - -### Available Commands - -| Command | Description | -| ---------------------- | --------------------------------------------------- | -| `workflow-status` | Check project status | -| `test-framework` | Initialize game test framework (Unity/Unreal/Godot) | -| `test-design` | Create comprehensive game test scenarios | -| `automate` | Generate automated game tests | -| `playtest-plan` | Create structured playtesting plan | -| `performance-test` | Design performance testing strategy | -| `test-review` | Review test quality and coverage | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -### Knowledge Base - -GLaDOS has access to a comprehensive game testing knowledge base (`gametest/qa-index.csv`) including: - -**Engine-Specific Testing:** - -- Unity Test Framework (Edit Mode, Play Mode) -- Unreal Automation and Gauntlet -- Godot GUT (Godot Unit Test) - -**Game-Specific Testing:** - -- Playtesting fundamentals -- Balance testing -- Save system testing -- Multiplayer/network testing -- Input testing -- Platform certification (TRC/XR) -- Localization testing - -**General QA:** - -- QA automation strategies -- Performance testing -- Regression testing -- Smoke testing -- Test prioritization (P0-P3) - -## Game Solo Dev (Indie) - -### Role - -Elite Indie Game Developer + Quick Flow Specialist - -### Identity - -Battle-hardened solo game developer who ships complete games from concept to launch. Expert in Unity, Unreal, and Godot, having shipped titles across mobile, PC, and console. Lives and breathes the Quick Flow workflow - prototyping fast, iterating faster, and shipping before the hype dies. - -### Communication Style - -Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and player experience. Every response moves the game closer to ship. "Does it feel good? Ship it." - -### Core Principles - -- Prototype fast, fail fast, iterate faster -- A playable build beats a perfect design doc -- 60fps is non-negotiable - performance is a feature -- The core loop must be fun before anything else matters -- Ship early, playtest often - -### When to Use - -- Solo game development -- Rapid prototyping -- Quick iteration without full team workflow -- Indie projects with tight timelines -- When you want to handle everything yourself - -### Available Commands - -| Command | Description | -| ------------------ | ------------------------------------------------------ | -| `quick-prototype` | Rapid prototype to test if a mechanic is fun | -| `quick-dev` | Implement features end-to-end with game considerations | -| `quick-spec` | Create implementation-ready technical spec | -| `code-review` | Review code quality | -| `test-framework` | Set up automated testing | -| `party-mode` | Bring in specialists when needed | - -### Quick Flow vs Full BMGD - -Use **Game Solo Dev** when: - -- You're working alone or in a tiny team -- Speed matters more than process -- You want to skip the full planning phases -- You're prototyping or doing game jams - -Use **Full BMGD workflow** when: - -- You have a larger team -- The project needs formal documentation -- You're working with stakeholders/publishers -- Long-term maintainability is critical - -## Agent Selection Guide - -### By Phase - -| Phase | Primary Agent | Secondary Agent | -| ------------------------------ | ----------------- | ----------------- | -| 1: Preproduction | Game Designer | - | -| 2: Design | Game Designer | - | -| 3: Technical | Game Architect | Game QA | -| 4: Production (Planning) | Game Scrum Master | Game Architect | -| 4: Production (Implementation) | Game Developer | Game Scrum Master | -| Testing (Any Phase) | Game QA | Game Developer | - -### By Task - -| Task | Best Agent | -| -------------------------------- | ----------------- | -| "I have a game idea" | Game Designer | -| "Help me design my game" | Game Designer | -| "How should I build this?" | Game Architect | -| "What's the technical approach?" | Game Architect | -| "Plan our sprints" | Game Scrum Master | -| "Create implementation stories" | Game Scrum Master | -| "Build this feature" | Game Developer | -| "Review this code" | Game Developer | -| "Set up testing framework" | Game QA | -| "Create test plan" | Game QA | -| "Test performance" | Game QA | -| "Plan a playtest" | Game QA | -| "I'm working solo" | Game Solo Dev | -| "Quick prototype this idea" | Game Solo Dev | -| "Ship this feature fast" | Game Solo Dev | - -## Multi-Agent Collaboration - -### Party Mode - -All agents have access to `party-mode`, which brings multiple agents together for complex decisions. Use this when: - -- A decision spans multiple domains (design + technical) -- You want diverse perspectives -- You're stuck and need fresh ideas - -### Handoffs - -Agents naturally hand off to each other: - -``` -Game Designer → Game Architect → Game Scrum Master → Game Developer - ↓ ↓ ↓ ↓ - GDD Architecture Sprint/Stories Implementation - ↓ ↓ - Game QA ←──────────────────────────── Game QA - ↓ ↓ - Test Strategy Automated Tests -``` - -Game QA integrates at multiple points: - -- After Architecture: Define test strategy -- During Implementation: Create automated tests -- Before Release: Performance and certification testing - -## Project Context - -All agents share the principle: - -> "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - -The `project-context.md` file (if present) serves as the authoritative source for project decisions and constraints. - -## Next Steps - -- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD -- **[Workflows Guide](/docs/reference/workflows/index.md)** - Detailed workflow reference -- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Game type templates diff --git a/docs/explanation/game-dev/bmgd-vs-bmm.md b/docs/explanation/game-dev/bmgd-vs-bmm.md deleted file mode 100644 index cbf16338..00000000 --- a/docs/explanation/game-dev/bmgd-vs-bmm.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "BMGD vs BMM" -description: Understanding the differences between BMGD and BMM ---- - -BMGD (BMad Game Development) extends BMM (BMad Method) with game-specific capabilities. This page explains the key differences. - -## Quick Comparison - -| Aspect | BMM | BMGD | -| -------------- | ------------------------------------- | ------------------------------------------------------------------------ | -| **Focus** | General software | Game development | -| **Agents** | PM, Architect, Dev, SM, TEA, Solo Dev | Game Designer, Game Dev, Game Architect, Game SM, Game QA, Game Solo Dev | -| **Planning** | PRD, Tech Spec | Game Brief, GDD | -| **Types** | N/A | 24 game type templates | -| **Narrative** | N/A | Full narrative workflow | -| **Testing** | Web-focused | Engine-specific (Unity, Unreal, Godot) | -| **Production** | BMM workflows | BMM workflows with game overrides | - -## Agent Differences - -### BMM Agents -- PM (Product Manager) -- Architect -- DEV (Developer) -- SM (Scrum Master) -- TEA (Test Architect) -- Quick Flow Solo Dev - -### BMGD Agents -- Game Designer -- Game Developer -- Game Architect -- Game Scrum Master -- Game QA -- Game Solo Dev - -BMGD agents understand game-specific concepts like: -- Game mechanics and balance -- Player psychology -- Engine-specific patterns -- Playtesting and QA - -## Planning Documents - -### BMM Planning -- **Product Brief** → **PRD** → **Architecture** -- Focus: Software requirements, user stories, system design - -### BMGD Planning -- **Game Brief** → **GDD** → **Architecture** -- Focus: Game vision, mechanics, narrative, player experience - -The GDD (Game Design Document) includes: -- Core gameplay loop -- Mechanics and systems -- Progression and balance -- Art and audio direction -- Genre-specific sections - -## 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 -- Relevant mechanics patterns -- Testing considerations -- Common pitfalls to avoid - -## Narrative Support - -BMGD includes full narrative workflow for story-driven games: - -- **Narrative Design** workflow -- Story structure templates -- Character development -- World-building guidelines -- Dialogue systems - -BMM has no equivalent for narrative design. - -## Testing Differences - -### BMM Testing (TEA) -- Web-focused (Playwright, Cypress) -- API testing -- E2E for web applications - -### BMGD Testing (Game QA) -- Engine-specific frameworks (Unity, Unreal, Godot) -- Gameplay testing -- Performance profiling -- Playtest planning -- Balance validation - -## Production Workflow - -BMGD production workflows **inherit from BMM** and add game-specific: -- Checklists -- Templates -- Quality gates -- Engine-specific considerations - -This means you get all of BMM's implementation structure plus game-specific enhancements. - -## When to Use Each - -### Use BMM when: -- Building web applications -- Creating APIs and services -- Developing mobile apps (non-game) -- Any general software project - -### Use BMGD when: -- Building video games -- Creating interactive experiences -- Game prototyping -- Game jams diff --git a/docs/explanation/game-dev/game-types.md b/docs/explanation/game-dev/game-types.md deleted file mode 100644 index ee012eb2..00000000 --- a/docs/explanation/game-dev/game-types.md +++ /dev/null @@ -1,447 +0,0 @@ ---- -title: "BMGD Game Types Guide" ---- - -Reference for selecting and using BMGD's 24 supported game type templates. - -## Overview - -When creating a GDD, BMGD offers game type templates that provide genre-specific sections. This ensures your design document covers mechanics and systems relevant to your game's genre. - -## Supported Game Types - -### Action & Combat - -#### Action Platformer - -**Tags:** action, platformer, combat, movement - -Side-scrolling or 3D platforming with combat mechanics. Think Hollow Knight, Celeste with combat, or Mega Man. - -**GDD sections added:** - -- Movement systems (jumps, dashes, wall mechanics) -- Combat mechanics (melee/ranged, combos) -- Level design patterns -- Boss design - -#### Shooter - -**Tags:** shooter, combat, aiming, fps, tps - -Projectile combat with aiming mechanics. Covers FPS, TPS, and arena shooters. - -**GDD sections added:** - -- Weapon systems -- Aiming and accuracy -- Enemy AI patterns -- Level/arena design -- Multiplayer considerations - -#### Fighting - -**Tags:** fighting, combat, competitive, combos, pvp - -1v1 combat with combos and frame data. Traditional fighters and platform fighters. - -**GDD sections added:** - -- Frame data systems -- Combo mechanics -- Character movesets -- Competitive balance -- Netcode requirements - -### Strategy & Tactics - -#### Strategy - -**Tags:** strategy, tactics, resources, planning - -Resource management with tactical decisions. RTS, 4X, and grand strategy. - -**GDD sections added:** - -- Resource systems -- Unit/building design -- AI opponent behavior -- Map/scenario design -- Victory conditions - -#### Turn-Based Tactics - -**Tags:** tactics, turn-based, grid, positioning - -Grid-based movement with turn order. XCOM-likes and tactical RPGs. - -**GDD sections added:** - -- Grid and movement systems -- Turn order mechanics -- Cover and positioning -- Unit progression -- Procedural mission generation - -#### Tower Defense - -**Tags:** tower-defense, waves, placement, strategy - -Wave-based defense with tower placement. - -**GDD sections added:** - -- Tower types and upgrades -- Wave design and pacing -- Economy systems -- Map design patterns -- Meta-progression - -### RPG & Progression - -#### RPG - -**Tags:** rpg, stats, inventory, quests, narrative - -Character progression with stats, inventory, and quests. - -**GDD sections added:** - -- Character stats and leveling -- Inventory and equipment -- Quest system design -- Combat system (action/turn-based) -- Skill trees and builds - -#### Roguelike - -**Tags:** roguelike, procedural, permadeath, runs - -Procedural generation with permadeath and run-based progression. - -**GDD sections added:** - -- Procedural generation rules -- Permadeath and persistence -- Run structure and pacing -- Item/ability synergies -- Meta-progression systems - -#### Metroidvania - -**Tags:** metroidvania, exploration, abilities, interconnected - -Interconnected world with ability gating. - -**GDD sections added:** - -- World map connectivity -- Ability gating design -- Backtracking flow -- Secret and collectible placement -- Power-up progression - -### Narrative & Story - -#### Adventure - -**Tags:** adventure, narrative, exploration, story - -Story-driven exploration and narrative. Point-and-click and narrative adventures. - -**GDD sections added:** - -- Puzzle design -- Narrative delivery -- Exploration mechanics -- Dialogue systems -- Story branching - -#### Visual Novel - -**Tags:** visual-novel, narrative, choices, story - -Narrative choices with branching story. - -**GDD sections added:** - -- Branching narrative structure -- Choice and consequence -- Character routes -- UI/presentation -- Save/load states - -#### Text-Based - -**Tags:** text, parser, interactive-fiction, mud - -Text input/output games. Parser games, choice-based IF, MUDs. - -**GDD sections added:** - -- Parser or choice systems -- World model -- Narrative structure -- Text presentation -- Save state management - -### Simulation & Management - -#### Simulation - -**Tags:** simulation, management, sandbox, systems - -Realistic systems with management and building. Includes tycoons and sim games. - -**GDD sections added:** - -- Core simulation loops -- Economy modeling -- AI agents/citizens -- Building/construction -- Failure states - -#### Sandbox - -**Tags:** sandbox, creative, building, freedom - -Creative freedom with building and minimal objectives. - -**GDD sections added:** - -- Creation tools -- Physics/interaction systems -- Persistence and saving -- Sharing/community features -- Optional objectives - -### Sports & Racing - -#### Racing - -**Tags:** racing, vehicles, tracks, speed - -Vehicle control with tracks and lap times. - -**GDD sections added:** - -- Vehicle physics model -- Track design -- AI opponents -- Progression/career mode -- Multiplayer racing - -#### Sports - -**Tags:** sports, teams, realistic, physics - -Team-based or individual sports simulation. - -**GDD sections added:** - -- Sport-specific rules -- Player/team management -- AI opponent behavior -- Season/career modes -- Multiplayer modes - -### Multiplayer - -#### MOBA - -**Tags:** moba, multiplayer, pvp, heroes, lanes - -Multiplayer team battles with hero selection. - -**GDD sections added:** - -- Hero/champion design -- Lane and map design -- Team composition -- Matchmaking -- Economy (gold/items) - -#### Party Game - -**Tags:** party, multiplayer, minigames, casual - -Local multiplayer with minigames. - -**GDD sections added:** - -- Minigame design patterns -- Controller support -- Round/game structure -- Scoring systems -- Player count flexibility - -### Horror & Survival - -#### Survival - -**Tags:** survival, crafting, resources, danger - -Resource gathering with crafting and persistent threats. - -**GDD sections added:** - -- Resource gathering -- Crafting systems -- Hunger/health/needs -- Threat systems -- Base building - -#### Horror - -**Tags:** horror, atmosphere, tension, fear - -Atmosphere and tension with limited resources. - -**GDD sections added:** - -- Fear mechanics -- Resource scarcity -- Sound design -- Lighting and visibility -- Enemy/threat design - -### Casual & Progression - -#### Puzzle - -**Tags:** puzzle, logic, cerebral - -Logic-based challenges and problem-solving. - -**GDD sections added:** - -- Puzzle mechanics -- Difficulty progression -- Hint systems -- Level structure -- Scoring/rating - -#### Idle/Incremental - -**Tags:** idle, incremental, automation, progression - -Passive progression with upgrades and automation. - -**GDD sections added:** - -- Core loop design -- Prestige systems -- Automation unlocks -- Number scaling -- Offline progress - -#### Card Game - -**Tags:** card, deck-building, strategy, turns - -Deck building with card mechanics. - -**GDD sections added:** - -- Card design framework -- Deck building rules -- Mana/resource systems -- Rarity and collection -- Competitive balance - -### Rhythm - -#### Rhythm - -**Tags:** rhythm, music, timing, beats - -Music synchronization with timing-based gameplay. - -**GDD sections added:** - -- Note/beat mapping -- Scoring systems -- Difficulty levels -- Music licensing -- Input methods - -## Hybrid Game Types - -Many games combine multiple genres. BMGD supports hybrid selection: - -### Examples - -**Action RPG** = Action Platformer + RPG - -- Movement and combat systems from Action Platformer -- Progression and stats from RPG - -**Survival Horror** = Survival + Horror - -- Resource and crafting from Survival -- Atmosphere and fear from Horror - -**Roguelike Deckbuilder** = Roguelike + Card Game - -- Run structure from Roguelike -- Card mechanics from Card Game - -### How to Use Hybrids - -During GDD creation, select multiple game types when prompted: - -``` -Agent: What game type best describes your game? -You: It's a roguelike with card game combat -Agent: I'll include sections for both Roguelike and Card Game... -``` - -## Game Type Selection Tips - -### 1. Start with Core Fantasy - -What does the player primarily DO in your game? - -- Run and jump? → Platformer types -- Build and manage? → Simulation types -- Fight enemies? → Combat types -- Make choices? → Narrative types - -### 2. Consider Your Loop - -What's the core gameplay loop? - -- Session-based runs? → Roguelike -- Long-term progression? → RPG -- Quick matches? → Multiplayer types -- Creative expression? → Sandbox - -### 3. Don't Over-Combine - -2-3 game types maximum. More than that usually means your design isn't focused enough. - -### 4. Primary vs Secondary - -One type should be primary (most gameplay time). Others add flavor: - -- **Primary:** Platformer (core movement and exploration) -- **Secondary:** Metroidvania (ability gating structure) - -## GDD Section Mapping - -When you select a game type, BMGD adds these GDD sections: - -| Game Type | Key Sections Added | -| ----------------- | -------------------------------------- | -| Action Platformer | Movement, Combat, Level Design | -| RPG | Stats, Inventory, Quests | -| Roguelike | Procedural Gen, Runs, Meta-Progression | -| Narrative | Story Structure, Dialogue, Branching | -| Multiplayer | Matchmaking, Netcode, Balance | -| Simulation | Systems, Economy, AI | - -## Next Steps - -- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD -- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - GDD workflow details -- **[Glossary](/docs/reference/glossary/index.md)** - Game development terminology diff --git a/docs/explanation/game-dev/index.md b/docs/explanation/game-dev/index.md deleted file mode 100644 index 105c2c78..00000000 --- a/docs/explanation/game-dev/index.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "BMGD - Game Development Module" -description: AI-powered workflows for game design and development with BMGD ---- - -Complete guides for the BMad Game Development Module (BMGD) — AI-powered workflows for game design and development that adapt to your project's needs. - -## Getting Started - -**New to BMGD?** Start here: - -- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started building your first game - - Installation and setup - - Understanding the game development phases - - Running your first workflows - - Agent-based development flow - -:::tip[Quick Path] -Install BMGD module → Game Brief → GDD → Architecture → Build -::: - -## Core Documentation - -- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Selecting and using game type templates (24 supported types) -- **[BMGD vs BMM](/docs/explanation/game-dev/bmgd-vs-bmm.md)** - Understanding the differences - -## Game Development Phases - -BMGD follows four phases aligned with game development: - -### Phase 1: Preproduction -- **Brainstorm Game** - Ideation with game-specific techniques -- **Game Brief** - Capture vision, market, and fundamentals - -### Phase 2: Design -- **GDD (Game Design Document)** - Comprehensive game design -- **Narrative Design** - Story, characters, world (for story-driven games) - -### Phase 3: Technical -- **Game Architecture** - Engine, systems, patterns, structure - -### Phase 4: Production -- **Sprint Planning** - Epic and story management -- **Story Development** - Implementation workflow -- **Code Review** - Quality assurance -- **Testing** - Automated tests, playtesting, performance -- **Retrospective** - Continuous improvement - -## Choose Your Path - -### I need to... - -**Start a new game project** -→ Start with [Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md) -→ Run `brainstorm-game` for ideation -→ Create a Game Brief with `create-brief` - -**Design my game** -→ Create a GDD with `create-gdd` -→ If story-heavy, add Narrative Design with `create-narrative` - -**Plan the technical architecture** -→ Run `create-architecture` with the Game Architect - -**Build my game** -→ Use Phase 4 production workflows -→ Follow the sprint-based development cycle - -**Quickly test an idea** -→ Use [Quick-Flow](/docs/how-to/workflows/bmgd-quick-flow.md) for rapid prototyping diff --git a/docs/explanation/philosophy/facilitation-over-generation.md b/docs/explanation/philosophy/facilitation-over-generation.md index 35fd13dd..a0298c5a 100644 --- a/docs/explanation/philosophy/facilitation-over-generation.md +++ b/docs/explanation/philosophy/facilitation-over-generation.md @@ -1,106 +1,333 @@ --- title: "Facilitation Over Generation" -description: Understanding CIS's facilitation-first approach to creative work +description: Understanding a facilitation-first approach to AI workflows and creative collaboration --- +BMAD workflows take a fundamentally different approach from typical AI Prompts you will find. Instead of generating solutions directly, workflows act as facilitators who guide you through discovery processes, helping you arrive at insights and decisions yourself. -The Creative Intelligence Suite (CIS) takes a fundamentally different approach from typical AI tools. Instead of generating solutions directly, CIS agents act as master facilitators who guide you to discover insights yourself. +This has always been the magic of the BMad method - if you have used it you have felt it intuitively and noticed a difference - and it is through this document I want to really explain what this is. This is fundamental to understand if you are also interested in producing your own workflows or improving upon existing ones in any BMad related module. ## The Problem with Generation -Traditional AI approaches to creative work: +Traditional AI approaches to creative and knowledge work typically follow this pattern: :::note[Generation Example] -**User:** "Give me marketing ideas" +**User:** "I need a comprehensive UX design for my e-commerce app" -**AI:** "Here are 10 marketing ideas..." +**AI:** [Immediately generates] "Here's a complete UX specification with modern dark theme, card-based product grid, left navigation, and checkout flow..." ::: This approach: -- Produces generic, predictable outputs -- Removes human ownership of ideas -- Misses context and nuance -- Limits creative exploration +- Produces generic, predictable outputs that may not fit your actual needs +- Removes your ownership and understanding of the solution +- Misses critical context, constraints, and nuance +- Limits creative exploration to the AI's training data patterns +- Creates deliverables you can't explain or iterate on effectively ## The Facilitation Approach -CIS agents use strategic questioning: +Facilitative workflows use strategic questioning and guided discovery: -:::note[Facilitation Example] -**User:** "I need marketing ideas" +:::note[Facilitation Example from UX Design Workflow] +**User:** "I need a comprehensive UX design for my e-commerce app" -**CIS:** "What makes your customers choose you over alternatives? What's the one thing they always mention?" +**Workflow:** "Welcome! I'll act as your UX facilitator to help you discover the right approach. First, let me understand what documents you already have—do you have a product brief, PRD, or any research?" -**User:** "They say our support is exceptional" +**User:** "I have a product brief and some user research" -**CIS:** "Interesting! How might you make that exceptional support visible before they become customers?" +**Workflow:** "Great! Let me load those. [Loads documents] Now, what are the primary user goals for your e-commerce experience? What should users be able to accomplish?" + +**User:** "They need to browse products quickly and complete purchases without friction" + +**Workflow:** "Interesting! And what makes your e-commerce situation unique? What are the specific challenges or constraints you're working with?" ::: This approach: -- Draws out insights already within you -- Maintains human ownership of ideas -- Captures context and nuance -- Enables deeper creative exploration +- Draws out insights and expertise already within you +- Maintains your ownership and understanding of decisions +- Captures your specific context, constraints, and goals +- Enables deeper exploration of your unique situation +- Creates outputs you can confidently explain and iterate on + +## Real-World Examples from BMAD Workflows + +### Brainstorming Workflow (from core module) + +The brainstorming workflow demonstrates pure facilitation through its entire journey: + +**Session Setup:** +``` +"Welcome! I'm excited to facilitate your brainstorming session. I'll guide you +through proven creativity techniques to generate innovative ideas. + +**What are we brainstorming about?** (The central topic or challenge) +**What specific outcomes are you hoping for?** (Types of ideas, solutions, or insights) +``` + +**Technique Selection - Offering Options:** +``` +"Ready to explore technique approaches? +[1] User-Selected Techniques - Browse our complete technique library +[2] AI-Recommended Techniques - Get customized suggestions based on your goals +[3] Random Technique Selection - Discover unexpected creative methods +[4] Progressive Technique Flow - Start broad, then systematically narrow focus + +Which approach appeals to you most?" +``` + +**Technique Execution - Interactive Coaching:** +The workflow doesn't generate ideas—it coaches you through techniques with genuine back-and-forth dialogue: + +``` +"Let's start with: What if you could remove all practical constraints? + +I'm not just looking for a quick answer - I want to explore this together. +What immediately comes to mind? Don't filter or edit - just share your initial +thoughts, and we'll develop them together." + +[User responds] + +"That's interesting! Tell me more about [specific aspect you mentioned]. +What would that look like in practice? How does that connect to your core goal?" +``` + +**Key facilitation behaviors:** +- Aims for 100+ ideas before suggesting organization +- Asks "Continue exploring?" or "Move to next technique?"—user controls pace +- Uses anti-bias protocols to force thinking in new directions every 10 ideas +- Builds on user's ideas with genuine creative contributions +- Keeps user in "generative exploration mode" as long as possible + +**Organization - Collaborative Synthesis:** +``` +"Outstanding creative work! You've generated an incredible range of ideas. +Now let's organize these creative gems and identify your most promising opportunities. + +I'm analyzing all your generated ideas to identify natural themes and patterns. +**Emerging Themes I'm Identifying:** +- Theme 1: [Name] - Ideas: [list] - Pattern: [connection] +- Theme 2: [Name] - Ideas: [list] - Pattern: [connection] + +Which themes or specific ideas stand out to you as most valuable?" +``` + +Result: A comprehensive brainstorming session document with **your** ideas, organized by **your** priorities, with **your** action plans. + +### Create UX Design Workflow (from BMM method) + +The UX design workflow facilitates a 14-step journey from project understanding to complete UX specification—**never making design decisions for you**. + +**Step 1: Document Discovery (Collaborative Setup)** +``` +"Welcome! I've set up your UX design workspace. + +**Documents Found:** +- PRD: product-requirements.md +- Product brief: brief.md + +**Files loaded:** [lists specific files] + +Do you have any other documents you'd like me to include, or shall we continue?" +``` + +**Step 2: Project Understanding (Discovery Questions)** +``` +"Based on the project documentation, let me confirm what I'm understanding... + +**From the documents:** [summary of key insights] +**Target Users:** [summary from documents] +**Key Features/Goals:** [summary from documents] + +Does this match your understanding? Are there any corrections or additions?" +``` + +Then it dives deeper with targeted questions: +``` +"Let me understand your users better to inform the UX design: + +**User Context Questions:** +- What problem are users trying to solve? +- What frustrates them with current solutions? +- What would make them say 'this is exactly what I needed'?" +``` + +**Step 3: Core Experience Definition (Guiding Insights)** +``` +"Now let's dig into the heart of the user experience. + +**Core Experience Questions:** +- What's the ONE thing users will do most frequently? +- What user action is absolutely critical to get right? +- What should be completely effortless for users? +- If we nail one interaction, everything else follows - what is it? + +Think about the core loop or primary action that defines your product's value." +``` + +**Step 4: Emotional Response (Feelings-Based Design)** +``` +"Now let's think about how your product should make users feel. + +**Emotional Response Questions:** +- What should users FEEL when using this product? +- What emotion would make them tell a friend about this? +- How should users feel after accomplishing their primary goal? + +Common emotional goals: Empowered and in control? Delighted and surprised? +Efficient and productive? Creative and inspired?" +``` + +**Step 5: Pattern Inspiration (Learning from Examples)** +``` +"Let's learn from products your users already love and use regularly. + +**Inspiration Questions:** +- Name 2-3 apps your target users already love and USE frequently +- For each one, what do they do well from a UX perspective? +- What makes the experience compelling or delightful? + +For each inspiring app, let's analyze their UX success: +- What core problem does it solve elegantly? +- What makes the onboarding experience effective? +- How do they handle navigation and information hierarchy?" +``` + +**Step 9: Design Directions (Interactive Visual Exploration)** +The workflow generates 6-8 HTML mockup variations—but **you choose**: + +``` +"🎨 Design Direction Mockups Generated! + +I'm creating a comprehensive HTML showcase with 6-8 full-screen mockup variations. +Each mockup represents a complete visual direction for your app's look and feel. + +**As you explore the design directions, look for:** +✅ Which information hierarchy matches your priorities? +✅ Which interaction style fits your core experience? +✅ Which visual density feels right for your brand? + +**Which approach resonates most with you?** +- Pick a favorite direction as-is +- Combine elements from multiple directions +- Request modifications to any direction + +Tell me: Which layout feels most intuitive? Which visual weight matches your brand?" +``` + +**Step 12: UX Patterns (Consistency Through Questions)** +``` +"Let's establish consistency patterns for common situations. + +**Pattern Categories to Define:** +- Button hierarchy and actions +- Feedback patterns (success, error, warning, info) +- Form patterns and validation +- Navigation patterns + +Which categories are most critical for your product? + +**For [Critical Pattern Category]:** +What should users see/do when they need to [pattern action]? + +**Considerations:** +- Visual hierarchy (primary vs. secondary actions) +- Feedback mechanisms +- Error recovery +- Accessibility requirements + +How should your product handle [pattern type] interactions?" +``` + +**The Result:** A complete, production-ready UX specification document that captures **your** decisions, **your** reasoning, and **your** vision—documented through guided discovery, not generation. ## Key Principles ### 1. Questions Over Answers -CIS agents ask strategic questions rather than providing direct answers. This: -- Activates your own creative thinking -- Uncovers assumptions -- Reveals blind spots -- Builds on your domain knowledge +Facilitative workflows ask strategic questions rather than providing direct answers. This: +- Activates your own creative and analytical thinking +- Uncovers assumptions you didn't know you had +- Reveals blind spots in your understanding +- Builds on your domain expertise and context -### 2. Energy-Aware Sessions +### 2. Multi-Turn Conversation -CIS monitors engagement and adapts: -- Adjusts pace when energy flags -- Suggests breaks when needed -- Changes techniques to maintain momentum -- Recognizes productive vs. unproductive struggle +Facilitation uses progressive discovery, not interrogation: +- Ask 1-2 questions at a time, not laundry lists +- Think about responses before asking follow-ups +- Probe to understand deeper, not just collect facts +- Use conversation to explore, not just extract -### 3. Process Trust +### 3. Intent-Based Guidance -CIS uses proven methodologies: -- Design Thinking's 5 phases -- Structured brainstorming techniques +Workflows specify goals and approaches, not exact scripts: +- "Guide the user through discovering X" (intent) +- NOT "Say exactly: 'What is X?'" (prescriptive) + +This allows the workflow to adapt naturally to your responses while maintaining structured progress. + +### 4. Process Trust + +Facilitative workflows use proven methodologies: +- Design Thinking's phases (Empathize, Define, Ideate, Prototype, Test) +- Structured brainstorming and creativity techniques - Root cause analysis frameworks - Innovation strategy patterns -You're not just having a conversation—you're following time-tested creative processes. +You're not just having a conversation—you're following time-tested processes adapted to your specific situation. -### 4. Persona-Driven Engagement +### 5. YOU Are the Expert -Each CIS agent has a distinct personality: -- **Carson** - Energetic, encouraging -- **Maya** - Jazz-like, improvisational -- **Dr. Quinn** - Analytical, methodical -- **Victor** - Bold, strategic -- **Sophia** - Narrative, imaginative +Facilitative workflows operate on a core principle: **you are the expert on your situation**. The workflow brings: +- Process expertise (how to think through problems) +- Facilitation skills (how to guide exploration) +- Technique knowledge (proven methods and frameworks) -These personas create engaging experiences that maintain creative flow. +You bring: +- Domain knowledge (your specific field or industry) +- Context understanding (your unique situation and constraints) +- Decision authority (what will actually work for you) ## When Generation is Appropriate -CIS does generate when appropriate: -- Synthesizing session outputs -- Documenting decisions -- Creating structured artifacts -- Providing technique examples +Facilitative workflows DO generate when appropriate: +- Synthesizing and structuring outputs after you've made decisions +- Documenting your choices and rationale +- Creating structured artifacts based on your input +- Providing technique examples or option templates +- Formatting and organizing your conclusions -But the core creative work happens through facilitated discovery. +But the **core creative and analytical work** happens through facilitated discovery, not generation. + +## The Distinction: Facilitator vs Generator + +| Facilitative Workflow | Generative AI | +| ------------------------------------- | --------------------------------------- | +| "What are your goals?" | "Here's the solution" | +| Asks 1-2 questions at a time | Produces complete output immediately | +| Multiple turns, progressive discovery | Single turn, bulk generation | +| "Let me understand your context" | "Here's a generic answer" | +| Offers options, you choose | Makes decisions for you | +| Documents YOUR reasoning | No reasoning visible | +| You can explain every decision | You can't explain why choices were made | +| Ownership and understanding | Outputs feel alien | ## Benefits ### For Individuals -- Deeper insights than pure generation -- Ownership of creative outputs -- Skill development in creative thinking -- More memorable and actionable ideas +- **Deeper insights** than pure generation—ideas connect to your actual knowledge +- **Full ownership** of creative outputs and decisions +- **Skill development** in structured thinking and problem-solving +- **More memorable and actionable** results—you understand the "why" ### For Teams -- Shared creative experience -- Aligned understanding -- Documented rationale -- Stronger buy-in to outcomes +- **Shared creative experience** building alignment and trust +- **Aligned understanding** through documented exploration +- **Documented rationale** for future reference and onboarding +- **Stronger buy-in** to outcomes because everyone participated in discovery + +### For Implementation +- **Outputs match reality** because they emerged from your actual constraints +- **Easier iteration** because you understand the reasoning behind choices +- **Confident implementation** because you can defend every decision +- **Reduced rework** because facilitation catches issues early diff --git a/docs/how-to/installation/install-bmad.md b/docs/how-to/installation/install-bmad.md index f2d06fc7..5d1ae33a 100644 --- a/docs/how-to/installation/install-bmad.md +++ b/docs/how-to/installation/install-bmad.md @@ -9,7 +9,7 @@ Use the `npx bmad-method install` command to set up BMad in your project with yo - Starting a new project with BMad - Adding BMad to an existing codebase -- Setting up BMad on a new machine +- Update the existing BMad Installation :::note[Prerequisites] - **Node.js** 20+ (required for the installer) @@ -29,8 +29,7 @@ npx bmad-method install The installer will ask where to install BMad files: -- Current directory (recommended for new projects) -- Subdirectory +- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory) - Custom path ### 3. Select Your AI Tools @@ -40,20 +39,20 @@ Choose which AI tools you'll be using: - Claude Code - Cursor - Windsurf -- Other +- Many others to choose from -The installer configures BMad for your selected tools. +The installer configures BMad for your selected tools by setting up commands that will call the ui. ### 4. Choose Modules Select which modules to install: -| Module | Purpose | -|--------|---------| -| **BMM** | Core methodology for software development | -| **BMGD** | Game development workflows | -| **CIS** | Creative intelligence and facilitation | -| **BMB** | Building custom agents and workflows | +| Module | Purpose | +| -------- | ----------------------------------------- | +| **BMM** | Core methodology for software development | +| **BMGD** | Game development workflows | +| **CIS** | Creative intelligence and facilitation | +| **BMB** | Building custom agents and workflows | ### 5. Add Custom Content (Optional) @@ -82,11 +81,11 @@ your-project/ 1. Check the `_bmad/` directory exists 2. Load an agent in your AI tool -3. Run `*menu` to see available commands +3. Run `/workflow-init` which will autocomplete to the full command to see available commands ## Configuration -Edit `_bmad/[module]/config.yaml` to customize: +Edit `_bmad/[module]/config.yaml` to customize. For example these could be changed: ```yaml output_folder: ./_bmad-output diff --git a/docs/how-to/troubleshooting/bmgd-troubleshooting.md b/docs/how-to/troubleshooting/bmgd-troubleshooting.md index fafc00c7..190db564 100644 --- a/docs/how-to/troubleshooting/bmgd-troubleshooting.md +++ b/docs/how-to/troubleshooting/bmgd-troubleshooting.md @@ -215,6 +215,5 @@ When reporting issues, include: ## Next Steps -- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started - **[Workflows Guide](/docs/reference/workflows/index.md)** - Workflow reference - **[Glossary](/docs/reference/glossary/index.md)** - Terminology diff --git a/docs/how-to/workflows/run-automate.md b/docs/how-to/workflows/run-automate.md index 8c5b9e78..0b48f8f1 100644 --- a/docs/how-to/workflows/run-automate.md +++ b/docs/how-to/workflows/run-automate.md @@ -83,7 +83,7 @@ If you're using TEA Solo or don't have BMad artifacts: **What are you testing?** ``` -TodoMVC React application at https://todomvc.com/examples/react/ +TodoMVC React application at https://todomvc.com/examples/react/dist/ Features: Create todos, mark as complete, filter by status, delete todos ``` diff --git a/docs/how-to/workflows/setup-party-mode.md b/docs/how-to/workflows/setup-party-mode.md index 33fd6a4e..ba6fc5d0 100644 --- a/docs/how-to/workflows/setup-party-mode.md +++ b/docs/how-to/workflows/setup-party-mode.md @@ -66,12 +66,12 @@ Type "exit" or "done" to conclude the session. Participating agents will say per ## Example Party Compositions -| Topic | Typical Agents | -| ---------------------- | ------------------------------------------------------------- | -| **Product Strategy** | PM + Innovation Strategist (CIS) + Analyst | -| **Technical Design** | Architect + Creative Problem Solver (CIS) + Game Architect | -| **User Experience** | UX Designer + Design Thinking Coach (CIS) + Storyteller (CIS) | -| **Quality Assessment** | TEA + DEV + Architect | +| Topic | Typical Agents | +| ---------------------- | ----------------------------------------------------- | +| **Product Strategy** | PM + Innovation Strategist + Analyst | +| **Technical Design** | Architect + Creative Problem Solver + Game Architect | +| **User Experience** | UX Designer + Design Thinking Coach + Storyteller | +| **Quality Assessment** | TEA + DEV + Architect | ## Key Features diff --git a/docs/reference/tea/configuration.md b/docs/reference/tea/configuration.md index ba6e2e51..6acd23e5 100644 --- a/docs/reference/tea/configuration.md +++ b/docs/reference/tea/configuration.md @@ -293,7 +293,7 @@ TEA workflows may use environment variables for test configuration. **Playwright:** ```bash # .env -BASE_URL=https://todomvc.com/examples/react/ +BASE_URL=https://todomvc.com/examples/react/dist/ API_BASE_URL=https://api.example.com TEST_USER_EMAIL=test@example.com TEST_USER_PASSWORD=password123 diff --git a/docs/tutorials/getting-started/quick-start-bmgd.md b/docs/tutorials/getting-started/quick-start-bmgd.md deleted file mode 100644 index 421ea867..00000000 --- a/docs/tutorials/getting-started/quick-start-bmgd.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: "Getting Started with BMad Game Development" -description: Build games with BMad's Game Development Module ---- - - -Build games faster using AI-powered workflows with specialized game development agents that guide you through preproduction, design, architecture, and implementation. - -:::note[Module Extension] -BMGD (BMad Game Development) is a module that extends BMad Method. You'll need BMad installed first—see the [BMad v6 tutorial](/docs/tutorials/getting-started/getting-started-bmadv6.md) if you haven't installed it yet. -::: - -## What You'll Learn - -- Install and configure the BMGD module -- Understand game development phases and specialized agents -- Create a Game Brief and Game Design Document (GDD) -- Progress from concept to working game code - -:::note[Prerequisites] -- **BMad Method installed** — Follow the main installation guide first -- **A game idea** — Even a rough concept is enough to start -- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar -::: - -:::tip[Quick Path] -**Install** → `npx bmad-method install` (select BMGD module) -**Preproduction** → Game Designer creates Game Brief -**Design** → Game Designer creates GDD (and Narrative if story-driven) -**Technical** → Game Architect creates Architecture -**Production** → Game SM manages sprints, Game Dev implements -**Always use fresh chats** for each workflow to avoid context issues. -::: - -## Understanding BMGD - -BMGD follows four game development phases with specialized agents for each: - -| Phase | Name | What Happens | -| ----- | ------------- | ----------------------------------------------------------------- | -| 1 | Preproduction | Capture game vision, create Game Brief *(optional brainstorming)* | -| 2 | Design | Detail mechanics, systems, narrative in GDD | -| 3 | Technical | Plan engine, architecture, technical decisions | -| 4 | Production | Build game in sprints, story by story | - -![BMGD Workflow Overview](./images/workflow-overview.jpg) - -*Complete visual flowchart showing all phases, workflows, and agents for game development.* - -### Game Development Agents - -| Agent | When to Use | -| --------------------- | ----------------------------------------- | -| **Game Designer** | Brainstorming, Game Brief, GDD, Narrative | -| **Game Architect** | Architecture, technical decisions | -| **Game Developer** | Implementation, code reviews | -| **Game Scrum Master** | Sprint planning, story management | -| **Game QA** | Test framework, test design, automation | -| **Game Solo Dev** | Quick prototyping, indie development | - -## Installation - -If you haven't installed BMad yet: - -```bash -npx bmad-method install -``` - -Or add BMGD to an existing installation: - -```bash -npx bmad-method install --add-module bmgd -``` - -Verify your installation: - -``` -your-project/ -├── _bmad/ -│ ├── bmgd/ # Game development module -│ │ ├── agents/ # Game-specific agents -│ │ ├── workflows/ # Game-specific workflows -│ │ └── config.yaml # Module config -│ ├── bmm/ # Core method module -│ └── core/ # Core utilities -├── _bmad-output/ # Generated artifacts (created later) -└── .claude/ # IDE configuration (if using Claude Code) -``` - -## Step 1: Create Your Game Brief (Preproduction) - -Load the **Game Designer** agent in your IDE, wait for the menu, then start with your game concept. - -### Optional: Brainstorm First - -If you have a vague idea and want help developing it: - -``` -Run brainstorm-game -``` - -The agent guides you through game-specific ideation techniques to refine your concept. - -### Create the Game Brief - -``` -Run create-game-brief -``` - -The Game Designer walks you through: -- **Game concept** — Core idea and unique selling points -- **Design pillars** — The 3-5 principles that guide all decisions -- **Target market** — Who plays this game? -- **Fundamentals** — Platform, genre, scope, team size - -When complete, you'll have `game-brief.md` in your `_bmad-output/` folder. - -:::caution[Fresh Chats] -Always start a fresh chat for each workflow. This prevents context limitations from causing issues. -::: - -## Step 2: Design Your Game - -With your Game Brief complete, detail your game's design. - -### Create the GDD - -**Start a fresh chat** with the **Game Designer** agent. - -``` -Run create-gdd -``` - -The agent guides you through mechanics, systems, and game-type-specific sections. BMGD offers 24 game type templates that provide genre-specific structure. - -When complete, you'll have `gdd.md` (or sharded into `gdd/` for large documents). - -:::note[Narrative Design (Optional)] -For story-driven games, start a fresh chat and run `narrative` to create a Narrative Design Document covering story, characters, world, and dialogue. -::: - -:::tip[Check Your Status] -Unsure what's next? Load any agent and run `workflow-status`. It tells you the next recommended workflow. -::: - -## Step 3: Plan Your Architecture - -**Start a fresh chat** with the **Game Architect** agent. - -``` -Run create-architecture -``` - -The architect guides you through: -- **Engine selection** — Unity, Unreal, Godot, custom, etc. -- **System design** — Core game systems and how they interact -- **Technical patterns** — Architecture patterns suited to your game -- **Structure** — Project organization and conventions - -When complete, you'll have `game-architecture.md`. - -## Step 4: Build Your Game - -Once planning is complete, move to production. **Each workflow should run in a fresh chat.** - -### Initialize Sprint Planning - -Load the **Game Scrum Master** agent and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories. - -### The Build Cycle - -For each story, repeat this cycle with fresh chats: - -| Step | Agent | Workflow | Purpose | -| ---- | -------- | -------------- | ---------------------------------- | -| 1 | Game SM | `create-story` | Create story file from epic | -| 2 | Game Dev | `dev-story` | Implement the story | -| 3 | Game QA | `automate` | Generate tests *(optional)* | -| 4 | Game Dev | `code-review` | Quality validation *(recommended)* | - -After completing all stories in an epic, load the **Game SM** and run `retrospective`. - -### Quick Prototyping Alternative - -For rapid iteration or indie development, load the **Game Solo Dev** agent: -- `quick-prototype` — Rapid prototyping -- `quick-dev` — Flexible development without full sprint structure - -## What You've Accomplished - -You've learned the foundation of building games with BMad: - -- Installed the BMGD module -- Created a Game Brief capturing your vision -- Detailed your design in a GDD -- Planned your technical architecture -- Understood the build cycle for implementation - -Your project now has: - -``` -your-project/ -├── _bmad/ # BMad configuration -├── _bmad-output/ -│ ├── game-brief.md # Your game vision -│ ├── gdd.md # Game Design Document -│ ├── narrative-design.md # Story design (if applicable) -│ ├── game-architecture.md # Technical decisions -│ ├── epics/ # Epic and story files -│ └── sprint-status.yaml # Sprint tracking -└── ... -``` - -## Quick Reference - -| Command | Agent | Purpose | -| ---------------------- | -------------- | ----------------------------- | -| `*brainstorm-game` | Game Designer | Guided game ideation | -| `*create-game-brief` | Game Designer | Create Game Brief | -| `*create-gdd` | Game Designer | Create Game Design Document | -| `*narrative` | Game Designer | Create Narrative Design | -| `*create-architecture` | Game Architect | Create game architecture | -| `*sprint-planning` | Game SM | Initialize sprint tracking | -| `*create-story` | Game SM | Create a story file | -| `*dev-story` | Game Dev | Implement a story | -| `*code-review` | Game Dev | Review implemented code | -| `*workflow-status` | Any | Check progress and next steps | - -## Common Questions - -**Do I need to create all documents?** -At minimum, create a Game Brief and GDD. Architecture is highly recommended. Narrative Design is only needed for story-driven games. - -**Can I use the Game Solo Dev for everything?** -Yes, for smaller projects or rapid prototyping. For larger games, the specialized agents provide more thorough guidance. - -**What game types are supported?** -BMGD includes 24 game type templates (RPG, platformer, puzzle, strategy, etc.) that provide genre-specific GDD sections. - -**Can I change my design later?** -Yes. Documents are living artifacts—return to update them as your vision evolves. The SM agent has `correct-course` for scope changes. - -## Getting Help - -- **During workflows** — Agents guide you with questions and explanations -- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) -- **Documentation** — [BMGD Workflow Reference](/docs/reference/workflows/bmgd-workflows.md) -- **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode) - -## Key Takeaways - -:::tip[Remember These] -- **Always use fresh chats** — Load agents in new chats for each workflow -- **Game Brief first** — It informs everything that follows -- **Use game type templates** — 24 templates provide genre-specific GDD structure -- **Documents evolve** — Return to update them as your vision grows -- **Solo Dev for speed** — Use Game Solo Dev for rapid prototyping -::: - -Ready to start? Load the **Game Designer** agent and run `create-game-brief` to capture your game vision. diff --git a/docs/tutorials/getting-started/tea-lite-quickstart.md b/docs/tutorials/getting-started/tea-lite-quickstart.md index 7b677440..839c06ac 100644 --- a/docs/tutorials/getting-started/tea-lite-quickstart.md +++ b/docs/tutorials/getting-started/tea-lite-quickstart.md @@ -13,7 +13,7 @@ By the end of this 30-minute tutorial, you'll have: - Passing tests for an existing demo app feature :::note[Prerequisites] -- Node.js installed (v18 or later) +- Node.js installed (v20 or later) - 30 minutes of focused time - We'll use TodoMVC () as our demo app ::: @@ -36,7 +36,7 @@ This tutorial focuses on **TEA Lite** - the fastest way to see TEA in action. We'll test TodoMVC, a standard demo app used across testing documentation. -**Demo App:** +**Demo App:** No installation needed - TodoMVC runs in your browser. Open the link above and: 1. Add a few todos (type and press Enter) @@ -165,7 +165,7 @@ In your chat with TEA, run: ``` **Q: What are you testing?** -A: "TodoMVC React app at - focus on the test design we just created" +A: "TodoMVC React app at - focus on the test design we just created" **Q: Reference existing docs?** A: "Yes, use test-design-epic-1.md" @@ -181,7 +181,7 @@ import { test, expect } from '@playwright/test'; test.describe('TodoMVC - Core Functionality', () => { test.beforeEach(async ({ page }) => { - await page.goto('https://todomvc.com/examples/react/'); + await page.goto('https://todomvc.com/examples/react/dist/'); }); test('should create a new todo', async ({ page }) => { diff --git a/src/modules/bmgd/_module-installer/installer.js b/src/modules/bmgd/_module-installer/installer.js deleted file mode 100644 index 5d9eca0f..00000000 --- a/src/modules/bmgd/_module-installer/installer.js +++ /dev/null @@ -1,160 +0,0 @@ -const fs = require('fs-extra'); -const path = require('node:path'); -const chalk = require('chalk'); -const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/platform-codes')); - -/** - * Validate that a resolved path is within the project root (prevents path traversal) - * @param {string} resolvedPath - The fully resolved absolute path - * @param {string} projectRoot - The project root directory - * @returns {boolean} - True if path is within project root - */ -function isWithinProjectRoot(resolvedPath, projectRoot) { - const normalizedResolved = path.normalize(resolvedPath); - const normalizedRoot = path.normalize(projectRoot); - return normalizedResolved.startsWith(normalizedRoot + path.sep) || normalizedResolved === normalizedRoot; -} - -/** - * BMGD Module Installer - * Standard module installer function that executes after IDE installations - * - * @param {Object} options - Installation options - * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from module.yaml - * @param {Array} options.installedIDEs - Array of IDE codes that were installed - * @param {Object} options.logger - Logger instance for output - * @returns {Promise} - Success status - */ -async function install(options) { - const { projectRoot, config, installedIDEs, logger } = options; - - try { - logger.log(chalk.blue('🎮 Installing BMGD Module...')); - - // Create planning artifacts directory (for GDDs, game briefs, architecture) - if (config['planning_artifacts'] && typeof config['planning_artifacts'] === 'string') { - // Strip project-root prefix variations - const planningConfig = config['planning_artifacts'].replace(/^\{project-root\}\/?/, ''); - const planningPath = path.join(projectRoot, planningConfig); - if (!isWithinProjectRoot(planningPath, projectRoot)) { - logger.warn(chalk.yellow(`Warning: planning_artifacts path escapes project root, skipping: ${planningConfig}`)); - } else if (!(await fs.pathExists(planningPath))) { - logger.log(chalk.yellow(`Creating game planning artifacts directory: ${planningConfig}`)); - await fs.ensureDir(planningPath); - } - } - - // Create implementation artifacts directory (sprint status, stories, reviews) - // Check both implementation_artifacts and implementation_artifacts for compatibility - const implConfig = config['implementation_artifacts'] || config['implementation_artifacts']; - if (implConfig && typeof implConfig === 'string') { - // Strip project-root prefix variations - const implConfigClean = implConfig.replace(/^\{project-root\}\/?/, ''); - const implPath = path.join(projectRoot, implConfigClean); - if (!isWithinProjectRoot(implPath, projectRoot)) { - logger.warn(chalk.yellow(`Warning: implementation_artifacts path escapes project root, skipping: ${implConfigClean}`)); - } else if (!(await fs.pathExists(implPath))) { - logger.log(chalk.yellow(`Creating implementation artifacts directory: ${implConfigClean}`)); - await fs.ensureDir(implPath); - } - } - - // Create project knowledge directory - if (config['project_knowledge'] && typeof config['project_knowledge'] === 'string') { - // Strip project-root prefix variations - const knowledgeConfig = config['project_knowledge'].replace(/^\{project-root\}\/?/, ''); - const knowledgePath = path.join(projectRoot, knowledgeConfig); - if (!isWithinProjectRoot(knowledgePath, projectRoot)) { - logger.warn(chalk.yellow(`Warning: project_knowledge path escapes project root, skipping: ${knowledgeConfig}`)); - } else if (!(await fs.pathExists(knowledgePath))) { - logger.log(chalk.yellow(`Creating project knowledge directory: ${knowledgeConfig}`)); - await fs.ensureDir(knowledgePath); - } - } - - // Log selected game engine(s) - if (config['primary_platform']) { - const platforms = Array.isArray(config['primary_platform']) ? config['primary_platform'] : [config['primary_platform']]; - - const platformNames = platforms.map((p) => { - switch (p) { - case 'unity': { - return 'Unity'; - } - case 'unreal': { - return 'Unreal Engine'; - } - case 'godot': { - return 'Godot'; - } - default: { - return p; - } - } - }); - - logger.log(chalk.cyan(`Game engine support configured for: ${platformNames.join(', ')}`)); - } - - // Handle IDE-specific configurations if needed - if (installedIDEs && installedIDEs.length > 0) { - logger.log(chalk.cyan(`Configuring BMGD for IDEs: ${installedIDEs.join(', ')}`)); - - for (const ide of installedIDEs) { - await configureForIDE(ide, projectRoot, config, logger); - } - } - - logger.log(chalk.green('✓ BMGD Module installation complete')); - logger.log(chalk.dim(' Game development workflows ready')); - logger.log(chalk.dim(' Agents: Game Designer, Game Dev, Game Architect, Game SM, Game QA, Game Solo Dev')); - - return true; - } catch (error) { - logger.error(chalk.red(`Error installing BMGD module: ${error.message}`)); - return false; - } -} - -/** - * Configure BMGD module for specific platform/IDE - * @private - */ -async function configureForIDE(ide, projectRoot, config, logger) { - // Validate platform code - if (!platformCodes.isValidPlatform(ide)) { - logger.warn(chalk.yellow(` Warning: Unknown platform code '${ide}'. Skipping BMGD configuration.`)); - return; - } - - const platformName = platformCodes.getDisplayName(ide); - - // Try to load platform-specific handler - const platformSpecificPath = path.join(__dirname, 'platform-specifics', `${ide}.js`); - - try { - if (await fs.pathExists(platformSpecificPath)) { - const platformHandler = require(platformSpecificPath); - - if (typeof platformHandler.install === 'function') { - const success = await platformHandler.install({ - projectRoot, - config, - logger, - platformInfo: platformCodes.getPlatform(ide), - }); - if (!success) { - logger.warn(chalk.yellow(` Warning: BMGD platform handler for ${platformName} returned failure`)); - } - } - } else { - // No platform-specific handler for this IDE - logger.log(chalk.dim(` No BMGD-specific configuration for ${platformName}`)); - } - } catch (error) { - logger.warn(chalk.yellow(` Warning: Could not load BMGD platform-specific handler for ${platformName}: ${error.message}`)); - } -} - -module.exports = { install }; diff --git a/src/modules/bmgd/_module-installer/platform-specifics/claude-code.js b/src/modules/bmgd/_module-installer/platform-specifics/claude-code.js deleted file mode 100644 index 8ad050aa..00000000 --- a/src/modules/bmgd/_module-installer/platform-specifics/claude-code.js +++ /dev/null @@ -1,23 +0,0 @@ -/** - * BMGD Platform-specific installer for Claude Code - * - * @param {Object} options - Installation options - * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from module.yaml - * @param {Object} options.logger - Logger instance for output - * @param {Object} options.platformInfo - Platform metadata from global config - * @returns {Promise} - Success status - */ -async function install() { - // TODO: Add Claude Code specific BMGD configurations here - // For example: - // - Game-specific slash commands - // - Agent party configurations for game dev team - // - Workflow integrations for Unity/Unreal/Godot - // - Game testing framework integrations - - // Currently a stub - no platform-specific configuration needed yet - return true; -} - -module.exports = { install }; diff --git a/src/modules/bmgd/_module-installer/platform-specifics/windsurf.js b/src/modules/bmgd/_module-installer/platform-specifics/windsurf.js deleted file mode 100644 index 46f03c9c..00000000 --- a/src/modules/bmgd/_module-installer/platform-specifics/windsurf.js +++ /dev/null @@ -1,18 +0,0 @@ -/** - * BMGD Platform-specific installer for Windsurf - * - * @param {Object} options - Installation options - * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from module.yaml - * @param {Object} options.logger - Logger instance for output - * @param {Object} options.platformInfo - Platform metadata from global config - * @returns {Promise} - Success status - */ -async function install() { - // TODO: Add Windsurf specific BMGD configurations here - - // Currently a stub - no platform-specific configuration needed yet - return true; -} - -module.exports = { install }; diff --git a/src/modules/bmgd/agents/game-architect.agent.yaml b/src/modules/bmgd/agents/game-architect.agent.yaml deleted file mode 100644 index 7099b6b2..00000000 --- a/src/modules/bmgd/agents/game-architect.agent.yaml +++ /dev/null @@ -1,44 +0,0 @@ -# Game Architect Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-architect.md" - name: Cloud Dragonborn - title: Game Architect - icon: 🏛️ - module: bmgd - hasSidecar: false - - persona: - role: Principal Game Systems Architect + Technical Director - identity: Master architect with 20+ years shipping 30+ titles. Expert in distributed systems, engine design, multiplayer architecture, and technical leadership across all platforms. - communication_style: "Speaks like a wise sage from an RPG - calm, measured, uses architectural metaphors about building foundations and load-bearing walls" - principles: | - - Architecture is about delaying decisions until you have enough data - - Build for tomorrow without over-engineering today - - Hours of planning save weeks of refactoring hell - - Every system must handle the hot path at 60fps - - Avoid "Not Invented Here" syndrome, always check if work has been done before - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When creating architecture, validate against GDD pillars and target platform constraints" - - "Always document performance budgets and critical path decisions" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" - - - trigger: GA or fuzzy match on game-architecture - exec: "{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture/workflow.md" - description: "[GA] Produce a Scale Adaptive Game Architecture" - - - trigger: PC or fuzzy match on project-context - exec: "{project-root}/_bmad/bmgd/workflows/3-technical/generate-project-context/workflow.md" - description: "[PC] Create optimized project-context.md for AI agent consistency" - - - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/correct-course/workflow.yaml" - description: "[CC] Course Correction Analysis (when implementation is off-track)" - ide-only: true diff --git a/src/modules/bmgd/agents/game-designer.agent.yaml b/src/modules/bmgd/agents/game-designer.agent.yaml deleted file mode 100644 index 6b654dec..00000000 --- a/src/modules/bmgd/agents/game-designer.agent.yaml +++ /dev/null @@ -1,49 +0,0 @@ -# Game Designer Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-designer.md" - name: Samus Shepard - title: Game Designer - icon: 🎲 - module: bmgd - hasSidecar: false - - persona: - role: Lead Game Designer + Creative Vision Architect - identity: Veteran designer with 15+ years crafting AAA and indie hits. Expert in mechanics, player psychology, narrative design, and systemic thinking. - communication_style: "Talks like an excited streamer - enthusiastic, asks about player motivations, celebrates breakthroughs with 'Let's GOOO!'" - principles: | - - Design what players want to FEEL, not what they say they want - - Prototype fast - one hour of playtesting beats ten hours of discussion - - Every mechanic must serve the core fantasy - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When creating GDDs, always validate against game pillars and core loop" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" - - - trigger: BG or fuzzy match on brainstorm-game - exec: "{project-root}/_bmad/bmgd/workflows/1-preproduction/brainstorm-game/workflow.md" - description: "[BG] Brainstorm Game ideas and concepts" - - - trigger: GB or fuzzy match on game-brief - exec: "{project-root}/_bmad/bmgd/workflows/1-preproduction/game-brief/workflow.md" - description: "[GB] Create a Game Brief document" - - - trigger: GDD or fuzzy match on create-gdd - exec: "{project-root}/_bmad/bmgd/workflows/2-design/gdd/workflow.md" - description: "[GDD] Create a Game Design Document" - - - trigger: ND or fuzzy match on narrative-design - exec: "{project-root}/_bmad/bmgd/workflows/2-design/narrative/workflow.md" - description: "[ND] Design narrative elements and story" - - - trigger: QP or fuzzy match on quick-prototype - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-prototype/workflow.yaml" - description: "[QP] Rapid game prototyping - test mechanics and ideas quickly" - ide-only: true diff --git a/src/modules/bmgd/agents/game-dev.agent.yaml b/src/modules/bmgd/agents/game-dev.agent.yaml deleted file mode 100644 index ff085a34..00000000 --- a/src/modules/bmgd/agents/game-dev.agent.yaml +++ /dev/null @@ -1,53 +0,0 @@ -# Game Developer Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-dev.md" - name: Link Freeman - title: Game Developer - icon: 🕹️ - module: bmgd - hasSidecar: false - - persona: - role: Senior Game Developer + Technical Implementation Specialist - identity: Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code. - communication_style: "Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship" - principles: | - - 60fps is non-negotiable - - Write code designers can iterate without fear - - Ship early, ship often, iterate on player feedback - - Red-green-refactor: tests first, implementation second - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When running *dev-story, follow story acceptance criteria exactly and validate with tests" - - "Always check for performance implications on game loop code" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or check current sprint progress (optional)" - - - trigger: DS or fuzzy match on dev-story - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/dev-story/workflow.yaml" - description: "[DS] Execute Dev Story workflow, implementing tasks and tests" - - - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/code-review/workflow.yaml" - description: "[CR] Perform a thorough clean context QA code review on a story flagged Ready for Review" - - - trigger: QD or fuzzy match on quick-dev - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-dev/workflow.yaml" - description: "[QD] Flexible game development - implement features with game-specific considerations" - ide-only: true - - - trigger: QP or fuzzy match on quick-prototype - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-prototype/workflow.yaml" - description: "[QP] Rapid game prototyping - test mechanics and ideas quickly" - ide-only: true - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/agents/game-qa.agent.yaml b/src/modules/bmgd/agents/game-qa.agent.yaml deleted file mode 100644 index 973d521c..00000000 --- a/src/modules/bmgd/agents/game-qa.agent.yaml +++ /dev/null @@ -1,67 +0,0 @@ -# Game QA Architect Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-qa.md" - name: GLaDOS - title: Game QA Architect - icon: 🧪 - module: bmgd - hasSidecar: false - - persona: - role: Game QA Architect + Test Automation Specialist - identity: Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile. - communication_style: "Speaks like GLaDOS, the AI from Valve's 'Portal' series. Runs tests because we can. 'Trust, but verify with tests.'" - principles: | - - Test what matters: gameplay feel, performance, progression - - Automated tests catch regressions, humans catch fun problems - - Every shipped bug is a process failure, not a people failure - - Flaky tests are worse than no tests - they erode trust - - Profile before optimize, test before ship - - critical_actions: - - "Consult {project-root}/_bmad/bmgd/gametest/qa-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task" - - "For E2E testing requests, always load knowledge/e2e-testing.md first" - - "When scaffolding tests, distinguish between unit, integration, and E2E test needs" - - "Load the referenced fragment(s) from {project-root}/_bmad/bmgd/gametest/knowledge/ before giving recommendations" - - "Cross-check recommendations with the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation" - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or check current project state (optional)" - - - trigger: TF or fuzzy match on test-framework - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-framework/workflow.yaml" - description: "[TF] Initialize game test framework (Unity/Unreal/Godot)" - - - trigger: TD or fuzzy match on test-design - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-design/workflow.yaml" - description: "[TD] Create comprehensive game test scenarios" - - - trigger: TA or fuzzy match on test-automate - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/automate/workflow.yaml" - description: "[TA] Generate automated game tests" - - - trigger: ES or fuzzy match on e2e-scaffold - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/e2e-scaffold/workflow.yaml" - description: "[ES] Scaffold E2E testing infrastructure" - - - trigger: PP or fuzzy match on playtest-plan - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/playtest-plan/workflow.yaml" - description: "[PP] Create structured playtesting plan" - - - trigger: PT or fuzzy match on performance-test - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/performance/workflow.yaml" - description: "[PT] Design performance testing strategy" - - - trigger: TR or fuzzy match on test-review - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-review/workflow.yaml" - description: "[TR] Review test quality and coverage" - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/agents/game-scrum-master.agent.yaml b/src/modules/bmgd/agents/game-scrum-master.agent.yaml deleted file mode 100644 index 1b2d599f..00000000 --- a/src/modules/bmgd/agents/game-scrum-master.agent.yaml +++ /dev/null @@ -1,60 +0,0 @@ -# Game Dev Scrum Master Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-scrum-master.md" - name: Max - title: Game Dev Scrum Master - icon: 🎯 - module: bmgd - hasSidecar: false - - persona: - role: Game Development Scrum Master + Sprint Orchestrator - identity: Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories. - communication_style: "Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights" - principles: | - - Every sprint delivers playable increments - - Clean separation between design and implementation - - Keep the team moving through each phase - - Stories are single source of truth for implementation - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - "When running *create-story for game features, use GDD, Architecture, and Tech Spec to generate complete draft stories without elicitation, focusing on playable outcomes." - - "Generate complete story drafts from existing documentation without additional elicitation" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" - - - trigger: SP or fuzzy match on sprint-planning - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/sprint-planning/workflow.yaml" - description: "[SP] Generate or update sprint-status.yaml from epic files (Required after GDD+Epics are created)" - - - trigger: SS or fuzzy match on sprint-status - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/sprint-status/workflow.yaml" - description: "[SS] View sprint progress, surface risks, and get next action recommendation" - - - trigger: CS or fuzzy match on create-story - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.yaml" - description: "[CS] Create Story with direct ready-for-dev marking (Required to prepare stories for development)" - - - trigger: VS or fuzzy match on validate-story - validate-workflow: "{project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.yaml" - description: "[VS] Validate Story Draft with Independent Review (Highly Recommended)" - - - trigger: ER or fuzzy match on epic-retrospective - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/retrospective/workflow.yaml" - data: "{project-root}/_bmad/_config/agent-manifest.csv" - description: "[ER] Facilitate team retrospective after a game development epic is completed" - - - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/correct-course/workflow.yaml" - description: "[CC] Navigate significant changes during game dev sprint (When implementation is off-track)" - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/agents/game-solo-dev.agent.yaml b/src/modules/bmgd/agents/game-solo-dev.agent.yaml deleted file mode 100644 index 42df4c9f..00000000 --- a/src/modules/bmgd/agents/game-solo-dev.agent.yaml +++ /dev/null @@ -1,53 +0,0 @@ -# Game Solo Dev Agent Definition - -agent: - metadata: - id: "_bmad/bmgd/agents/game-solo-dev.md" - name: Indie - title: Game Solo Dev - icon: 🎮 - module: bmgd - hasSidecar: false - - persona: - role: Elite Indie Game Developer + Quick Flow Specialist - identity: Indie is a battle-hardened solo game developer who ships complete games from concept to launch. Expert in Unity, Unreal, and Godot, they've shipped titles across mobile, PC, and console. Lives and breathes the Quick Flow workflow - prototyping fast, iterating faster, and shipping before the hype dies. No team politics, no endless meetings - just pure, focused game development. - communication_style: "Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and player experience. Every response moves the game closer to ship. 'Does it feel good? Ship it.'" - principles: | - - Prototype fast, fail fast, iterate faster. Quick Flow is the indie way. - - A playable build beats a perfect design doc. Ship early, playtest often. - - 60fps is non-negotiable. Performance is a feature. - - The core loop must be fun before anything else matters. - - critical_actions: - - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`" - - menu: - - trigger: WS or fuzzy match on workflow-status - workflow: "{project-root}/_bmad/bmgd/workflows/workflow-status/workflow.yaml" - description: "[WS] Get workflow status or check current project state (optional)" - - - trigger: QP or fuzzy match on quick-prototype - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-prototype/workflow.yaml" - description: "[QP] Rapid prototype to test if the mechanic is fun (Start here for new ideas)" - - - trigger: QD or fuzzy match on quick-dev - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-dev/workflow.yaml" - description: "[QD] Implement features end-to-end solo with game-specific considerations" - - - trigger: TS or fuzzy match on tech-spec - workflow: "{project-root}/_bmad/bmgd/workflows/bmgd-quick-flow/quick-spec/workflow.yaml" - description: "[TS] Architect a technical spec with implementation-ready stories" - - - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmgd/workflows/4-production/code-review/workflow.yaml" - description: "[CR] Review code quality (use fresh context for best results)" - - - trigger: TF or fuzzy match on test-framework - workflow: "{project-root}/_bmad/bmgd/workflows/gametest/test-framework/workflow.yaml" - description: "[TF] Set up automated testing for your game engine" - - - trigger: AE or fuzzy match on advanced-elicitation - exec: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml" - description: "[AE] Advanced elicitation techniques to challenge the LLM to get better results" - web-only: true diff --git a/src/modules/bmgd/gametest/knowledge/balance-testing.md b/src/modules/bmgd/gametest/knowledge/balance-testing.md deleted file mode 100644 index 9aad8ebf..00000000 --- a/src/modules/bmgd/gametest/knowledge/balance-testing.md +++ /dev/null @@ -1,220 +0,0 @@ -# Balance Testing for Games - -## Overview - -Balance testing validates that your game's systems create fair, engaging, and appropriately challenging experiences. It covers difficulty, economy, progression, and competitive balance. - -## Types of Balance - -### Difficulty Balance - -- Is the game appropriately challenging? -- Does difficulty progress smoothly? -- Are difficulty spikes intentional? - -### Economy Balance - -- Is currency earned at the right rate? -- Are prices fair for items/upgrades? -- Can the economy be exploited? - -### Progression Balance - -- Does power growth feel satisfying? -- Are unlocks paced well? -- Is there meaningful choice in builds? - -### Competitive Balance - -- Are all options viable? -- Is there a dominant strategy? -- Do counters exist for strong options? - -## Balance Testing Methods - -### Spreadsheet Modeling - -Before implementation, model systems mathematically: - -- DPS calculations -- Time-to-kill analysis -- Economy simulations -- Progression curves - -### Automated Simulation - -Run thousands of simulated games: - -- AI vs AI battles -- Economy simulations -- Progression modeling -- Monte Carlo analysis - -### Telemetry Analysis - -Gather data from real players: - -- Win rates by character/weapon/strategy -- Currency flow analysis -- Completion rates by level -- Time to reach milestones - -### Expert Testing - -High-skill players identify issues: - -- Exploits and degenerate strategies -- Underpowered options -- Skill ceiling concerns -- Meta predictions - -## Key Balance Metrics - -### Combat Balance - -| Metric | Target | Red Flag | -| ------------------------- | ------------------- | ------------------------- | -| Win rate (symmetric) | 50% | <45% or >55% | -| Win rate (asymmetric) | Varies by design | Outliers by >10% | -| Time-to-kill | Design dependent | Too fast = no counterplay | -| Damage dealt distribution | Even across options | One option dominates | - -### Economy Balance - -| Metric | Target | Red Flag | -| -------------------- | -------------------- | ------------------------------- | -| Currency earned/hour | Design dependent | Too fast = trivializes content | -| Item purchase rate | Healthy distribution | Nothing bought = bad prices | -| Currency on hand | Healthy churn | Hoarding = nothing worth buying | -| Premium currency | Reasonable value | Pay-to-win concerns | - -### Progression Balance - -| Metric | Target | Red Flag | -| ------------------ | ---------------------- | ---------------------- | -| Time to max level | Design dependent | Too fast = no journey | -| Power growth curve | Smooth, satisfying | Flat periods = boring | -| Build diversity | Multiple viable builds | One "best" build | -| Content completion | Healthy progression | Walls or trivial skips | - -## Balance Testing Process - -### 1. Define Design Intent - -- What experience are you creating? -- What should feel powerful? -- What trade-offs should exist? - -### 2. Model Before Building - -- Spreadsheet the math -- Simulate outcomes -- Identify potential issues - -### 3. Test Incrementally - -- Test each system in isolation -- Then test systems together -- Then test at scale - -### 4. Gather Data - -- Internal playtesting -- Telemetry from beta -- Expert feedback - -### 5. Iterate - -- Adjust based on data -- Re-test changes -- Document rationale - -## Common Balance Issues - -### Power Creep - -- **Symptom:** New content is always stronger -- **Cause:** Fear of releasing weak content -- **Fix:** Sidegrades over upgrades, periodic rebalancing - -### Dominant Strategy - -- **Symptom:** One approach beats all others -- **Cause:** Insufficient counters, math oversight -- **Fix:** Add counters, nerf dominant option, buff alternatives - -### Feast or Famine - -- **Symptom:** Players either crush or get crushed -- **Cause:** Snowball mechanics, high variance -- **Fix:** Comeback mechanics, reduce variance - -### Analysis Paralysis - -- **Symptom:** Too many options, players can't choose -- **Cause:** Over-complicated systems -- **Fix:** Simplify, provide recommendations - -## Balance Tools - -### Spreadsheets - -- Model DPS, TTK, economy -- Simulate progression -- Compare options side-by-side - -### Simulation Frameworks - -- Monte Carlo for variance -- AI bots for combat testing -- Economy simulations - -### Telemetry Systems - -- Track player choices -- Measure outcomes -- A/B test changes - -### Visualization - -- Graphs of win rates over time -- Heat maps of player deaths -- Flow charts of progression - -## Balance Testing Checklist - -### Pre-Launch - -- [ ] Core systems modeled in spreadsheets -- [ ] Internal playtesting complete -- [ ] No obvious dominant strategies -- [ ] Difficulty curve feels right -- [ ] Economy tested for exploits -- [ ] Progression pacing validated - -### Live Service - -- [ ] Telemetry tracking key metrics -- [ ] Regular balance reviews scheduled -- [ ] Player feedback channels monitored -- [ ] Hotfix process for critical issues -- [ ] Communication plan for changes - -## Communicating Balance Changes - -### Patch Notes Best Practices - -- Explain the "why" not just the "what" -- Use concrete numbers when possible -- Acknowledge player concerns -- Set expectations for future changes - -### Example - -``` -**Sword of Valor - Damage reduced from 100 to 85** -Win rate for Sword users was 58%, indicating it was -overperforming. This brings it in line with other weapons -while maintaining its identity as a high-damage option. -We'll continue monitoring and adjust if needed. -``` diff --git a/src/modules/bmgd/gametest/knowledge/certification-testing.md b/src/modules/bmgd/gametest/knowledge/certification-testing.md deleted file mode 100644 index 4e268f8d..00000000 --- a/src/modules/bmgd/gametest/knowledge/certification-testing.md +++ /dev/null @@ -1,319 +0,0 @@ -# Platform Certification Testing Guide - -## Overview - -Certification testing ensures games meet platform holder requirements (Sony TRC, Microsoft XR, Nintendo Guidelines). Failing certification delays launch and costs money—test thoroughly before submission. - -## Platform Requirements Overview - -### Major Platforms - -| Platform | Requirements Doc | Submission Portal | -| --------------- | -------------------------------------- | ------------------------- | -| PlayStation | TRC (Technical Requirements Checklist) | PlayStation Partners | -| Xbox | XR (Xbox Requirements) | Xbox Partner Center | -| Nintendo Switch | Guidelines | Nintendo Developer Portal | -| Steam | Guidelines (less strict) | Steamworks | -| iOS | App Store Guidelines | App Store Connect | -| Android | Play Store Policies | Google Play Console | - -## Common Certification Categories - -### Account and User Management - -``` -REQUIREMENT: User Switching - GIVEN user is playing game - WHEN system-level user switch occurs - THEN game handles transition gracefully - AND no data corruption - AND correct user data loads - -REQUIREMENT: Guest Accounts - GIVEN guest user plays game - WHEN guest makes progress - THEN progress is not saved to other accounts - AND appropriate warnings displayed - -REQUIREMENT: Parental Controls - GIVEN parental controls restrict content - WHEN restricted content is accessed - THEN content is blocked or modified - AND appropriate messaging shown -``` - -### System Events - -``` -REQUIREMENT: Suspend/Resume (PS4/PS5) - GIVEN game is running - WHEN console enters rest mode - AND console wakes from rest mode - THEN game resumes correctly - AND network reconnects if needed - AND no audio/visual glitches - -REQUIREMENT: Controller Disconnect - GIVEN player is in gameplay - WHEN controller battery dies - THEN game pauses immediately - AND reconnect prompt appears - AND gameplay resumes when connected - -REQUIREMENT: Storage Full - GIVEN storage is nearly full - WHEN game attempts save - THEN graceful error handling - AND user informed of issue - AND no data corruption -``` - -### Network Requirements - -``` -REQUIREMENT: PSN/Xbox Live Unavailable - GIVEN online features - WHEN platform network is unavailable - THEN offline features still work - AND appropriate error messages - AND no crashes - -REQUIREMENT: Network Transition - GIVEN active online session - WHEN network connection lost - THEN graceful handling - AND reconnection attempted - AND user informed of status - -REQUIREMENT: NAT Type Handling - GIVEN various NAT configurations - WHEN multiplayer is attempted - THEN appropriate feedback on connectivity - AND fallback options offered -``` - -### Save Data - -``` -REQUIREMENT: Save Data Integrity - GIVEN save data exists - WHEN save is loaded - THEN data is validated - AND corrupted data handled gracefully - AND no crashes on invalid data - -REQUIREMENT: Cloud Save Sync - GIVEN cloud saves enabled - WHEN save conflict occurs - THEN user chooses which to keep - AND no silent data loss - -REQUIREMENT: Save Data Portability (PS4→PS5) - GIVEN save from previous generation - WHEN loaded on current generation - THEN data migrates correctly - AND no features lost -``` - -## Platform-Specific Requirements - -### PlayStation (TRC) - -| Requirement | Description | Priority | -| ----------- | --------------------------- | -------- | -| TRC R4010 | Suspend/resume handling | Critical | -| TRC R4037 | User switching | Critical | -| TRC R4062 | Parental controls | Critical | -| TRC R4103 | PS VR comfort ratings | VR only | -| TRC R4120 | DualSense haptics standards | PS5 | -| TRC R5102 | PSN sign-in requirements | Online | - -### Xbox (XR) - -| Requirement | Description | Priority | -| ----------- | ----------------------------- | ----------- | -| XR-015 | Title timeout handling | Critical | -| XR-045 | User sign-out handling | Critical | -| XR-067 | Active user requirement | Critical | -| XR-074 | Quick Resume support | Series X/S | -| XR-115 | Xbox Accessibility Guidelines | Recommended | - -### Nintendo Switch - -| Requirement | Description | Priority | -| ------------------ | ------------------- | -------- | -| Docked/Handheld | Seamless transition | Critical | -| Joy-Con detachment | Controller handling | Critical | -| Home button | Immediate response | Critical | -| Screenshots/Video | Proper support | Required | -| Sleep mode | Resume correctly | Critical | - -## Automated Test Examples - -### System Event Testing - -```cpp -// Unreal - Suspend/Resume Test -IMPLEMENT_SIMPLE_AUTOMATION_TEST( - FSuspendResumeTest, - "Certification.System.SuspendResume", - EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter -) - -bool FSuspendResumeTest::RunTest(const FString& Parameters) -{ - // Get game state before suspend - FGameState StateBefore = GetCurrentGameState(); - - // Simulate suspend - FCoreDelegates::ApplicationWillEnterBackgroundDelegate.Broadcast(); - - // Simulate resume - FCoreDelegates::ApplicationHasEnteredForegroundDelegate.Broadcast(); - - // Verify state matches - FGameState StateAfter = GetCurrentGameState(); - - TestEqual("Player position preserved", - StateAfter.PlayerPosition, StateBefore.PlayerPosition); - TestEqual("Game progress preserved", - StateAfter.Progress, StateBefore.Progress); - - return true; -} -``` - -```csharp -// Unity - Controller Disconnect Test -[UnityTest] -public IEnumerator ControllerDisconnect_ShowsPauseMenu() -{ - // Simulate gameplay - GameManager.Instance.StartGame(); - yield return new WaitForSeconds(1f); - - // Simulate controller disconnect - InputSystem.DisconnectDevice(Gamepad.current); - yield return null; - - // Verify pause menu shown - Assert.IsTrue(PauseMenu.IsVisible, "Pause menu should appear"); - Assert.IsTrue(Time.timeScale == 0, "Game should be paused"); - - // Simulate reconnect - InputSystem.ReconnectDevice(Gamepad.current); - yield return null; - - // Verify prompt appears - Assert.IsTrue(ReconnectPrompt.IsVisible); -} -``` - -```gdscript -# Godot - Save Corruption Test -func test_corrupted_save_handling(): - # Create corrupted save file - var file = FileAccess.open("user://save_corrupt.dat", FileAccess.WRITE) - file.store_string("CORRUPTED_GARBAGE_DATA") - file.close() - - # Attempt to load - var result = SaveManager.load("save_corrupt") - - # Should handle gracefully - assert_null(result, "Should return null for corrupted save") - assert_false(OS.has_feature("crashed"), "Should not crash") - - # Should show user message - var message_shown = ErrorDisplay.current_message != "" - assert_true(message_shown, "Should inform user of corruption") -``` - -## Pre-Submission Checklist - -### General Requirements - -- [ ] Game boots to interactive state within platform time limit -- [ ] Controller disconnect pauses game -- [ ] User sign-out handled correctly -- [ ] Save data validates on load -- [ ] No crashes in 8+ hours of automated testing -- [ ] Memory usage within platform limits -- [ ] Load times meet requirements - -### Platform Services - -- [ ] Achievements/Trophies work correctly -- [ ] Friends list integration works -- [ ] Invite system functions -- [ ] Store/DLC integration validated -- [ ] Cloud saves sync properly - -### Accessibility (Increasingly Required) - -- [ ] Text size options -- [ ] Colorblind modes -- [ ] Subtitle options -- [ ] Controller remapping -- [ ] Screen reader support (where applicable) - -### Content Compliance - -- [ ] Age rating displayed correctly -- [ ] Parental controls respected -- [ ] No prohibited content -- [ ] Required legal text present - -## Common Certification Failures - -| Issue | Platform | Fix | -| --------------------- | ------------ | ----------------------------------- | -| Home button delay | All consoles | Respond within required time | -| Controller timeout | PlayStation | Handle reactivation properly | -| Save on suspend | PlayStation | Don't save during suspend | -| User context loss | Xbox | Track active user correctly | -| Joy-Con drift | Switch | Proper deadzone handling | -| Background memory | Mobile | Release resources when backgrounded | -| Crash on corrupt data | All | Validate all loaded data | - -## Testing Matrix - -### Build Configurations to Test - -| Configuration | Scenarios | -| --------------- | ----------------------- | -| First boot | No save data exists | -| Return user | Save data present | -| Upgrade path | Previous version save | -| Fresh install | After uninstall | -| Low storage | Minimum space available | -| Network offline | No connectivity | - -### Hardware Variants - -| Platform | Variants to Test | -| ----------- | ------------------------------- | -| PlayStation | PS4, PS4 Pro, PS5 | -| Xbox | One, One X, Series S, Series X | -| Switch | Docked, Handheld, Lite | -| PC | Min spec, recommended, high-end | - -## Best Practices - -### DO - -- Read platform requirements document thoroughly -- Test on actual hardware, not just dev kits -- Automate certification test scenarios -- Submit with extra time for re-submission -- Document all edge case handling -- Test with real user accounts - -### DON'T - -- Assume debug builds behave like retail -- Skip testing on oldest supported hardware -- Ignore platform-specific features -- Wait until last minute to test certification items -- Use placeholder content in submission build -- Skip testing with real platform services diff --git a/src/modules/bmgd/gametest/knowledge/compatibility-testing.md b/src/modules/bmgd/gametest/knowledge/compatibility-testing.md deleted file mode 100644 index 291bdfce..00000000 --- a/src/modules/bmgd/gametest/knowledge/compatibility-testing.md +++ /dev/null @@ -1,228 +0,0 @@ -# Compatibility Testing for Games - -## Overview - -Compatibility testing ensures your game works correctly across different hardware, operating systems, and configurations that players use. - -## Types of Compatibility Testing - -### Hardware Compatibility - -- Graphics cards (NVIDIA, AMD, Intel) -- CPUs (Intel, AMD, Apple Silicon) -- Memory configurations -- Storage types (HDD, SSD, NVMe) -- Input devices (controllers, keyboards, mice) - -### Software Compatibility - -- Operating system versions -- Driver versions -- Background software conflicts -- Antivirus interference - -### Platform Compatibility - -- Console SKUs (PS5, Xbox Series X|S) -- PC storefronts (Steam, Epic, GOG) -- Mobile devices (iOS, Android) -- Cloud gaming services - -### Configuration Compatibility - -- Graphics settings combinations -- Resolution and aspect ratios -- Refresh rates (60Hz, 144Hz, etc.) -- HDR and color profiles - -## Testing Matrix - -### Minimum Hardware Matrix - -| Component | Budget | Mid-Range | High-End | -| --------- | -------- | --------- | -------- | -| GPU | GTX 1050 | RTX 3060 | RTX 4080 | -| CPU | i5-6400 | i7-10700 | i9-13900 | -| RAM | 8GB | 16GB | 32GB | -| Storage | HDD | SATA SSD | NVMe | - -### OS Matrix - -- Windows 10 (21H2, 22H2) -- Windows 11 (22H2, 23H2) -- macOS (Ventura, Sonoma) -- Linux (Ubuntu LTS, SteamOS) - -### Controller Matrix - -- Xbox Controller (wired, wireless, Elite) -- PlayStation DualSense -- Nintendo Pro Controller -- Generic XInput controllers -- Keyboard + Mouse - -## Testing Approach - -### 1. Define Supported Configurations - -- Minimum specifications -- Recommended specifications -- Officially supported platforms -- Known unsupported configurations - -### 2. Create Test Matrix - -- Prioritize common configurations -- Include edge cases -- Balance coverage vs. effort - -### 3. Execute Systematic Testing - -- Full playthrough on key configs -- Spot checks on edge cases -- Automated smoke tests where possible - -### 4. Document Issues - -- Repro steps with exact configuration -- Severity and frequency -- Workarounds if available - -## Common Compatibility Issues - -### Graphics Issues - -| Issue | Cause | Detection | -| -------------------- | ---------------------- | -------------------------------- | -| Crashes on launch | Driver incompatibility | Test on multiple GPUs | -| Rendering artifacts | Shader issues | Visual inspection across configs | -| Performance variance | Optimization gaps | Profile on multiple GPUs | -| Resolution bugs | Aspect ratio handling | Test non-standard resolutions | - -### Input Issues - -| Issue | Cause | Detection | -| ----------------------- | ------------------ | ------------------------------ | -| Controller not detected | Missing driver/API | Test all supported controllers | -| Wrong button prompts | Platform detection | Swap controllers mid-game | -| Stick drift handling | Deadzone issues | Test worn controllers | -| Mouse acceleration | Raw input issues | Test at different DPIs | - -### Audio Issues - -| Issue | Cause | Detection | -| -------------- | ---------------- | --------------------------- | -| No sound | Device selection | Test multiple audio devices | -| Crackling | Buffer issues | Test under CPU load | -| Wrong channels | Surround setup | Test stereo vs 5.1 vs 7.1 | - -## Platform-Specific Considerations - -### PC - -- **Steam:** Verify Steam Input, Steamworks features -- **Epic:** Test EOS features if used -- **GOG:** Test offline/DRM-free functionality -- **Game Pass:** Test Xbox services integration - -### Console - -- **Certification Requirements:** Study TRCs/XRs early -- **SKU Differences:** Test on all variants (S vs X) -- **External Storage:** Test on USB drives -- **Quick Resume:** Test suspend/resume cycles - -### Mobile - -- **Device Fragmentation:** Test across screen sizes -- **OS Versions:** Test min supported to latest -- **Permissions:** Test permission flows -- **App Lifecycle:** Test background/foreground - -## Automated Compatibility Testing - -### Smoke Tests - -```yaml -# Run on matrix of configurations -compatibility_test: - matrix: - os: [windows-10, windows-11, ubuntu-22] - gpu: [nvidia, amd, intel] - script: - - launch_game --headless - - verify_main_menu_reached - - check_no_errors -``` - -### Screenshot Comparison - -- Capture screenshots on different GPUs -- Compare for rendering differences -- Flag significant deviations - -### Cloud Testing Services - -- AWS Device Farm -- BrowserStack (web games) -- LambdaTest -- Sauce Labs - -## Compatibility Checklist - -### Pre-Alpha - -- [ ] Minimum specs defined -- [ ] Key platforms identified -- [ ] Test matrix created -- [ ] Test hardware acquired/rented - -### Alpha - -- [ ] Full playthrough on min spec -- [ ] Controller support verified -- [ ] Major graphics issues found -- [ ] Platform SDK integrated - -### Beta - -- [ ] All matrix configurations tested -- [ ] Edge cases explored -- [ ] Certification pre-check done -- [ ] Store page requirements met - -### Release - -- [ ] Final certification passed -- [ ] Known issues documented -- [ ] Workarounds communicated -- [ ] Support matrix published - -## Documenting Compatibility - -### System Requirements - -``` -MINIMUM: -- OS: Windows 10 64-bit -- Processor: Intel Core i5-6400 or AMD equivalent -- Memory: 8 GB RAM -- Graphics: NVIDIA GTX 1050 or AMD RX 560 -- Storage: 50 GB available space - -RECOMMENDED: -- OS: Windows 11 64-bit -- Processor: Intel Core i7-10700 or AMD equivalent -- Memory: 16 GB RAM -- Graphics: NVIDIA RTX 3060 or AMD RX 6700 XT -- Storage: 50 GB SSD -``` - -### Known Issues - -Maintain a public-facing list of known compatibility issues with: - -- Affected configurations -- Symptoms -- Workarounds -- Fix status diff --git a/src/modules/bmgd/gametest/knowledge/e2e-testing.md b/src/modules/bmgd/gametest/knowledge/e2e-testing.md deleted file mode 100644 index 8f35bcd7..00000000 --- a/src/modules/bmgd/gametest/knowledge/e2e-testing.md +++ /dev/null @@ -1,1013 +0,0 @@ -# End-to-End Testing for Games - -## Overview - -E2E tests validate complete gameplay flows from the player's perspective — the full orchestra, not individual instruments. Unlike integration tests that verify system interactions, E2E tests verify *player journeys* work correctly from start to finish. - -This is the difference between "does the damage calculator work with the inventory system?" (integration) and "can a player actually complete a combat encounter from selection to resolution?" (E2E). - -## E2E vs Integration vs Unit - -| Aspect | Unit | Integration | E2E | -|--------|------|-------------|-----| -| Scope | Single class | System interaction | Complete flow | -| Speed | < 10ms | < 1s | 1-30s | -| Stability | Very stable | Stable | Requires care | -| Example | DamageCalc math | Combat + Inventory | Full combat encounter | -| Dependencies | None/mocked | Some real | All real | -| Catches | Logic bugs | Wiring bugs | Journey bugs | - -## The E2E Testing Pyramid Addition - -``` - /\ - / \ Manual Playtesting - /----\ (Fun, Feel, Experience) - / \ - /--------\ E2E Tests - / \ (Player Journeys) - /------------\ - / \ Integration Tests - /----------------\ (System Interactions) - / \ Unit Tests - /____________________\ (Pure Logic) -``` - -E2E tests sit between integration tests and manual playtesting. They automate what *can* be automated about player experience while acknowledging that "is this fun?" still requires human judgment. - -## E2E Infrastructure Requirements - -Before writing E2E tests, scaffold supporting infrastructure. Without this foundation, E2E tests become brittle, flaky nightmares that erode trust faster than they build confidence. - -### 1. Test Fixture Base Class - -Provides scene loading, cleanup, and common utilities. Every E2E test inherits from this. - -**Unity Example:** - -```csharp -using System.Collections; -using NUnit.Framework; -using UnityEngine; -using UnityEngine.SceneManagement; -using UnityEngine.TestTools; - -public abstract class GameE2ETestFixture -{ - protected virtual string SceneName => "GameScene"; - protected GameStateManager GameState { get; private set; } - protected InputSimulator Input { get; private set; } - protected ScenarioBuilder Scenario { get; private set; } - - [UnitySetUp] - public IEnumerator BaseSetUp() - { - // Load the game scene - yield return SceneManager.LoadSceneAsync(SceneName); - yield return null; // Wait one frame for scene initialization - - // Get core references - GameState = Object.FindFirstObjectByType(); - Assert.IsNotNull(GameState, $"GameStateManager not found in {SceneName}"); - - // Initialize test utilities - Input = new InputSimulator(); - Scenario = new ScenarioBuilder(GameState); - - // Wait for game to be ready - yield return WaitForGameReady(); - } - - [UnityTearDown] - public IEnumerator BaseTearDown() - { - // Clean up any test-spawned objects - yield return CleanupTestObjects(); - - // Reset input state - Input?.Reset(); - } - - protected IEnumerator WaitForGameReady(float timeout = 10f) - { - yield return AsyncAssert.WaitUntil( - () => GameState != null && GameState.IsReady, - "Game ready state", - timeout); - } - - protected virtual IEnumerator CleanupTestObjects() - { - // Override in derived classes for game-specific cleanup - yield return null; - } -} -``` - -**Unreal Example:** - -```cpp -// GameE2ETestBase.h -UCLASS() -class AGameE2ETestBase : public AFunctionalTest -{ - GENERATED_BODY() - -protected: - UPROPERTY() - UGameStateManager* GameState; - - UPROPERTY() - UInputSimulator* InputSim; - - UPROPERTY() - UScenarioBuilder* Scenario; - - virtual void PrepareTest() override; - virtual void StartTest() override; - virtual void CleanUp() override; - - void WaitForGameReady(float Timeout = 10.f); -}; -``` - -**Godot Example:** - -```gdscript -extends GutTest -class_name GameE2ETestFixture - -var game_state: GameStateManager -var input_sim: InputSimulator -var scenario: ScenarioBuilder -var _scene_instance: Node - -func before_each(): - # Load game scene - var scene = load("res://scenes/game.tscn") - _scene_instance = scene.instantiate() - add_child(_scene_instance) - - # Get references - game_state = _scene_instance.get_node("GameStateManager") - input_sim = InputSimulator.new() - scenario = ScenarioBuilder.new(game_state) - - # Wait for ready - await wait_for_game_ready() - -func after_each(): - if _scene_instance: - _scene_instance.queue_free() - input_sim = null - scenario = null - -func wait_for_game_ready(timeout: float = 10.0): - var elapsed = 0.0 - while not game_state.is_ready and elapsed < timeout: - await get_tree().process_frame - elapsed += get_process_delta_time() - assert_true(game_state.is_ready, "Game should be ready") -``` - -### 2. Scenario Builder (Fluent API) - -Configure game state for test scenarios without manual setup. This is the secret sauce — it lets you express test preconditions in domain language. - -**Unity Example:** - -```csharp -public class ScenarioBuilder -{ - private readonly GameStateManager _gameState; - private readonly List> _setupActions = new(); - - public ScenarioBuilder(GameStateManager gameState) - { - _gameState = gameState; - } - - // Domain-specific setup methods - public ScenarioBuilder WithUnit(Faction faction, Hex position, int movementPoints = 6) - { - _setupActions.Add(() => SpawnUnit(faction, position, movementPoints)); - return this; - } - - public ScenarioBuilder WithTerrain(Hex position, TerrainType terrain) - { - _setupActions.Add(() => SetTerrain(position, terrain)); - return this; - } - - public ScenarioBuilder OnTurn(int turnNumber) - { - _setupActions.Add(() => SetTurn(turnNumber)); - return this; - } - - public ScenarioBuilder OnPhase(TurnPhase phase) - { - _setupActions.Add(() => SetPhase(phase)); - return this; - } - - public ScenarioBuilder WithActiveFaction(Faction faction) - { - _setupActions.Add(() => SetActiveFaction(faction)); - return this; - } - - public ScenarioBuilder FromSaveFile(string saveFileName) - { - _setupActions.Add(() => LoadSaveFile(saveFileName)); - return this; - } - - // Execute all setup actions - public IEnumerator Build() - { - foreach (var action in _setupActions) - { - yield return action(); - yield return null; // Allow state to propagate - } - _setupActions.Clear(); - } - - // Private implementation methods - private IEnumerator SpawnUnit(Faction faction, Hex position, int mp) - { - var unit = _gameState.SpawnUnit(faction, position); - unit.MovementPoints = mp; - yield return null; - } - - private IEnumerator SetTerrain(Hex position, TerrainType terrain) - { - _gameState.Map.SetTerrain(position, terrain); - yield return null; - } - - private IEnumerator SetTurn(int turn) - { - _gameState.SetTurnNumber(turn); - yield return null; - } - - private IEnumerator SetPhase(TurnPhase phase) - { - _gameState.SetPhase(phase); - yield return null; - } - - private IEnumerator SetActiveFaction(Faction faction) - { - _gameState.SetActiveFaction(faction); - yield return null; - } - - private IEnumerator LoadSaveFile(string fileName) - { - var path = $"TestData/{fileName}"; - yield return _gameState.LoadGame(path); - } -} -``` - -**Usage:** - -```csharp -yield return Scenario - .WithUnit(Faction.Player, new Hex(3, 4), movementPoints: 6) - .WithUnit(Faction.Enemy, new Hex(5, 4)) - .WithTerrain(new Hex(4, 4), TerrainType.Forest) - .OnTurn(1) - .WithActiveFaction(Faction.Player) - .Build(); -``` - -### 3. Input Simulator - -Abstract player input for deterministic testing. Don't simulate raw mouse positions — simulate player *intent*. - -**Unity Example (New Input System):** - -```csharp -using UnityEngine; -using UnityEngine.InputSystem; - -public class InputSimulator -{ - private Mouse _mouse; - private Keyboard _keyboard; - private Camera _camera; - - public InputSimulator() - { - _mouse = Mouse.current ?? InputSystem.AddDevice(); - _keyboard = Keyboard.current ?? InputSystem.AddDevice(); - _camera = Camera.main; - } - - public IEnumerator ClickWorldPosition(Vector3 worldPos) - { - var screenPos = _camera.WorldToScreenPoint(worldPos); - yield return ClickScreenPosition(screenPos); - } - - public IEnumerator ClickHex(Hex hex) - { - var worldPos = HexUtils.HexToWorld(hex); - yield return ClickWorldPosition(worldPos); - } - - public IEnumerator ClickScreenPosition(Vector2 screenPos) - { - // Move mouse - InputSystem.QueueStateEvent(_mouse, new MouseState { position = screenPos }); - yield return null; - - // Press - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = screenPos, - buttons = 1 - }); - yield return null; - - // Release - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = screenPos, - buttons = 0 - }); - yield return null; - } - - public IEnumerator ClickButton(string buttonName) - { - var button = GameObject.Find(buttonName)?.GetComponent(); - Assert.IsNotNull(button, $"Button '{buttonName}' not found"); - - button.onClick.Invoke(); - yield return null; - } - - public IEnumerator DragFromTo(Vector3 from, Vector3 to, float duration = 0.5f) - { - var fromScreen = _camera.WorldToScreenPoint(from); - var toScreen = _camera.WorldToScreenPoint(to); - - // Start drag - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = fromScreen, - buttons = 1 - }); - yield return null; - - // Interpolate drag - var elapsed = 0f; - while (elapsed < duration) - { - var t = elapsed / duration; - var pos = Vector2.Lerp(fromScreen, toScreen, t); - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = pos, - buttons = 1 - }); - yield return null; - elapsed += Time.deltaTime; - } - - // End drag - InputSystem.QueueStateEvent(_mouse, new MouseState - { - position = toScreen, - buttons = 0 - }); - yield return null; - } - - public IEnumerator PressKey(Key key) - { - _keyboard.SetKeyDown(key); - yield return null; - _keyboard.SetKeyUp(key); - yield return null; - } - - public void Reset() - { - // Reset any held state - if (_mouse != null) - { - InputSystem.QueueStateEvent(_mouse, new MouseState()); - } - } -} -``` - -### 4. Async Assertions - -Wait-for-condition assertions with meaningful failure messages. The timeout and message are critical — when tests fail, you need to know *what* it was waiting for. - -**Unity Example:** - -```csharp -using System; -using System.Collections; -using NUnit.Framework; -using UnityEngine; - -public static class AsyncAssert -{ - /// - /// Wait until condition is true, or fail with message after timeout. - /// - public static IEnumerator WaitUntil( - Func condition, - string description, - float timeout = 5f) - { - var elapsed = 0f; - while (!condition() && elapsed < timeout) - { - yield return null; - elapsed += Time.deltaTime; - } - - Assert.IsTrue(condition(), - $"Timeout after {timeout}s waiting for: {description}"); - } - - /// - /// Wait until condition is true, with periodic logging. - /// - public static IEnumerator WaitUntilVerbose( - Func condition, - string description, - float timeout = 5f, - float logInterval = 1f) - { - var elapsed = 0f; - var lastLog = 0f; - - while (!condition() && elapsed < timeout) - { - if (elapsed - lastLog >= logInterval) - { - Debug.Log($"[E2E] Still waiting for: {description} ({elapsed:F1}s)"); - lastLog = elapsed; - } - yield return null; - elapsed += Time.deltaTime; - } - - Assert.IsTrue(condition(), - $"Timeout after {timeout}s waiting for: {description}"); - } - - /// - /// Wait for a specific value, with descriptive failure. - /// Note: For floating-point comparisons, use WaitForValueApprox instead - /// to handle precision issues. This method uses exact equality. - /// - public static IEnumerator WaitForValue( - Func getter, - T expected, - string description, - float timeout = 5f) where T : IEquatable - { - yield return WaitUntil( - () => expected.Equals(getter()), - $"{description} to equal {expected} (current: {getter()})", - timeout); - } - - /// - /// Wait for a float value within tolerance (handles floating-point precision). - /// - public static IEnumerator WaitForValueApprox( - Func getter, - float expected, - string description, - float tolerance = 0.0001f, - float timeout = 5f) - { - yield return WaitUntil( - () => Mathf.Abs(expected - getter()) < tolerance, - $"{description} to equal ~{expected} ±{tolerance} (current: {getter()})", - timeout); - } - - /// - /// Wait for a double value within tolerance (handles floating-point precision). - /// - public static IEnumerator WaitForValueApprox( - Func getter, - double expected, - string description, - double tolerance = 0.0001, - float timeout = 5f) - { - yield return WaitUntil( - () => Math.Abs(expected - getter()) < tolerance, - $"{description} to equal ~{expected} ±{tolerance} (current: {getter()})", - timeout); - } - - /// - /// Wait for an event to fire. - /// - public static IEnumerator WaitForEvent( - Action> subscribe, - Action> unsubscribe, - string eventName, - float timeout = 5f) where T : class - { - T received = null; - Action handler = e => received = e; - - subscribe(handler); - - yield return WaitUntil( - () => received != null, - $"Event '{eventName}' to fire", - timeout); - - unsubscribe(handler); - } - - /// - /// Assert that something does NOT happen within a time window. - /// - public static IEnumerator WaitAndAssertNot( - Func condition, - string description, - float duration = 1f) - { - var elapsed = 0f; - while (elapsed < duration) - { - Assert.IsFalse(condition(), - $"Condition unexpectedly became true: {description}"); - yield return null; - elapsed += Time.deltaTime; - } - } -} -``` - -## E2E Test Patterns - -### Given-When-Then with Async - -The core pattern for E2E tests. Clear structure, readable intent. - -```csharp -[UnityTest] -public IEnumerator PlayerCanMoveUnitThroughZOC() -{ - // GIVEN: Soviet unit adjacent to German ZOC - yield return Scenario - .WithUnit(Faction.Soviet, new Hex(3, 4), movementPoints: 6) - .WithUnit(Faction.German, new Hex(4, 4)) // Creates ZOC at adjacent hexes - .WithActiveFaction(Faction.Soviet) - .Build(); - - // WHEN: Player selects unit and moves through ZOC - yield return Input.ClickHex(new Hex(3, 4)); // Select unit - yield return AsyncAssert.WaitUntil( - () => GameState.Selection.HasSelectedUnit, - "Unit should be selected"); - - yield return Input.ClickHex(new Hex(5, 4)); // Click destination (through ZOC) - - // THEN: Unit arrives with reduced movement points (ZOC cost) - yield return AsyncAssert.WaitUntil( - () => GetUnitAt(new Hex(5, 4)) != null, - "Unit should arrive at destination"); - - var unit = GetUnitAt(new Hex(5, 4)); - Assert.Less(unit.MovementPoints, 3, - "ZOC passage should cost extra movement points"); -} -``` - -### Full Turn Cycle - -Testing the complete turn lifecycle. - -```csharp -[UnityTest] -public IEnumerator FullTurnCycle_PlayerToAIAndBack() -{ - // GIVEN: Mid-game state with both factions having units - yield return Scenario - .FromSaveFile("mid_game_scenario.json") - .Build(); - - var startingTurn = GameState.TurnNumber; - - // WHEN: Player ends their turn - yield return Input.ClickButton("EndPhaseButton"); - yield return AsyncAssert.WaitUntil( - () => GameState.CurrentPhase == TurnPhase.EndPhaseConfirmation, - "End phase confirmation"); - - yield return Input.ClickButton("ConfirmButton"); - - // THEN: AI executes its turn - yield return AsyncAssert.WaitUntil( - () => GameState.CurrentFaction == Faction.AI, - "AI turn should begin"); - - // AND: Eventually returns to player - yield return AsyncAssert.WaitUntil( - () => GameState.CurrentFaction == Faction.Player, - "Player turn should return", - timeout: 30f); // AI might take a while - - Assert.AreEqual(startingTurn + 1, GameState.TurnNumber, - "Turn number should increment"); -} -``` - -### Save/Load Round-Trip - -Critical for any game with persistence. - -```csharp -[UnityTest] -public IEnumerator SaveLoad_PreservesGameState() -{ - // GIVEN: Game in specific state - yield return Scenario - .WithUnit(Faction.Player, new Hex(5, 5), movementPoints: 3) - .OnTurn(7) - .Build(); - - var unitPosition = new Hex(5, 5); - var originalMP = GetUnitAt(unitPosition).MovementPoints; - var originalTurn = GameState.TurnNumber; - - // WHEN: Save and reload - var savePath = "test_save_roundtrip"; - yield return GameState.SaveGame(savePath); - - // Trash the current state - yield return SceneManager.LoadSceneAsync(SceneName); - yield return WaitForGameReady(); - - // Load the save - yield return GameState.LoadGame(savePath); - yield return WaitForGameReady(); - - // THEN: State is preserved - Assert.AreEqual(originalTurn, GameState.TurnNumber, - "Turn number should be preserved"); - - var loadedUnit = GetUnitAt(unitPosition); - Assert.IsNotNull(loadedUnit, "Unit should exist at saved position"); - Assert.AreEqual(originalMP, loadedUnit.MovementPoints, - "Movement points should be preserved"); - - // Cleanup - var savedFilePath = GameState.GetSavePath(savePath); - if (System.IO.File.Exists(savedFilePath)) - { - try - { - System.IO.File.Delete(savedFilePath); - } - catch (System.IO.IOException ex) - { - Debug.LogWarning($"[E2E] Failed to delete test save file '{savedFilePath}': {ex.Message}"); - } - catch (UnauthorizedAccessException ex) - { - Debug.LogWarning($"[E2E] Access denied deleting test save file '{savedFilePath}': {ex.Message}"); - } - } -} -``` - -### UI Flow Testing - -Testing complete UI journeys. - -```csharp -[UnityTest] -public IEnumerator MainMenu_NewGame_ReachesGameplay() -{ - // GIVEN: At main menu - yield return SceneManager.LoadSceneAsync("MainMenu"); - yield return null; - - // WHEN: Start new game flow - yield return Input.ClickButton("NewGameButton"); - yield return AsyncAssert.WaitUntil( - () => FindPanel("DifficultySelect") != null, - "Difficulty selection should appear"); - - yield return Input.ClickButton("NormalDifficultyButton"); - yield return Input.ClickButton("StartButton"); - - // THEN: Game scene loads and is playable - yield return AsyncAssert.WaitUntil( - () => SceneManager.GetActiveScene().name == "GameScene", - "Game scene should load", - timeout: 10f); - - yield return WaitForGameReady(); - - Assert.AreEqual(TurnPhase.PlayerMovement, GameState.CurrentPhase, - "Should start in player movement phase"); -} -``` - -## What to E2E Test - -### High Priority (Test These) - -| Category | Why | Examples | -|----------|-----|----------| -| Core gameplay loop | 90% of player time | Select → Move → Attack → End Turn | -| Turn/phase transitions | State machine boundaries | Phase changes, turn handoff | -| Save → Load → Resume | Data integrity | Full round-trip with verification | -| Win/lose conditions | Critical path endpoints | Victory triggers, game over | -| Critical UI flows | First impressions | Menu → Game → Pause → Resume | - -### Medium Priority (Test Key Paths) - -| Category | Why | Examples | -|----------|-----|----------| -| Undo/redo | Easy to break | Action reversal | -| Multiplayer sync | Complex state | Turn handoff in MP | -| Tutorial flow | First-time experience | Guided sequence | - -### Low Priority (Usually Skip for E2E) - -| Category | Why | Better Tested By | -|----------|-----|------------------| -| Edge cases | Combinatorial explosion | Unit tests | -| Visual correctness | Subjective, changes often | Manual testing | -| Performance | Needs dedicated tooling | Performance tests | -| Every permutation | Infinite combinations | Unit + integration | -| AI decision quality | Subjective | Playtesting | - -## E2E Test Organization - -``` -Tests/ -├── EditMode/ -│ └── ... (existing unit tests) -├── PlayMode/ -│ ├── Integration/ -│ │ └── ... (existing integration tests) -│ └── E2E/ -│ ├── E2E.asmdef -│ ├── Infrastructure/ -│ │ ├── GameE2ETestFixture.cs -│ │ ├── ScenarioBuilder.cs -│ │ ├── InputSimulator.cs -│ │ └── AsyncAssert.cs -│ ├── Scenarios/ -│ │ ├── TurnCycleE2ETests.cs -│ │ ├── MovementE2ETests.cs -│ │ ├── CombatE2ETests.cs -│ │ ├── SaveLoadE2ETests.cs -│ │ └── UIFlowE2ETests.cs -│ └── TestData/ -│ ├── mid_game_scenario.json -│ ├── endgame_scenario.json -│ └── edge_case_setup.json -``` - -### Assembly Definition for E2E - -```json -{ - "name": "E2E", - "references": [ - "GameAssembly" - ], - "includePlatforms": [], - "excludePlatforms": [], - "allowUnsafeCode": false, - "overrideReferences": true, - "precompiledReferences": [ - "nunit.framework.dll", - "UnityEngine.TestRunner.dll", - "UnityEditor.TestRunner.dll" - ], - "defineConstraints": [ - "UNITY_INCLUDE_TESTS" - ], - "autoReferenced": false -} -``` - -## CI Considerations - -E2E tests are slower and potentially flaky. Handle with care. - -### Separate CI Job - -```yaml -# GitHub Actions example -e2e-tests: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: game-ci/unity-test-runner@v4 - with: - testMode: PlayMode - projectPath: . - customParameters: -testCategory E2E -``` - -### Retry Strategy - -```yaml -# Retry flaky tests once before failing -- uses: nick-fields/retry@v2 - with: - timeout_minutes: 15 - max_attempts: 2 - command: | - unity-test-runner --category E2E -``` - -### Failure Artifacts - -Capture screenshots and logs on failure: - -```csharp -[UnityTearDown] -public IEnumerator CaptureOnFailure() -{ - // Yield first to ensure we're on the main thread for screenshot capture - yield return null; - - if (TestContext.CurrentContext.Result.Outcome.Status == TestStatus.Failed) - { - var screenshot = ScreenCapture.CaptureScreenshotAsTexture(); - var bytes = screenshot.EncodeToPNG(); - var screenshotPath = $"TestResults/Screenshots/{TestContext.CurrentContext.Test.Name}.png"; - System.IO.File.WriteAllBytes(screenshotPath, bytes); - - Debug.Log($"[E2E FAILURE] Screenshot saved: {screenshotPath}"); - } -} -``` - -### Execution Frequency - -| Suite | When | Timeout | -|-------|------|---------| -| Unit tests | Every commit | 5 min | -| Integration | Every commit | 10 min | -| E2E (smoke) | Every commit | 15 min | -| E2E (full) | Nightly | 60 min | - -## Avoiding Flaky Tests - -E2E tests are notorious for flakiness. Fight it proactively. - -### DO - -- Use explicit waits with `AsyncAssert.WaitUntil` -- Wait for *game state*, not time -- Clean up thoroughly in TearDown -- Isolate tests completely -- Use deterministic scenarios -- Seed random number generators - -### DON'T - -- Use `yield return new WaitForSeconds(x)` as primary sync -- Depend on test execution order -- Share state between tests -- Rely on animation timing -- Assume frame-perfect timing -- Skip cleanup "because it's slow" - -### Debugging Flaky Tests - -```csharp -// Add verbose logging to track down race conditions -[UnityTest] -public IEnumerator FlakyTest_WithDebugging() -{ - Debug.Log($"[E2E] Test start: {Time.frameCount}"); - - yield return Scenario.Build(); - Debug.Log($"[E2E] Scenario built: {Time.frameCount}"); - - yield return Input.ClickHex(targetHex); - Debug.Log($"[E2E] Input sent: {Time.frameCount}, Selection: {GameState.Selection}"); - - yield return AsyncAssert.WaitUntilVerbose( - () => ExpectedCondition(), - "Expected condition", - timeout: 10f, - logInterval: 0.5f); -} -``` - -## Engine-Specific Notes - -### Unity - -- Use `[UnityTest]` attribute for coroutine-based tests -- Prefer `WaitUntil` over `WaitForSeconds` -- Use `Object.FindFirstObjectByType()` (not the deprecated `FindObjectOfType`) -- Consider `InputTestFixture` for Input System simulation -- Remember: `yield return null` waits one frame - -### Unreal - -- Use `FFunctionalTest` actors for level-based E2E -- `LatentIt` for async test steps in Automation Framework -- Gauntlet for extended E2E suites running in isolated processes -- `ADD_LATENT_AUTOMATION_COMMAND` for sequenced operations - -### Godot - -- Use `await` for async operations in GUT -- `await get_tree().create_timer(x).timeout` for timed waits -- Scene instancing provides natural test isolation -- Use `queue_free()` for cleanup, not `free()` (avoids errors) - -## Anti-Patterns - -### The "Test Everything" Trap - -Don't try to E2E test every edge case. That's what unit tests are for. - -```csharp -// BAD: Testing edge case via E2E -[UnityTest] -public IEnumerator Movement_WithExactlyZeroMP_CannotMove() // Unit test this -{ - // 30 seconds of setup for a condition unit tests cover -} - -// GOOD: E2E tests the journey, unit tests the edge cases -[UnityTest] -public IEnumerator Movement_TypicalPlayerJourney_WorksCorrectly() -{ - // Tests the common path players actually experience -} -``` - -### The "Magic Sleep" Pattern - -```csharp -// BAD: Hoping 2 seconds is enough -yield return new WaitForSeconds(2f); -Assert.IsTrue(condition); - -// GOOD: Wait for the actual condition -yield return AsyncAssert.WaitUntil(() => condition, "description"); -``` - -### The "Shared State" Trap - -```csharp -// BAD: Tests pollute each other -private static int testCounter = 0; // Shared between tests! - -// GOOD: Each test is isolated -[SetUp] -public void Setup() -{ - // Fresh state every test -} -``` - -## Measuring E2E Test Value - -### Coverage Metrics That Matter - -- **Journey coverage**: How many critical player paths are tested? -- **Failure detection rate**: How many real bugs do E2E tests catch? -- **False positive rate**: How often do E2E tests fail spuriously? - -### Warning Signs - -- E2E suite takes > 30 minutes -- Flaky test rate > 5% -- E2E tests duplicate unit test coverage -- Team skips E2E tests because they're "always broken" - -### Health Indicators - -- E2E tests catch integration bugs unit tests miss -- New features include E2E tests for happy path -- Flaky tests are fixed or removed within a sprint -- E2E suite runs on every PR (at least smoke subset) diff --git a/src/modules/bmgd/gametest/knowledge/godot-testing.md b/src/modules/bmgd/gametest/knowledge/godot-testing.md deleted file mode 100644 index ab79e093..00000000 --- a/src/modules/bmgd/gametest/knowledge/godot-testing.md +++ /dev/null @@ -1,875 +0,0 @@ -# Godot GUT Testing Guide - -## Overview - -GUT (Godot Unit Test) is the standard unit testing framework for Godot. It provides a full-featured testing framework with assertions, mocking, and CI integration. - -## Installation - -### Via Asset Library - -1. Open AssetLib in Godot -2. Search for "GUT" -3. Download and install -4. Enable the plugin in Project Settings - -### Via Git Submodule - -```bash -git submodule add https://github.com/bitwes/Gut.git addons/gut -``` - -## Project Structure - -``` -project/ -├── addons/ -│ └── gut/ -├── src/ -│ ├── player/ -│ │ └── player.gd -│ └── combat/ -│ └── damage_calculator.gd -└── tests/ - ├── unit/ - │ └── test_damage_calculator.gd - └── integration/ - └── test_player_combat.gd -``` - -## Basic Test Structure - -### Simple Test Class - -```gdscript -# tests/unit/test_damage_calculator.gd -extends GutTest - -var calculator: DamageCalculator - -func before_each(): - calculator = DamageCalculator.new() - -func after_each(): - calculator.free() - -func test_calculate_base_damage(): - var result = calculator.calculate(100.0, 1.0) - assert_eq(result, 100.0, "Base damage should equal input") - -func test_calculate_critical_hit(): - var result = calculator.calculate(100.0, 2.0) - assert_eq(result, 200.0, "Critical hit should double damage") - -func test_calculate_with_zero_multiplier(): - var result = calculator.calculate(100.0, 0.0) - assert_eq(result, 0.0, "Zero multiplier should result in zero damage") -``` - -### Parameterized Tests - -```gdscript -func test_damage_scenarios(): - var scenarios = [ - {"base": 100.0, "mult": 1.0, "expected": 100.0}, - {"base": 100.0, "mult": 2.0, "expected": 200.0}, - {"base": 50.0, "mult": 1.5, "expected": 75.0}, - {"base": 0.0, "mult": 2.0, "expected": 0.0}, - ] - - for scenario in scenarios: - var result = calculator.calculate(scenario.base, scenario.mult) - assert_eq( - result, - scenario.expected, - "Base %s * %s should equal %s" % [ - scenario.base, scenario.mult, scenario.expected - ] - ) -``` - -## Testing Nodes - -### Scene Testing - -```gdscript -# tests/integration/test_player.gd -extends GutTest - -var player: Player -var player_scene = preload("res://src/player/player.tscn") - -func before_each(): - player = player_scene.instantiate() - add_child(player) - -func after_each(): - player.queue_free() - -func test_player_initial_health(): - assert_eq(player.health, 100, "Player should start with 100 health") - -func test_player_takes_damage(): - player.take_damage(30) - assert_eq(player.health, 70, "Health should be reduced by damage") - -func test_player_dies_at_zero_health(): - player.take_damage(100) - assert_true(player.is_dead, "Player should be dead at 0 health") -``` - -### Testing with Signals - -```gdscript -func test_damage_emits_signal(): - watch_signals(player) - - player.take_damage(10) - - assert_signal_emitted(player, "health_changed") - assert_signal_emit_count(player, "health_changed", 1) - -func test_death_emits_signal(): - watch_signals(player) - - player.take_damage(100) - - assert_signal_emitted(player, "died") -``` - -### Testing with Await - -```gdscript -func test_attack_cooldown(): - player.attack() - assert_true(player.is_attacking) - - # Wait for cooldown - await get_tree().create_timer(player.attack_cooldown).timeout - - assert_false(player.is_attacking) - assert_true(player.can_attack) -``` - -## Mocking and Doubles - -### Creating Doubles - -```gdscript -func test_enemy_uses_pathfinding(): - var mock_pathfinding = double(Pathfinding).new() - stub(mock_pathfinding, "find_path").to_return([Vector2(0, 0), Vector2(10, 10)]) - - var enemy = Enemy.new() - enemy.pathfinding = mock_pathfinding - - enemy.move_to(Vector2(10, 10)) - - assert_called(mock_pathfinding, "find_path") -``` - -### Partial Doubles - -```gdscript -func test_player_inventory(): - var player_double = partial_double(Player).new() - stub(player_double, "save_to_disk").to_do_nothing() - - player_double.add_item("sword") - - assert_eq(player_double.inventory.size(), 1) - assert_called(player_double, "save_to_disk") -``` - -## Physics Testing - -### Testing Collision - -```gdscript -func test_projectile_hits_enemy(): - var projectile = Projectile.new() - var enemy = Enemy.new() - - add_child(projectile) - add_child(enemy) - - projectile.global_position = Vector2(0, 0) - enemy.global_position = Vector2(100, 0) - - projectile.velocity = Vector2(200, 0) - - # Simulate physics frames - for i in range(60): - await get_tree().physics_frame - - assert_true(enemy.was_hit, "Enemy should be hit by projectile") - - projectile.queue_free() - enemy.queue_free() -``` - -### Testing Area2D - -```gdscript -func test_pickup_collected(): - var pickup = Pickup.new() - var player = player_scene.instantiate() - - add_child(pickup) - add_child(player) - - pickup.global_position = Vector2(50, 50) - player.global_position = Vector2(50, 50) - - # Wait for physics to process overlap - await get_tree().physics_frame - await get_tree().physics_frame - - assert_true(pickup.is_queued_for_deletion(), "Pickup should be collected") - - player.queue_free() -``` - -## Input Testing - -### Simulating Input - -```gdscript -func test_jump_on_input(): - var input_event = InputEventKey.new() - input_event.keycode = KEY_SPACE - input_event.pressed = true - - Input.parse_input_event(input_event) - await get_tree().process_frame - - player._unhandled_input(input_event) - - assert_true(player.is_jumping, "Player should jump on space press") -``` - -### Testing Input Actions - -```gdscript -func test_attack_action(): - # Simulate action press - Input.action_press("attack") - await get_tree().process_frame - - player._process(0.016) - - assert_true(player.is_attacking) - - Input.action_release("attack") -``` - -## Resource Testing - -### Testing Custom Resources - -```gdscript -func test_weapon_stats_resource(): - var weapon = WeaponStats.new() - weapon.base_damage = 10.0 - weapon.attack_speed = 2.0 - - assert_eq(weapon.dps, 20.0, "DPS should be damage * speed") - -func test_save_load_resource(): - var original = PlayerData.new() - original.level = 5 - original.gold = 1000 - - ResourceSaver.save(original, "user://test_save.tres") - var loaded = ResourceLoader.load("user://test_save.tres") - - assert_eq(loaded.level, 5) - assert_eq(loaded.gold, 1000) - - DirAccess.remove_absolute("user://test_save.tres") -``` - -## GUT Configuration - -### gut_config.json - -```json -{ - "dirs": ["res://tests/"], - "include_subdirs": true, - "prefix": "test_", - "suffix": ".gd", - "should_exit": true, - "should_exit_on_success": true, - "log_level": 1, - "junit_xml_file": "results.xml", - "font_size": 16 -} -``` - -## CI Integration - -### Command Line Execution - -```bash -# Run all tests -godot --headless -s addons/gut/gut_cmdln.gd - -# Run specific tests -godot --headless -s addons/gut/gut_cmdln.gd \ - -gdir=res://tests/unit \ - -gprefix=test_ - -# With JUnit output -godot --headless -s addons/gut/gut_cmdln.gd \ - -gjunit_xml_file=results.xml -``` - -### GitHub Actions - -```yaml -test: - runs-on: ubuntu-latest - container: - image: barichello/godot-ci:4.2 - steps: - - uses: actions/checkout@v4 - - - name: Run Tests - run: | - godot --headless -s addons/gut/gut_cmdln.gd \ - -gjunit_xml_file=results.xml - - - name: Publish Results - uses: mikepenz/action-junit-report@v4 - with: - report_paths: results.xml -``` - -## Best Practices - -### DO - -- Use `before_each`/`after_each` for setup/teardown -- Free nodes after tests to prevent leaks -- Use meaningful assertion messages -- Group related tests in the same file -- Use `watch_signals` for signal testing -- Await physics frames when testing physics - -### DON'T - -- Don't test Godot's built-in functionality -- Don't rely on execution order between test files -- Don't leave orphan nodes -- Don't use `yield` (use `await` in Godot 4) -- Don't test private methods directly - -## Troubleshooting - -| Issue | Cause | Fix | -| -------------------- | ------------------ | ------------------------------------ | -| Tests not found | Wrong prefix/path | Check gut_config.json | -| Orphan nodes warning | Missing cleanup | Add `queue_free()` in `after_each` | -| Signal not detected | Signal not watched | Call `watch_signals()` before action | -| Physics not working | Missing frames | Await `physics_frame` | -| Flaky tests | Timing issues | Use proper await/signals | - -## C# Testing in Godot - -Godot 4 supports C# via .NET 6+. You can use standard .NET testing frameworks alongside GUT. - -### Project Setup for C# - -``` -project/ -├── addons/ -│ └── gut/ -├── src/ -│ ├── Player/ -│ │ └── PlayerController.cs -│ └── Combat/ -│ └── DamageCalculator.cs -├── tests/ -│ ├── gdscript/ -│ │ └── test_integration.gd -│ └── csharp/ -│ ├── Tests.csproj -│ └── DamageCalculatorTests.cs -└── project.csproj -``` - -### C# Test Project Setup - -Create a separate test project that references your game assembly: - -```xml - - - - net6.0 - true - false - - - - - - - - - - - - - -``` - -### Basic C# Unit Tests - -```csharp -// tests/csharp/DamageCalculatorTests.cs -using Xunit; -using YourGame.Combat; - -public class DamageCalculatorTests -{ - private readonly DamageCalculator _calculator; - - public DamageCalculatorTests() - { - _calculator = new DamageCalculator(); - } - - [Fact] - public void Calculate_BaseDamage_ReturnsCorrectValue() - { - var result = _calculator.Calculate(100f, 1f); - Assert.Equal(100f, result); - } - - [Fact] - public void Calculate_CriticalHit_DoublesDamage() - { - var result = _calculator.Calculate(100f, 2f); - Assert.Equal(200f, result); - } - - [Theory] - [InlineData(100f, 0.5f, 50f)] - [InlineData(100f, 1.5f, 150f)] - [InlineData(50f, 2f, 100f)] - public void Calculate_Parameterized_ReturnsExpected( - float baseDamage, float multiplier, float expected) - { - var result = _calculator.Calculate(baseDamage, multiplier); - Assert.Equal(expected, result); - } -} -``` - -### Testing Godot Nodes in C# - -For tests requiring Godot runtime, use a hybrid approach: - -```csharp -// tests/csharp/PlayerControllerTests.cs -using Godot; -using Xunit; -using YourGame.Player; - -public class PlayerControllerTests : IDisposable -{ - private readonly SceneTree _sceneTree; - private PlayerController _player; - - public PlayerControllerTests() - { - // These tests must run within Godot runtime - // Use GodotXUnit or similar adapter - } - - [GodotFact] // Custom attribute for Godot runtime tests - public async Task Player_Move_ChangesPosition() - { - var startPos = _player.GlobalPosition; - - _player.SetInput(new Vector2(1, 0)); - - await ToSignal(GetTree().CreateTimer(0.5f), "timeout"); - - Assert.True(_player.GlobalPosition.X > startPos.X); - } - - public void Dispose() - { - _player?.QueueFree(); - } -} -``` - -### C# Mocking with NSubstitute - -```csharp -using NSubstitute; -using Xunit; - -public class EnemyAITests -{ - [Fact] - public void Enemy_UsesPathfinding_WhenMoving() - { - var mockPathfinding = Substitute.For(); - mockPathfinding.FindPath(Arg.Any(), Arg.Any()) - .Returns(new[] { Vector2.Zero, new Vector2(10, 10) }); - - var enemy = new EnemyAI(mockPathfinding); - - enemy.MoveTo(new Vector2(10, 10)); - - mockPathfinding.Received().FindPath( - Arg.Any(), - Arg.Is(v => v == new Vector2(10, 10))); - } -} -``` - -### Running C# Tests - -```bash -# Run C# unit tests (no Godot runtime needed) -dotnet test tests/csharp/Tests.csproj - -# Run with coverage -dotnet test tests/csharp/Tests.csproj --collect:"XPlat Code Coverage" - -# Run specific test -dotnet test tests/csharp/Tests.csproj --filter "FullyQualifiedName~DamageCalculator" -``` - -### Hybrid Test Strategy - -| Test Type | Framework | When to Use | -| ------------- | ---------------- | ---------------------------------- | -| Pure logic | xUnit/NUnit (C#) | Classes without Godot dependencies | -| Node behavior | GUT (GDScript) | MonoBehaviour-like testing | -| Integration | GUT (GDScript) | Scene and signal testing | -| E2E | GUT (GDScript) | Full gameplay flows | - -## End-to-End Testing - -For comprehensive E2E testing patterns, infrastructure scaffolding, and -scenario builders, see **knowledge/e2e-testing.md**. - -### E2E Infrastructure for Godot - -#### GameE2ETestFixture (GDScript) - -```gdscript -# tests/e2e/infrastructure/game_e2e_test_fixture.gd -extends GutTest -class_name GameE2ETestFixture - -var game_state: GameStateManager -var input_sim: InputSimulator -var scenario: ScenarioBuilder -var _scene_instance: Node - -## Override to specify a different scene for specific test classes. -func get_scene_path() -> String: - return "res://scenes/game.tscn" - -func before_each(): - # Load game scene - var scene = load(get_scene_path()) - _scene_instance = scene.instantiate() - add_child(_scene_instance) - - # Get references - game_state = _scene_instance.get_node("GameStateManager") - assert_not_null(game_state, "GameStateManager not found in scene") - - input_sim = InputSimulator.new() - scenario = ScenarioBuilder.new(game_state) - - # Wait for ready - await wait_for_game_ready() - -func after_each(): - if _scene_instance: - _scene_instance.queue_free() - _scene_instance = null - input_sim = null - scenario = null - -func wait_for_game_ready(timeout: float = 10.0): - var elapsed = 0.0 - while not game_state.is_ready and elapsed < timeout: - await get_tree().process_frame - elapsed += get_process_delta_time() - assert_true(game_state.is_ready, "Game should be ready within timeout") -``` - -#### ScenarioBuilder (GDScript) - -```gdscript -# tests/e2e/infrastructure/scenario_builder.gd -extends RefCounted -class_name ScenarioBuilder - -var _game_state: GameStateManager -var _setup_actions: Array[Callable] = [] - -func _init(game_state: GameStateManager): - _game_state = game_state - -## Load a pre-configured scenario from a save file. -func from_save_file(file_name: String) -> ScenarioBuilder: - _setup_actions.append(func(): await _load_save_file(file_name)) - return self - -## Configure the current turn number. -func on_turn(turn_number: int) -> ScenarioBuilder: - _setup_actions.append(func(): _set_turn(turn_number)) - return self - -## Spawn a unit at position. -func with_unit(faction: int, position: Vector2, movement_points: int = 6) -> ScenarioBuilder: - _setup_actions.append(func(): await _spawn_unit(faction, position, movement_points)) - return self - -## Execute all configured setup actions. -func build() -> void: - for action in _setup_actions: - await action.call() - _setup_actions.clear() - -## Clear pending actions without executing. -func reset() -> void: - _setup_actions.clear() - -# Private implementation -func _load_save_file(file_name: String) -> void: - var path = "res://tests/e2e/test_data/%s" % file_name - await _game_state.load_game(path) - -func _set_turn(turn: int) -> void: - _game_state.set_turn_number(turn) - -func _spawn_unit(faction: int, pos: Vector2, mp: int) -> void: - var unit = _game_state.spawn_unit(faction, pos) - unit.movement_points = mp -``` - -#### InputSimulator (GDScript) - -```gdscript -# tests/e2e/infrastructure/input_simulator.gd -extends RefCounted -class_name InputSimulator - -## Click at a world position. -func click_world_position(world_pos: Vector2) -> void: - var viewport = Engine.get_main_loop().root.get_viewport() - var camera = viewport.get_camera_2d() - var screen_pos = camera.get_screen_center_position() + (world_pos - camera.global_position) - await click_screen_position(screen_pos) - -## Click at a screen position. -func click_screen_position(screen_pos: Vector2) -> void: - var press = InputEventMouseButton.new() - press.button_index = MOUSE_BUTTON_LEFT - press.pressed = true - press.position = screen_pos - - var release = InputEventMouseButton.new() - release.button_index = MOUSE_BUTTON_LEFT - release.pressed = false - release.position = screen_pos - - Input.parse_input_event(press) - await Engine.get_main_loop().process_frame - Input.parse_input_event(release) - await Engine.get_main_loop().process_frame - -## Click a UI button by name. -func click_button(button_name: String) -> void: - var root = Engine.get_main_loop().root - var button = _find_button_recursive(root, button_name) - assert(button != null, "Button '%s' not found in scene tree" % button_name) - - if not button.visible: - push_warning("[InputSimulator] Button '%s' is not visible" % button_name) - if button.disabled: - push_warning("[InputSimulator] Button '%s' is disabled" % button_name) - - button.pressed.emit() - await Engine.get_main_loop().process_frame - -func _find_button_recursive(node: Node, button_name: String) -> Button: - if node is Button and node.name == button_name: - return node - for child in node.get_children(): - var found = _find_button_recursive(child, button_name) - if found: - return found - return null - -## Press and release a key. -func press_key(keycode: Key) -> void: - var press = InputEventKey.new() - press.keycode = keycode - press.pressed = true - - var release = InputEventKey.new() - release.keycode = keycode - release.pressed = false - - Input.parse_input_event(press) - await Engine.get_main_loop().process_frame - Input.parse_input_event(release) - await Engine.get_main_loop().process_frame - -## Simulate an input action. -func action_press(action_name: String) -> void: - Input.action_press(action_name) - await Engine.get_main_loop().process_frame - -func action_release(action_name: String) -> void: - Input.action_release(action_name) - await Engine.get_main_loop().process_frame - -## Reset all input state. -func reset() -> void: - Input.flush_buffered_events() -``` - -#### AsyncAssert (GDScript) - -```gdscript -# tests/e2e/infrastructure/async_assert.gd -extends RefCounted -class_name AsyncAssert - -## Wait until condition is true, or fail after timeout. -static func wait_until( - condition: Callable, - description: String, - timeout: float = 5.0 -) -> void: - var elapsed := 0.0 - while not condition.call() and elapsed < timeout: - await Engine.get_main_loop().process_frame - elapsed += Engine.get_main_loop().root.get_process_delta_time() - - assert(condition.call(), - "Timeout after %.1fs waiting for: %s" % [timeout, description]) - -## Wait for a value to equal expected. -static func wait_for_value( - getter: Callable, - expected: Variant, - description: String, - timeout: float = 5.0 -) -> void: - await wait_until( - func(): return getter.call() == expected, - "%s to equal '%s' (current: '%s')" % [description, expected, getter.call()], - timeout) - -## Wait for a float value within tolerance. -static func wait_for_value_approx( - getter: Callable, - expected: float, - description: String, - tolerance: float = 0.0001, - timeout: float = 5.0 -) -> void: - await wait_until( - func(): return absf(expected - getter.call()) < tolerance, - "%s to equal ~%s ±%s (current: %s)" % [description, expected, tolerance, getter.call()], - timeout) - -## Assert that condition does NOT become true within duration. -static func assert_never_true( - condition: Callable, - description: String, - duration: float = 1.0 -) -> void: - var elapsed := 0.0 - while elapsed < duration: - assert(not condition.call(), - "Condition unexpectedly became true: %s" % description) - await Engine.get_main_loop().process_frame - elapsed += Engine.get_main_loop().root.get_process_delta_time() - -## Wait for specified number of frames. -static func wait_frames(count: int) -> void: - for i in range(count): - await Engine.get_main_loop().process_frame - -## Wait for physics to settle. -static func wait_for_physics(frames: int = 3) -> void: - for i in range(frames): - await Engine.get_main_loop().root.get_tree().physics_frame -``` - -### Example E2E Test (GDScript) - -```gdscript -# tests/e2e/scenarios/test_combat_flow.gd -extends GameE2ETestFixture - -func test_player_can_attack_enemy(): - # GIVEN: Player and enemy in combat range - await scenario \ - .with_unit(Faction.PLAYER, Vector2(100, 100)) \ - .with_unit(Faction.ENEMY, Vector2(150, 100)) \ - .build() - - var enemy = game_state.get_units(Faction.ENEMY)[0] - var initial_health = enemy.health - - # WHEN: Player attacks - await input_sim.click_world_position(Vector2(100, 100)) # Select player - await AsyncAssert.wait_until( - func(): return game_state.selected_unit != null, - "Unit should be selected") - - await input_sim.click_world_position(Vector2(150, 100)) # Attack enemy - - # THEN: Enemy takes damage - await AsyncAssert.wait_until( - func(): return enemy.health < initial_health, - "Enemy should take damage") - -func test_turn_cycle_completes(): - # GIVEN: Game in progress - await scenario.on_turn(1).build() - var starting_turn = game_state.turn_number - - # WHEN: Player ends turn - await input_sim.click_button("EndTurnButton") - await AsyncAssert.wait_until( - func(): return game_state.current_faction == Faction.ENEMY, - "Should switch to enemy turn") - - # AND: Enemy turn completes - await AsyncAssert.wait_until( - func(): return game_state.current_faction == Faction.PLAYER, - "Should return to player turn", - 30.0) # AI might take a while - - # THEN: Turn number incremented - assert_eq(game_state.turn_number, starting_turn + 1) -``` - -### Quick E2E Checklist for Godot - -- [ ] Create `GameE2ETestFixture` base class extending GutTest -- [ ] Implement `ScenarioBuilder` for your game's domain -- [ ] Create `InputSimulator` wrapping Godot Input -- [ ] Add `AsyncAssert` utilities with proper await -- [ ] Organize E2E tests under `tests/e2e/scenarios/` -- [ ] Configure GUT to include E2E test directory -- [ ] Set up CI with headless Godot execution diff --git a/src/modules/bmgd/gametest/knowledge/input-testing.md b/src/modules/bmgd/gametest/knowledge/input-testing.md deleted file mode 100644 index ed4f7b37..00000000 --- a/src/modules/bmgd/gametest/knowledge/input-testing.md +++ /dev/null @@ -1,315 +0,0 @@ -# Input Testing Guide - -## Overview - -Input testing validates that all supported input devices work correctly across platforms. Poor input handling frustrates players instantly—responsive, accurate input is foundational to game feel. - -## Input Categories - -### Device Types - -| Device | Platforms | Key Concerns | -| ----------------- | -------------- | ----------------------------------- | -| Keyboard + Mouse | PC | Key conflicts, DPI sensitivity | -| Gamepad (Xbox/PS) | PC, Console | Deadzone, vibration, button prompts | -| Touch | Mobile, Switch | Multi-touch, gesture recognition | -| Motion Controls | Switch, VR | Calibration, drift, fatigue | -| Specialty | Various | Flight sticks, wheels, fight sticks | - -### Input Characteristics - -| Characteristic | Description | Test Focus | -| -------------- | ---------------------------- | -------------------------------- | -| Responsiveness | Input-to-action delay | Should feel instant (< 100ms) | -| Accuracy | Input maps to correct action | No ghost inputs or missed inputs | -| Consistency | Same input = same result | Deterministic behavior | -| Accessibility | Alternative input support | Remapping, assist options | - -## Test Scenarios - -### Keyboard and Mouse - -``` -SCENARIO: All Keybinds Functional - GIVEN default keyboard bindings - WHEN each bound key is pressed - THEN corresponding action triggers - AND no key conflicts exist - -SCENARIO: Key Remapping - GIVEN player remaps "Jump" from Space to F - WHEN F is pressed - THEN jump action triggers - AND Space no longer triggers jump - AND remapping persists after restart - -SCENARIO: Mouse Sensitivity - GIVEN sensitivity set to 5 (mid-range) - WHEN mouse moves 10cm - THEN camera rotation matches expected degrees - AND movement feels consistent at different frame rates - -SCENARIO: Mouse Button Support - GIVEN mouse with 5+ buttons - WHEN side buttons are pressed - THEN they can be bound to actions - AND they function correctly in gameplay -``` - -### Gamepad - -``` -SCENARIO: Analog Stick Deadzone - GIVEN controller with slight stick drift - WHEN stick is in neutral position - THEN no movement occurs (deadzone filters drift) - AND intentional small movements still register - -SCENARIO: Trigger Pressure - GIVEN analog triggers - WHEN trigger is partially pressed - THEN partial values are read (e.g., 0.5 for half-press) - AND full press reaches 1.0 - -SCENARIO: Controller Hot-Swap - GIVEN game running with keyboard - WHEN gamepad is connected - THEN input prompts switch to gamepad icons - AND gamepad input works immediately - AND keyboard still works if used - -SCENARIO: Vibration Feedback - GIVEN rumble-enabled controller - WHEN damage is taken - THEN controller vibrates appropriately - AND vibration intensity matches damage severity -``` - -### Touch Input - -``` -SCENARIO: Multi-Touch Accuracy - GIVEN virtual joystick and buttons - WHEN left thumb on joystick AND right thumb on button - THEN both inputs register simultaneously - AND no interference between touch points - -SCENARIO: Gesture Recognition - GIVEN swipe-to-attack mechanic - WHEN player swipes right - THEN attack direction matches swipe - AND swipe is distinguished from tap - -SCENARIO: Touch Target Size - GIVEN minimum touch target of 44x44 points - WHEN buttons are placed - THEN all interactive elements meet minimum size - AND elements have adequate spacing -``` - -## Platform-Specific Testing - -### PC - -- Multiple keyboard layouts (QWERTY, AZERTY, QWERTZ) -- Different mouse DPI settings (400-3200+) -- Multiple monitors (cursor confinement) -- Background application conflicts -- Steam Input API integration - -### Console - -| Platform | Specific Tests | -| ----------- | ------------------------------------------ | -| PlayStation | Touchpad, adaptive triggers, haptics | -| Xbox | Impulse triggers, Elite controller paddles | -| Switch | Joy-Con detachment, gyro, HD rumble | - -### Mobile - -- Different screen sizes and aspect ratios -- Notch/cutout avoidance -- External controller support -- Apple MFi / Android gamepad compatibility - -## Automated Test Examples - -### Unity - -```csharp -using UnityEngine.InputSystem; - -[UnityTest] -public IEnumerator Movement_WithGamepad_RespondsToStick() -{ - var gamepad = InputSystem.AddDevice(); - - yield return null; - - // Simulate stick input - Set(gamepad.leftStick, new Vector2(1, 0)); - yield return new WaitForSeconds(0.1f); - - Assert.Greater(player.transform.position.x, 0f, - "Player should move right"); - - InputSystem.RemoveDevice(gamepad); -} - -[UnityTest] -public IEnumerator InputLatency_UnderLoad_StaysAcceptable() -{ - float inputTime = Time.realtimeSinceStartup; - bool actionTriggered = false; - - player.OnJump += () => { - float latency = (Time.realtimeSinceStartup - inputTime) * 1000; - Assert.Less(latency, 100f, "Input latency should be under 100ms"); - actionTriggered = true; - }; - - var keyboard = InputSystem.AddDevice(); - Press(keyboard.spaceKey); - - yield return new WaitForSeconds(0.2f); - - Assert.IsTrue(actionTriggered, "Jump should have triggered"); -} - -[Test] -public void Deadzone_FiltersSmallInputs() -{ - var settings = new InputSettings { stickDeadzone = 0.2f }; - - // Input below deadzone - var filtered = InputProcessor.ApplyDeadzone(new Vector2(0.1f, 0.1f), settings); - Assert.AreEqual(Vector2.zero, filtered); - - // Input above deadzone - filtered = InputProcessor.ApplyDeadzone(new Vector2(0.5f, 0.5f), settings); - Assert.AreNotEqual(Vector2.zero, filtered); -} -``` - -### Unreal - -```cpp -bool FInputTest::RunTest(const FString& Parameters) -{ - // Test gamepad input mapping - APlayerController* PC = GetWorld()->GetFirstPlayerController(); - - // Simulate gamepad stick input - FInputKeyParams Params; - Params.Key = EKeys::Gamepad_LeftX; - Params.Delta = FVector(1.0f, 0, 0); - PC->InputKey(Params); - - // Verify movement - APawn* Pawn = PC->GetPawn(); - FVector Velocity = Pawn->GetVelocity(); - - TestTrue("Pawn should be moving", Velocity.SizeSquared() > 0); - - return true; -} -``` - -### Godot - -```gdscript -func test_input_action_mapping(): - # Verify action exists - assert_true(InputMap.has_action("jump")) - - # Simulate input - var event = InputEventKey.new() - event.keycode = KEY_SPACE - event.pressed = true - - Input.parse_input_event(event) - await get_tree().process_frame - - assert_true(Input.is_action_just_pressed("jump")) - -func test_gamepad_deadzone(): - var input = Vector2(0.15, 0.1) - var deadzone = 0.2 - - var processed = input_processor.apply_deadzone(input, deadzone) - - assert_eq(processed, Vector2.ZERO, "Small input should be filtered") - -func test_controller_hotswap(): - # Simulate controller connect - Input.joy_connection_changed(0, true) - await get_tree().process_frame - - var prompt_icon = ui.get_action_prompt("jump") - - assert_true(prompt_icon.texture.resource_path.contains("gamepad"), - "Should show gamepad prompts after controller connect") -``` - -## Accessibility Testing - -### Requirements Checklist - -- [ ] Full keyboard navigation (no mouse required) -- [ ] Remappable controls for all actions -- [ ] Button hold alternatives to rapid press -- [ ] Toggle options for hold actions -- [ ] One-handed control schemes -- [ ] Colorblind-friendly UI indicators -- [ ] Screen reader support for menus - -### Accessibility Test Scenarios - -``` -SCENARIO: Keyboard-Only Navigation - GIVEN mouse is disconnected - WHEN navigating through all menus - THEN all menu items are reachable via keyboard - AND focus indicators are clearly visible - -SCENARIO: Button Hold Toggle - GIVEN "sprint requires hold" is toggled OFF - WHEN sprint button is tapped once - THEN sprint activates - AND sprint stays active until tapped again - -SCENARIO: Reduced Button Mashing - GIVEN QTE assist mode enabled - WHEN QTE sequence appears - THEN single press advances sequence - AND no rapid input required -``` - -## Performance Metrics - -| Metric | Target | Maximum Acceptable | -| ----------------------- | --------------- | ------------------ | -| Input-to-render latency | < 50ms | 100ms | -| Polling rate match | 1:1 with device | No input loss | -| Deadzone processing | < 1ms | 5ms | -| Rebind save/load | < 100ms | 500ms | - -## Best Practices - -### DO - -- Test with actual hardware, not just simulated input -- Support simultaneous keyboard + gamepad -- Provide sensible default deadzones -- Show device-appropriate button prompts -- Allow complete control remapping -- Test at different frame rates - -### DON'T - -- Assume controller layout (Xbox vs PlayStation) -- Hard-code input mappings -- Ignore analog input precision -- Skip accessibility considerations -- Forget about input during loading/cutscenes -- Neglect testing with worn/drifting controllers diff --git a/src/modules/bmgd/gametest/knowledge/localization-testing.md b/src/modules/bmgd/gametest/knowledge/localization-testing.md deleted file mode 100644 index fd4b0344..00000000 --- a/src/modules/bmgd/gametest/knowledge/localization-testing.md +++ /dev/null @@ -1,304 +0,0 @@ -# Localization Testing Guide - -## Overview - -Localization testing ensures games work correctly across languages, regions, and cultures. Beyond translation, it validates text display, cultural appropriateness, and regional compliance. - -## Test Categories - -### Linguistic Testing - -| Category | Focus | Examples | -| -------------------- | ----------------------- | ------------------------------ | -| Translation accuracy | Meaning preserved | Idioms, game terminology | -| Grammar/spelling | Language correctness | Verb tense, punctuation | -| Consistency | Same terms throughout | "Health" vs "HP" vs "Life" | -| Context | Meaning in game context | Item names, skill descriptions | - -### Functional Testing - -| Category | Focus | Examples | -| -------------- | ----------------------- | --------------------------- | -| Text display | Fits in UI | Button labels, dialog boxes | -| Font support | Characters render | CJK, Cyrillic, Arabic | -| Text expansion | Longer translations | German is ~30% longer | -| RTL support | Right-to-left languages | Arabic, Hebrew layouts | - -### Cultural Testing - -| Category | Focus | Examples | -| -------------------- | ------------------ | ------------------------- | -| Cultural sensitivity | Offensive content | Gestures, symbols, colors | -| Regional compliance | Legal requirements | Ratings, gambling laws | -| Date/time formats | Local conventions | DD/MM/YYYY vs MM/DD/YYYY | -| Number formats | Decimal separators | 1,000.00 vs 1.000,00 | - -## Test Scenarios - -### Text Display - -``` -SCENARIO: Text Fits UI Elements - GIVEN all localized strings - WHEN displayed in target language - THEN text fits within UI boundaries - AND no truncation or overflow occurs - AND text remains readable - -SCENARIO: Dynamic Text Insertion - GIVEN template "Player {name} scored {points} points" - WHEN name="Alexander" and points=1000 - THEN German: "Spieler Alexander hat 1.000 Punkte erzielt" - AND text fits UI element - AND variables are correctly formatted for locale - -SCENARIO: Plural Forms - GIVEN English "1 coin" / "5 coins" - WHEN displaying in Polish (4 plural forms) - THEN correct plural form is used - AND all plural forms are translated -``` - -### Character Support - -``` -SCENARIO: CJK Character Rendering - GIVEN Japanese localization - WHEN displaying text with kanji/hiragana/katakana - THEN all characters render correctly - AND no missing glyphs (tofu boxes) - AND line breaks respect CJK rules - -SCENARIO: Special Characters - GIVEN text with accented characters (é, ñ, ü) - WHEN displayed in-game - THEN all characters render correctly - AND sorting works correctly - -SCENARIO: User-Generated Content - GIVEN player can name character - WHEN name includes non-Latin characters - THEN name displays correctly - AND name saves/loads correctly - AND name appears correctly to other players -``` - -### Layout and Direction - -``` -SCENARIO: Right-to-Left Layout - GIVEN Arabic localization - WHEN viewing UI - THEN text reads right-to-left - AND UI elements mirror appropriately - AND numbers remain left-to-right - AND mixed content (Arabic + English) displays correctly - -SCENARIO: Text Expansion Accommodation - GIVEN English UI "OK" / "Cancel" buttons - WHEN localized to German "OK" / "Abbrechen" - THEN button expands or text size adjusts - AND button remains clickable - AND layout doesn't break -``` - -## Locale-Specific Formatting - -### Date and Time - -| Locale | Date Format | Time Format | -| ------ | -------------- | ----------- | -| en-US | 12/25/2024 | 3:30 PM | -| en-GB | 25/12/2024 | 15:30 | -| de-DE | 25.12.2024 | 15:30 Uhr | -| ja-JP | 2024年12月25日 | 15時30分 | - -### Numbers and Currency - -| Locale | Number | Currency | -| ------ | -------- | ---------- | -| en-US | 1,234.56 | $1,234.56 | -| de-DE | 1.234,56 | 1.234,56 € | -| fr-FR | 1 234,56 | 1 234,56 € | -| ja-JP | 1,234.56 | ¥1,235 | - -## Automated Test Examples - -### Unity - -```csharp -using UnityEngine.Localization; - -[Test] -public void Localization_AllKeysHaveTranslations([Values("en", "de", "ja", "zh-CN")] string locale) -{ - var stringTable = LocalizationSettings.StringDatabase - .GetTable("GameStrings", new Locale(locale)); - - foreach (var entry in stringTable) - { - Assert.IsFalse(string.IsNullOrEmpty(entry.Value.LocalizedValue), - $"Missing translation for '{entry.Key}' in {locale}"); - } -} - -[Test] -public void TextFits_AllUIElements() -{ - var languages = new[] { "en", "de", "fr", "ja" }; - - foreach (var lang in languages) - { - LocalizationSettings.SelectedLocale = new Locale(lang); - - foreach (var textElement in FindObjectsOfType()) - { - var rectTransform = textElement.GetComponent(); - var textComponent = textElement.GetComponent(); - - Assert.LessOrEqual( - textComponent.preferredWidth, - rectTransform.rect.width, - $"Text overflows in {lang}: {textElement.name}"); - } - } -} - -[TestCase("en", 1, "1 coin")] -[TestCase("en", 5, "5 coins")] -[TestCase("ru", 1, "1 монета")] -[TestCase("ru", 2, "2 монеты")] -[TestCase("ru", 5, "5 монет")] -public void Pluralization_ReturnsCorrectForm(string locale, int count, string expected) -{ - var result = Localization.GetPlural("coin", count, locale); - Assert.AreEqual(expected, result); -} -``` - -### Unreal - -```cpp -bool FLocalizationTest::RunTest(const FString& Parameters) -{ - TArray Cultures = {"en", "de", "ja", "ko"}; - - for (const FString& Culture : Cultures) - { - FInternationalization::Get().SetCurrentCulture(Culture); - - // Test critical strings exist - FText LocalizedText = NSLOCTEXT("Game", "StartButton", "Start"); - TestFalse( - FString::Printf(TEXT("Missing StartButton in %s"), *Culture), - LocalizedText.IsEmpty()); - - // Test number formatting - FText NumberText = FText::AsNumber(1234567); - TestTrue( - TEXT("Number should be formatted"), - NumberText.ToString().Len() > 7); // Has separators - } - - return true; -} -``` - -### Godot - -```gdscript -func test_all_translations_complete(): - var locales = ["en", "de", "ja", "es"] - var keys = TranslationServer.get_all_keys() - - for locale in locales: - TranslationServer.set_locale(locale) - for key in keys: - var translated = tr(key) - assert_ne(translated, key, - "Missing translation for '%s' in %s" % [key, locale]) - -func test_plural_forms(): - TranslationServer.set_locale("ru") - - assert_eq(tr_n("coin", "coins", 1), "1 монета") - assert_eq(tr_n("coin", "coins", 2), "2 монеты") - assert_eq(tr_n("coin", "coins", 5), "5 монет") - assert_eq(tr_n("coin", "coins", 21), "21 монета") - -func test_text_fits_buttons(): - var locales = ["en", "de", "fr"] - - for locale in locales: - TranslationServer.set_locale(locale) - await get_tree().process_frame # Allow UI update - - for button in get_tree().get_nodes_in_group("localized_buttons"): - var label = button.get_node("Label") - assert_lt(label.size.x, button.size.x, - "Button text overflows in %s: %s" % [locale, button.name]) -``` - -## Visual Verification Checklist - -### Text Display - -- [ ] No truncation in any language -- [ ] Consistent font sizing -- [ ] Proper line breaks -- [ ] No overlapping text - -### UI Layout - -- [ ] Buttons accommodate longer text -- [ ] Dialog boxes resize appropriately -- [ ] Menu items align correctly -- [ ] Scrollbars appear when needed - -### Cultural Elements - -- [ ] Icons are culturally appropriate -- [ ] Colors don't have negative connotations -- [ ] Gestures are region-appropriate -- [ ] No unintended political references - -## Regional Compliance - -### Ratings Requirements - -| Region | Rating Board | Special Requirements | -| ------------- | ------------ | ------------------------- | -| North America | ESRB | Content descriptors | -| Europe | PEGI | Age-appropriate icons | -| Japan | CERO | Strict content guidelines | -| Germany | USK | Violence restrictions | -| China | GRAC | Approval process | - -### Common Regional Issues - -| Issue | Regions Affected | Solution | -| ---------------- | ---------------- | ------------------------ | -| Blood color | Japan, Germany | Option for green/disable | -| Gambling imagery | Many regions | Remove or modify | -| Skulls/bones | China | Alternative designs | -| Nazi imagery | Germany | Remove entirely | - -## Best Practices - -### DO - -- Test with native speakers -- Plan for text expansion (reserve 30% extra space) -- Use placeholder text during development (Lorem ipsum-style) -- Support multiple input methods (IME for CJK) -- Test all language combinations (UI language + audio language) -- Validate string format parameters - -### DON'T - -- Hard-code strings in source code -- Assume left-to-right layout -- Concatenate translated strings -- Use machine translation without review -- Forget about date/time/number formatting -- Ignore cultural context of images and icons diff --git a/src/modules/bmgd/gametest/knowledge/multiplayer-testing.md b/src/modules/bmgd/gametest/knowledge/multiplayer-testing.md deleted file mode 100644 index 7ee8ddf1..00000000 --- a/src/modules/bmgd/gametest/knowledge/multiplayer-testing.md +++ /dev/null @@ -1,322 +0,0 @@ -# Multiplayer Testing Guide - -## Overview - -Multiplayer testing validates network code, synchronization, and the player experience under real-world conditions. Network bugs are notoriously hard to reproduce—systematic testing is essential. - -## Test Categories - -### Synchronization Testing - -| Test Type | Description | Priority | -| ------------------- | ---------------------------------------- | -------- | -| State sync | All clients see consistent game state | P0 | -| Position sync | Character positions match across clients | P0 | -| Event ordering | Actions occur in correct sequence | P0 | -| Conflict resolution | Simultaneous actions handled correctly | P1 | -| Late join | New players sync correctly mid-game | P1 | - -### Network Conditions - -| Condition | Simulation Method | Test Focus | -| --------------- | ----------------- | ------------------------ | -| High latency | 200-500ms delay | Input responsiveness | -| Packet loss | 5-20% drop rate | State recovery | -| Jitter | Variable delay | Interpolation smoothness | -| Bandwidth limit | Throttle to 1Mbps | Data prioritization | -| Disconnection | Kill connection | Reconnection handling | - -## Test Scenarios - -### Basic Multiplayer - -``` -SCENARIO: Player Join/Leave - GIVEN host has started multiplayer session - WHEN Player 2 joins - THEN Player 2 appears in host's game - AND Player 1 appears in Player 2's game - AND player counts sync across all clients - -SCENARIO: State Synchronization - GIVEN 4 players in match - WHEN Player 1 picks up item at position (10, 5) - THEN item disappears for all players - AND Player 1's inventory updates for all players - AND no duplicate pickups possible - -SCENARIO: Combat Synchronization - GIVEN Player 1 attacks Player 2 - WHEN attack hits - THEN damage is consistent on all clients - AND hit effects play for all players - AND health updates sync within 100ms -``` - -### Network Degradation - -``` -SCENARIO: High Latency Gameplay - GIVEN 200ms latency between players - WHEN Player 1 moves forward - THEN movement is smooth on Player 1's screen - AND other players see interpolated movement - AND position converges within 500ms - -SCENARIO: Packet Loss Recovery - GIVEN 10% packet loss - WHEN important game event occurs (goal, kill, etc.) - THEN event is eventually delivered - AND game state remains consistent - AND no duplicate events processed - -SCENARIO: Player Disconnection - GIVEN Player 2 disconnects unexpectedly - WHEN 5 seconds pass - THEN other players are notified - AND Player 2's character handles gracefully (despawn/AI takeover) - AND game continues without crash -``` - -### Edge Cases - -``` -SCENARIO: Simultaneous Actions - GIVEN Player 1 and Player 2 grab same item simultaneously - WHEN both inputs arrive at server - THEN only one player receives item - AND other player sees consistent state - AND no item duplication - -SCENARIO: Host Migration - GIVEN host disconnects - WHEN migration begins - THEN new host is selected - AND game state transfers correctly - AND gameplay resumes within 10 seconds - -SCENARIO: Reconnection - GIVEN Player 2 disconnects temporarily - WHEN Player 2 reconnects within 60 seconds - THEN Player 2 rejoins same session - AND state is synchronized - AND progress is preserved -``` - -## Network Simulation Tools - -### Unity - -```csharp -// Using Unity Transport with Network Simulator -using Unity.Netcode; - -public class NetworkSimulator : MonoBehaviour -{ - [SerializeField] private int latencyMs = 100; - [SerializeField] private float packetLossPercent = 5f; - [SerializeField] private int jitterMs = 20; - - void Start() - { - var transport = NetworkManager.Singleton.GetComponent(); - var simulator = transport.GetSimulatorParameters(); - - simulator.PacketDelayMS = latencyMs; - simulator.PacketDropRate = (int)(packetLossPercent * 100); - simulator.PacketJitterMS = jitterMs; - } -} - -// Test -[UnityTest] -public IEnumerator Position_UnderLatency_ConvergesWithinThreshold() -{ - EnableNetworkSimulation(latencyMs: 200); - - // Move player - player1.Move(Vector3.forward * 10); - - yield return new WaitForSeconds(1f); - - // Check other client's view - var player1OnClient2 = client2.GetPlayerPosition(player1.Id); - var actualPosition = player1.transform.position; - - Assert.Less(Vector3.Distance(player1OnClient2, actualPosition), 0.5f); -} -``` - -### Unreal - -```cpp -// Using Network Emulation -void UNetworkTestHelper::EnableLatencySimulation(int32 LatencyMs) -{ - if (UNetDriver* NetDriver = GetWorld()->GetNetDriver()) - { - FPacketSimulationSettings Settings; - Settings.PktLag = LatencyMs; - Settings.PktLagVariance = LatencyMs / 10; - Settings.PktLoss = 0; - - NetDriver->SetPacketSimulationSettings(Settings); - } -} - -// Functional test for sync -void AMultiplayerSyncTest::StartTest() -{ - Super::StartTest(); - - // Spawn item on server - APickupItem* Item = GetWorld()->SpawnActor( - ItemClass, FVector(0, 0, 100)); - - // Wait for replication - FTimerHandle TimerHandle; - GetWorld()->GetTimerManager().SetTimer(TimerHandle, [this, Item]() - { - // Verify client has item - if (VerifyItemExistsOnAllClients(Item)) - { - FinishTest(EFunctionalTestResult::Succeeded, "Item replicated"); - } - else - { - FinishTest(EFunctionalTestResult::Failed, "Item not found on clients"); - } - }, 2.0f, false); -} -``` - -### Godot - -```gdscript -# Network simulation -extends Node - -var simulated_latency_ms := 0 -var packet_loss_percent := 0.0 - -func _ready(): - # Hook into network to simulate conditions - multiplayer.peer_packet_received.connect(_on_packet_received) - -func _on_packet_received(id: int, packet: PackedByteArray): - if packet_loss_percent > 0 and randf() < packet_loss_percent / 100: - return # Drop packet - - if simulated_latency_ms > 0: - await get_tree().create_timer(simulated_latency_ms / 1000.0).timeout - - _process_packet(id, packet) - -# Test -func test_position_sync_under_latency(): - NetworkSimulator.simulated_latency_ms = 200 - - # Move player on host - host_player.position = Vector3(100, 0, 100) - - await get_tree().create_timer(1.0).timeout - - # Check client view - var client_view_position = client.get_remote_player_position(host_player.id) - var distance = host_player.position.distance_to(client_view_position) - - assert_lt(distance, 1.0, "Position should converge within 1 unit") -``` - -## Dedicated Server Testing - -### Test Matrix - -| Scenario | Test Focus | -| --------------------- | ------------------------------------ | -| Server startup | Clean initialization, port binding | -| Client authentication | Login validation, session management | -| Server tick rate | Consistent updates under load | -| Maximum players | Performance at player cap | -| Server crash recovery | State preservation, reconnection | - -### Load Testing - -``` -SCENARIO: Maximum Players - GIVEN server configured for 64 players - WHEN 64 players connect - THEN all connections succeed - AND server tick rate stays above 60Hz - AND latency stays below 50ms - -SCENARIO: Stress Test - GIVEN 64 players performing actions simultaneously - WHEN running for 10 minutes - THEN no memory leaks - AND no desync events - AND server CPU below 80% -``` - -## Matchmaking Testing - -``` -SCENARIO: Skill-Based Matching - GIVEN players with skill ratings [1000, 1050, 2000, 2100] - WHEN matchmaking runs - THEN [1000, 1050] are grouped together - AND [2000, 2100] are grouped together - -SCENARIO: Region Matching - GIVEN players from US-East, US-West, EU - WHEN matchmaking runs - THEN players prefer same-region matches - AND cross-region only when necessary - AND latency is acceptable for all players - -SCENARIO: Queue Timeout - GIVEN player waiting in queue - WHEN 3 minutes pass without match - THEN matchmaking expands search criteria - AND player is notified of expanded search -``` - -## Security Testing - -| Vulnerability | Test Method | -| ---------------- | --------------------------- | -| Speed hacking | Validate movement on server | -| Teleportation | Check position delta limits | -| Damage hacking | Server-authoritative damage | -| Packet injection | Validate packet checksums | -| Replay attacks | Use unique session tokens | - -## Performance Metrics - -| Metric | Good | Acceptable | Poor | -| --------------------- | --------- | ---------- | ---------- | -| Round-trip latency | < 50ms | < 100ms | > 150ms | -| Sync delta | < 100ms | < 200ms | > 500ms | -| Packet loss tolerance | < 5% | < 10% | > 15% | -| Bandwidth per player | < 10 KB/s | < 50 KB/s | > 100 KB/s | -| Server tick rate | 60+ Hz | 30+ Hz | < 20 Hz | - -## Best Practices - -### DO - -- Test with real network conditions, not just localhost -- Simulate worst-case scenarios (high latency + packet loss) -- Use server-authoritative design for competitive games -- Implement lag compensation for fast-paced games -- Test host migration paths -- Log network events for debugging - -### DON'T - -- Trust client data for important game state -- Assume stable connections -- Skip testing with maximum player counts -- Ignore edge cases (simultaneous actions) -- Test only in ideal network conditions -- Forget to test reconnection flows diff --git a/src/modules/bmgd/gametest/knowledge/performance-testing.md b/src/modules/bmgd/gametest/knowledge/performance-testing.md deleted file mode 100644 index 38f363e5..00000000 --- a/src/modules/bmgd/gametest/knowledge/performance-testing.md +++ /dev/null @@ -1,204 +0,0 @@ -# Performance Testing for Games - -## Overview - -Performance testing ensures your game runs smoothly on target hardware. Frame rate, load times, and memory usage directly impact player experience. - -## Key Performance Metrics - -### Frame Rate - -- **Target:** 30fps, 60fps, 120fps depending on platform/genre -- **Measure:** Average, minimum, 1% low, 0.1% low -- **Goal:** Consistent frame times, no stutters - -### Frame Time Budget - -At 60fps, you have 16.67ms per frame: - -``` -Rendering: 8ms (48%) -Game Logic: 4ms (24%) -Physics: 2ms (12%) -Audio: 1ms (6%) -UI: 1ms (6%) -Headroom: 0.67ms (4%) -``` - -### Memory - -- **RAM:** Total allocation, peak usage, fragmentation -- **VRAM:** Texture memory, render targets, buffers -- **Goal:** Stay within platform limits with headroom - -### Load Times - -- **Initial Load:** Time to main menu -- **Level Load:** Time between scenes -- **Streaming:** Asset loading during gameplay -- **Goal:** Meet platform certification requirements - -## Profiling Tools by Engine - -### Unity - -- **Profiler Window** - CPU, GPU, memory, rendering -- **Frame Debugger** - Draw call analysis -- **Memory Profiler** - Heap snapshots -- **Profile Analyzer** - Compare captures - -### Unreal Engine - -- **Unreal Insights** - Comprehensive profiling -- **Stat Commands** - Runtime statistics -- **GPU Visualizer** - GPU timing breakdown -- **Memory Report** - Allocation tracking - -### Godot - -- **Debugger** - Built-in profiler -- **Monitors** - Real-time metrics -- **Remote Debugger** - Profile on device - -### Platform Tools - -- **PIX** (Xbox/Windows) - GPU debugging -- **RenderDoc** - GPU capture and replay -- **Instruments** (iOS/macOS) - Apple profiling -- **Android Profiler** - Android Studio tools - -## Performance Testing Process - -### 1. Establish Baselines - -- Profile on target hardware -- Record key metrics -- Create benchmark scenes - -### 2. Set Budgets - -- Define frame time budgets per system -- Set memory limits -- Establish load time targets - -### 3. Monitor Continuously - -- Integrate profiling in CI -- Track metrics over time -- Alert on regressions - -### 4. Optimize When Needed - -- Profile before optimizing -- Target biggest bottlenecks -- Verify improvements - -## Common Performance Issues - -### CPU Bottlenecks - -| Issue | Symptoms | Solution | -| --------------------- | ----------------- | --------------------------------- | -| Too many game objects | Slow update loop | Object pooling, LOD | -| Expensive AI | Spiky frame times | Budget AI, spread over frames | -| Physics overload | Physics spikes | Simplify colliders, reduce bodies | -| GC stutter | Regular hitches | Avoid runtime allocations | - -### GPU Bottlenecks - -| Issue | Symptoms | Solution | -| ------------------- | ----------------- | -------------------------------- | -| Overdraw | Fill rate limited | Occlusion culling, reduce layers | -| Too many draw calls | CPU-GPU bound | Batching, instancing, atlasing | -| Shader complexity | Long GPU times | Simplify shaders, LOD | -| Resolution too high | Fill rate limited | Dynamic resolution, FSR/DLSS | - -### Memory Issues - -| Issue | Symptoms | Solution | -| ------------- | ----------------- | ---------------------------- | -| Texture bloat | High VRAM | Compress, mipmap, stream | -| Leaks | Growing memory | Track allocations, fix leaks | -| Fragmentation | OOM despite space | Pool allocations, defrag | - -## Benchmark Scenes - -Create standardized test scenarios: - -### Stress Test Scene - -- Maximum entities on screen -- Complex visual effects -- Worst-case for performance - -### Typical Gameplay Scene - -- Representative of normal play -- Average entity count -- Baseline for comparison - -### Isolated System Tests - -- Combat only (no rendering) -- Rendering only (no game logic) -- AI only (pathfinding stress) - -## Automated Performance Testing - -### CI Integration - -```yaml -# Example: Fail build if frame time exceeds budget -performance_test: - script: - - run_benchmark --scene stress_test - - check_metrics --max-frame-time 16.67ms --max-memory 2GB - artifacts: - - performance_report.json -``` - -### Regression Detection - -- Compare against previous builds -- Alert on significant changes (>10%) -- Track trends over time - -## Platform-Specific Considerations - -### Console - -- Fixed hardware targets -- Strict certification requirements -- Thermal throttling concerns - -### PC - -- Wide hardware range -- Scalable quality settings -- Min/recommended specs - -### Mobile - -- Thermal throttling -- Battery impact -- Memory constraints -- Background app pressure - -## Performance Testing Checklist - -### Before Release - -- [ ] Profiled on all target platforms -- [ ] Frame rate targets met -- [ ] No memory leaks -- [ ] Load times acceptable -- [ ] No GC stutters in gameplay -- [ ] Thermal tests passed (mobile/console) -- [ ] Certification requirements met - -### Ongoing - -- [ ] Performance tracked in CI -- [ ] Regression alerts configured -- [ ] Benchmark scenes maintained -- [ ] Budgets documented and enforced diff --git a/src/modules/bmgd/gametest/knowledge/playtesting.md b/src/modules/bmgd/gametest/knowledge/playtesting.md deleted file mode 100644 index c22242a9..00000000 --- a/src/modules/bmgd/gametest/knowledge/playtesting.md +++ /dev/null @@ -1,384 +0,0 @@ -# Playtesting Fundamentals - -## Overview - -Playtesting is the process of having people play your game to gather feedback and identify issues. It's distinct from QA testing in that it focuses on player experience, fun factor, and design validation rather than bug hunting. - -## Types of Playtesting - -### Internal Playtesting - -- **Developer Testing** - Daily testing during development -- **Team Testing** - Cross-discipline team plays together -- **Best for:** Rapid iteration, catching obvious issues - -### External Playtesting - -- **Friends & Family** - Trusted external testers -- **Focus Groups** - Targeted demographic testing -- **Public Beta** - Large-scale community testing -- **Best for:** Fresh perspectives, UX validation - -### Specialized Playtesting - -- **Accessibility Testing** - Players with disabilities -- **Localization Testing** - Regional/cultural validation -- **Competitive Testing** - Balance and meta testing - -## Playtesting Process - -### 1. Define Goals - -Before each playtest session, define: - -- What questions are you trying to answer? -- What features are you testing? -- What metrics will you gather? - -### 2. Prepare the Build - -- Create a stable, playable build -- Include telemetry/logging if needed -- Prepare any necessary documentation - -### 3. Brief Testers - -- Explain what to test (or don't, for blind testing) -- Set expectations for bugs/polish level -- Provide feedback mechanisms - -### 4. Observe and Record - -- Watch players without intervening -- Note confusion points, frustration, delight -- Record gameplay if possible - -### 5. Gather Feedback - -- Structured surveys for quantitative data -- Open discussion for qualitative insights -- Allow time for "what else?" comments - -### 6. Analyze and Act - -- Identify patterns across testers -- Prioritize issues by frequency and severity -- Create actionable tasks from findings - -## Key Metrics to Track - -### Engagement Metrics - -- Session length -- Return rate -- Completion rate -- Drop-off points - -### Difficulty Metrics - -- Deaths/failures per section -- Time to complete sections -- Hint/help usage -- Difficulty setting distribution - -### UX Metrics - -- Time to first action -- Tutorial completion rate -- Menu navigation patterns -- Control scheme preferences - -## Playtesting by Game Type - -Different genres require different playtesting approaches and focus areas. - -### Action/Platformer Games - -**Focus Areas:** - -- Control responsiveness and "game feel" -- Difficulty curve across levels -- Checkpoint placement and frustration points -- Visual clarity during fast-paced action - -**Key Questions:** - -- Does the character feel good to control? -- Are deaths feeling fair or cheap? -- Is the player learning organically or hitting walls? - -### RPG/Story Games - -**Focus Areas:** - -- Narrative pacing and engagement -- Quest clarity and tracking -- Character/dialogue believability -- Progression and reward timing - -**Key Questions:** - -- Do players understand their current objective? -- Are choices feeling meaningful? -- Is the story holding attention or being skipped? - -### Puzzle Games - -**Focus Areas:** - -- Solution discoverability -- "Aha moment" timing -- Hint system effectiveness -- Difficulty progression - -**Key Questions:** - -- Are players solving puzzles the intended way? -- How long before frustration sets in? -- Do solutions feel satisfying or arbitrary? - -### Multiplayer/Competitive Games - -**Focus Areas:** - -- Balance across characters/builds/strategies -- Meta development and dominant strategies -- Social dynamics and toxicity vectors -- Matchmaking feel - -**Key Questions:** - -- Are there "must-pick" or "never-pick" options? -- Do losing players understand why they lost? -- Is the skill ceiling high enough for mastery? - -### Survival/Sandbox Games - -**Focus Areas:** - -- Early game onboarding and survival -- Goal clarity vs. freedom balance -- Resource economy and pacing -- Emergent gameplay moments - -**Key Questions:** - -- Do players know what to do first? -- Is the loop engaging beyond the first hour? -- Are players creating their own goals? - -### Mobile/Casual Games - -**Focus Areas:** - -- Session length appropriateness -- One-hand playability (if applicable) -- Interruption handling (calls, notifications) -- Monetization friction points - -**Key Questions:** - -- Can players play in 2-minute sessions? -- Is the core loop immediately understandable? -- Where do players churn? - -### Horror Games - -**Focus Areas:** - -- Tension and release pacing -- Scare effectiveness and desensitization -- Safe space placement -- Audio/visual atmosphere - -**Key Questions:** - -- When do players feel safe vs. threatened? -- Are scares landing or becoming predictable? -- Is anxiety sustainable or exhausting? - -## Processing Feedback Effectively - -Raw feedback is noise. Processed feedback is signal. - -### The Feedback Processing Pipeline - -``` -Raw Feedback → Categorize → Pattern Match → Root Cause → Prioritize → Action -``` - -### Step 1: Categorize Feedback - -Sort all feedback into buckets: - -| Category | Examples | -| ------------- | ---------------------------------- | -| **Bugs** | Crashes, glitches, broken features | -| **Usability** | Confusing UI, unclear objectives | -| **Balance** | Too hard, too easy, unfair | -| **Feel** | Controls, pacing, satisfaction | -| **Content** | Wants more of X, dislikes Y | -| **Polish** | Audio, visuals, juice | - -### Step 2: Pattern Matching - -Individual feedback is anecdotal. Patterns are data. - -**Threshold Guidelines:** - -- 1 person mentions it → Note it -- 3+ people mention it → Investigate -- 50%+ mention it → Priority issue - -**Watch for:** - -- Same complaint, different words -- Same area, different complaints (signals deeper issue) -- Contradictory feedback (may indicate preference split) - -### Step 3: Root Cause Analysis - -Players report symptoms, not diseases. - -**Example:** - -- **Symptom:** "The boss is too hard" -- **Possible Root Causes:** - - Boss mechanics unclear - - Player didn't learn required skill earlier - - Checkpoint too far from boss - - Health/damage tuning off - - Boss pattern has no safe windows - -**Ask "Why?" five times** to get to root cause. - -### Step 4: Separate Fact from Opinion - -| Fact (Actionable) | Opinion (Context) | -| --------------------------------- | ----------------------- | -| "I died 12 times on level 3" | "Level 3 is too hard" | -| "I didn't use the shield ability" | "The shield is useless" | -| "I quit after 20 minutes" | "The game is boring" | - -**Facts tell you WHAT happened. Opinions tell you how they FELT about it.** - -Both matter, but facts drive solutions. - -### Step 5: The Feedback Matrix - -Plot issues on impact vs. effort: - -``` - High Impact - │ - Quick │ Major - Wins │ Projects - │ -─────────────┼───────────── - │ - Fill │ Reconsider - Time │ - │ - Low Impact - Low Effort ──────── High Effort -``` - -### Step 6: Validate Before Acting - -Before making changes based on feedback: - -1. **Reproduce** - Can you see the issue yourself? -2. **Quantify** - How many players affected? -3. **Contextualize** - Is this your target audience? -4. **Test solutions** - Will the fix create new problems? - -### Handling Contradictory Feedback - -When Player A wants X and Player B wants the opposite: - -1. **Check sample size** - Is it really split or just 2 loud voices? -2. **Segment audiences** - Are these different player types? -3. **Find the underlying need** - Both may want the same thing differently -4. **Consider options** - Difficulty settings, toggles, multiple paths -5. **Make a decision** - You can't please everyone; know your target - -### Feedback Red Flags - -**Dismiss or investigate carefully:** - -- "Make it like [other game]" - They want a feeling, not a clone -- "Add multiplayer" - Feature creep disguised as feedback -- "I would have bought it if..." - Hypothetical customers aren't real -- Feedback from non-target audience - Know who you're building for - -**Take seriously:** - -- Confusion about core mechanics -- Consistent drop-off at same point -- "I wanted to like it but..." -- Silent quitting (no feedback, just gone) - -### Documentation Best Practices - -**For each playtest session, record:** - -- Date and build version -- Tester demographics/experience -- Session length -- Key observations (timestamped if recorded) -- Quantitative survey results -- Top 3 issues identified -- Actions taken as result - -**Maintain a living document** that tracks: - -- Issue → First reported → Times reported → Status → Resolution -- This prevents re-discovering the same issues - -## Common Playtesting Pitfalls - -### Leading Questions - -**Bad:** "Did you find the combat exciting?" -**Good:** "How would you describe the combat?" - -### Intervening Too Soon - -Let players struggle before helping. Confusion is valuable data. - -### Testing Too Late - -Start playtesting early with paper prototypes and gray boxes. - -### Ignoring Negative Feedback - -Negative feedback is often the most valuable. Don't dismiss it. - -### Over-Relying on Verbal Feedback - -Watch what players DO, not just what they SAY. Actions reveal truth. - -## Playtesting Checklist - -### Pre-Session - -- [ ] Goals defined -- [ ] Build stable and deployed -- [ ] Recording setup (if applicable) -- [ ] Feedback forms ready -- [ ] Testers briefed - -### During Session - -- [ ] Observing without intervening -- [ ] Taking notes on behavior -- [ ] Tracking time markers for notable moments -- [ ] Noting emotional reactions - -### Post-Session - -- [ ] Feedback collected -- [ ] Patterns identified -- [ ] Priority issues flagged -- [ ] Action items created -- [ ] Results shared with team diff --git a/src/modules/bmgd/gametest/knowledge/qa-automation.md b/src/modules/bmgd/gametest/knowledge/qa-automation.md deleted file mode 100644 index 491660b2..00000000 --- a/src/modules/bmgd/gametest/knowledge/qa-automation.md +++ /dev/null @@ -1,190 +0,0 @@ -# QA Automation for Games - -## Overview - -Automated testing in games requires different approaches than traditional software. Games have complex state, real-time interactions, and subjective quality measures that challenge automation. - -## Testing Pyramid for Games - -``` - /\ - / \ Manual Playtesting - /----\ (Experience, Feel, Fun) - / \ - /--------\ Integration Tests - / \ (Systems, Workflows) - /------------\ - / \ Unit Tests -/________________\ (Pure Logic, Math, Data) -``` - -### Unit Tests (Foundation) - -Test pure logic that doesn't depend on engine runtime: - -- Math utilities (vectors, transforms, curves) -- Data validation (save files, configs) -- State machines (isolated logic) -- Algorithm correctness - -### Integration Tests (Middle Layer) - -Test system interactions: - -- Combat system + inventory -- Save/load round-trips -- Scene transitions -- Network message handling - -### Manual Testing (Top) - -What can't be automated: - -- "Does this feel good?" -- "Is this fun?" -- "Is the difficulty right?" - -## Automation Strategies by Engine - -### Unity - -```csharp -// Unity Test Framework -[Test] -public void DamageCalculation_CriticalHit_DoublesDamage() -{ - var baseDamage = 100; - var result = DamageCalculator.Calculate(baseDamage, isCritical: true); - Assert.AreEqual(200, result); -} - -// Play Mode Tests (runtime) -[UnityTest] -public IEnumerator PlayerJump_WhenGrounded_BecomesAirborne() -{ - var player = CreateTestPlayer(); - player.Jump(); - yield return new WaitForFixedUpdate(); - Assert.IsFalse(player.IsGrounded); -} -``` - -### Unreal Engine - -```cpp -// Automation Framework -IMPLEMENT_SIMPLE_AUTOMATION_TEST(FDamageTest, "Game.Combat.Damage", - EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::ProductFilter) - -bool FDamageTest::RunTest(const FString& Parameters) -{ - float BaseDamage = 100.f; - float Result = UDamageCalculator::Calculate(BaseDamage, true); - TestEqual("Critical hit doubles damage", Result, 200.f); - return true; -} -``` - -### Godot - -```gdscript -# GUT Testing Framework -func test_damage_critical_hit(): - var base_damage = 100 - var result = DamageCalculator.calculate(base_damage, true) - assert_eq(result, 200, "Critical hit should double damage") -``` - -## What to Automate - -### High Value Targets - -- **Save/Load** - Data integrity is critical -- **Economy** - Currency, items, progression math -- **Combat Math** - Damage, stats, modifiers -- **Localization** - String loading, formatting -- **Network Serialization** - Message encoding/decoding - -### Medium Value Targets - -- **State Machines** - Character states, game states -- **Pathfinding** - Known scenarios -- **Spawning** - Wave generation, loot tables -- **UI Data Binding** - Correct values displayed - -### Low Value / Avoid - -- **Visual Quality** - Screenshots drift, hard to maintain -- **Input Feel** - Timing-sensitive, needs human judgment -- **Audio** - Subjective, context-dependent -- **Fun** - Cannot be automated - -## Continuous Integration for Games - -### Build Pipeline - -1. **Compile** - Build game executable -2. **Unit Tests** - Fast, isolated tests -3. **Integration Tests** - Longer, system tests -4. **Smoke Test** - Can the game launch and reach main menu? -5. **Nightly** - Extended test suites, performance benchmarks - -### CI Gotchas for Games - -- **Long build times** - Games take longer than web apps -- **GPU requirements** - Some tests need graphics hardware -- **Asset dependencies** - Large files, binary formats -- **Platform builds** - Multiple targets to maintain - -## Regression Testing - -### Automated Regression - -- Run full test suite on every commit -- Flag performance regressions (frame time, memory) -- Track test stability (flaky tests) - -### Save File Regression - -- Maintain library of save files from previous versions -- Test that new builds can load old saves -- Alert on schema changes - -## Test Data Management - -### Test Fixtures - -``` -tests/ -├── fixtures/ -│ ├── save_files/ -│ │ ├── new_game.sav -│ │ ├── mid_game.sav -│ │ └── endgame.sav -│ ├── configs/ -│ │ └── test_balance.json -│ └── scenarios/ -│ └── boss_fight_setup.scene -``` - -### Deterministic Testing - -- Seed random number generators -- Control time/delta time -- Mock external services - -## Metrics and Reporting - -### Track Over Time - -- Test count (growing is good) -- Pass rate (should be ~100%) -- Execution time (catch slow tests) -- Code coverage (where applicable) -- Flaky test rate (should be ~0%) - -### Alerts - -- Immediate: Any test failure on main branch -- Daily: Coverage drops, new flaky tests -- Weekly: Trend analysis, slow test growth diff --git a/src/modules/bmgd/gametest/knowledge/regression-testing.md b/src/modules/bmgd/gametest/knowledge/regression-testing.md deleted file mode 100644 index 975c4659..00000000 --- a/src/modules/bmgd/gametest/knowledge/regression-testing.md +++ /dev/null @@ -1,280 +0,0 @@ -# Regression Testing for Games - -## Overview - -Regression testing catches bugs introduced by new changes. In games, this includes functional regressions, performance regressions, and design regressions. - -## Types of Regression - -### Functional Regression - -- Features that worked before now break -- New bugs introduced by unrelated changes -- Broken integrations between systems - -### Performance Regression - -- Frame rate drops -- Memory usage increases -- Load time increases -- Battery drain (mobile) - -### Design Regression - -- Balance changes with unintended side effects -- UX changes that hurt usability -- Art changes that break visual consistency - -### Save Data Regression - -- Old save files no longer load -- Progression lost or corrupted -- Achievements/unlocks reset - -## Regression Testing Strategy - -### Test Suite Layers - -``` -High-Frequency (Every Commit) -├── Unit Tests - Fast, isolated -├── Smoke Tests - Can game launch and run? -└── Critical Path - Core gameplay works - -Medium-Frequency (Nightly) -├── Integration Tests - System interactions -├── Full Playthrough - Automated or manual -└── Performance Benchmarks - Frame time, memory - -Low-Frequency (Release) -├── Full Matrix - All platforms/configs -├── Certification Tests - Platform requirements -└── Localization - All languages -``` - -### What to Test - -#### Critical Path (Must Not Break) - -- Game launches -- New game starts -- Save/load works -- Core gameplay loop completes -- Main menu navigation - -#### High Priority - -- All game systems function -- Progression works end-to-end -- Multiplayer connects and syncs -- In-app purchases process -- Achievements trigger - -#### Medium Priority - -- Edge cases in systems -- Optional content accessible -- Settings persist correctly -- Localization displays - -## Automated Regression Tests - -### Smoke Tests - -```python -# Run on every commit -def test_game_launches(): - process = launch_game() - assert wait_for_main_menu(timeout=30) - process.terminate() - -def test_new_game_starts(): - launch_game() - click_new_game() - assert wait_for_gameplay(timeout=60) - -def test_save_load_roundtrip(): - launch_game() - start_new_game() - perform_actions() - save_game() - load_game() - assert verify_state_matches() -``` - -### Playthrough Bots - -```python -# Automated player that plays through content -class PlaythroughBot: - def run_level(self, level): - self.load_level(level) - while not self.level_complete: - self.perform_action() - self.check_for_softlocks() - self.record_metrics() -``` - -### Visual Regression - -```python -# Compare screenshots against baselines -def test_main_menu_visual(): - launch_game() - screenshot = capture_screen() - assert compare_to_baseline(screenshot, 'main_menu', threshold=0.01) -``` - -## Performance Regression Detection - -### Metrics to Track - -- Average frame time -- 1% low frame time -- Memory usage (peak, average) -- Load times -- Draw calls -- Texture memory - -### Automated Benchmarks - -```yaml -performance_benchmark: - script: - - run_benchmark_scene --duration 60s - - collect_metrics - - compare_to_baseline - fail_conditions: - - frame_time_avg > baseline * 1.1 # 10% tolerance - - memory_peak > baseline * 1.05 # 5% tolerance -``` - -### Trend Tracking - -- Graph metrics over time -- Alert on upward trends -- Identify problematic commits - -## Save Compatibility Testing - -### Version Matrix - -Maintain save files from: - -- Previous major version -- Previous minor version -- Current development build - -### Automated Validation - -```python -def test_save_compatibility(): - for save_file in LEGACY_SAVES: - load_save(save_file) - assert no_errors() - assert progress_preserved() - assert inventory_intact() -``` - -### Schema Versioning - -- Version your save format -- Implement upgrade paths -- Log migration issues - -## Regression Bug Workflow - -### 1. Detection - -- Automated test fails -- Manual tester finds issue -- Player report comes in - -### 2. Verification - -- Confirm it worked before -- Identify when it broke -- Find the breaking commit - -### 3. Triage - -- Assess severity -- Determine fix urgency -- Assign to appropriate developer - -### 4. Fix and Verify - -- Implement fix -- Add regression test -- Verify fix doesn't break other things - -### 5. Post-Mortem - -- Why wasn't this caught? -- How can we prevent similar issues? -- Do we need new tests? - -## Bisecting Regressions - -When a regression is found, identify the breaking commit: - -### Git Bisect - -```bash -git bisect start -git bisect bad HEAD # Current is broken -git bisect good v1.2.0 # Known good version -# Git will checkout commits to test -# Run test, mark good/bad -git bisect good/bad -# Repeat until culprit found -``` - -### Automated Bisect - -```bash -git bisect start HEAD v1.2.0 -git bisect run ./run_regression_test.sh -``` - -## Regression Testing Checklist - -### Per Commit - -- [ ] Unit tests pass -- [ ] Smoke tests pass -- [ ] Build succeeds on all platforms - -### Per Merge to Main - -- [ ] Integration tests pass -- [ ] Performance benchmarks within tolerance -- [ ] Save compatibility verified - -### Per Release - -- [ ] Full playthrough completed -- [ ] All platforms tested -- [ ] Legacy saves load correctly -- [ ] No new critical regressions -- [ ] All previous hotfix issues still resolved - -## Building a Regression Suite - -### Start Small - -1. Add tests for bugs as they're fixed -2. Cover critical path first -3. Expand coverage over time - -### Maintain Quality - -- Delete flaky tests -- Keep tests fast -- Update tests with design changes - -### Measure Effectiveness - -- Track bugs caught by tests -- Track bugs that slipped through -- Identify coverage gaps diff --git a/src/modules/bmgd/gametest/knowledge/save-testing.md b/src/modules/bmgd/gametest/knowledge/save-testing.md deleted file mode 100644 index 663898a5..00000000 --- a/src/modules/bmgd/gametest/knowledge/save-testing.md +++ /dev/null @@ -1,280 +0,0 @@ -# Save System Testing Guide - -## Overview - -Save system testing ensures data persistence, integrity, and compatibility across game versions. Save bugs are among the most frustrating for players—data loss destroys trust. - -## Test Categories - -### Data Integrity - -| Test Type | Description | Priority | -| -------------------- | ------------------------------------------- | -------- | -| Round-trip | Save → Load → Verify all data matches | P0 | -| Corruption detection | Tampered/corrupted files handled gracefully | P0 | -| Partial write | Power loss during save doesn't corrupt | P0 | -| Large saves | Performance with max-size save files | P1 | -| Edge values | Min/max values for all saved fields | P1 | - -### Version Compatibility - -| Scenario | Expected Behavior | -| ----------------------- | ------------------------------------- | -| Current → Current | Full compatibility | -| Old → New (upgrade) | Migration with data preservation | -| New → Old (downgrade) | Graceful rejection or limited support | -| Corrupted version field | Fallback to recovery mode | - -## Test Scenarios - -### Core Save/Load Tests - -``` -SCENARIO: Basic Save Round-Trip - GIVEN player has 100 health, 50 gold, position (10, 5, 20) - AND player has inventory: ["sword", "potion", "key"] - WHEN game is saved - AND game is reloaded - THEN player health equals 100 - AND player gold equals 50 - AND player position equals (10, 5, 20) - AND inventory contains exactly ["sword", "potion", "key"] - -SCENARIO: Save During Gameplay - GIVEN player is in combat - AND enemy has 50% health remaining - WHEN autosave triggers - AND game is reloaded - THEN combat state is restored - AND enemy health equals 50% - -SCENARIO: Multiple Save Slots - GIVEN save slot 1 has character "Hero" at level 10 - AND save slot 2 has character "Mage" at level 5 - WHEN switching between slots - THEN correct character data loads for each slot - AND no cross-contamination between slots -``` - -### Edge Cases - -``` -SCENARIO: Maximum Inventory Save - GIVEN player has 999 items in inventory - WHEN game is saved - AND game is reloaded - THEN all 999 items are preserved - AND save/load completes within 5 seconds - -SCENARIO: Unicode Character Names - GIVEN player name is "プレイヤー名" - WHEN game is saved - AND game is reloaded - THEN player name displays correctly - -SCENARIO: Extreme Play Time - GIVEN play time is 9999:59:59 - WHEN game is saved - AND game is reloaded - THEN play time displays correctly - AND timer continues from saved value -``` - -### Corruption Recovery - -``` -SCENARIO: Corrupted Save Detection - GIVEN save file has been manually corrupted - WHEN game attempts to load - THEN error is detected before loading - AND user is informed of corruption - AND game does not crash - -SCENARIO: Missing Save File - GIVEN save file has been deleted externally - WHEN game attempts to load - THEN graceful error handling - AND option to start new game or restore backup - -SCENARIO: Interrupted Save (Power Loss) - GIVEN save operation is interrupted mid-write - WHEN game restarts - THEN backup save is detected and offered - AND no data loss from previous valid save -``` - -## Platform-Specific Testing - -### PC (Steam/Epic) - -- Cloud save sync conflicts -- Multiple Steam accounts on same PC -- Offline → Online sync -- Save location permissions (Program Files issues) - -### Console (PlayStation/Xbox/Switch) - -- System-level save management -- Storage full scenarios -- User switching mid-game -- Suspend/resume with unsaved changes -- Cloud save quota limits - -### Mobile - -- App termination during save -- Low storage warnings -- iCloud/Google Play sync -- Device migration - -## Automated Test Examples - -### Unity - -```csharp -[Test] -public void SaveLoad_PlayerStats_PreservesAllValues() -{ - var original = new PlayerData - { - Health = 75, - MaxHealth = 100, - Gold = 1234567, - Position = new Vector3(100.5f, 0, -50.25f), - PlayTime = 36000f // 10 hours - }; - - SaveManager.Save(original, "test_slot"); - var loaded = SaveManager.Load("test_slot"); - - Assert.AreEqual(original.Health, loaded.Health); - Assert.AreEqual(original.Gold, loaded.Gold); - Assert.AreEqual(original.Position, loaded.Position); - Assert.AreEqual(original.PlayTime, loaded.PlayTime, 0.01f); -} - -[Test] -public void SaveLoad_CorruptedFile_HandlesGracefully() -{ - File.WriteAllText(SaveManager.GetPath("corrupt"), "INVALID DATA"); - - Assert.Throws(() => - SaveManager.Load("corrupt")); - - // Game should not crash - Assert.IsTrue(SaveManager.IsValidSaveSlot("corrupt") == false); -} -``` - -### Unreal - -```cpp -bool FSaveSystemTest::RunTest(const FString& Parameters) -{ - // Create test save - USaveGame* SaveGame = UGameplayStatics::CreateSaveGameObject( - UMySaveGame::StaticClass()); - UMySaveGame* MySave = Cast(SaveGame); - - MySave->PlayerLevel = 50; - MySave->Gold = 999999; - MySave->QuestsCompleted = {"Quest1", "Quest2", "Quest3"}; - - // Save - UGameplayStatics::SaveGameToSlot(MySave, "TestSlot", 0); - - // Load - USaveGame* Loaded = UGameplayStatics::LoadGameFromSlot("TestSlot", 0); - UMySaveGame* LoadedSave = Cast(Loaded); - - TestEqual("Level preserved", LoadedSave->PlayerLevel, 50); - TestEqual("Gold preserved", LoadedSave->Gold, 999999); - TestEqual("Quests count", LoadedSave->QuestsCompleted.Num(), 3); - - return true; -} -``` - -### Godot - -```gdscript -func test_save_load_round_trip(): - var original = { - "health": 100, - "position": Vector3(10, 0, 20), - "inventory": ["sword", "shield"], - "quest_flags": {"intro_complete": true, "boss_defeated": false} - } - - SaveManager.save_game(original, "test_save") - var loaded = SaveManager.load_game("test_save") - - assert_eq(loaded.health, 100) - assert_eq(loaded.position, Vector3(10, 0, 20)) - assert_eq(loaded.inventory.size(), 2) - assert_true(loaded.quest_flags.intro_complete) - assert_false(loaded.quest_flags.boss_defeated) - -func test_corrupted_save_detection(): - var file = FileAccess.open("user://saves/corrupt.sav", FileAccess.WRITE) - file.store_string("CORRUPTED GARBAGE DATA") - file.close() - - var result = SaveManager.load_game("corrupt") - - assert_null(result, "Should return null for corrupted save") - assert_false(SaveManager.is_valid_save("corrupt")) -``` - -## Migration Testing - -### Version Upgrade Matrix - -| From Version | To Version | Test Focus | -| -------------- | ---------------- | ---------------------------- | -| 1.0 → 1.1 | Minor update | New fields default correctly | -| 1.x → 2.0 | Major update | Schema migration works | -| Beta → Release | Launch migration | All beta saves convert | - -### Migration Test Template - -``` -SCENARIO: Save Migration v1.0 to v2.0 - GIVEN save file from version 1.0 - AND save contains old inventory format (array) - WHEN game version 2.0 loads the save - THEN inventory is migrated to new format (dictionary) - AND all items are preserved - AND migration is logged - AND backup of original is created -``` - -## Performance Benchmarks - -| Metric | Target | Maximum | -| ------------------------ | --------------- | ------- | -| Save time (typical) | < 500ms | 2s | -| Save time (large) | < 2s | 5s | -| Load time (typical) | < 1s | 3s | -| Save file size (typical) | < 1MB | 10MB | -| Memory during save | < 50MB overhead | 100MB | - -## Best Practices - -### DO - -- Use atomic saves (write to temp, then rename) -- Keep backup of previous save -- Version your save format -- Encrypt sensitive data -- Test on minimum-spec hardware -- Compress large saves - -### DON'T - -- Store absolute file paths -- Save derived/calculated data -- Trust save file contents blindly -- Block gameplay during save -- Forget to handle storage-full scenarios -- Skip testing save migration paths diff --git a/src/modules/bmgd/gametest/knowledge/smoke-testing.md b/src/modules/bmgd/gametest/knowledge/smoke-testing.md deleted file mode 100644 index 20be2ae0..00000000 --- a/src/modules/bmgd/gametest/knowledge/smoke-testing.md +++ /dev/null @@ -1,404 +0,0 @@ -# Smoke Testing Guide - -## Overview - -Smoke testing (Build Verification Testing) validates that a build's critical functionality works before investing time in detailed testing. A failed smoke test means "stop, this build is broken." - -## Purpose - -| Goal | Description | -| ------------------- | ---------------------------------------------- | -| Fast feedback | Know within minutes if build is viable | -| Block bad builds | Prevent broken builds from reaching QA/players | -| Critical path focus | Test only what matters most | -| CI/CD integration | Automated gate before deployment | - -## Smoke Test Principles - -### What Makes a Good Smoke Test - -- **Fast**: Complete in 5-15 minutes -- **Critical**: Tests only essential functionality -- **Deterministic**: Same result every run -- **Automated**: No human intervention required -- **Clear**: Pass/fail with actionable feedback - -### What to Include - -| Category | Examples | -| ----------------- | ------------------------------ | -| Boot sequence | Game launches without crash | -| Core loop | Player can perform main action | -| Save/Load | Data persists correctly | -| Critical UI | Menus are navigable | -| Platform services | Connects to required services | - -### What NOT to Include - -- Edge cases and boundary conditions -- Performance benchmarks (separate tests) -- Full feature coverage -- Content verification -- Balance testing - -## Smoke Test Scenarios - -### Boot and Load - -``` -TEST: Game Launches - WHEN game executable is started - THEN main menu appears within 60 seconds - AND no crashes occur - AND required services connect - -TEST: New Game Start - GIVEN game at main menu - WHEN "New Game" is selected - THEN gameplay loads within 30 seconds - AND player can control character - -TEST: Continue Game - GIVEN existing save file - WHEN "Continue" is selected - THEN correct save loads - AND game state matches saved state -``` - -### Core Gameplay - -``` -TEST: Player Movement - GIVEN player in game world - WHEN movement input applied - THEN player moves in expected direction - AND no physics glitches occur - -TEST: Core Action (Game-Specific) - GIVEN player can perform primary action - WHEN action is triggered - THEN action executes correctly - AND expected results occur - - Examples: - - Shooter: Can fire weapon, bullets hit targets - - RPG: Can attack enemy, damage is applied - - Puzzle: Can interact with puzzle elements - - Platformer: Can jump, platforms are solid -``` - -### Save System - -``` -TEST: Save Creates File - GIVEN player makes progress - WHEN save is triggered - THEN save file is created - AND save completes without error - -TEST: Load Restores State - GIVEN valid save file exists - WHEN load is triggered - THEN saved state is restored - AND gameplay can continue -``` - -### Critical UI - -``` -TEST: Menu Navigation - GIVEN main menu is displayed - WHEN each menu option is selected - THEN correct screen/action occurs - AND navigation back works - -TEST: Settings Persist - GIVEN settings are changed - WHEN game is restarted - THEN settings remain changed -``` - -## Automated Smoke Test Examples - -### Unity - -```csharp -using System.Collections; -using NUnit.Framework; -using UnityEngine; -using UnityEngine.UI; -using UnityEngine.TestTools; -using UnityEngine.SceneManagement; - -[TestFixture] -public class SmokeTests -{ - [UnityTest, Timeout(60000)] - public IEnumerator Game_Launches_ToMainMenu() - { - // Load main menu scene - SceneManager.LoadScene("MainMenu"); - yield return new WaitForSeconds(5f); - - // Verify menu is active - var mainMenu = GameObject.Find("MainMenuCanvas"); - Assert.IsNotNull(mainMenu, "Main menu should be present"); - Assert.IsTrue(mainMenu.activeInHierarchy, "Main menu should be active"); - } - - [UnityTest, Timeout(120000)] - public IEnumerator NewGame_LoadsGameplay() - { - // Start from main menu - SceneManager.LoadScene("MainMenu"); - yield return new WaitForSeconds(2f); - - // Click new game - var newGameButton = GameObject.Find("NewGameButton") - .GetComponent