@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/cloud-save-sync/SKILL.md

@@ -0,0 +1,527 @@
+---
+name: cloud-save-sync
+description: Cloud save and cross-device synchronization. Firebase Cloud Save, PlayFab, conflict resolution, offline-first patterns, and data migration for Unity mobile games.
+---
+
+# Cloud Save Sync Skill
+
+> **Purpose**: Enable seamless cross-device gameplay progression.
+
+## When to Use
+- Implementing cloud save functionality
+- Enabling cross-device play
+- Handling save conflicts
+- Building offline-first games
+
+---
+
+## 1. Save Data Architecture
+
+### Flexible Save Structure
+```csharp
+[System.Serializable]
+public class CloudSaveData
+{
+    // Metadata
+    public string playerId;
+    public string deviceId;
+    public long timestamp;      // Unix timestamp
+    public int saveVersion;     // For migration
+    public string checksum;     // Data integrity
+    
+    // Game Data
+    public PlayerProgress player;
+    public InventoryData inventory;
+    public QuestProgress quests;
+    public SettingsData settings;
+    
+    // Custom
+    public Dictionary<string, string> customData;
+}
+
+[System.Serializable]
+public class PlayerProgress
+{
+    public int level;
+    public long experience;
+    public int gold;
+    public int gems;
+    public string currentRealm;     // For cultivation games
+    public float[] position;        // Last position
+    public long playTimeSeconds;
+}
+
+[System.Serializable]
+public class InventoryData
+{
+    public InventorySlot[] slots;
+    public EquipmentSlot[] equipment;
+    public string[] unlockedRecipes;
+    public CardDeckData[] decks;    // For card games
+}
+```
+
+---
+
+## 2. Cloud Save Manager
+
+### Core Implementation
+```csharp
+public class CloudSaveManager : MonoBehaviour
+{
+    public static CloudSaveManager Instance { get; private set; }
+    
+    [SerializeField] private CloudProvider _provider;
+    [SerializeField] private float _autoSaveInterval = 300f; // 5 minutes
+    
+    public bool IsOnline { get; private set; }
+    public bool IsSyncing { get; private set; }
+    public DateTime LastSyncTime { get; private set; }
+    
+    public event Action<CloudSaveData> OnSaveLoaded;
+    public event Action OnSaveUploaded;
+    public event Action<SaveConflict> OnConflictDetected;
+    public event Action<string> OnSyncError;
+    
+    private CloudSaveData _localSave;
+    private CloudSaveData _cloudSave;
+    
+    private void Start()
+    {
+        StartCoroutine(AutoSaveLoop());
+        StartCoroutine(MonitorConnectivity());
+    }
+    
+    #region Save Operations
+    
+    public async Task SaveLocal(CloudSaveData data)
+    {
+        data.timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
+        data.deviceId = SystemInfo.deviceUniqueIdentifier;
+        data.checksum = CalculateChecksum(data);
+        
+        string json = JsonUtility.ToJson(data);
+        
+        // Save to local storage
+        PlayerPrefs.SetString("local_save", json);
+        PlayerPrefs.Save();
+        
+        _localSave = data;
+        
+        // Attempt cloud sync if online
+        if (IsOnline)
+        {
+            await SyncToCloud(data);
+        }
+    }
+    
+    public async Task<CloudSaveData> LoadSave()
+    {
+        // Load local
+        string localJson = PlayerPrefs.GetString("local_save", "");
+        _localSave = string.IsNullOrEmpty(localJson) 
+            ? new CloudSaveData() 
+            : JsonUtility.FromJson<CloudSaveData>(localJson);
+        
+        // Try load cloud
+        if (IsOnline)
+        {
+            try
+            {
+                _cloudSave = await _provider.FetchCloudSave();
+                
+                // Check for conflict
+                if (_cloudSave != null && _localSave.timestamp > 0)
+                {
+                    var resolution = ResolveConflict(_localSave, _cloudSave);
+                    return resolution;
+                }
+                
+                return _cloudSave ?? _localSave;
+            }
+            catch (Exception e)
+            {
+                OnSyncError?.Invoke(e.Message);
+                return _localSave;
+            }
+        }
+        
+        return _localSave;
+    }
+    
+    private async Task SyncToCloud(CloudSaveData data)
+    {
+        IsSyncing = true;
+        
+        try
+        {
+            await _provider.UploadSave(data);
+            LastSyncTime = DateTime.UtcNow;
+            OnSaveUploaded?.Invoke();
+        }
+        catch (Exception e)
+        {
+            OnSyncError?.Invoke($"Cloud sync failed: {e.Message}");
+        }
+        finally
+        {
+            IsSyncing = false;
+        }
+    }
+    
+    #endregion
+    
+    #region Conflict Resolution
+    
+    private CloudSaveData ResolveConflict(CloudSaveData local, CloudSaveData cloud)
+    {
+        // Same timestamp = no conflict
+        if (local.timestamp == cloud.timestamp)
+            return local;
+        
+        // Auto-resolve: newer wins
+        if (Mathf.Abs(local.timestamp - cloud.timestamp) < 60) // Within 1 minute
+        {
+            return local.timestamp > cloud.timestamp ? local : cloud;
+        }
+        
+        // Significant difference: ask player
+        var conflict = new SaveConflict
+        {
+            localSave = local,
+            cloudSave = cloud,
+            localTime = DateTimeOffset.FromUnixTimeSeconds(local.timestamp).LocalDateTime,
+            cloudTime = DateTimeOffset.FromUnixTimeSeconds(cloud.timestamp).LocalDateTime
+        };
+        
+        OnConflictDetected?.Invoke(conflict);
+        
+        // Default to newer while waiting for resolution
+        return local.timestamp > cloud.timestamp ? local : cloud;
+    }
+    
+    public void ResolveConflictWith(ConflictChoice choice)
+    {
+        CloudSaveData chosen = choice switch
+        {
+            ConflictChoice.KeepLocal => _localSave,
+            ConflictChoice.KeepCloud => _cloudSave,
+            ConflictChoice.MergePreferLocal => MergeSaves(_localSave, _cloudSave),
+            ConflictChoice.MergePreferCloud => MergeSaves(_cloudSave, _localSave),
+            _ => _localSave
+        };
+        
+        _localSave = chosen;
+        SaveLocal(chosen);
+    }
+    
+    private CloudSaveData MergeSaves(CloudSaveData primary, CloudSaveData secondary)
+    {
+        var merged = JsonUtility.FromJson<CloudSaveData>(JsonUtility.ToJson(primary));
+        
+        // Take higher values
+        merged.player.level = Mathf.Max(primary.player.level, secondary.player.level);
+        merged.player.experience = Mathf.Max(primary.player.experience, secondary.player.experience);
+        merged.player.gold = Mathf.Max(primary.player.gold, secondary.player.gold);
+        merged.player.playTimeSeconds = Mathf.Max(primary.player.playTimeSeconds, secondary.player.playTimeSeconds);
+        
+        // Merge inventory (union of items)
+        merged.inventory = MergeInventories(primary.inventory, secondary.inventory);
+        
+        // Merge quests (completed on either = completed)
+        merged.quests = MergeQuests(primary.quests, secondary.quests);
+        
+        return merged;
+    }
+    
+    #endregion
+}
+
+public struct SaveConflict
+{
+    public CloudSaveData localSave;
+    public CloudSaveData cloudSave;
+    public DateTime localTime;
+    public DateTime cloudTime;
+}
+
+public enum ConflictChoice
+{
+    KeepLocal,
+    KeepCloud,
+    MergePreferLocal,
+    MergePreferCloud
+}
+```
+
+---
+
+## 3. Firebase Cloud Save
+
+### Firebase Provider
+```csharp
+public class FirebaseCloudProvider : CloudProvider
+{
+    private DatabaseReference _db;
+    private FirebaseAuth _auth;
+    
+    public override async Task Initialize()
+    {
+        var dependencyStatus = await FirebaseApp.CheckAndFixDependenciesAsync();
+        if (dependencyStatus != DependencyStatus.Available)
+        {
+            throw new Exception($"Firebase error: {dependencyStatus}");
+        }
+        
+        _auth = FirebaseAuth.DefaultInstance;
+        _db = FirebaseDatabase.DefaultInstance.RootReference;
+    }
+    
+    public override async Task<CloudSaveData> FetchCloudSave()
+    {
+        string userId = _auth.CurrentUser.UserId;
+        
+        var snapshot = await _db.Child("saves").Child(userId).GetValueAsync();
+        
+        if (!snapshot.Exists)
+            return null;
+        
+        string json = snapshot.GetRawJsonValue();
+        return JsonUtility.FromJson<CloudSaveData>(json);
+    }
+    
+    public override async Task UploadSave(CloudSaveData data)
+    {
+        string userId = _auth.CurrentUser.UserId;
+        string json = JsonUtility.ToJson(data);
+        
+        await _db.Child("saves").Child(userId).SetRawJsonValueAsync(json);
+    }
+    
+    public override async Task DeleteSave()
+    {
+        string userId = _auth.CurrentUser.UserId;
+        await _db.Child("saves").Child(userId).RemoveValueAsync();
+    }
+}
+```
+
+### Firebase Security Rules
+```json
+{
+  "rules": {
+    "saves": {
+      "$userId": {
+        ".read": "$userId === auth.uid",
+        ".write": "$userId === auth.uid",
+        ".validate": "newData.hasChildren(['playerId', 'timestamp', 'saveVersion'])"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 4. PlayFab Integration
+
+### PlayFab Provider
+```csharp
+public class PlayFabCloudProvider : CloudProvider
+{
+    public override async Task<CloudSaveData> FetchCloudSave()
+    {
+        var tcs = new TaskCompletionSource<CloudSaveData>();
+        
+        PlayFabClientAPI.GetUserData(
+            new GetUserDataRequest { Keys = new List<string> { "save_data" } },
+            result =>
+            {
+                if (result.Data.TryGetValue("save_data", out var record))
+                {
+                    var data = JsonUtility.FromJson<CloudSaveData>(record.Value);
+                    tcs.SetResult(data);
+                }
+                else
+                {
+                    tcs.SetResult(null);
+                }
+            },
+            error => tcs.SetException(new Exception(error.ErrorMessage))
+        );
+        
+        return await tcs.Task;
+    }
+    
+    public override async Task UploadSave(CloudSaveData data)
+    {
+        var tcs = new TaskCompletionSource<bool>();
+        
+        string json = JsonUtility.ToJson(data);
+        
+        PlayFabClientAPI.UpdateUserData(
+            new UpdateUserDataRequest
+            {
+                Data = new Dictionary<string, string> { { "save_data", json } }
+            },
+            result => tcs.SetResult(true),
+            error => tcs.SetException(new Exception(error.ErrorMessage))
+        );
+        
+        await tcs.Task;
+    }
+}
+```
+
+---
+
+## 5. Offline-First Pattern
+
+### Queue-Based Sync
+```csharp
+public class OfflineQueueManager : MonoBehaviour
+{
+    private Queue<PendingOperation> _pendingOperations = new();
+    private bool _isProcessing = false;
+    
+    public void QueueSave(CloudSaveData data)
+    {
+        _pendingOperations.Enqueue(new PendingOperation
+        {
+            type = OperationType.Save,
+            data = data,
+            timestamp = DateTime.UtcNow
+        });
+        
+        // Save queue locally
+        PersistQueue();
+        
+        // Try process if online
+        if (CloudSaveManager.Instance.IsOnline)
+        {
+            ProcessQueue();
+        }
+    }
+    
+    private async void ProcessQueue()
+    {
+        if (_isProcessing || _pendingOperations.Count == 0)
+            return;
+        
+        _isProcessing = true;
+        
+        while (_pendingOperations.Count > 0 && CloudSaveManager.Instance.IsOnline)
+        {
+            var operation = _pendingOperations.Peek();
+            
+            try
+            {
+                await ExecuteOperation(operation);
+                _pendingOperations.Dequeue();
+                PersistQueue();
+            }
+            catch
+            {
+                // Keep in queue for retry
+                break;
+            }
+        }
+        
+        _isProcessing = false;
+    }
+    
+    private void OnConnectivityRestored()
+    {
+        ProcessQueue();
+    }
+}
+
+[System.Serializable]
+public class PendingOperation
+{
+    public OperationType type;
+    public CloudSaveData data;
+    public DateTime timestamp;
+}
+
+public enum OperationType { Save, Delete, Achievement }
+```
+
+---
+
+## 6. Data Migration
+
+### Version Migration
+```csharp
+public class SaveMigrator
+{
+    private static readonly int CURRENT_VERSION = 3;
+    
+    public static CloudSaveData Migrate(CloudSaveData data)
+    {
+        while (data.saveVersion < CURRENT_VERSION)
+        {
+            data = MigrateStep(data);
+        }
+        
+        return data;
+    }
+    
+    private static CloudSaveData MigrateStep(CloudSaveData data)
+    {
+        switch (data.saveVersion)
+        {
+            case 1:
+                return MigrateV1ToV2(data);
+            case 2:
+                return MigrateV2ToV3(data);
+            default:
+                return data;
+        }
+    }
+    
+    private static CloudSaveData MigrateV1ToV2(CloudSaveData data)
+    {
+        // V2 added gems currency
+        data.player.gems = 0;
+        
+        // V2 split inventory into slots
+        if (data.customData.TryGetValue("old_inventory", out string oldInv))
+        {
+            data.inventory = ConvertOldInventory(oldInv);
+            data.customData.Remove("old_inventory");
+        }
+        
+        data.saveVersion = 2;
+        return data;
+    }
+    
+    private static CloudSaveData MigrateV2ToV3(CloudSaveData data)
+    {
+        // V3 added card decks
+        data.inventory.decks = new CardDeckData[0];
+        
+        data.saveVersion = 3;
+        return data;
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Save on every change | Batch saves, use intervals |
+| Ignore offline | Queue operations for retry |
+| Auto-resolve conflicts silently | Show player clear options |
+| No checksums | Validate data integrity |
+| No versioning | Support migration |
+
+---
+
+## Related Skills
+- `game-development/game-state-manager` - Local save patterns
+- `firebase` - Firebase integration
+- `game-development/liveops` - Remote config