cz.xprees.variables 1.0.24 → 1.0.25

package/README.md

@@ -13,6 +13,7 @@ ScriptableObject-based variable architecture for decoupled state management, eve
   `ResetToDefault()`.
 - **PlayMode Transition Resets** - Declarative `[ResetOnPlayMode]` attribute controls automatic reset when entering or exiting Play Mode.
 - **State Lifetime Control** - Inherits `DescriptionBaseSO.lifetime` (`Scenario`, `Session`, `Persistent`) for boundary-aware resets.
+- **Persistent Variables** - `PersistentVariableBaseSO<T>` backs a variable with `PlayerPrefs` so its value survives across sessions.
 - **References** - Inspector-switchable references (`ReferenceBase<T>`) supporting both inlined values and shared variable assets.
 - **Variable Modifiers & Aggregations** - Compose and transform variable streams dynamically.
 
@@ -84,3 +85,32 @@ Every variable ScriptableObject exposes the **Lifetime** dropdown in the Inspect
 [StatefulLifetime(StateLifetime.Persistent)]
 public class MasterVolumeVariable : FloatVariable { }
 ```
+
+---
+
+## Persistent Variables (PlayerPrefs)
+
+[`PersistentVariableBaseSO<T>`](Runtime/Base/PersistentVariableBaseSO.cs) stores its value in `PlayerPrefs` instead of keeping it purely in memory. It
+is declared `[StatefulLifetime(StateLifetime.Persistent)]` and `[ResetOnPlayMode(PlayModeResetTiming.None)]`, so it is skipped by both the scenario
+snapshot restore and the Play Mode reset, and loads from `PlayerPrefs` on `OnEnable()` instead of cloning `defaultValue`.
+
+Ready-made asset types live under `Assets > Create > Variables/Persistent`:
+
+| Type                       | Backing store                 |
+|----------------------------|-------------------------------|
+| `PersistentBoolVariable`   | `PlayerPrefs` int (`0` / `1`) |
+| `PersistentIntVariable`    | `PlayerPrefs` int             |
+| `PersistentFloatVariable`  | `PlayerPrefs` float           |
+| `PersistentStringVariable` | `PlayerPrefs` string          |
+
+Key points:
+
+- **`playerPrefsKey` is required.** There is no implicit key - an empty key logs an error and the value is not stored.
+- **Write-through.** Every `CurrentValue` set writes to `PlayerPrefs` before `onValueChanged` fires. Unity flushes to disk on quit and focus loss;
+  call `Flush()` when an immediate write is required.
+- **`defaultValue` is the fallback** used when the key is not present yet. `ResetToDefault()` also overwrites the stored value, while
+  `ClearStoredValue()` deletes the key.
+- **Other types** can extend [`PersistentJsonVariableSO<T>`](Runtime/Base/PersistentJsonVariableSO.cs), which stores `JsonUtility` JSON in a string
+  key. `JsonUtility` only round-trips `[Serializable]` classes and structs - top level primitives, enums and arrays need their own
+  `PersistentVariableBaseSO<T>` subclass.
+- The inherited **Lifetime** dropdown is inert on these assets, because the class-level `[StatefulLifetime]` attribute takes precedence.

package/Runtime/Base/PersistentJsonVariableSO.cs

@@ -0,0 +1,30 @@
+using System;
+using UnityEngine;
+
+namespace Xprees.Variables.Base
+{
+    /// Base class for persistent variables of arbitrary serializable types, stored as JSON in PlayerPrefs.
+    /// Only [Serializable] classes and structs round-trip through JsonUtility - top level primitives,
+    /// enums, and arrays are not supported and need a dedicated subclass of PersistentVariableBaseSO.
+    /// <typeparam name="T">Unity-Serializable or System.Serializable class or struct</typeparam>
+    public abstract class PersistentJsonVariableSO<T> : PersistentVariableBaseSO<T>
+    {
+        protected override T ReadStoredValue(string key, T fallback)
+        {
+            var json = PlayerPrefs.GetString(key, string.Empty);
+            if (string.IsNullOrEmpty(json) || json == "{}" || json == "null") return fallback;
+
+            try
+            {
+                return JsonUtility.FromJson<T>(json);
+            }
+            catch (Exception exception)
+            {
+                Debug.LogError($"Failed to deserialize persistent variable '{name}' from PlayerPrefs key '{key}': {exception.Message}", this);
+                return fallback;
+            }
+        }
+
+        protected override void WriteStoredValue(string key, T value) => PlayerPrefs.SetString(key, JsonUtility.ToJson(value));
+    }
+}

package/Runtime/Base/PersistentJsonVariableSO.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: c2c5bcd7dffd19540970331068c40fc3

package/Runtime/Base/PersistentVariableBaseSO.cs

@@ -0,0 +1,94 @@
+using UnityEngine;
+using Xprees.Core;
+using Xprees.Variables.Utils;
+
+namespace Xprees.Variables.Base
+{
+    /// Base class for variable ScriptableObjects, whose value is backed by PlayerPrefs and survives across sessions.
+    /// The value is written through on every set and loaded when the asset is enabled.
+    /// Opted out of both the Play Mode reset and the StateSnapshotService scenario restore.
+    /// <typeparam name="T">Unity Serializable or System.Serializable</typeparam>
+    [StatefulLifetime(StateLifetime.Persistent)]
+    [ResetOnPlayMode(PlayModeResetTiming.None)]
+    public abstract class PersistentVariableBaseSO<T> : VariableBaseSO<T>
+    {
+        [Header("Persistence Settings")]
+        [Tooltip("PlayerPrefs key backing this variable. Required and must be unique across the project.")]
+        [SerializeField] private string playerPrefsKey;
+
+        public string PlayerPrefsKey => playerPrefsKey;
+
+        public bool HasStoredValue => !string.IsNullOrEmpty(playerPrefsKey) && PlayerPrefs.HasKey(playerPrefsKey);
+
+        public override T CurrentValue
+        {
+            get => base.CurrentValue;
+            set
+            {
+                // Persist before notifying so listeners always observe an already stored value
+                Persist(value);
+                base.CurrentValue = value;
+            }
+        }
+
+#if UNITY_EDITOR
+        protected override void OnValidate()
+        {
+            if (string.IsNullOrEmpty(playerPrefsKey))
+            {
+                Debug.LogError($"Persistent variable '{name}' has no PlayerPrefs key assigned and will not be stored.", this);
+            }
+
+            // Unlike a regular variable, the Editor should show what is actually stored, not the authored default.
+            if (!Application.isPlaying) currentValue = ReadStoredOrDefault();
+        }
+#endif
+
+        /// Reads the stored value from PlayerPrefs, returning the fallback when no value is stored.
+        protected abstract T ReadStoredValue(string key, T fallback);
+
+        /// Writes the value to PlayerPrefs under the given key.
+        protected abstract void WriteStoredValue(string key, T value);
+
+        protected override void InitializeValue() => Load();
+
+        /// Loads the value from PlayerPrefs, falling back to the authored default when nothing is stored, and notifies listeners.
+        public void Load()
+        {
+            currentValue = ReadStoredOrDefault();
+            onValueChanged?.Invoke(currentValue);
+        }
+
+        /// Resets the variable to its authored default value and overwrites the stored value with it.
+        public override void ResetToDefault() => CurrentValue = CloningTools.Clone(defaultValue);
+
+        /// Deletes the stored value and resets the variable to its authored default value.
+        public void ClearStoredValue()
+        {
+            if (!string.IsNullOrEmpty(playerPrefsKey)) PlayerPrefs.DeleteKey(playerPrefsKey);
+            base.ResetToDefault();
+        }
+
+        /// Forces PlayerPrefs to write to disk immediately.
+        /// Rarely needed - Unity flushes on quit and on focus loss.
+        public void Flush() => PlayerPrefs.Save();
+
+        /// Reads the stored value without notifying listeners, falling back to a fresh clone of the authored default value.
+        private T ReadStoredOrDefault()
+        {
+            var fallback = CloningTools.Clone(defaultValue);
+            return HasStoredValue ? ReadStoredValue(playerPrefsKey, fallback) : fallback;
+        }
+
+        private void Persist(T value)
+        {
+            if (string.IsNullOrEmpty(playerPrefsKey))
+            {
+                Debug.LogError($"Persistent variable '{name}' has no PlayerPrefs key assigned - value was not stored.", this);
+                return;
+            }
+
+            WriteStoredValue(playerPrefsKey, value);
+        }
+    }
+}

package/Runtime/Base/PersistentVariableBaseSO.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: ea26ad77ede55db4ca446b8ba81bd416

package/Runtime/Base/VariableBaseSO.cs

@@ -10,9 +10,12 @@ namespace Xprees.Variables.Base
         protected virtual void OnEnable()
         {
             hideFlags = HideFlags.DontUnloadUnusedAsset;
-            ResetToDefault();
+            InitializeValue();
         }
 
+        /// Initializes the runtime value when the asset is loaded. Defaults to the authored default value.
+        protected virtual void InitializeValue() => ResetToDefault();
+
         /// Resets the variable to its authored default value.
         public abstract void ResetToDefault();
     }
@@ -28,7 +31,7 @@ namespace Xprees.Variables.Base
         [SerializeField] protected T defaultValue;
 
         [Tooltip("Current value of variable - Runtime only value. Replaced with default value on OnEnable/PlayMode start.")]
-        [SerializeField] private T currentValue;
+        [SerializeField] protected T currentValue;
 
 #if UNITY_EDITOR
         protected virtual void OnValidate()

package/Runtime/Persistent/PersistentBoolVariable.cs

@@ -0,0 +1,13 @@
+using UnityEngine;
+using Xprees.Variables.Base;
+
+namespace Xprees.Variables.Persistent
+{
+    [CreateAssetMenu(menuName = "Variables/Persistent/Bool", fileName = "Bool_PersistVar")]
+    public class PersistentBoolVariable : PersistentVariableBaseSO<bool>
+    {
+        protected override bool ReadStoredValue(string key, bool fallback) => PlayerPrefs.GetInt(key, fallback ? 1 : 0) != 0;
+
+        protected override void WriteStoredValue(string key, bool value) => PlayerPrefs.SetInt(key, value ? 1 : 0);
+    }
+}

package/Runtime/Persistent/PersistentBoolVariable.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 80c182662bc041b4aa60856e2d194282

package/Runtime/Persistent/PersistentFloatVariable.cs

@@ -0,0 +1,13 @@
+using UnityEngine;
+using Xprees.Variables.Base;
+
+namespace Xprees.Variables.Persistent
+{
+    [CreateAssetMenu(menuName = "Variables/Persistent/Float", fileName = "Float_PersistVar")]
+    public class PersistentFloatVariable : PersistentVariableBaseSO<float>
+    {
+        protected override float ReadStoredValue(string key, float fallback) => PlayerPrefs.GetFloat(key, fallback);
+
+        protected override void WriteStoredValue(string key, float value) => PlayerPrefs.SetFloat(key, value);
+    }
+}

package/Runtime/Persistent/PersistentFloatVariable.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: ff48fa2ba5f54504c86a2c71c5dde1ec

package/Runtime/Persistent/PersistentIntVariable.cs

@@ -0,0 +1,13 @@
+using UnityEngine;
+using Xprees.Variables.Base;
+
+namespace Xprees.Variables.Persistent
+{
+    [CreateAssetMenu(menuName = "Variables/Persistent/Int", fileName = "Int_PersistVar")]
+    public class PersistentIntVariable : PersistentVariableBaseSO<int>
+    {
+        protected override int ReadStoredValue(string key, int fallback) => PlayerPrefs.GetInt(key, fallback);
+
+        protected override void WriteStoredValue(string key, int value) => PlayerPrefs.SetInt(key, value);
+    }
+}

package/Runtime/Persistent/PersistentIntVariable.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 93a449f7d0ee70e4bb21defcfbb8fc25

package/Runtime/Persistent/PersistentStringVariable.cs

@@ -0,0 +1,13 @@
+using UnityEngine;
+using Xprees.Variables.Base;
+
+namespace Xprees.Variables.Persistent
+{
+    [CreateAssetMenu(menuName = "Variables/Persistent/String", fileName = "String_PersistVar")]
+    public class PersistentStringVariable : PersistentVariableBaseSO<string>
+    {
+        protected override string ReadStoredValue(string key, string fallback) => PlayerPrefs.GetString(key, fallback);
+
+        protected override void WriteStoredValue(string key, string value) => PlayerPrefs.SetString(key, value);
+    }
+}

package/Runtime/Persistent/PersistentStringVariable.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 04b7f2b4fe108b64a9046f367ed734ce

package/Runtime/Persistent.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 2783884d6a4a28d40b847300ec2d9414
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cz.xprees.variables",
   "displayName": "Variables",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "unity": "2021.3",
   "description": "This package contains a system for creating variables based on ScriptableObjects in Editor.",
   "license": "Apache-2.0",