Added scope-aware file routing (Global vs Slot) via ISaveable<TState>.Scope

Author: nickpettit

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.14.0] – 2025-10-27
+
+### Breaking Change: Scoped file routing
+
+- `ISaveable<TState>` now declares `StorageScope` Scope (Global or Slot), making pathing explicit and removing the need to toggle `SaveManager.SaveSlotIndex` just to “ignore” slots. 
+- Scope remembered at registration: `SaveManager` records a filename scope mapping when `RegisterSaveable(...)` is called and uses it for path resolution. (Internal change; no new public API.)
+- `FileHandler` pathing updated: `GetPartialPath()` now prefixes slot{N}/ only for Slot‑scoped files. Attempting to save/load a Slot‑scoped file with no selected slot throws a clear error. (Prevents global files like Options from accidentally ending up in a slot folder.) 
+
+### Migration notes
+
+- Add `StorageScope Scope { get; }` to every `ISaveable<TState>`. Use Global for shared data (e.g., options/settings) and Slot for per‑profile data. 
+- Remove any code that temporarily sets SaveManager.SaveSlotIndex = -1 around global saves; it’s no longer necessary.
+
 ## [0.13.0] – 2025-09-22
 
 ### Breaking Change

Runtime/FileHandler.cs

@@ -67,9 +67,19 @@ protected string GetPartialPath(string pathOrFilename)
 
             string path = $"{pathOrFilename}{FilenameSuffix}{FileExtension}";
 
-            if (SaveManager.SaveSlotIndex > -1)
+            var scope = SaveManager.ResolveScopeFor(pathOrFilename);
+            
+            if (scope == StorageScope.Slot)
+            {
+                if (SaveManager.SaveSlotIndex < 0)
+                    throw new InvalidOperationException(
+                        "[Save Async] Slot-scoped file requested but SaveSlotIndex is not set. " +
+                        "Set SaveManager.SaveSlotIndex before saving/loading slot-scoped files.");
+
                 return Path.Combine($"slot{SaveManager.SaveSlotIndex}", path);
+            }
 
+            // If the scope is global, just return the path as-is
             return path;
         }
 

Runtime/ISaveable.cs

@@ -2,6 +2,8 @@
 
 namespace Buck.SaveAsync
 {
+    public enum StorageScope { Global, Slot }
+    
     /// <summary>
     /// Allows an object to be saved and loaded via the SaveManager class using a strongly-typed state.
     /// Implementations should define a serializable struct or class for TState.
@@ -23,6 +25,11 @@ public interface ISaveable<TState>
         /// </summary>
         string Filename { get; }
 
+        /// <summary>
+        /// This indicates whether the data is saved globally or per save slot.
+        /// </summary>
+        StorageScope Scope { get; }
+        
         /// <summary>
         /// This is the current version of this ISaveable's data structure.
         /// If you change the TState structure, increment this version number.

Runtime/SaveManager.cs

@@ -110,6 +110,7 @@ sealed class LoadedSaveable
         static readonly Dictionary<string, IBoxedSaveable> m_saveables = new();
         static readonly List<LoadedSaveable> m_loadedSaveables = new();
         static readonly Queue<FileOperation> m_fileOperationQueue = new();
+        static readonly Dictionary<string, StorageScope> s_fileScopes = new();
 
         static readonly object s_QueueLock = new();
         static bool m_initialized;
@@ -174,20 +175,22 @@ public static void RegisterSaveable<TState>(ISaveable<TState> saveable)
             var boxed = new BoxedSaveable<TState>(saveable);
             if (!m_saveables.TryAdd(boxed.Key, boxed))
                 Debug.LogWarning($"[Save Async] SaveManager.RegisterSaveable() - Saveable with Key \"{boxed.Key}\" already exists.");
+            
+            var scope = saveable.Scope;
+            if (s_fileScopes.TryGetValue(boxed.Filename, out var existing) && existing != scope)
+                Debug.LogError($"[Save Async] Conflicting scopes for filename \"{boxed.Filename}\": {existing} vs {scope}.");
+            else
+                s_fileScopes[boxed.Filename] = scope;
         }
-
-        /// <summary>
-        /// Unregisters a previously registered ISaveable by key. This is useful when unloading scenes.
-        /// </summary>
-        /// <param name="key">The unique key of the ISaveable to unregister.</param>
-        public static void UnregisterSaveable(string key)
+        
+        internal static StorageScope ResolveScopeFor(string filename)
         {
-            Initialize();
-
-            if (string.IsNullOrEmpty(key))
-                return;
+            if (string.IsNullOrEmpty(filename))
+                return StorageScope.Slot; // safest default
 
-            m_saveables.Remove(key);
+            return s_fileScopes.TryGetValue(filename, out var scope)
+                ? scope
+                : StorageScope.Slot; // default Slot unless explicitly registered as Global
         }
 
         /// <summary>

Samples~/SaveAsyncExample/CacheDataExample.cs

@@ -25,8 +25,8 @@ public class CacheDataExample : MonoBehaviour, ISaveable<CacheDataExample.MySave
         void OnValidate() => SaveManager.GetSerializableGuid(ref m_guidBytes);
 
         public string Filename => Files.SomeFile;
-        
-        public int Version => 1;
+        public StorageScope Scope => StorageScope.Global;
+        public int Version => 0;
 
         [Serializable]
         public struct MySaveData

Samples~/SaveAsyncExample/GameDataExample.cs

@@ -19,8 +19,8 @@ public class GameDataExample : MonoBehaviour, ISaveable<GameDataExample.MyCustom
         // For an example that uses a Guid, see CacheDataExample.cs.
         public string Key => "GameDataExample";
         public string Filename => Files.GameData;
-        
-        public int Version => 1;
+        public StorageScope Scope => StorageScope.Global;
+        public int Version => 0;
 
         [Serializable]
         public struct Item

package.json

@@ -1,6 +1,6 @@
 {
   "name": "co.buck.saveasync",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "displayName": "Save Async",
   "description": "Save Async is BUCK's Unity package for asynchronously saving and loading data in the background using Unity's Awaitable class. Capture and restore state without interrupting Unity's main render thread.",
   "unity": "2023.1",