@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/card-battle-engine/SKILL.md

@@ -0,0 +1,618 @@
+---
+name: card-battle-engine
+description: Card game and deck building systems. Card data structures, deck management, turn-based combat, effect stacking, synergies, gacha/pack opening, and hand management for Unity.
+---
+
+# Card Battle Engine Skill
+
+> **Purpose**: Build card-based RPG and strategy games.
+
+## When to Use
+- Building card battle games
+- Implementing deck building mechanics
+- Creating turn-based card combat
+- Designing gacha/pack systems
+
+---
+
+## 1. Card Data Structure
+
+### Core Card Definition
+```csharp
+[CreateAssetMenu(fileName = "Card", menuName = "Game/Cards/CardData")]
+public class CardData : ScriptableObject
+{
+    [Header("Identity")]
+    public string cardId;
+    public string cardName;
+    public Sprite artwork;
+    public CardRarity rarity;
+    public CardType type;
+    
+    [Header("Cost")]
+    public int manaCost;
+    public ResourceCost[] additionalCosts;
+    
+    [Header("Stats (for Units)")]
+    public int attack;
+    public int health;
+    
+    [Header("Effects")]
+    public CardEffect[] onPlayEffects;
+    public CardEffect[] onDeathEffects;
+    public CardEffect[] passiveEffects;
+    
+    [Header("Keywords")]
+    public CardKeyword[] keywords;
+    
+    [Header("Deckbuilding")]
+    public int maxCopiesInDeck = 3;
+    public CardFaction faction;
+    
+    [Header("Flavor")]
+    [TextArea] public string flavorText;
+    public string artistName;
+}
+
+public enum CardRarity
+{
+    Common,
+    Uncommon,
+    Rare,
+    Epic,
+    Legendary
+}
+
+public enum CardType
+{
+    Unit,       // Creatures/minions
+    Spell,      // One-time effects
+    Equipment,  // Attach to units
+    Structure,  // Persistent on field
+    Trap        // Triggered effects
+}
+
+public enum CardKeyword
+{
+    Taunt,          // Must be attacked first
+    Rush,           // Can attack immediately
+    Stealth,        // Can't be targeted
+    Divine Shield,  // Blocks first damage
+    Lifesteal,      // Heal on damage
+    Poison,         // Destroy on damage
+    Freeze,         // Skip next action
+    Silence,        // Remove abilities
+    DoublStrike     // Attack twice
+}
+```
+
+---
+
+## 2. Card Effect System
+
+### Effect Architecture
+```csharp
+[System.Serializable]
+public class CardEffect
+{
+    public EffectType type;
+    public TargetType target;
+    public int value;
+    public int duration; // For buffs/debuffs
+    public EffectCondition condition;
+    
+    [Header("Advanced")]
+    public CardEffect[] chainedEffects;
+    public string customEffectId;
+}
+
+public enum EffectType
+{
+    // Damage
+    DealDamage,
+    DealDamageToAll,
+    DealDamageRandom,
+    
+    // Healing
+    Heal,
+    HealAll,
+    
+    // Stats
+    BuffAttack,
+    BuffHealth,
+    DebuffAttack,
+    SetStats,
+    
+    // Card Manipulation
+    DrawCards,
+    DiscardCards,
+    DiscardRandom,
+    ReturnToHand,
+    ShuffleIntoDeck,
+    
+    // Summon
+    SummonUnit,
+    SummonCopy,
+    Transform,
+    
+    // Control
+    Destroy,
+    Silence,
+    Freeze,
+    Stun,
+    
+    // Resource
+    GainMana,
+    GainGold,
+    RestoreMana,
+    
+    // Special
+    Custom // For complex effects
+}
+
+public enum TargetType
+{
+    Self,
+    SingleEnemy,
+    SingleAlly,
+    AllEnemies,
+    AllAllies,
+    AllUnits,
+    RandomEnemy,
+    RandomAlly,
+    EnemyHero,
+    AllyHero,
+    Adjacent,
+    Chosen // Player chooses
+}
+```
+
+### Effect Executor
+```csharp
+public class EffectExecutor : MonoBehaviour
+{
+    public IEnumerator ExecuteEffect(CardEffect effect, ICardTarget source, ICardTarget target)
+    {
+        // Check condition
+        if (effect.condition != null && !effect.condition.IsMet(source, target))
+            yield break;
+        
+        switch (effect.type)
+        {
+            case EffectType.DealDamage:
+                yield return DealDamage(target, effect.value, source);
+                break;
+                
+            case EffectType.Heal:
+                yield return Heal(target, effect.value);
+                break;
+                
+            case EffectType.DrawCards:
+                yield return DrawCards(source.Owner, effect.value);
+                break;
+                
+            case EffectType.SummonUnit:
+                yield return SummonUnit(source.Owner, effect.customEffectId);
+                break;
+                
+            case EffectType.BuffAttack:
+                yield return ApplyBuff(target, StatType.Attack, effect.value, effect.duration);
+                break;
+                
+            case EffectType.Custom:
+                yield return ExecuteCustomEffect(effect.customEffectId, source, target);
+                break;
+        }
+        
+        // Execute chained effects
+        if (effect.chainedEffects != null)
+        {
+            foreach (var chained in effect.chainedEffects)
+            {
+                yield return ExecuteEffect(chained, source, target);
+            }
+        }
+    }
+}
+```
+
+---
+
+## 3. Deck Management
+
+### Deck Data
+```csharp
+[CreateAssetMenu(fileName = "Deck", menuName = "Game/Cards/Deck")]
+public class DeckData : ScriptableObject
+{
+    public string deckName;
+    public CardFaction primaryFaction;
+    public Sprite deckIcon;
+    
+    [Header("Cards")]
+    public DeckEntry[] cards;
+    
+    [Header("Validation")]
+    public int minCards = 30;
+    public int maxCards = 40;
+    
+    public int TotalCards => cards.Sum(e => e.count);
+    
+    public bool IsValid()
+    {
+        if (TotalCards < minCards || TotalCards > maxCards)
+            return false;
+        
+        // Check max copies
+        foreach (var entry in cards)
+        {
+            if (entry.count > entry.card.maxCopiesInDeck)
+                return false;
+        }
+        
+        return true;
+    }
+}
+
+[System.Serializable]
+public struct DeckEntry
+{
+    public CardData card;
+    public int count;
+}
+```
+
+### Runtime Deck Manager
+```csharp
+public class DeckManager
+{
+    private List<CardData> _drawPile = new();
+    private List<CardData> _discardPile = new();
+    private List<CardData> _hand = new();
+    private List<CardData> _exhaustPile = new(); // Removed from game
+    
+    public int HandSize => _hand.Count;
+    public int DrawPileSize => _drawPile.Count;
+    public int DiscardSize => _discardPile.Count;
+    
+    public event Action<CardData> OnCardDrawn;
+    public event Action<CardData> OnCardDiscarded;
+    public event Action OnDeckShuffled;
+    public event Action OnDeckEmpty;
+    
+    public void InitializeDeck(DeckData deckData)
+    {
+        _drawPile.Clear();
+        
+        foreach (var entry in deckData.cards)
+        {
+            for (int i = 0; i < entry.count; i++)
+            {
+                _drawPile.Add(entry.card);
+            }
+        }
+        
+        Shuffle();
+    }
+    
+    public void Shuffle()
+    {
+        // Fisher-Yates shuffle
+        for (int i = _drawPile.Count - 1; i > 0; i--)
+        {
+            int j = Random.Range(0, i + 1);
+            (_drawPile[i], _drawPile[j]) = (_drawPile[j], _drawPile[i]);
+        }
+        
+        OnDeckShuffled?.Invoke();
+    }
+    
+    public CardData DrawCard()
+    {
+        if (_drawPile.Count == 0)
+        {
+            if (_discardPile.Count == 0)
+            {
+                OnDeckEmpty?.Invoke();
+                return null;
+            }
+            
+            // Shuffle discard into draw
+            _drawPile.AddRange(_discardPile);
+            _discardPile.Clear();
+            Shuffle();
+        }
+        
+        CardData card = _drawPile[0];
+        _drawPile.RemoveAt(0);
+        _hand.Add(card);
+        
+        OnCardDrawn?.Invoke(card);
+        return card;
+    }
+    
+    public void DiscardCard(CardData card)
+    {
+        if (_hand.Remove(card))
+        {
+            _discardPile.Add(card);
+            OnCardDiscarded?.Invoke(card);
+        }
+    }
+    
+    public void ExhaustCard(CardData card)
+    {
+        _hand.Remove(card);
+        _exhaustPile.Add(card); // Removed from game entirely
+    }
+}
+```
+
+---
+
+## 4. Turn-Based Battle System
+
+### Battle State Machine
+```csharp
+public class CardBattleManager : MonoBehaviour
+{
+    public BattleState CurrentState { get; private set; }
+    public Player ActivePlayer { get; private set; }
+    public int TurnNumber { get; private set; }
+    
+    public event Action<BattleState> OnStateChanged;
+    public event Action<Player> OnTurnStarted;
+    public event Action<Player> OnTurnEnded;
+    
+    public void StartBattle(Player player1, Player player2)
+    {
+        TurnNumber = 0;
+        ActivePlayer = DetermineFirstPlayer(player1, player2);
+        
+        StartCoroutine(BattleLoop());
+    }
+    
+    private IEnumerator BattleLoop()
+    {
+        SetState(BattleState.BattleStart);
+        
+        // Initial draws
+        yield return DrawInitialHands();
+        
+        while (!IsGameOver())
+        {
+            TurnNumber++;
+            
+            // Player 1 turn
+            yield return RunTurn(ActivePlayer);
+            
+            if (IsGameOver()) break;
+            
+            // Switch active player
+            ActivePlayer = GetOpponent(ActivePlayer);
+        }
+        
+        SetState(BattleState.BattleEnd);
+        DetermineWinner();
+    }
+    
+    private IEnumerator RunTurn(Player player)
+    {
+        OnTurnStarted?.Invoke(player);
+        
+        // Start of turn
+        SetState(BattleState.TurnStart);
+        yield return player.GainMana(TurnNumber);
+        yield return player.DrawCard();
+        yield return TriggerStartOfTurnEffects(player);
+        
+        // Main phase - player actions
+        SetState(BattleState.MainPhase);
+        yield return WaitForPlayerActions(player);
+        
+        // Combat phase
+        SetState(BattleState.CombatPhase);
+        yield return ResolveCombat(player);
+        
+        // End of turn
+        SetState(BattleState.TurnEnd);
+        yield return TriggerEndOfTurnEffects(player);
+        
+        OnTurnEnded?.Invoke(player);
+    }
+}
+
+public enum BattleState
+{
+    BattleStart,
+    TurnStart,
+    MainPhase,
+    CombatPhase,
+    TurnEnd,
+    BattleEnd
+}
+```
+
+---
+
+## 5. Card Synergies
+
+### Synergy System
+```csharp
+[CreateAssetMenu(fileName = "Synergy", menuName = "Game/Cards/Synergy")]
+public class CardSynergy : ScriptableObject
+{
+    public string synergyName;
+    public SynergyType type;
+    
+    [Header("Trigger")]
+    public SynergyTrigger trigger;
+    public int requiredCount = 3; // Cards needed to activate
+    
+    [Header("Effect")]
+    public CardEffect[] bonusEffects;
+    public float statMultiplier = 1.2f;
+}
+
+public enum SynergyType
+{
+    Tribal,     // Same creature type (Dragon, Undead)
+    Elemental,  // Same element (Fire, Ice)
+    Faction,    // Same faction
+    Keyword,    // Share keyword (Taunt, Rush)
+    Cost,       // Same mana cost
+    Set         // Specific card combination
+}
+
+public class SynergyTracker : MonoBehaviour
+{
+    private Dictionary<CardSynergy, int> _synergyCounts = new();
+    private HashSet<CardSynergy> _activeSynergies = new();
+    
+    public event Action<CardSynergy> OnSynergyActivated;
+    public event Action<CardSynergy> OnSynergyDeactivated;
+    
+    public void OnCardPlayed(CardData card)
+    {
+        // Check all synergies this card contributes to
+        foreach (var synergy in GetApplicableSynergies(card))
+        {
+            _synergyCounts.TryGetValue(synergy, out int count);
+            _synergyCounts[synergy] = count + 1;
+            
+            // Check activation
+            if (!_activeSynergies.Contains(synergy) && 
+                _synergyCounts[synergy] >= synergy.requiredCount)
+            {
+                ActivateSynergy(synergy);
+            }
+        }
+    }
+    
+    private void ActivateSynergy(CardSynergy synergy)
+    {
+        _activeSynergies.Add(synergy);
+        OnSynergyActivated?.Invoke(synergy);
+        
+        // Apply bonus effects
+        foreach (var effect in synergy.bonusEffects)
+        {
+            ApplySynergyBonus(effect);
+        }
+    }
+}
+```
+
+---
+
+## 6. Pack/Gacha System
+
+### Pack Opening
+```csharp
+[CreateAssetMenu(fileName = "CardPack", menuName = "Game/Cards/Pack")]
+public class CardPackData : ScriptableObject
+{
+    public string packName;
+    public Sprite packArt;
+    public int cardsPerPack = 5;
+    public int goldCost = 100;
+    public int gemCost = 0;
+    
+    [Header("Rarity Distribution")]
+    public RarityDrop[] rarityDrops;
+    
+    [Header("Pity System")]
+    public bool hasPitySystem = true;
+    public int pityThreshold = 10; // Guaranteed rare after X packs
+    
+    [Header("Card Pool")]
+    public CardData[] availableCards;
+}
+
+[System.Serializable]
+public struct RarityDrop
+{
+    public CardRarity rarity;
+    public float dropRate;
+    public int guaranteedSlot; // -1 = no guarantee, 4 = slot 5 guaranteed
+}
+
+public class PackOpener : MonoBehaviour
+{
+    private int _packsSinceRare = 0;
+    
+    public List<CardData> OpenPack(CardPackData pack)
+    {
+        List<CardData> results = new List<CardData>();
+        
+        for (int i = 0; i < pack.cardsPerPack; i++)
+        {
+            CardRarity rarity = RollRarity(pack, i);
+            CardData card = GetRandomCardOfRarity(pack, rarity);
+            results.Add(card);
+        }
+        
+        // Pity system
+        bool hasRareOrBetter = results.Any(c => c.rarity >= CardRarity.Rare);
+        if (hasRareOrBetter)
+        {
+            _packsSinceRare = 0;
+        }
+        else
+        {
+            _packsSinceRare++;
+            if (_packsSinceRare >= pack.pityThreshold)
+            {
+                // Force upgrade last card
+                int lastIndex = results.Count - 1;
+                results[lastIndex] = GetRandomCardOfRarity(pack, CardRarity.Rare);
+                _packsSinceRare = 0;
+            }
+        }
+        
+        return results;
+    }
+    
+    private CardRarity RollRarity(CardPackData pack, int slotIndex)
+    {
+        // Check guaranteed slots
+        foreach (var drop in pack.rarityDrops)
+        {
+            if (drop.guaranteedSlot == slotIndex)
+                return drop.rarity;
+        }
+        
+        // Roll based on drop rates
+        float roll = Random.value;
+        float cumulative = 0f;
+        
+        foreach (var drop in pack.rarityDrops.OrderByDescending(d => d.rarity))
+        {
+            cumulative += drop.dropRate;
+            if (roll < cumulative)
+                return drop.rarity;
+        }
+        
+        return CardRarity.Common;
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Hardcode card effects | Data-driven effect system |
+| Mutable CardData | Treat CardData as immutable |
+| Sync effects immediately | Use coroutines for animations |
+| Ignore effect order | Clear priority/stack system |
+| No pity system | Protect player investment |
+
+---
+
+## Related Skills
+- `game-development/game-economy-designer` - Card economy
+- `game-development/combat-system` - Combat calculations
+- `game-development/liveops` - Card balance updates