bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/modules/bmgd/gametest/knowledge/playtesting.md

@@ -0,0 +1,384 @@
+# 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

package/src/modules/bmgd/gametest/knowledge/qa-automation.md

@@ -0,0 +1,190 @@
+# 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