@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/ai-playtest-framework/SKILL.md

@@ -0,0 +1,570 @@
+---
+name: ai-playtest-framework
+description: AI-powered automated playtesting framework. Deploy bots that play your game, find bugs, test balance, and measure player experience.
+---
+
+# AI Playtest Framework 🤖🎮
+
+> **Let AI play your game 24/7.** Find bugs, test balance, and measure fun before players do.
+
+## Overview
+
+This skill provides patterns for implementing AI-powered playtesting bots that can:
+- Play through your entire game automatically
+- Find crashes, soft locks, and progression blockers
+- Test game balance and identify exploits
+- Measure difficulty curves and player experience
+- Generate coverage and performance reports
+
+---
+
+## Bot Types
+
+### 1. Random Bot (Monkey Testing)
+
+**Purpose**: Find crashes and edge cases through random actions
+
+```python
+# random_bot.py
+class RandomBot:
+    """Executes random valid actions to find edge cases"""
+    
+    def __init__(self, game_api):
+        self.game = game_api
+        self.action_log = []
+        self.crash_log = []
+        
+    def run(self, max_steps=10000, max_crashes=10):
+        steps = 0
+        crashes = 0
+        
+        while steps < max_steps and crashes < max_crashes:
+            try:
+                # Get current valid actions
+                actions = self.game.get_valid_actions()
+                
+                if not actions:
+                    self.log_softlock(steps)
+                    self.game.reset()
+                    continue
+                
+                # Random action selection
+                action = random.choice(actions)
+                self.action_log.append(action)
+                
+                # Execute
+                result = self.game.execute(action)
+                
+                # Check for anomalies
+                self.check_anomalies(result, steps)
+                
+                steps += 1
+                
+            except Exception as e:
+                crashes += 1
+                self.log_crash(steps, e)
+                self.game.reset()
+        
+        return self.generate_report()
+```
+
+### 2. Explorer Bot (Coverage Testing)
+
+**Purpose**: Maximize game state coverage
+
+```python
+# explorer_bot.py
+class ExplorerBot:
+    """Systematically explores game states for maximum coverage"""
+    
+    def __init__(self, game_api):
+        self.game = game_api
+        self.visited_states = set()
+        self.state_graph = {}
+        
+    def run(self, target_coverage=0.8):
+        while self.get_coverage() < target_coverage:
+            # Prioritize unvisited states
+            current = self.game.get_state_hash()
+            
+            if current not in self.visited_states:
+                self.visited_states.add(current)
+                self.map_connections(current)
+            
+            # Move toward unexplored areas
+            next_action = self.find_path_to_unexplored()
+            
+            if next_action:
+                self.game.execute(next_action)
+            else:
+                # Random exploration when stuck
+                self.random_action()
+        
+        return self.generate_coverage_map()
+```
+
+### 3. Speedrun Bot (Exploit Detection)
+
+**Purpose**: Find sequence breaks and exploits
+
+```python
+# speedrun_bot.py
+class SpeedrunBot:
+    """Uses optimization to find fastest paths, exposing exploits"""
+    
+    def __init__(self, game_api):
+        self.game = game_api
+        self.best_time = float('inf')
+        self.best_route = []
+        
+    def run(self, iterations=1000):
+        for i in range(iterations):
+            self.game.reset()
+            route, time = self.attempt_speedrun()
+            
+            if time < self.best_time:
+                self.best_time = time
+                self.best_route = route
+                self.check_for_exploits(route)
+        
+        return self.generate_report()
+    
+    def check_for_exploits(self, route):
+        """Flag suspicious sequences"""
+        # Look for: skipped levels, duplicate rewards, etc.
+        for i, action in enumerate(route):
+            if self.is_sequence_break(route[max(0,i-5):i+1]):
+                self.log_potential_exploit(route[i-5:i+5])
+```
+
+### 4. Balance Bot (RL-Based)
+
+**Purpose**: Find overpowered strategies using machine learning
+
+```python
+# balance_bot.py
+class BalanceBot:
+    """Uses reinforcement learning to find optimal strategies"""
+    
+    def __init__(self, game_api, model_path=None):
+        self.game = game_api
+        self.model = self.load_or_create_model(model_path)
+        self.strategy_stats = {}
+        
+    def train(self, episodes=10000):
+        for episode in range(episodes):
+            state = self.game.reset()
+            total_reward = 0
+            strategy_used = []
+            
+            while not self.game.is_done():
+                action = self.model.predict(state)
+                next_state, reward, done = self.game.step(action)
+                
+                self.model.learn(state, action, reward, next_state)
+                
+                strategy_used.append(action)
+                total_reward += reward
+                state = next_state
+            
+            self.log_strategy(strategy_used, total_reward)
+        
+        return self.analyze_dominant_strategies()
+    
+    def analyze_dominant_strategies(self):
+        """Find strategies that win too often"""
+        report = {
+            "dominant_strategies": [],
+            "underused_strategies": [],
+            "balance_issues": []
+        }
+        
+        for strategy, stats in self.strategy_stats.items():
+            win_rate = stats['wins'] / stats['total']
+            
+            if win_rate > 0.6:
+                report["dominant_strategies"].append({
+                    "strategy": strategy,
+                    "win_rate": win_rate,
+                    "recommendation": "Consider nerfing"
+                })
+            elif win_rate < 0.4:
+                report["underused_strategies"].append({
+                    "strategy": strategy,
+                    "win_rate": win_rate,
+                    "recommendation": "Consider buffing"
+                })
+        
+        return report
+```
+
+### 5. New Player Bot (UX Testing)
+
+**Purpose**: Simulate new player experience
+
+```python
+# newplayer_bot.py
+class NewPlayerBot:
+    """Simulates a new player to test onboarding and UX"""
+    
+    def __init__(self, game_api, skill_level="novice"):
+        self.game = game_api
+        self.skill_level = skill_level
+        self.confusion_log = []
+        self.frustration_log = []
+        
+    def run(self):
+        self.game.reset()
+        
+        while not self.game.is_tutorial_complete():
+            # Simulate confusion: don't always pick optimal action
+            actions = self.game.get_valid_actions()
+            
+            # New players might miss hints
+            if not self.noticed_hint():
+                self.confusion_log.append({
+                    "state": self.game.get_state(),
+                    "issue": "Missed tutorial hint"
+                })
+            
+            # Simulate imperfect play
+            action = self.pick_suboptimal_action(actions)
+            result = self.game.execute(action)
+            
+            # Track frustration
+            if result.is_failure:
+                self.track_frustration()
+        
+        return self.generate_ux_report()
+    
+    def track_frustration(self):
+        """Track repeated failures at same point"""
+        current_level = self.game.get_current_level()
+        
+        if current_level in self.failure_counts:
+            self.failure_counts[current_level] += 1
+            
+            if self.failure_counts[current_level] > 3:
+                self.frustration_log.append({
+                    "level": current_level,
+                    "issue": "Difficulty spike - 3+ failures"
+                })
+```
+
+---
+
+## Unity ML-Agents Integration
+
+### Setup
+
+```csharp
+// PlaytestAgent.cs
+using Unity.MLAgents;
+using Unity.MLAgents.Sensors;
+using Unity.MLAgents.Actuators;
+
+public class PlaytestAgent : Agent
+{
+    [Header("References")]
+    [SerializeField] private GameManager _gameManager;
+    
+    [Header("Playtest Mode")]
+    [SerializeField] private PlaytestMode _mode = PlaytestMode.Explorer;
+    
+    public enum PlaytestMode
+    {
+        Explorer,    // Maximize coverage
+        Speedrunner, // Minimize time
+        Griefer,     // Find exploits
+        NewPlayer    // Simulate confusion
+    }
+    
+    public override void OnEpisodeBegin()
+    {
+        _gameManager.ResetGame();
+    }
+    
+    public override void CollectObservations(VectorSensor sensor)
+    {
+        // Add game state observations
+        sensor.AddObservation(_gameManager.PlayerPosition);
+        sensor.AddObservation(_gameManager.PlayerHealth);
+        sensor.AddObservation(_gameManager.EnemyPositions);
+        sensor.AddObservation(_gameManager.CurrentLevel);
+    }
+    
+    public override void OnActionReceived(ActionBuffers actions)
+    {
+        // Execute action
+        int action = actions.DiscreteActions[0];
+        var result = _gameManager.ExecuteAction(action);
+        
+        // Reward based on mode
+        switch (_mode)
+        {
+            case PlaytestMode.Explorer:
+                AddReward(result.NewStateDiscovered ? 1f : 0f);
+                break;
+            case PlaytestMode.Speedrunner:
+                AddReward(-0.01f); // Penalize time
+                AddReward(result.LevelCompleted ? 10f : 0f);
+                break;
+            case PlaytestMode.Griefer:
+                AddReward(result.FoundExploit ? 100f : 0f);
+                break;
+        }
+        
+        // End episode on game over
+        if (result.GameOver)
+        {
+            LogPlaytestResult(result);
+            EndEpisode();
+        }
+    }
+}
+```
+
+### Training Configuration
+
+```yaml
+# playtest_agent.yaml
+behaviors:
+  PlaytestBot:
+    trainer_type: ppo
+    hyperparameters:
+      batch_size: 1024
+      buffer_size: 10240
+      learning_rate: 3.0e-4
+      beta: 5.0e-3
+      epsilon: 0.2
+      lambd: 0.95
+      num_epoch: 3
+    network_settings:
+      normalize: true
+      hidden_units: 256
+      num_layers: 2
+    reward_signals:
+      extrinsic:
+        gamma: 0.99
+        strength: 1.0
+    max_steps: 5000000
+    time_horizon: 128
+    summary_freq: 10000
+```
+
+---
+
+## Godot RL Integration
+
+### GDScript Agent
+
+```gdscript
+# playtest_agent.gd
+extends Node
+
+class_name PlaytestAgent
+
+enum Mode { RANDOM, EXPLORER, SPEEDRUN, BALANCE }
+
+@export var mode: Mode = Mode.EXPLORER
+@export var max_steps: int = 10000
+
+var step_count: int = 0
+var visited_states: Dictionary = {}
+var bug_log: Array = []
+
+func _ready():
+    run_playtest()
+
+func run_playtest():
+    while step_count < max_steps:
+        var state = get_game_state()
+        var action = select_action(state)
+        
+        var result = execute_action(action)
+        
+        check_for_issues(result)
+        
+        step_count += 1
+    
+    generate_report()
+
+func select_action(state: Dictionary) -> int:
+    match mode:
+        Mode.RANDOM:
+            return randi() % get_action_count()
+        Mode.EXPLORER:
+            return find_unexplored_action(state)
+        Mode.SPEEDRUN:
+            return find_fastest_action(state)
+        _:
+            return 0
+
+func check_for_issues(result: Dictionary):
+    if result.has("error"):
+        bug_log.append({
+            "step": step_count,
+            "error": result.error,
+            "state": get_game_state()
+        })
+    
+    if result.get("stuck", false):
+        bug_log.append({
+            "step": step_count,
+            "issue": "Soft lock detected",
+            "state": get_game_state()
+        })
+```
+
+---
+
+## Test Reports
+
+### Coverage Report
+
+```markdown
+# Playtest Coverage Report
+
+## Summary
+- **Total States Explored**: 1,247
+- **Estimated Coverage**: 78%
+- **Unique Paths Found**: 342
+- **Test Duration**: 4 hours
+
+## Unexplored Areas
+1. Level 7 secret room (requires specific item combo)
+2. Boss phase 3 rage mode (never triggered)
+3. Multiplayer lobby (not tested)
+
+## Heatmap
+[Generated level heatmap showing visited areas]
+
+## Recommendations
+- Add tutorial hint for secret room
+- Lower boss phase 3 trigger threshold for testing
+```
+
+### Bug Report
+
+```markdown
+# Automated Bug Report
+
+## Critical (2)
+1. **Crash at Level 5 Boss**
+   - Steps to reproduce: [action log]
+   - Stack trace: NullReferenceException at BossAI.cs:147
+   
+2. **Soft Lock in Puzzle Room**
+   - Trigger: Push both blocks simultaneously
+   - Player cannot reset or escape
+
+## High (5)
+1. Out of bounds at coordinates (145, -20)
+2. Duplicate reward on rapid retry
+3. ...
+
+## Medium (12)
+...
+
+## Low (34)
+...
+```
+
+### Balance Report
+
+```markdown
+# Balance Analysis Report
+
+## Dominant Strategies
+| Strategy | Win Rate | Usage | Recommendation |
+|----------|----------|-------|----------------|
+| Spam Attack | 72% | 45% | Reduce attack speed |
+| Corner Camp | 68% | 23% | Add anti-camping mechanic |
+
+## Underused Strategies
+| Strategy | Win Rate | Usage | Recommendation |
+|----------|----------|-------|----------------|
+| Defensive Build | 31% | 5% | Buff shield abilities |
+| Stealth Approach | 28% | 3% | Reduce detection range |
+
+## Difficulty Curve
+[Graph showing expected vs actual difficulty by level]
+- Level 6: Spike detected (35% more deaths than expected)
+- Level 12-14: Too easy (consider adding challenge)
+```
+
+---
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/playtest.yml
+name: Automated Playtest
+
+on:
+  push:
+    branches: [main, develop]
+  schedule:
+    - cron: '0 2 * * *'  # Nightly
+
+jobs:
+  playtest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Build Game
+        run: |
+          unity-builder --target StandaloneLinux64
+          
+      - name: Run Random Bot (30 min)
+        run: |
+          python scripts/playtest/random_bot.py \
+            --duration 1800 \
+            --output reports/random_bot.json
+            
+      - name: Run Explorer Bot (1 hour)
+        run: |
+          python scripts/playtest/explorer_bot.py \
+            --target-coverage 0.7 \
+            --max-duration 3600 \
+            --output reports/explorer.json
+            
+      - name: Run Balance Bot (2 hours)
+        run: |
+          python scripts/playtest/balance_bot.py \
+            --episodes 1000 \
+            --output reports/balance.json
+            
+      - name: Generate Report
+        run: |
+          python scripts/playtest/generate_report.py \
+            --inputs reports/*.json \
+            --output reports/final_report.md
+            
+      - name: Upload Reports
+        uses: actions/upload-artifact@v4
+        with:
+          name: playtest-reports
+          path: reports/
+          
+      - name: Fail on Critical Bugs
+        run: |
+          python scripts/playtest/check_critical.py reports/final_report.md
+```
+
+---
+
+## Best Practices
+
+| Practice | Why |
+|----------|-----|
+| Run nightly | Catch regressions early |
+| Vary seed values | Different random paths |
+| Combine bot types | Each finds different issues |
+| Track metrics over time | Detect trends |
+| Automate report creation | Reduce manual work |
+
+---
+
+> **AI playtesting runs while you sleep.** Wake up to bug reports and balance insights. 🌙