@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/data-driven-balance/SKILL.md

@@ -0,0 +1,535 @@
+---
+name: data-driven-balance
+description: Data-driven game balancing systems. External configuration files, hot-patching values, A/B testing for game balance, spreadsheet imports, and live tuning for Unity.
+---
+
+# Data-Driven Balance Skill
+
+> **Purpose**: Enable rapid iteration and live balancing without app updates.
+
+## When to Use
+- Setting up external config files
+- Implementing hot-patching for balance
+- Running A/B tests for game values
+- Importing from spreadsheets
+
+---
+
+## 1. External Configuration System
+
+### JSON Config Pattern
+```csharp
+[System.Serializable]
+public class GameBalanceConfig
+{
+    public PlayerConfig player;
+    public EnemyConfig[] enemies;
+    public ItemConfig[] items;
+    public EconomyConfig economy;
+}
+
+[System.Serializable]
+public class PlayerConfig
+{
+    public float baseHealth = 100f;
+    public float baseAttack = 10f;
+    public float baseMoveSpeed = 5f;
+    public float healthPerLevel = 10f;
+    public float attackPerLevel = 2f;
+    
+    // Cultivation specific
+    public float[] qiRequirementsPerRealm;
+    public float breakthroughBaseChance = 0.5f;
+}
+
+[System.Serializable]
+public class EnemyConfig
+{
+    public string enemyId;
+    public float health;
+    public float attack;
+    public float expReward;
+    public float goldDrop;
+    public float[] dropRates;
+}
+
+[System.Serializable]
+public class EconomyConfig
+{
+    public int startingGold = 100;
+    public float goldMultiplier = 1f;
+    public float expMultiplier = 1f;
+    public int dailyRewardBase = 50;
+    public float[] dailyRewardStreak; // Day 1, 2, 3... bonuses
+}
+```
+
+### Config Loader
+```csharp
+public class ConfigManager : MonoBehaviour
+{
+    public static ConfigManager Instance { get; private set; }
+    
+    private GameBalanceConfig _config;
+    private string _configVersion;
+    
+    public GameBalanceConfig Config => _config;
+    
+    public event Action<GameBalanceConfig> OnConfigLoaded;
+    public event Action<GameBalanceConfig> OnConfigUpdated;
+    
+    private void Awake()
+    {
+        Instance = this;
+        LoadLocalConfig();
+    }
+    
+    private void Start()
+    {
+        // Fetch remote on start
+        StartCoroutine(FetchRemoteConfig());
+    }
+    
+    private void LoadLocalConfig()
+    {
+        // Load bundled default
+        TextAsset defaultConfig = Resources.Load<TextAsset>("default_config");
+        _config = JsonUtility.FromJson<GameBalanceConfig>(defaultConfig.text);
+        
+        // Check for cached remote
+        string cached = PlayerPrefs.GetString("cached_config", "");
+        if (!string.IsNullOrEmpty(cached))
+        {
+            _config = JsonUtility.FromJson<GameBalanceConfig>(cached);
+        }
+        
+        OnConfigLoaded?.Invoke(_config);
+    }
+    
+    private IEnumerator FetchRemoteConfig()
+    {
+        string url = "https://your-cdn.com/config/balance.json";
+        
+        using UnityWebRequest request = UnityWebRequest.Get(url);
+        yield return request.SendWebRequest();
+        
+        if (request.result == UnityWebRequest.Result.Success)
+        {
+            string json = request.downloadHandler.text;
+            var newConfig = JsonUtility.FromJson<GameBalanceConfig>(json);
+            
+            // Cache locally
+            PlayerPrefs.SetString("cached_config", json);
+            
+            // Apply if changed
+            if (HasConfigChanged(newConfig))
+            {
+                _config = newConfig;
+                OnConfigUpdated?.Invoke(_config);
+            }
+        }
+    }
+    
+    public T GetValue<T>(string path)
+    {
+        // Access nested values via path like "player.baseHealth"
+        return ReflectionHelper.GetNestedValue<T>(_config, path);
+    }
+}
+```
+
+---
+
+## 2. Firebase Remote Config
+
+### Firebase Integration
+```csharp
+public class FirebaseConfigManager : MonoBehaviour
+{
+    private FirebaseRemoteConfig _remoteConfig;
+    
+    public async Task Initialize()
+    {
+        await FirebaseApp.CheckAndFixDependenciesAsync();
+        
+        _remoteConfig = FirebaseRemoteConfig.DefaultInstance;
+        
+        // Set defaults
+        var defaults = new Dictionary<string, object>
+        {
+            { "player_base_health", 100 },
+            { "player_base_attack", 10 },
+            { "exp_multiplier", 1.0 },
+            { "gold_multiplier", 1.0 },
+            { "daily_reward_base", 50 },
+            { "feature_flag_new_mode", false }
+        };
+        
+        await _remoteConfig.SetDefaultsAsync(defaults);
+    }
+    
+    public async Task FetchAndActivate()
+    {
+        // Fetch with cache expiration
+        await _remoteConfig.FetchAsync(TimeSpan.FromHours(1));
+        await _remoteConfig.ActivateAsync();
+        
+        GameEvents.OnRemoteConfigUpdated?.Invoke();
+    }
+    
+    public float GetFloat(string key)
+    {
+        return (float)_remoteConfig.GetValue(key).DoubleValue;
+    }
+    
+    public int GetInt(string key)
+    {
+        return (int)_remoteConfig.GetValue(key).LongValue;
+    }
+    
+    public bool GetBool(string key)
+    {
+        return _remoteConfig.GetValue(key).BooleanValue;
+    }
+    
+    public string GetString(string key)
+    {
+        return _remoteConfig.GetValue(key).StringValue;
+    }
+    
+    public T GetJson<T>(string key)
+    {
+        string json = GetString(key);
+        return JsonUtility.FromJson<T>(json);
+    }
+}
+```
+
+---
+
+## 3. A/B Testing for Balance
+
+### Experiment System
+```csharp
+[System.Serializable]
+public class BalanceExperiment
+{
+    public string experimentId;
+    public string experimentName;
+    public bool isActive;
+    
+    public ExperimentVariant[] variants;
+    public string[] targetUserGroups; // "new_users", "paying_users"
+    
+    public float[] variantWeights; // Distribution
+}
+
+[System.Serializable]
+public class ExperimentVariant
+{
+    public string variantId;
+    public string variantName;
+    
+    public BalanceOverride[] overrides;
+}
+
+[System.Serializable]
+public class BalanceOverride
+{
+    public string configPath;
+    public string valueJson;
+}
+
+public class ABTestManager : MonoBehaviour
+{
+    private Dictionary<string, string> _userAssignments = new();
+    
+    public event Action<string, string> OnExperimentAssigned;
+    
+    public void AssignToExperiment(BalanceExperiment experiment)
+    {
+        if (_userAssignments.ContainsKey(experiment.experimentId))
+            return; // Already assigned
+        
+        // Consistent assignment based on user ID
+        int hash = GetUserHash(experiment.experimentId);
+        float roll = (hash % 1000) / 1000f;
+        
+        float cumulative = 0f;
+        for (int i = 0; i < experiment.variants.Length; i++)
+        {
+            cumulative += experiment.variantWeights[i];
+            if (roll < cumulative)
+            {
+                string variantId = experiment.variants[i].variantId;
+                _userAssignments[experiment.experimentId] = variantId;
+                
+                ApplyVariant(experiment.variants[i]);
+                
+                // Log for analytics
+                Analytics.LogEvent("experiment_assigned", new Dictionary<string, object>
+                {
+                    { "experiment_id", experiment.experimentId },
+                    { "variant_id", variantId }
+                });
+                
+                OnExperimentAssigned?.Invoke(experiment.experimentId, variantId);
+                break;
+            }
+        }
+    }
+    
+    private void ApplyVariant(ExperimentVariant variant)
+    {
+        foreach (var override_ in variant.overrides)
+        {
+            ConfigManager.Instance.SetOverride(override_.configPath, override_.valueJson);
+        }
+    }
+    
+    public string GetAssignedVariant(string experimentId)
+    {
+        return _userAssignments.TryGetValue(experimentId, out var variant) ? variant : null;
+    }
+}
+```
+
+---
+
+## 4. Spreadsheet Import
+
+### Google Sheets Integration
+```csharp
+public class SpreadsheetImporter
+{
+    private const string SHEET_ID = "your-google-sheet-id";
+    private const string API_KEY = "your-api-key";
+    
+    public async Task<List<EnemyConfig>> ImportEnemies(string sheetName)
+    {
+        string url = $"https://sheets.googleapis.com/v4/spreadsheets/{SHEET_ID}/values/{sheetName}?key={API_KEY}";
+        
+        using var client = new HttpClient();
+        string json = await client.GetStringAsync(url);
+        
+        var response = JsonConvert.DeserializeObject<SheetsResponse>(json);
+        
+        var enemies = new List<EnemyConfig>();
+        var headers = response.values[0]; // First row = headers
+        
+        for (int i = 1; i < response.values.Count; i++)
+        {
+            var row = response.values[i];
+            
+            enemies.Add(new EnemyConfig
+            {
+                enemyId = row[0],
+                health = float.Parse(row[1]),
+                attack = float.Parse(row[2]),
+                expReward = float.Parse(row[3]),
+                goldDrop = float.Parse(row[4])
+            });
+        }
+        
+        return enemies;
+    }
+}
+
+#if UNITY_EDITOR
+public class SpreadsheetImportEditor : EditorWindow
+{
+    [MenuItem("Tools/Import Balance from Sheets")]
+    public static async void ImportFromSheets()
+    {
+        var importer = new SpreadsheetImporter();
+        
+        // Import enemies
+        var enemies = await importer.ImportEnemies("Enemies");
+        SaveToScriptableObjects(enemies);
+        
+        Debug.Log($"Imported {enemies.Count} enemies from spreadsheet");
+    }
+}
+#endif
+```
+
+### CSV Import for Offline Use
+```csharp
+public class CSVImporter
+{
+    public static List<T> Import<T>(string csvPath) where T : new()
+    {
+        var results = new List<T>();
+        var lines = File.ReadAllLines(csvPath);
+        
+        if (lines.Length < 2) return results;
+        
+        var headers = ParseCSVLine(lines[0]);
+        var type = typeof(T);
+        
+        for (int i = 1; i < lines.Length; i++)
+        {
+            var values = ParseCSVLine(lines[i]);
+            var item = new T();
+            
+            for (int j = 0; j < headers.Length && j < values.Length; j++)
+            {
+                var field = type.GetField(headers[j]);
+                if (field != null)
+                {
+                    object value = Convert.ChangeType(values[j], field.FieldType);
+                    field.SetValue(item, value);
+                }
+            }
+            
+            results.Add(item);
+        }
+        
+        return results;
+    }
+    
+    private static string[] ParseCSVLine(string line)
+    {
+        // Handle quoted values with commas
+        var regex = new Regex(",(?=(?:[^\"]*\"[^\"]*\")*[^\"]*$)");
+        return regex.Split(line).Select(s => s.Trim('"')).ToArray();
+    }
+}
+```
+
+---
+
+## 5. Live Tuning Dashboard
+
+### In-Game Debug Panel
+```csharp
+public class LiveTuningPanel : MonoBehaviour
+{
+    [SerializeField] private GameObject _panelRoot;
+    [SerializeField] private Transform _sliderContainer;
+    [SerializeField] private GameObject _sliderPrefab;
+    
+    private Dictionary<string, Slider> _sliders = new();
+    
+    private void Start()
+    {
+        #if DEVELOPMENT_BUILD || UNITY_EDITOR
+        CreateTuningSliders();
+        #else
+        _panelRoot.SetActive(false);
+        #endif
+    }
+    
+    private void CreateTuningSliders()
+    {
+        CreateSlider("player.baseHealth", 50, 200, 100);
+        CreateSlider("player.baseAttack", 5, 50, 10);
+        CreateSlider("economy.goldMultiplier", 0.5f, 3f, 1f);
+        CreateSlider("economy.expMultiplier", 0.5f, 3f, 1f);
+    }
+    
+    private void CreateSlider(string configPath, float min, float max, float defaultValue)
+    {
+        var go = Instantiate(_sliderPrefab, _sliderContainer);
+        var slider = go.GetComponentInChildren<Slider>();
+        var label = go.GetComponentInChildren<TMP_Text>();
+        
+        slider.minValue = min;
+        slider.maxValue = max;
+        slider.value = ConfigManager.Instance.GetValue<float>(configPath);
+        
+        label.text = $"{configPath}: {slider.value:F1}";
+        
+        slider.onValueChanged.AddListener(value =>
+        {
+            ConfigManager.Instance.SetOverride(configPath, value);
+            label.text = $"{configPath}: {value:F1}";
+        });
+        
+        _sliders[configPath] = slider;
+    }
+    
+    public void ExportCurrentValues()
+    {
+        var overrides = new Dictionary<string, float>();
+        
+        foreach (var kvp in _sliders)
+        {
+            overrides[kvp.Key] = kvp.Value.value;
+        }
+        
+        string json = JsonConvert.SerializeObject(overrides, Formatting.Indented);
+        GUIUtility.systemCopyBuffer = json;
+        
+        Debug.Log($"Copied to clipboard:\n{json}");
+    }
+}
+```
+
+---
+
+## 6. Balance Analytics
+
+### Track Balance Metrics
+```csharp
+public class BalanceAnalytics : MonoBehaviour
+{
+    public void LogCombatResult(CombatResult result)
+    {
+        Analytics.LogEvent("combat_end", new Dictionary<string, object>
+        {
+            { "player_level", result.playerLevel },
+            { "enemy_id", result.enemyId },
+            { "victory", result.playerWon },
+            { "duration_seconds", result.durationSeconds },
+            { "damage_dealt", result.playerDamageDealt },
+            { "damage_taken", result.playerDamageTaken },
+            { "skills_used", result.skillsUsed },
+            { "items_consumed", result.itemsConsumed },
+            { "player_health_percent", result.playerHealthPercent }
+        });
+    }
+    
+    public void LogEconomyAction(string action, int amount, string source)
+    {
+        Analytics.LogEvent("economy", new Dictionary<string, object>
+        {
+            { "action", action },         // "gain", "spend"
+            { "currency", "gold" },
+            { "amount", amount },
+            { "source", source },          // "quest", "shop", "loot"
+            { "balance_after", PlayerStats.Gold }
+        });
+    }
+    
+    public void LogProgressionMilestone(string milestone, int attempts, float timeSpentMinutes)
+    {
+        Analytics.LogEvent("milestone", new Dictionary<string, object>
+        {
+            { "milestone", milestone },
+            { "attempts", attempts },
+            { "time_minutes", timeSpentMinutes },
+            { "player_level", PlayerStats.Level }
+        });
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Hardcode balance values | External configs |
+| Require app update to balance | Hot-patch via Remote Config |
+| Guess what to tune | Track metrics, A/B test |
+| Manual data entry | Import from spreadsheets |
+| No version control for configs | Git-track config files |
+
+---
+
+## Related Skills
+- `game-development/liveops` - Live operations
+- `game-development/game-economy-designer` - Economy design
+- `game-development/game-analytics-integrator` - Analytics