@musashishao/agent-kit 1.8.2 → 1.9.1

package/.agent/skills/game-development/testing-qa/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: testing-qa
+description: Comprehensive QA and testing patterns for games. Playtesting, alpha/beta phases, bug triage, performance testing, and automated testing for Unity.
+---
+
+# Game Testing & QA Skill
+
+> **Purpose**: Systematic quality assurance for game development.
+
+## When to Use
+- Preparing for alpha/beta release
+- Setting up automated test suites
+- Organizing playtesting sessions
+- Debugging production issues
+
+---
+
+## 1. Testing Phases
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TESTING LIFECYCLE                        │
+├─────────────────────────────────────────────────────────────┤
+│  DEV TEST → ALPHA → CLOSED BETA → OPEN BETA → RELEASE      │
+│     ↓         ↓          ↓            ↓           ↓        │
+│  Internal   Friends    Invited     Public     Everyone      │
+│  Team only   & Family   Testers    Testers                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Phase Goals
+| Phase | Focus | Testers |
+|-------|-------|---------|
+| **Dev Test** | Core mechanics work | Team only |
+| **Alpha** | Feature complete, major bugs | 10-50 |
+| **Closed Beta** | Balance, UX, edge cases | 100-1000 |
+| **Open Beta** | Scale, server load, final polish | Unlimited |
+
+---
+
+## 2. Playtesting Sessions
+
+### Session Structure
+```markdown
+## Playtest Session Plan
+
+**Duration**: 30-60 minutes
+**Testers**: [X] people
+**Build**: v[X.X.X]
+
+### Pre-Session (5 min)
+- Explain purpose (not testing player, testing game)
+- No hints during play
+- Think-aloud protocol
+
+### Observation (20-40 min)
+- Silent observation
+- Note confusion points
+- Track completion times
+
+### Post-Session (10-15 min)
+- Open questions first
+- Then specific questions
+- Collect written feedback
+```
+
+### Observation Checklist
+- [ ] Where did player get stuck?
+- [ ] What did player try that didn't work?
+- [ ] What did player miss?
+- [ ] What caused frustration?
+- [ ] What caused joy?
+
+---
+
+## 3. Bug Triage System
+
+### Severity Classification
+| Severity | Definition | Response Time |
+|----------|------------|---------------|
+| **S1 - Critical** | Game unplayable, data loss, crash | Immediate |
+| **S2 - Major** | Feature broken, blocking progression | 24 hours |
+| **S3 - Minor** | Annoying but workaround exists | Next sprint |
+| **S4 - Trivial** | Cosmetic, typo, minor polish | Backlog |
+
+### Bug Report Template
+```markdown
+## Bug: [Short Description]
+
+**Severity**: S[1-4]
+**Platform**: [iOS/Android/PC]
+**Build**: v[X.X.X]
+
+### Steps to Reproduce
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Expected Behavior
+[What should happen]
+
+### Actual Behavior
+[What actually happens]
+
+### Evidence
+[Screenshot/Video/Logs]
+
+### Additional Context
+[Device, OS version, etc.]
+```
+
+---
+
+## 4. Performance Testing
+
+### Target Metrics
+| Metric | Mobile Target | PC Target |
+|--------|---------------|-----------|
+| **FPS** | 30-60 stable | 60+ stable |
+| **Frame Time** | <33ms | <16ms |
+| **Memory** | <500MB | <2GB |
+| **Load Time** | <5s | <3s |
+| **Battery Drain** | <10%/hour | N/A |
+
+### Performance Test Checklist
+- [ ] Profile on lowest target device
+- [ ] Test full session (30+ min)
+- [ ] Monitor thermal throttling
+- [ ] Check memory leaks
+- [ ] Measure after 100 entity spawns
+
+### Unity Profiler Commands
+```csharp
+// Frame timing
+Profiler.BeginSample("MySystem");
+// ... code ...
+Profiler.EndSample();
+
+// Memory snapshot
+UnityEngine.Profiling.Memory.Experimental.MemoryProfiler.TakeSnapshot();
+```
+
+---
+
+## 5. Automated Testing (Unity)
+
+### Test Types
+
+| Type | Purpose | Location |
+|------|---------|----------|
+| **Edit Mode** | Logic, utilities, pure C# | `Tests/Editor/` |
+| **Play Mode** | Runtime, MonoBehaviour | `Tests/Runtime/` |
+| **Integration** | Full systems together | `Tests/Integration/` |
+
+### Edit Mode Test Example
+```csharp
+// Tests/Editor/CombatTests.cs
+using NUnit.Framework;
+
+[TestFixture]
+public class CombatTests
+{
+    [Test]
+    public void Damage_ReducesHealth()
+    {
+        var health = new HealthComponent(100);
+        health.TakeDamage(25);
+        Assert.AreEqual(75, health.CurrentHealth);
+    }
+    
+    [Test]
+    public void Damage_CannotGoBelowZero()
+    {
+        var health = new HealthComponent(50);
+        health.TakeDamage(100);
+        Assert.AreEqual(0, health.CurrentHealth);
+    }
+}
+```
+
+### Play Mode Test Example
+```csharp
+// Tests/Runtime/PlayerMovementTests.cs
+using System.Collections;
+using NUnit.Framework;
+using UnityEngine;
+using UnityEngine.TestTools;
+
+public class PlayerMovementTests
+{
+    private GameObject _player;
+    
+    [SetUp]
+    public void Setup()
+    {
+        _player = new GameObject("Player");
+        _player.AddComponent<PlayerController>();
+    }
+    
+    [TearDown]
+    public void Teardown()
+    {
+        Object.Destroy(_player);
+    }
+    
+    [UnityTest]
+    public IEnumerator Player_MovesRight_WhenInputPositive()
+    {
+        var controller = _player.GetComponent<PlayerController>();
+        var startPos = _player.transform.position;
+        
+        controller.SimulateInput(Vector2.right);
+        yield return new WaitForSeconds(0.5f);
+        
+        Assert.Greater(_player.transform.position.x, startPos.x);
+    }
+}
+```
+
+---
+
+## 6. Regression Testing
+
+### When to Run
+- Before every release
+- After major feature merge
+- After engine update
+- After platform SDK update
+
+### Regression Checklist
+- [ ] All save files load correctly
+- [ ] Tutorial completes without errors
+- [ ] IAP flow works (sandbox)
+- [ ] Ads display and reward correctly
+- [ ] Analytics events fire
+- [ ] All levels completable
+- [ ] No new crashes in crash reporter
+
+---
+
+## 7. Test Coverage Guidelines
+
+| System | Required Coverage |
+|--------|-------------------|
+| **Save/Load** | 90%+ (critical) |
+| **Economy** | 80%+ (balance-sensitive) |
+| **Combat** | 70%+ (core mechanic) |
+| **UI Navigation** | 50%+ (regression) |
+| **Visual Polish** | Manual only |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Test only happy path | Test edge cases |
+| Skip low-end device testing | Test on min spec |
+| Rely only on team testing | Use external testers |
+| Fix all bugs at once | Prioritize by severity |
+| Ship without regression | Run full suite before release |
+
+---
+
+## Related Skills
+- `game-development/game-analytics-integrator`
+- `game-development/unity-integration`
+
+## Related Workflows
+- `/game-launch` - Includes pre-launch audit

