@musashishao/agent-kit 1.8.1 → 1.9.0

package/.agent/skills/game-development/procedural-generation/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: procedural-generation
+description: Procedural content generation for games. Algorithms for dungeons, terrain, items, and narratives.
+allowed-tools: Read, Write, Edit, Bash, Grep
+---
+
+# Procedural Generation Skill
+
+> Creating infinite content through algorithms.
+
+## When to Use
+
+- Generating dungeons, levels, or terrain
+- Creating random items, loot, or enemies
+- Building procedural narratives
+- Implementing roguelike mechanics
+
+---
+
+## Algorithm Selection
+
+| Algorithm | Best For | Complexity |
+|-----------|----------|------------|
+| **Perlin/Simplex Noise** | Terrain, textures | Low |
+| **BSP (Binary Space)** | Room-based dungeons | Medium |
+| **Cellular Automata** | Cave systems | Low |
+| **WFC** | Tile-based levels | High |
+| **L-Systems** | Plants, fractals | Medium |
+| **Markov Chains** | Names, text, music | Low |
+| **Grammar-Based** | Quests, dialogue | Medium |
+
+---
+
+## Dungeon Generation (BSP)
+
+```python
+class BSPDungeon:
+    def __init__(self, width, height, min_room=6):
+        self.width = width
+        self.height = height
+        self.min_room = min_room
+        self.rooms = []
+    
+    def generate(self):
+        root = {"x": 0, "y": 0, "w": self.width, "h": self.height}
+        self._split(root)
+        self._create_rooms(root)
+        self._connect_rooms()
+        return self.rooms
+    
+    def _split(self, node, depth=0):
+        if depth > 4 or node["w"] < self.min_room * 2:
+            return
+        
+        if random.random() > 0.5:  # Horizontal
+            split = random.randint(self.min_room, node["h"] - self.min_room)
+            node["left"] = {"x": node["x"], "y": node["y"], "w": node["w"], "h": split}
+            node["right"] = {"x": node["x"], "y": node["y"] + split, "w": node["w"], "h": node["h"] - split}
+        else:  # Vertical  
+            split = random.randint(self.min_room, node["w"] - self.min_room)
+            node["left"] = {"x": node["x"], "y": node["y"], "w": split, "h": node["h"]}
+            node["right"] = {"x": node["x"] + split, "y": node["y"], "w": node["w"] - split, "h": node["h"]}
+        
+        self._split(node.get("left"), depth + 1)
+        self._split(node.get("right"), depth + 1)
+```
+
+---
+
+## Terrain Generation (Noise)
+
+```python
+import noise
+
+def generate_heightmap(width, height, scale=100, octaves=6):
+    heightmap = []
+    for y in range(height):
+        row = []
+        for x in range(width):
+            value = noise.pnoise2(
+                x / scale, y / scale,
+                octaves=octaves,
+                persistence=0.5,
+                lacunarity=2.0
+            )
+            row.append((value + 1) / 2)  # Normalize to 0-1
+        heightmap.append(row)
+    return heightmap
+```
+
+---
+
+## Item Generation (Weighted Random)
+
+```python
+ITEM_TEMPLATES = {
+    "weapon": {
+        "prefixes": ["Rusty", "Sharp", "Ancient", "Cursed"],
+        "bases": ["Sword", "Axe", "Dagger", "Spear"],
+        "suffixes": ["of Fire", "of Ice", "of Speed", "of Power"]
+    }
+}
+
+def generate_item(item_type, rarity):
+    template = ITEM_TEMPLATES[item_type]
+    
+    name_parts = [random.choice(template["bases"])]
+    
+    if rarity >= 2:
+        name_parts.insert(0, random.choice(template["prefixes"]))
+    if rarity >= 3:
+        name_parts.append(random.choice(template["suffixes"]))
+    
+    return {
+        "name": " ".join(name_parts),
+        "damage": 10 + rarity * 5 + random.randint(0, 10),
+        "rarity": rarity
+    }
+```
+
+---
+
+## Wave Function Collapse (Concept)
+
+```
+Constraints → Propagation → Collapse → Repeat
+
+1. Start with superposition (all tiles possible everywhere)
+2. Pick cell with lowest entropy (fewest options)
+3. Collapse to single tile (weighted random)
+4. Propagate constraints to neighbors
+5. Repeat until all cells collapsed or contradiction
+```
+
+---
+
+## Seeds & Reproducibility
+
+```python
+def generate_world(seed: int):
+    random.seed(seed)
+    np.random.seed(seed)
+    
+    # All RNG calls now deterministic
+    terrain = generate_terrain()
+    dungeons = generate_dungeons()
+    items = generate_items()
+    
+    return World(terrain, dungeons, items, seed=seed)
+
+# Same seed = same world
+world1 = generate_world(12345)
+world2 = generate_world(12345)
+assert world1 == world2
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Pure random | Seed-based reproducibility |
+| Generate at runtime | Pre-generate or cache |
+| No validation | Playtest generated content |
+| Ignore edge cases | Handle impossible states |
+
+> **Remember:** Procedural generation creates possibility space. Design constraints create meaning.

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.