bmad-method 6.0.0-alpha.17 → 6.0.0-alpha.18

package/src/modules/bmgd/gametest/knowledge/performance-testing.md

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

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