package/.agent/skills/game-development/unity-integration/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: unity-integration
+description: Unity Engine expert skill covering C# scripting, DOTS/ECS, Unity 6 features, XR development, and AI integration with ML-Agents and Sentis. Use when developing games with Unity.
+allowed-tools: Read, Write, Edit, Bash, Grep, WebSearch
+---
+
+# Unity Integration Skill
+
+> Expert-level Unity development patterns for Unity 6 (2025+).
+
+---
+
+## When to Use This Skill
+
+- Building games with Unity Engine
+- Implementing Unity-specific patterns (C#, MonoBehaviour, DOTS)
+- Optimizing Unity performance
+- Integrating AI with ML-Agents or Sentis
+- Developing XR experiences with Unity XR
+
+---
+
+## Unity 6 Key Features (2025)
+
+| Feature | Description | Use When |
+|---------|-------------|----------|
+| **GPU Resident Drawer** | Automatic GPU instancing | Large open worlds |
+| **Multiplayer Center** | Netcode setup wizard | Multiplayer games |
+| **Sentis** | On-device AI inference | ML in production |
+| **Adaptive Probe Volumes** | Dynamic GI for open worlds | Large outdoor scenes |
+| **DOTS Entities 1.0** | Stable ECS | Performance-critical |
+
+---
+
+## Architecture Patterns
+
+### 1. MonoBehaviour vs DOTS Decision
+
+| Factor | MonoBehaviour | DOTS/ECS |
+|--------|---------------|----------|
+| **Entity Count** | < 1000 | > 1000 |
+| **Team Experience** | Any | Advanced |
+| **Development Speed** | Fast | Slower |
+| **Performance** | Good | Excellent |
+| **Debugging** | Easy | Complex |
+
+**Recommendation**: Start with MonoBehaviour. Migrate to DOTS only when profiler shows need.
+
+### 2. Recommended Project Structure
+
+```
+Assets/
+├── _Project/           # Your game code
+│   ├── Scripts/
+│   │   ├── Core/       # Singletons, managers
+│   │   ├── Gameplay/   # Game-specific logic
+│   │   ├── UI/         # UI controllers
+│   │   └── Utils/      # Helper classes
+│   ├── Prefabs/
+│   ├── Scenes/
+│   └── ScriptableObjects/
+├── Art/                # Art assets
+├── Audio/              # Audio assets
+├── Plugins/            # Third-party
+└── Resources/          # Runtime-loaded (use sparingly)
+```
+
+### 3. Dependency Injection Pattern
+
+```csharp
+// Instead of FindObjectOfType or Singletons, use explicit injection
+public class PlayerController : MonoBehaviour
+{
+    [SerializeField] private GameManager _gameManager;
+    [SerializeField] private AudioManager _audioManager;
+    
+    // Dependencies are visible in Inspector
+    // Testable and mockable
+}
+```
+
+---
+
+## C# Best Practices for Unity
+
+### 1. Avoid Allocations in Update
+
+```csharp
+// ❌ BAD - Allocates every frame
+void Update()
+{
+    var enemies = FindObjectsOfType<Enemy>();
+    string debug = $"Enemies: {enemies.Length}";
+}
+
+// ✅ GOOD - Cache and reuse
+private Enemy[] _enemyCache = new Enemy[100];
+private StringBuilder _sb = new StringBuilder();
+
+void Update()
+{
+    int count = Physics.OverlapSphereNonAlloc(pos, radius, _enemyCache);
+    _sb.Clear();
+    _sb.Append("Enemies: ").Append(count);
+}
+```
+
+### 2. Object Pooling
+
+```csharp
+public class BulletPool : MonoBehaviour
+{
+    [SerializeField] private GameObject _bulletPrefab;
+    [SerializeField] private int _poolSize = 100;
+    
+    private Queue<GameObject> _pool = new Queue<GameObject>();
+    
+    void Awake()
+    {
+        for (int i = 0; i < _poolSize; i++)
+        {
+            var bullet = Instantiate(_bulletPrefab);
+            bullet.SetActive(false);
+            _pool.Enqueue(bullet);
+        }
+    }
+    
+    public GameObject Get()
+    {
+        if (_pool.Count == 0) return Instantiate(_bulletPrefab);
+        var bullet = _pool.Dequeue();
+        bullet.SetActive(true);
+        return bullet;
+    }
+    
+    public void Return(GameObject bullet)
+    {
+        bullet.SetActive(false);
+        _pool.Enqueue(bullet);
+    }
+}
+```
+
+### 3. Event System (Zero Allocation)
+
+```csharp
+// Define events with Action instead of UnityEvent for perf-critical paths
+public static class GameEvents
+{
+    public static event Action<int> OnScoreChanged;
+    public static event Action OnPlayerDied;
+    
+    public static void ScoreChanged(int newScore) => OnScoreChanged?.Invoke(newScore);
+    public static void PlayerDied() => OnPlayerDied?.Invoke();
+}
+```
+
+---
+
+## Unity ML-Agents Integration
+
+### Setup
+
+```bash
+# Install ML-Agents
+pip install mlagents
+
+# In Unity Package Manager, add:
+# com.unity.ml-agents
+```
+
+### Basic Agent
+
+```csharp
+using Unity.MLAgents;
+using Unity.MLAgents.Sensors;
+using Unity.MLAgents.Actuators;
+
+public class PlayerAgent : Agent
+{
+    [SerializeField] private float _moveSpeed = 5f;
+    
+    public override void CollectObservations(VectorSensor sensor)
+    {
+        sensor.AddObservation(transform.localPosition);
+        sensor.AddObservation(_target.localPosition);
+    }
+    
+    public override void OnActionReceived(ActionBuffers actions)
+    {
+        float moveX = actions.ContinuousActions[0];
+        float moveZ = actions.ContinuousActions[1];
+        
+        transform.localPosition += new Vector3(moveX, 0, moveZ) * _moveSpeed * Time.deltaTime;
+        
+        // Reward shaping
+        float distanceToTarget = Vector3.Distance(transform.localPosition, _target.localPosition);
+        AddReward(-distanceToTarget * 0.001f);
+        
+        if (distanceToTarget < 1.5f)
+        {
+            AddReward(1.0f);
+            EndEpisode();
+        }
+    }
+    
+    public override void Heuristic(in ActionBuffers actionsOut)
+    {
+        // Human control for testing
+        var continuousActions = actionsOut.ContinuousActions;
+        continuousActions[0] = Input.GetAxis("Horizontal");
+        continuousActions[1] = Input.GetAxis("Vertical");
+    }
+}
+```
+
+---
+
+## Unity Sentis (On-Device AI)
+
+### Loading and Running ONNX Model
+
+```csharp
+using Unity.Sentis;
+
+public class AIController : MonoBehaviour
+{
+    [SerializeField] private ModelAsset _modelAsset;
+    
+    private Model _model;
+    private IWorker _worker;
+    
+    void Start()
+    {
+        _model = ModelLoader.Load(_modelAsset);
+        _worker = WorkerFactory.CreateWorker(BackendType.GPUCompute, _model);
+    }
+    
+    public float[] Predict(float[] input)
+    {
+        using var inputTensor = new TensorFloat(new TensorShape(1, input.Length), input);
+        _worker.Execute(inputTensor);
+        
+        var outputTensor = _worker.PeekOutput() as TensorFloat;
+        outputTensor.MakeReadable();
+        
+        return outputTensor.ToReadOnlyArray();
+    }
+    
+    void OnDestroy()
+    {
+        _worker?.Dispose();
+    }
+}
+```
+
+---
+
+## Performance Optimization
+
+### Profiler Checklist
+
+| Metric | Target | Tool |
+|--------|--------|------|
+| Frame Time | < 16.67ms (60fps) | Profiler |
+| GC Allocations | 0 in gameplay | Profiler > GC Alloc |
+| Draw Calls | < 200 mobile, < 2000 PC | Frame Debugger |
+| SetPass Calls | < 100 mobile | Frame Debugger |
+| Physics Time | < 3ms | Physics Debugger |
+
+### Quick Wins
+
+```csharp
+// 1. Cache GetComponent
+private Rigidbody _rb;
+void Awake() => _rb = GetComponent<Rigidbody>();
+
+// 2. Use CompareTag instead of ==
+if (other.CompareTag("Enemy")) // NOT other.tag == "Enemy"
+
+// 3. Avoid LINQ in Update
+// ❌ enemies.Where(e => e.IsAlive).ToList()
+// ✅ Manual loop with cached list
+
+// 4. Use NonAlloc physics
+Physics.RaycastNonAlloc(ray, _hitBuffer, maxDistance);
+Physics.OverlapSphereNonAlloc(pos, radius, _colliderBuffer);
+```
+
+---
+
+## XR Development (Unity XR)
+
+### Setup XR Interaction Toolkit
+
+```csharp
+// XR Rig setup in code
+using UnityEngine.XR.Interaction.Toolkit;
+
+public class XRSetup : MonoBehaviour
+{
+    [SerializeField] private XRController _leftController;
+    [SerializeField] private XRController _rightController;
+    
+    void Start()
+    {
+        // Bind inputs
+        _rightController.selectAction.action.performed += OnGrab;
+        _leftController.activateAction.action.performed += OnActivate;
+    }
+    
+    private void OnGrab(InputAction.CallbackContext ctx)
+    {
+        // Handle grab input
+    }
+}
+```
+
+### VR Performance Targets
+
+| Metric | Quest 2/3 | PC VR |
+|--------|-----------|-------|
+| FPS | 72-90 | 90 |
+| Draw Calls | < 100 | < 300 |
+| Triangles | < 500K | < 2M |
+| Texture Memory | < 1GB | < 4GB |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| `FindObjectOfType` in Update | Cache in Awake |
+| `Resources.Load` at runtime | Addressables |
+| String comparisons for tags | `CompareTag()` |
+| `foreach` with LINQ | `for` loop |
+| Create materials at runtime | Shared materials |
+| Instantiate in hot path | Object pooling |
+
+---
+
+## Quick Reference Commands
+
+```bash
+# Build from command line
+Unity -quit -batchmode -projectPath . -buildTarget StandaloneWindows64 -buildOutput build.exe
+
+# Run tests
+Unity -runTests -testPlatform playmode -testResults results.xml
+
+# Import package
+Unity -importPackage package.unitypackage
+```
+
+---
+
+> **Remember:** Unity is a tool, not the game. Profile before optimizing, prototype before polishing.