@musashishao/agent-kit 1.8.2 → 1.9.1

package/.agent/skills/game-development/godot-expert/SKILL.md

@@ -0,0 +1,462 @@
+---
+name: godot-expert
+description: Godot Engine expert skill covering GDScript, C#, Godot 4.3+ features, shader language, and performance optimization. Use when developing games with Godot.
+allowed-tools: Read, Write, Edit, Bash, Grep, WebSearch
+---
+
+# Godot Expert Skill
+
+> Master Godot 4.3+ development with modern best practices.
+
+---
+
+## When to Use This Skill
+
+- Building games with Godot Engine
+- Writing GDScript or C# for Godot
+- Optimizing Godot performance
+- Creating custom shaders in Godot
+- Integrating AI with Godot RL Agents
+
+---
+
+## Godot 4.3+ Key Features (2025)
+
+| Feature | Description | Use When |
+|---------|-------------|----------|
+| **Enhanced TileMap** | Multi-layer, physics | 2D games |
+| **Compositor Effects** | Custom post-processing | Visual effects |
+| **Interactive Music** | Adaptive audio streams | Dynamic soundtrack |
+| **Navigation Links** | Better pathfinding | Complex AI |
+| **Typed Collections** | Type-safe Arrays/Dicts | Clean code |
+
+---
+
+## Architecture Patterns
+
+### 1. Scene Tree Philosophy
+
+```
+MainGame (Node)
+├── World (Node2D/3D)
+│   ├── Level (Node)
+│   │   ├── Tilemap
+│   │   └── Entities (Node)
+│   │       ├── Player
+│   │       └── Enemies
+│   └── Camera
+├── UI (CanvasLayer)
+│   ├── HUD
+│   └── Menus
+├── Audio (Node)
+│   ├── MusicPlayer
+│   └── SFXPool
+└── Managers (Node)
+    ├── GameManager (Autoload)
+    └── SaveManager (Autoload)
+```
+
+### 2. Autoload (Singleton) Pattern
+
+```gdscript
+# GameManager.gd - Register as Autoload
+extends Node
+
+signal game_paused
+signal game_resumed
+signal score_changed(new_score: int)
+
+var score: int = 0:
+    set(value):
+        score = value
+        score_changed.emit(score)
+
+var is_paused: bool = false:
+    set(value):
+        is_paused = value
+        get_tree().paused = value
+        if value:
+            game_paused.emit()
+        else:
+            game_resumed.emit()
+
+func reset_game() -> void:
+    score = 0
+    is_paused = false
+```
+
+### 3. Recommended Project Structure
+
+```
+project/
+├── addons/           # Third-party plugins
+├── assets/
+│   ├── art/
+│   ├── audio/
+│   └── fonts/
+├── scenes/
+│   ├── levels/
+│   ├── ui/
+│   └── entities/
+├── scripts/
+│   ├── autoloads/
+│   ├── components/
+│   ├── resources/
+│   └── utils/
+├── shaders/
+└── project.godot
+```
+
+---
+
+## GDScript Best Practices
+
+### 1. Type Hints (Always Use)
+
+```gdscript
+# ✅ GOOD - Fully typed
+class_name Player
+extends CharacterBody2D
+
+@export var speed: float = 200.0
+@export var jump_force: float = -400.0
+
+var health: int = 100
+var velocity_component: VelocityComponent
+
+func take_damage(amount: int) -> void:
+    health -= amount
+    if health <= 0:
+        die()
+
+func die() -> void:
+    queue_free()
+```
+
+### 2. Signals for Decoupling
+
+```gdscript
+# Player.gd
+signal health_changed(new_health: int, max_health: int)
+signal died
+
+func take_damage(amount: int) -> void:
+    health -= amount
+    health_changed.emit(health, max_health)
+    if health <= 0:
+        died.emit()
+
+# HealthBar.gd (Connect in editor or code)
+func _ready() -> void:
+    var player := get_tree().get_first_node_in_group("player") as Player
+    player.health_changed.connect(_on_health_changed)
+
+func _on_health_changed(current: int, maximum: int) -> void:
+    value = float(current) / float(maximum)
+```
+
+### 3. Resource-Based Data
+
+```gdscript
+# weapon_data.gd
+class_name WeaponData
+extends Resource
+
+@export var name: String
+@export var damage: int
+@export var fire_rate: float
+@export var icon: Texture2D
+@export var projectile_scene: PackedScene
+
+# Usage in code
+@export var weapon: WeaponData
+
+func attack() -> void:
+    var projectile := weapon.projectile_scene.instantiate()
+    projectile.damage = weapon.damage
+    add_child(projectile)
+```
+
+### 4. Component Pattern
+
+```gdscript
+# health_component.gd
+class_name HealthComponent
+extends Node
+
+signal health_changed(current: int, maximum: int)
+signal died
+
+@export var max_health: int = 100
+var current_health: int
+
+func _ready() -> void:
+    current_health = max_health
+
+func take_damage(amount: int) -> void:
+    current_health = maxi(0, current_health - amount)
+    health_changed.emit(current_health, max_health)
+    if current_health == 0:
+        died.emit()
+
+func heal(amount: int) -> void:
+    current_health = mini(max_health, current_health + amount)
+    health_changed.emit(current_health, max_health)
+```
+
+---
+
+## State Machine Implementation
+
+```gdscript
+# state_machine.gd
+class_name StateMachine
+extends Node
+
+@export var initial_state: State
+var current_state: State
+
+func _ready() -> void:
+    for child in get_children():
+        if child is State:
+            child.state_machine = self
+    
+    if initial_state:
+        initial_state.enter()
+        current_state = initial_state
+
+func _process(delta: float) -> void:
+    if current_state:
+        current_state.update(delta)
+
+func _physics_process(delta: float) -> void:
+    if current_state:
+        current_state.physics_update(delta)
+
+func transition_to(state_name: String) -> void:
+    var new_state := get_node_or_null(state_name) as State
+    if new_state and new_state != current_state:
+        current_state.exit()
+        current_state = new_state
+        current_state.enter()
+
+# state.gd
+class_name State
+extends Node
+
+var state_machine: StateMachine
+
+func enter() -> void:
+    pass
+
+func exit() -> void:
+    pass
+
+func update(_delta: float) -> void:
+    pass
+
+func physics_update(_delta: float) -> void:
+    pass
+```
+
+---
+
+## Godot Shaders
+
+### Basic 2D Shader
+
+```gdshader
+shader_type canvas_item;
+
+uniform vec4 flash_color : source_color = vec4(1.0, 1.0, 1.0, 1.0);
+uniform float flash_amount : hint_range(0.0, 1.0) = 0.0;
+
+void fragment() {
+    vec4 tex_color = texture(TEXTURE, UV);
+    COLOR = mix(tex_color, flash_color, flash_amount);
+    COLOR.a = tex_color.a;
+}
+```
+
+### Outline Shader
+
+```gdshader
+shader_type canvas_item;
+
+uniform float outline_width : hint_range(0.0, 10.0) = 1.0;
+uniform vec4 outline_color : source_color = vec4(0.0, 0.0, 0.0, 1.0);
+
+void fragment() {
+    vec2 size = TEXTURE_PIXEL_SIZE * outline_width;
+    
+    float alpha = texture(TEXTURE, UV).a;
+    alpha += texture(TEXTURE, UV + vec2(size.x, 0)).a;
+    alpha += texture(TEXTURE, UV + vec2(-size.x, 0)).a;
+    alpha += texture(TEXTURE, UV + vec2(0, size.y)).a;
+    alpha += texture(TEXTURE, UV + vec2(0, -size.y)).a;
+    
+    vec4 final_color = texture(TEXTURE, UV);
+    if (final_color.a < 1.0 && alpha > 0.0) {
+        final_color = outline_color;
+    }
+    COLOR = final_color;
+}
+```
+
+---
+
+## Godot RL Agents Integration
+
+### Setup
+
+```bash
+# Install Python package
+pip install godot-rl
+
+# Clone sync wrapper
+git clone https://github.com/edbeeching/godot_rl_agents_plugin
+```
+
+### Basic RL Environment
+
+```gdscript
+# ai_agent.gd
+extends AIController2D
+
+func get_observations() -> Dictionary:
+    return {
+        "position": [global_position.x, global_position.y],
+        "velocity": [velocity.x, velocity.y],
+        "target": [target.global_position.x, target.global_position.y]
+    }
+
+func set_action(action: Dictionary) -> void:
+    var move_x: float = action["move"][0]
+    var move_y: float = action["move"][1]
+    velocity = Vector2(move_x, move_y) * speed
+
+func get_reward() -> float:
+    var distance := global_position.distance_to(target.global_position)
+    return -distance * 0.001
+
+func is_done() -> bool:
+    return global_position.distance_to(target.global_position) < 10.0
+```
+
+---
+
+## Performance Optimization
+
+### Profiler Checklist
+
+| Metric | Target | Check |
+|--------|--------|-------|
+| Frame Time | < 16ms | Debugger > Profiler |
+| Physics FPS | 60 stable | Monitor > Debugger |
+| Draw Calls | < 500 2D, < 200 mobile | Frame > Debugger |
+| Object Count | Monitor growth | Remote > Nodes |
+
+### Quick Wins
+
+```gdscript
+# 1. Use object pooling
+var bullet_pool: Array[Bullet] = []
+
+func get_bullet() -> Bullet:
+    if bullet_pool.is_empty():
+        return bullet_scene.instantiate()
+    return bullet_pool.pop_back()
+
+func return_bullet(bullet: Bullet) -> void:
+    bullet.visible = false
+    bullet_pool.append(bullet)
+
+# 2. Use call_deferred for heavy operations
+queue_free.call_deferred()
+
+# 3. Disable processing when not needed
+set_process(false)
+set_physics_process(false)
+
+# 4. Use groups for efficient queries
+get_tree().get_nodes_in_group("enemies")
+```
+
+---
+
+## C# in Godot
+
+### When to Use C#
+
+| Use GDScript When | Use C# When |
+|-------------------|-------------|
+| Rapid prototyping | Complex systems |
+| Simple games | Team knows C# |
+| Learning Godot | Need .NET libraries |
+| Hot reload needed | Performance-critical |
+
+### C# Example
+
+```csharp
+using Godot;
+
+public partial class Player : CharacterBody2D
+{
+    [Export] public float Speed { get; set; } = 200.0f;
+    [Export] public float JumpForce { get; set; } = -400.0f;
+    
+    private float _gravity = ProjectSettings.GetSetting("physics/2d/default_gravity").AsSingle();
+    
+    public override void _PhysicsProcess(double delta)
+    {
+        Vector2 velocity = Velocity;
+        
+        if (!IsOnFloor())
+            velocity.Y += _gravity * (float)delta;
+        
+        if (Input.IsActionJustPressed("jump") && IsOnFloor())
+            velocity.Y = JumpForce;
+        
+        float direction = Input.GetAxis("move_left", "move_right");
+        velocity.X = direction * Speed;
+        
+        Velocity = velocity;
+        MoveAndSlide();
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| `get_node` with long paths | `@onready` + short paths |
+| Process when not needed | `set_process(false)` |
+| Create nodes in `_process` | Object pooling |
+| Use strings for node paths | `@export NodePath` |
+| Hardcode values | Resources or exports |
+| Skip type hints | Always use type hints |
+
+---
+
+## Quick Reference Commands
+
+```bash
+# Export from command line
+godot --headless --export-release "Windows Desktop" build/game.exe
+
+# Run specific scene
+godot scenes/main.tscn
+
+# Run tests (GUT plugin)
+godot --headless -s addons/gut/gut_cmdln.gd -gdir=res://test/
+
+# Convert project format
+godot --convert-project
+```
+
+---
+
+> **Remember:** Godot's strength is simplicity. Don't fight the engine—embrace scene composition and signals.

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