@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/hybrid-game-spec/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: hybrid-game-spec
+description: Templates và hướng dẫn tạo Macro Spec cho game phức tạp. Bao gồm SPEC-architecture và SCHEMA-data patterns.
+---
+
+# Hybrid Game Spec Skill
+
+> **Purpose**: Cung cấp templates và nguyên tắc để tạo "Macro Spec" cho game trước khi code.
+
+## Khi Nào Sử Dụng
+- Bắt đầu dự án game phức tạp (3+ systems)
+- Khi cần định nghĩa architecture trước khi phát triển
+- Khi muốn nhiều agents làm việc song song
+
+---
+
+## 1. SPEC-architecture.md Template
+
+Template đầy đủ tại: [SPEC-architecture-template.md](./templates/SPEC-architecture-template.md)
+
+### Nội dung bắt buộc:
+
+| Section | Mô tả |
+|---------|-------|
+| **Event Bus** | Liệt kê TẤT CẢ game events (OnPlayerHurt, OnScoreChanged...) |
+| **Manager Sequence** | Thứ tự khởi tạo Singletons |
+| **Save System** | Contract cho save/load data |
+| **Input Abstraction** | Interface cho touch/keyboard |
+
+### Event Bus Pattern
+
+```csharp
+// GameEvents.cs - Static event bus
+public static class GameEvents
+{
+    // Core Events
+    public static event Action<int> OnScoreChanged;
+    public static event Action<int> OnHealthChanged;
+    public static event Action OnPlayerDied;
+    public static event Action<int> OnLevelComplete;
+    
+    // UI Events
+    public static event Action OnPauseRequested;
+    public static event Action OnResumeRequested;
+    
+    // Economy Events
+    public static event Action<int> OnCoinCollected;
+    public static event Action<string, int> OnItemPurchased;
+    
+    // Invocation helpers
+    public static void ScoreChanged(int score) => OnScoreChanged?.Invoke(score);
+    public static void PlayerDied() => OnPlayerDied?.Invoke();
+    
+    // Cleanup (call on scene unload)
+    public static void ClearAll()
+    {
+        OnScoreChanged = null;
+        OnHealthChanged = null;
+        OnPlayerDied = null;
+        // ... clear all
+    }
+}
+```
+
+---
+
+## 2. SCHEMA-data.md Template
+
+Template đầy đủ tại: [SCHEMA-data-template.md](./templates/SCHEMA-data-template.md)
+
+### Nguyên Tắc ScriptableObject
+
+| Rule | Lý Do |
+|------|-------|
+| **Mọi số balance phải trong SO** | AI có thể sửa .asset mà không làm hỏng logic |
+| **Nested structs cho complex data** | Tổ chức rõ ràng |
+| **[CreateAssetMenu] attribute** | Dễ tạo asset trong Editor |
+| **Default values có ý nghĩa** | Game chạy được ngay cả khi chưa tune |
+
+### ScriptableObject Patterns
+
+```csharp
+// CharacterData.cs
+[CreateAssetMenu(fileName = "CharacterData", menuName = "Game/Data/Character")]
+public class CharacterData : ScriptableObject
+{
+    [Header("Movement")]
+    public float MoveSpeed = 5f;
+    public float JumpForce = 10f;
+    public float Gravity = 2f;
+    
+    [Header("Combat")]
+    public int MaxHealth = 100;
+    public int AttackDamage = 10;
+    public float AttackCooldown = 0.5f;
+    
+    [Header("Progression")]
+    public AnimationCurve LevelUpCurve;
+    public int BaseXP = 100;
+}
+
+// EnemyData.cs
+[CreateAssetMenu(fileName = "EnemyData", menuName = "Game/Data/Enemy")]
+public class EnemyData : ScriptableObject
+{
+    public string EnemyName;
+    public Sprite Icon;
+    
+    [Header("Stats")]
+    public int Health = 50;
+    public int Damage = 10;
+    public float MoveSpeed = 3f;
+    
+    [Header("Behavior")]
+    public float DetectionRange = 5f;
+    public float AttackRange = 1.5f;
+    public float PatrolSpeed = 2f;
+    
+    [Header("Drops")]
+    public int MinCoinDrop = 5;
+    public int MaxCoinDrop = 15;
+    public float DropChance = 0.3f;
+}
+
+// LevelConfig.cs
+[CreateAssetMenu(fileName = "Level_01", menuName = "Game/Data/Level")]
+public class LevelConfig : ScriptableObject
+{
+    public int LevelNumber;
+    public string LevelName;
+    public string SceneName;
+    
+    [Header("Difficulty")]
+    public Difficulty Difficulty;
+    public int EnemyCount;
+    public float TimeLimit;
+    
+    [Header("Rewards")]
+    public int StarThreshold1;
+    public int StarThreshold2;
+    public int StarThreshold3;
+    public int CompletionBonus;
+}
+
+public enum Difficulty { Easy, Normal, Hard, Nightmare }
+```
+
+---
+
+## 3. Decoupled System Pattern
+
+### Why Decoupling?
+
+| Coupled (❌) | Decoupled (✅) |
+|--------------|---------------|
+| Agent A sửa file → Agent B bị conflict | Agents làm song song |
+| Change UI → phải sửa Combat code | Change 1 nơi, không ảnh hưởng nơi khác |
+| Hard to test | Easy to unit test |
+
+### Implementation
+
+```csharp
+// ✅ Combat KHÔNG biết về UI
+public class CombatSystem : MonoBehaviour
+{
+    [SerializeField] private CharacterData _data;
+    private int _currentHealth;
+    
+    void Start() => _currentHealth = _data.MaxHealth;
+    
+    public void TakeDamage(int damage)
+    {
+        _currentHealth -= damage;
+        
+        // Fire event, KHÔNG gọi UI trực tiếp
+        GameEvents.HealthChanged(_currentHealth);
+        
+        if (_currentHealth <= 0)
+            GameEvents.PlayerDied();
+    }
+}
+
+// ✅ UI SUBSCRIBE to events
+public class HealthUI : MonoBehaviour
+{
+    [SerializeField] private Slider _healthBar;
+    [SerializeField] private CharacterData _data;
+    
+    void OnEnable() => GameEvents.OnHealthChanged += UpdateHealth;
+    void OnDisable() => GameEvents.OnHealthChanged -= UpdateHealth;
+    
+    void UpdateHealth(int current)
+    {
+        _healthBar.value = (float)current / _data.MaxHealth;
+    }
+}
+```
+
+---
+
+## 4. Checklist Trước Khi Code
+
+- [ ] Event Bus defined với TẤT CẢ events
+- [ ] Manager bootstrap sequence documented
+- [ ] Save system contract defined
+- [ ] Character ScriptableObject template created
+- [ ] Enemy ScriptableObject template created
+- [ ] Level ScriptableObject template created
+- [ ] Input abstraction layer designed
+
+---
+
+## Related Skills
+- `game-development/unity-integration`
+- `game-development/game-design`
+- `clean-code`
+
+## Related Workflows
+- `/game-hybrid` - Sử dụng skill này cho Tầng 1
+- `/game-from-idea` - Simplified workflow cho rapid prototyping