@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/narrative-branching/SKILL.md

@@ -0,0 +1,593 @@
+---
+name: narrative-branching
+description: Branching narrative and dialogue systems. Dialogue trees, story branches, player choices, relationship systems, quest journals, and conditional content for Unity.
+---
+
+# Narrative Branching Skill
+
+> **Purpose**: Build games with meaningful choices and branching stories.
+
+## When to Use
+- Building story-driven games
+- Implementing dialogue systems
+- Creating relationship mechanics
+- Designing quest systems
+
+---
+
+## 1. Dialogue Node System
+
+### Core Data Structures
+```csharp
+[CreateAssetMenu(fileName = "DialogueTree", menuName = "Game/Narrative/DialogueTree")]
+public class DialogueTree : ScriptableObject
+{
+    public string treeId;
+    public string treeName;
+    
+    [Header("Nodes")]
+    public DialogueNode startNode;
+    public DialogueNode[] allNodes;
+    
+    [Header("Requirements")]
+    public Condition[] startConditions;
+    
+    [Header("Metadata")]
+    public CharacterData speaker;
+    public bool isRepeatable = true;
+}
+
+[System.Serializable]
+public class DialogueNode
+{
+    public string nodeId;
+    public NodeType type;
+    
+    [Header("Content")]
+    public CharacterData speaker;
+    [TextArea(3, 10)]
+    public string dialogueText;
+    public AudioClip voiceover;
+    public float displayDuration = 0f; // 0 = wait for input
+    
+    [Header("Choices")]
+    public DialogueChoice[] choices;
+    
+    [Header("Auto-Continue")]
+    public DialogueNode nextNode; // Used when no choices
+    
+    [Header("Effects")]
+    public DialogueEffect[] onEnterEffects;
+    public DialogueEffect[] onExitEffects;
+}
+
+public enum NodeType
+{
+    Dialogue,       // Normal dialogue
+    Choice,         // Player makes choice
+    Branch,         // Conditional branch (NPC decides)
+    Event,          // Trigger game event
+    End             // End conversation
+}
+
+[System.Serializable]
+public class DialogueChoice
+{
+    public string choiceText;
+    public DialogueNode targetNode;
+    
+    [Header("Requirements")]
+    public Condition[] showConditions;    // To display choice
+    public Condition[] enableConditions;  // To select choice (grayed vs available)
+    
+    [Header("Tooltip")]
+    public string disabledReason; // "Requires 5 Charisma"
+    
+    [Header("Effects")]
+    public DialogueEffect[] onSelectEffects;
+}
+```
+
+---
+
+## 2. Condition System
+
+### Conditions for Branching
+```csharp
+[System.Serializable]
+public class Condition
+{
+    public ConditionType type;
+    public string targetId;
+    public ComparisonOperator comparison;
+    public int value;
+    
+    public bool Evaluate()
+    {
+        int actualValue = GetActualValue();
+        
+        return comparison switch
+        {
+            ComparisonOperator.Equals => actualValue == value,
+            ComparisonOperator.NotEquals => actualValue != value,
+            ComparisonOperator.GreaterThan => actualValue > value,
+            ComparisonOperator.LessThan => actualValue < value,
+            ComparisonOperator.GreaterOrEqual => actualValue >= value,
+            ComparisonOperator.LessOrEqual => actualValue <= value,
+            _ => false
+        };
+    }
+    
+    private int GetActualValue()
+    {
+        return type switch
+        {
+            ConditionType.HasItem => InventoryManager.GetItemCount(targetId),
+            ConditionType.QuestState => QuestManager.GetQuestState(targetId),
+            ConditionType.RelationshipLevel => RelationshipManager.GetLevel(targetId),
+            ConditionType.PlayerStat => PlayerStats.GetStat(targetId),
+            ConditionType.Flag => FlagManager.IsSet(targetId) ? 1 : 0,
+            ConditionType.DialogueHistory => DialogueHistory.TimesChosen(targetId),
+            ConditionType.TimeOfDay => TimeManager.CurrentHour,
+            ConditionType.Random => Random.Range(0, 100),
+            _ => 0
+        };
+    }
+}
+
+public enum ConditionType
+{
+    HasItem,
+    QuestState,
+    RelationshipLevel,
+    PlayerStat,
+    Flag,
+    DialogueHistory,
+    TimeOfDay,
+    Random
+}
+
+public enum ComparisonOperator
+{
+    Equals,
+    NotEquals,
+    GreaterThan,
+    LessThan,
+    GreaterOrEqual,
+    LessOrEqual
+}
+```
+
+---
+
+## 3. Dialogue Effects
+
+### Effect System
+```csharp
+[System.Serializable]
+public class DialogueEffect
+{
+    public EffectType type;
+    public string targetId;
+    public int value;
+    public string stringValue;
+    
+    public void Execute()
+    {
+        switch (type)
+        {
+            case EffectType.GiveItem:
+                InventoryManager.AddItem(targetId, value);
+                break;
+                
+            case EffectType.TakeItem:
+                InventoryManager.RemoveItem(targetId, value);
+                break;
+                
+            case EffectType.ChangeRelationship:
+                RelationshipManager.Modify(targetId, value);
+                break;
+                
+            case EffectType.SetFlag:
+                FlagManager.Set(targetId, value == 1);
+                break;
+                
+            case EffectType.StartQuest:
+                QuestManager.StartQuest(targetId);
+                break;
+                
+            case EffectType.CompleteQuestObjective:
+                QuestManager.CompleteObjective(targetId);
+                break;
+                
+            case EffectType.ChangePlayerStat:
+                PlayerStats.Modify(targetId, value);
+                break;
+                
+            case EffectType.PlayCutscene:
+                CutsceneManager.Play(targetId);
+                break;
+                
+            case EffectType.TeleportPlayer:
+                PlayerManager.Teleport(targetId);
+                break;
+                
+            case EffectType.SpawnNPC:
+                NPCManager.Spawn(targetId);
+                break;
+                
+            case EffectType.Custom:
+                GameEvents.OnCustomDialogueEffect?.Invoke(targetId, stringValue);
+                break;
+        }
+        
+        GameEvents.OnDialogueEffectExecuted?.Invoke(this);
+    }
+}
+
+public enum EffectType
+{
+    GiveItem,
+    TakeItem,
+    ChangeRelationship,
+    SetFlag,
+    StartQuest,
+    CompleteQuestObjective,
+    ChangePlayerStat,
+    PlayCutscene,
+    TeleportPlayer,
+    SpawnNPC,
+    Custom
+}
+```
+
+---
+
+## 4. Dialogue Manager
+
+### Runtime Controller
+```csharp
+public class DialogueManager : MonoBehaviour
+{
+    public static DialogueManager Instance { get; private set; }
+    
+    [SerializeField] private DialogueUI _dialogueUI;
+    
+    public bool IsInDialogue { get; private set; }
+    public DialogueTree CurrentTree { get; private set; }
+    public DialogueNode CurrentNode { get; private set; }
+    
+    public event Action<DialogueTree> OnDialogueStarted;
+    public event Action<DialogueNode> OnNodeEntered;
+    public event Action<DialogueChoice> OnChoiceSelected;
+    public event Action OnDialogueEnded;
+    
+    public bool StartDialogue(DialogueTree tree)
+    {
+        // Check start conditions
+        if (!EvaluateConditions(tree.startConditions))
+            return false;
+        
+        IsInDialogue = true;
+        CurrentTree = tree;
+        
+        OnDialogueStarted?.Invoke(tree);
+        _dialogueUI.Show();
+        
+        EnterNode(tree.startNode);
+        return true;
+    }
+    
+    private void EnterNode(DialogueNode node)
+    {
+        CurrentNode = node;
+        
+        // Execute on-enter effects
+        foreach (var effect in node.onEnterEffects)
+        {
+            effect.Execute();
+        }
+        
+        OnNodeEntered?.Invoke(node);
+        
+        // Update UI
+        _dialogueUI.DisplayNode(node);
+        
+        // Handle node type
+        switch (node.type)
+        {
+            case NodeType.Dialogue:
+                // Wait for player input or auto-continue
+                if (node.nextNode != null && node.displayDuration > 0)
+                {
+                    StartCoroutine(AutoContinue(node.displayDuration));
+                }
+                break;
+                
+            case NodeType.Choice:
+                // Display available choices
+                var validChoices = GetValidChoices(node.choices);
+                _dialogueUI.ShowChoices(validChoices);
+                break;
+                
+            case NodeType.Branch:
+                // Auto-select based on conditions
+                AutoBranch(node.choices);
+                break;
+                
+            case NodeType.Event:
+                // Execute and continue
+                foreach (var effect in node.onExitEffects)
+                {
+                    effect.Execute();
+                }
+                if (node.nextNode != null)
+                    EnterNode(node.nextNode);
+                else
+                    EndDialogue();
+                break;
+                
+            case NodeType.End:
+                EndDialogue();
+                break;
+        }
+    }
+    
+    public void SelectChoice(DialogueChoice choice)
+    {
+        // Execute choice effects
+        foreach (var effect in choice.onSelectEffects)
+        {
+            effect.Execute();
+        }
+        
+        // Record in history
+        DialogueHistory.RecordChoice(CurrentTree.treeId, CurrentNode.nodeId, choice.choiceText);
+        
+        OnChoiceSelected?.Invoke(choice);
+        
+        // Navigate to target
+        if (choice.targetNode != null)
+        {
+            // Execute current node exit effects
+            foreach (var effect in CurrentNode.onExitEffects)
+            {
+                effect.Execute();
+            }
+            
+            EnterNode(choice.targetNode);
+        }
+        else
+        {
+            EndDialogue();
+        }
+    }
+    
+    private void EndDialogue()
+    {
+        IsInDialogue = false;
+        _dialogueUI.Hide();
+        
+        OnDialogueEnded?.Invoke();
+        GameEvents.OnDialogueEnded?.Invoke(CurrentTree);
+        
+        CurrentTree = null;
+        CurrentNode = null;
+    }
+}
+```
+
+---
+
+## 5. Relationship System
+
+### Relationship Data
+```csharp
+[CreateAssetMenu(fileName = "Character", menuName = "Game/Narrative/Character")]
+public class CharacterData : ScriptableObject
+{
+    public string characterId;
+    public string displayName;
+    public Sprite portrait;
+    
+    [Header("Relationship")]
+    public int defaultRelationship = 50; // 0-100
+    public RelationshipTier[] tiers;
+    
+    [Header("Personality")]
+    public PersonalityTrait[] traits;
+    public string[] likes;
+    public string[] dislikes;
+}
+
+[System.Serializable]
+public class RelationshipTier
+{
+    public string tierName; // Stranger, Acquaintance, Friend, Close Friend, Romance
+    public int minValue;
+    public DialogueTree[] availableDialogues;
+    public Sprite tierIcon;
+}
+
+public class RelationshipManager : MonoBehaviour
+{
+    private Dictionary<string, int> _relationships = new();
+    
+    public event Action<string, int, int> OnRelationshipChanged; // characterId, oldVal, newVal
+    public event Action<string, RelationshipTier> OnTierChanged;
+    
+    public int GetLevel(string characterId)
+    {
+        _relationships.TryGetValue(characterId, out int level);
+        return level;
+    }
+    
+    public void Modify(string characterId, int delta)
+    {
+        int oldValue = GetLevel(characterId);
+        int newValue = Mathf.Clamp(oldValue + delta, 0, 100);
+        
+        _relationships[characterId] = newValue;
+        
+        OnRelationshipChanged?.Invoke(characterId, oldValue, newValue);
+        
+        // Check tier change
+        var oldTier = GetTier(characterId, oldValue);
+        var newTier = GetTier(characterId, newValue);
+        
+        if (oldTier != newTier)
+        {
+            OnTierChanged?.Invoke(characterId, newTier);
+            GameEvents.OnRelationshipTierChanged?.Invoke(characterId, newTier);
+        }
+    }
+    
+    public void GiveGift(string characterId, ItemData item)
+    {
+        var character = GetCharacter(characterId);
+        
+        int delta = 5; // Base
+        
+        if (character.likes.Contains(item.itemId))
+            delta = 15;
+        else if (character.dislikes.Contains(item.itemId))
+            delta = -10;
+        
+        Modify(characterId, delta);
+        GameEvents.OnGiftGiven?.Invoke(characterId, item, delta);
+    }
+}
+```
+
+---
+
+## 6. Quest Journal
+
+### Quest System
+```csharp
+[CreateAssetMenu(fileName = "Quest", menuName = "Game/Narrative/Quest")]
+public class QuestData : ScriptableObject
+{
+    public string questId;
+    public string questName;
+    [TextArea] public string description;
+    
+    public QuestType type;
+    public CharacterData questGiver;
+    
+    [Header("Objectives")]
+    public QuestObjective[] objectives;
+    
+    [Header("Rewards")]
+    public ItemReward[] itemRewards;
+    public int goldReward;
+    public int expReward;
+    
+    [Header("Flow")]
+    public QuestData[] prerequisiteQuests;
+    public DialogueTree startDialogue;
+    public DialogueTree completeDialogue;
+}
+
+[System.Serializable]
+public class QuestObjective
+{
+    public string objectiveId;
+    public string description;
+    public ObjectiveType type;
+    public string targetId;
+    public int requiredCount = 1;
+    public bool isOptional = false;
+}
+
+public enum ObjectiveType
+{
+    Kill,           // Kill X enemies of type
+    Collect,        // Collect X items
+    TalkTo,         // Talk to NPC
+    GoTo,           // Reach location
+    Escort,         // Escort NPC
+    Defend,         // Defend location for time
+    Deliver,        // Bring item to NPC
+    Investigate,    // Examine objects
+    Custom          // Custom trigger
+}
+
+public class QuestManager : MonoBehaviour
+{
+    private Dictionary<string, QuestState> _questStates = new();
+    private Dictionary<string, int> _objectiveProgress = new();
+    
+    public event Action<QuestData> OnQuestStarted;
+    public event Action<QuestData, QuestObjective> OnObjectiveCompleted;
+    public event Action<QuestData> OnQuestCompleted;
+    
+    public void StartQuest(string questId)
+    {
+        var quest = GetQuestData(questId);
+        if (quest == null || _questStates.ContainsKey(questId))
+            return;
+        
+        _questStates[questId] = QuestState.Active;
+        
+        // Initialize objective progress
+        foreach (var obj in quest.objectives)
+        {
+            _objectiveProgress[$"{questId}_{obj.objectiveId}"] = 0;
+        }
+        
+        OnQuestStarted?.Invoke(quest);
+        GameEvents.OnQuestStarted?.Invoke(quest);
+    }
+    
+    public void UpdateObjective(string questId, string objectiveId, int progress)
+    {
+        string key = $"{questId}_{objectiveId}";
+        _objectiveProgress[key] = progress;
+        
+        var quest = GetQuestData(questId);
+        var objective = quest.objectives.First(o => o.objectiveId == objectiveId);
+        
+        if (progress >= objective.requiredCount)
+        {
+            OnObjectiveCompleted?.Invoke(quest, objective);
+            CheckQuestCompletion(quest);
+        }
+    }
+    
+    private void CheckQuestCompletion(QuestData quest)
+    {
+        bool allComplete = quest.objectives
+            .Where(o => !o.isOptional)
+            .All(o => IsObjectiveComplete(quest.questId, o.objectiveId));
+        
+        if (allComplete)
+        {
+            _questStates[quest.questId] = QuestState.Completed;
+            GiveRewards(quest);
+            OnQuestCompleted?.Invoke(quest);
+        }
+    }
+}
+
+public enum QuestState { NotStarted, Active, Completed, Failed }
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Hardcode dialogue text | Data-driven dialogue trees |
+| Binary choices only | Gradient of options |
+| Ignore past choices | Track and reference history |
+| One-time dialogues | Reactive, contextual dialogue |
+| Linear quests | Branching objectives |
+
+---
+
+## Related Skills
+- `game-development/ai-dialogue-engine` - LLM-powered NPCs
+- `game-development/game-state-manager` - Save narrative state
+- `game-development/localization` - Translate dialogues