cz.xprees.variables 1.0.20 → 1.0.23

package/README.md

@@ -2,29 +2,23 @@
 
 [![NPM Version](https://img.shields.io/npm/v/cz.xprees.variables)](https://www.npmjs.com/package/cz.xprees.variables)
 
-This package contains a set of variables based on the ScriptableObjects,
-which make it great for storing and simply sharing state without tight coupling.
-Moreover, it provides a way to share variables (state) across multiple scenes making it powerful for multi-scene Unity project.
+ScriptableObject-based variable architecture for decoupled state management, event observation, and multi-scene data sharing in Unity.
 
 ## Features
 
-- **ScriptableObject Variables** - A set of variables that can be used to store and share state across scenes.
-    - Simply extend the [`VariableBaseSO<T>`](Runtime/Base/VariableBaseSO.cs) class to create your own variable types, see examples in
-      the [BoolVariable](Runtime/Primitive/BoolVariable.cs) folder.
-    - Watchable Variables - You can subscribe to `onValueChanged` event to get notified when the value changes.
-- **References** - A way to reference variables or inlined values in the Project (changeable in the Inspector).
-    - You can directly set the value in the Inspector or reference a variable.
-    - This makes flexible go to choice how to use the variables or inlined values in your scripts.
-- **Variable Modifiers** - Wrapper classes that allow you to modify the value of the variable in a specific way.
-    - For example, you can use the [`BoolModifier`](Runtime/Modifiers/BoolModifier.cs)
-- **Variable Aggregations** - A set of classes that allow you to aggregate multiple variables into one.
-    - For example, you can use the [`BoolAggregation`](Runtime/Aggregations/BoolAggregation.cs) to aggregate multiple boolean variables into one.
+- **ScriptableObject Variables** - Store and share state without coupling systems together.
+    - Extend [`VariableBaseSO<T>`](Runtime/Base/VariableBaseSO.cs) to author custom typed variables.
+    - Observe runtime changes via the `onValueChanged` event.
+- **Standalone Default State** - Every variable manages its own authored `defaultValue` and deep-clones it into `currentValue` on `OnEnable()` and
+  `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.
+- **References** - Inspector-switchable references (`ReferenceBase<T>`) supporting both inlined values and shared variable assets.
+- **Variable Modifiers & Aggregations** - Compose and transform variable streams dynamically.
 
 ## Installation
 
-Install the package using npm scoped registry in `Project Settings > Package Manager > Scoped Registries`
-
-[Unity Docs - Install a UPM package from a Git URL](https://docs.unity3d.com/6000.1/Documentation/Manual/upm-ui-giturl.html)
+Install the package using npm scoped registry in `Project Settings > Package Manager > Scoped Registries`:
 
 ```json
 {
@@ -35,7 +29,58 @@ Install the package using npm scoped registry in `Project Settings > Package Man
         "com.dbrizov.naughtyattributes"
     ]
 }
+```
+
+Then install `cz.xprees.variables` via the Unity Package Manager.
+
+---
+
+## State Lifecycle & PlayMode Reset (DX)
+
+Variables are completely self-contained and integrate with the centralized `StateSnapshotService` without requiring bespoke registration systems.
+
+### 1. Default Behavior
+
+By default, `VariableBaseSO<T>`:
+
+1. Clones `defaultValue` into `currentValue` on `OnEnable()`.
+2. Automatically resets to default on entering Play Mode via `[ResetOnPlayMode(PlayModeResetTiming.EnterPlayMode)]`.
+3. In Unity Editor, captures its baseline snapshot before the first runtime mutation via `StateSnapshotService.EnsureCaptured(this)`.
+4. Reverts cleanly to baseline upon exiting Play Mode without dirtying asset files on disk.
 
+### 2. Customizing PlayMode Resets via `[ResetOnPlayMode]`
+
+Use `[ResetOnPlayMode]` to customize when custom variable classes reset:
+
+```csharp
+using Xprees.Core;
+using Xprees.Variables.Base;
+
+// 1. Default: resets on Play Mode entry
+public class AmmoVariable : IntVariable { }
+
+// 2. Prevent Play Mode reset (e.g. for persistent editor values or external saves)
+[ResetOnPlayMode(PlayModeResetTiming.None)]
+public class PlayerProfileVariable : StringVariable { }
+
+// 3. Reset on both entry and exit
+[ResetOnPlayMode(PlayModeResetTiming.Both)]
+public class TransientDebugFlagVariable : BoolVariable { }
 ```
 
-Then simply install the package using the Unity Package Manager using the _NPM - xprees_ scope or by the package name `cz.xprees.variables`.
+### 3. Setting State Lifetime per Variable
+
+Every variable ScriptableObject exposes the **Lifetime** dropdown in the Inspector (inherited from `DescriptionBaseSO`):
+
+- **`Scenario` (Default)**:
+  Resets automatically whenever a scenario starts or restarts via `ScenarioStateRegistrySO` and `StateSnapshotService.RestoreAll()`.
+- **`Session`**:
+  Persists across scenarios, resetting only when returning to the Main Menu or quitting.
+- **`Persistent`**:
+  **Never reset** by scenario resets or Play Mode entry (e.g. Audio volume, resolution settings).
+
+```csharp
+// You can also enforce class-level lifetime via attribute:
+[StatefulLifetime(StateLifetime.Persistent)]
+public class MasterVolumeVariable : FloatVariable { }
+```

package/Runtime/Base/ReferenceBase.cs

@@ -3,25 +3,45 @@
 // ------------------------------------------------------------------------------------------------------
 
 using System;
+using UnityEngine;
 using UnityEngine.Events;
 using Xprees.Core;
 using Xprees.Variables.Utils;
 
 namespace Xprees.Variables.Base
 {
-    /// <summary>
     /// Base class for all variable references used in the game. It can either use an inlined value or reference a VariableBaseSO Scriptable Object. The Value property abstracts this choice away, so users of ReferenceBase don't have to care about it.
-    /// </summary>
     /// <typeparam name="T">Unity Serializable</typeparam>
     [Serializable]
-    public class ReferenceBase<T> : IResettable
+    public class ReferenceBase<T> : ISerializationCallbackReceiver
     {
+        private bool _hasCapturedBaseline; // Used to check if baseline has been captured
         private T _defaultInlinedValue; // Used to reset state of inlined value
 
         public bool useInlined = true;
         public T inlinedValue;
         public VariableBaseSO<T> variable;
 
+        public void OnBeforeSerialize()
+        {
+        }
+
+        public void OnAfterDeserialize()
+        {
+            if (!PlayModeStateTracker.IsPlaying)
+            {
+                _defaultInlinedValue = CloningTools.Clone(inlinedValue);
+                _hasCapturedBaseline = false;
+                return;
+            }
+
+            if (!_hasCapturedBaseline)
+            {
+                _defaultInlinedValue = CloningTools.Clone(inlinedValue);
+                _hasCapturedBaseline = true;
+            }
+        }
+
         // Internal event for inlined value changes, since VariableBaseSO already has its own onValueChanged event.
         private UnityAction<T> _onInlinedValueChanged;
 
@@ -31,7 +51,7 @@ namespace Xprees.Variables.Base
         {
             add
             {
-                var shouldRedirectToVarEvent = !useInlined && variable != null;
+                var shouldRedirectToVarEvent = !useInlined && variable;
                 if (shouldRedirectToVarEvent)
                 {
                     variable.onValueChanged += value;
@@ -43,7 +63,7 @@ namespace Xprees.Variables.Base
 
             remove
             {
-                var shouldRedirectToVarEvent = !useInlined && variable != null;
+                var shouldRedirectToVarEvent = !useInlined && variable;
                 if (shouldRedirectToVarEvent)
                 {
                     variable.onValueChanged -= value;
@@ -63,6 +83,7 @@ namespace Xprees.Variables.Base
             useInlined = true;
             inlinedValue = value;
             _defaultInlinedValue = value;
+            _hasCapturedBaseline = true;
         }
 
         public T Value
@@ -84,22 +105,14 @@ namespace Xprees.Variables.Base
 
         public static implicit operator T(ReferenceBase<T> reference) => reference != null ? reference.Value : default;
 
-        public virtual void BackupStartState()
-        {
-            if (!useInlined) return; // Variables does that by themselves
-
-            _defaultInlinedValue = CloningTools.Clone(inlinedValue);
-        }
-
-        public virtual void ResetState()
+        /// Resets the inlined value to its baseline value captured at deserialization/initialization.
+        /// If this reference points to a VariableBaseSO, it does nothing (the shared variable state is managed by StateSnapshotService).
+        public virtual void ResetToDefault()
         {
             if (useInlined)
             {
                 inlinedValue = CloningTools.Clone(_defaultInlinedValue);
-                return;
             }
-
-            variable?.ResetState();
         }
     }
 }

package/Runtime/Base/VariableAgregationBaseSO.cs

@@ -8,12 +8,6 @@ namespace Xprees.Variables.Base
         [Tooltip("Aggregated variables.")]
         [SerializeField] protected VariableBaseSO<T>[] variables;
 
-        private void OnEnable()
-        {
-            hideFlags = HideFlags.DontUnloadUnusedAsset;
-            ResetState();
-        }
-
         public override T CurrentValue
         {
             get => AggregateValue(variables);
@@ -22,15 +16,14 @@ namespace Xprees.Variables.Base
 
         protected abstract T AggregateValue(VariableBaseSO<T>[] variableBases);
 
-        public override void ResetState()
+        public override void ResetToDefault()
         {
-            base.ResetState();
-            if (variables == null) return;
+            // Aggregations do not hold independent state; values are computed dynamically.
+        }
 
-            foreach (var variable in variables)
-            {
-                variable?.ResetState();
-            }
+        public override void ClearTransientState()
+        {
+            // Aggregations do not hold independent state; values are computed dynamically.
         }
     }
 }

package/Runtime/Base/VariableBaseSO.cs

@@ -7,42 +7,46 @@ namespace Xprees.Variables.Base
 {
     public abstract class VariableBaseSO : DescriptionBaseSO
     {
-        private void OnEnable()
+        protected virtual void OnEnable()
         {
             hideFlags = HideFlags.DontUnloadUnusedAsset;
-            ForceResetState();
+            ResetToDefault();
         }
 
-        /// Force reset state regardless of any protection settings.
-        public abstract void ForceResetState();
-
-        public override void ResetState() => ForceResetState();
+        /// Resets the variable to its authored default value.
+        public abstract void ResetToDefault();
     }
 
-    /// <summary>
-    /// Base class for all variables ScriptableObjects.
-    /// Object holds the state on runtime, but reset every time OnEnable to defaultValue.
-    /// </summary>
+    /// Base class for all variable ScriptableObjects.
+    /// Manages its own default initialization self-contained, and integrates with StateSnapshotService for scenario boundaries.
+    /// By default, resets on EnterPlayMode unless decorated with a custom [ResetOnPlayMode] or marked Persistent.
     /// <typeparam name="T">Unity Serializable or System.Serializable</typeparam>
-    public class VariableBaseSO<T> : VariableBaseSO
+    [ResetOnPlayMode(PlayModeResetTiming.EnterPlayMode)]
+    public class VariableBaseSO<T> : VariableBaseSO, IRuntimeStateOwner
     {
-        [Tooltip("Value to which the variable will be reset on OnEnable or ResetState call.")]
+        [Tooltip("Authored default value of the variable.")]
         [SerializeField] protected T defaultValue;
 
-        [Tooltip("Current value of variable - Runtime only value.")]
+        [Tooltip("Current value of variable - Runtime only value. Replaced with default value on OnEnable/PlayMode start.")]
         [SerializeField] private T currentValue;
 
-        [Header("Settings")]
-        [Tooltip("If true, the variable will not be reset when calling ResetState()."
-                 + " However, it will still be reset on OnEnable and when ForceResetState() is called. "
-                 + "Useful for game-system variables where runtime value should persist unless explicitly reset.")]
-        [SerializeField] protected bool protectedDontReset = false;
+#if UNITY_EDITOR
+        protected virtual void OnValidate()
+        {
+            // If not playing, reset current value to default value on validate to ensure that the variable is always in a valid state in Editor.
+            if (!Application.isPlaying) currentValue = CloningTools.Clone(defaultValue);
+        }
+#endif
 
         public virtual T CurrentValue
         {
             get => currentValue;
             set
             {
+#if UNITY_EDITOR
+                // If not already captured in Editor capture before changing the value
+                if (PlayModeStateTracker.IsPlaying) StateSnapshotService.EnsureCaptured(this);
+#endif
                 currentValue = value;
                 onValueChanged?.Invoke(value);
             }
@@ -58,13 +62,18 @@ namespace Xprees.Variables.Base
         public static implicit operator T(VariableBaseSO<T> variable) =>
             variable != null ? variable.CurrentValue : default;
 
-        public override void ResetState()
+        /// Resets the variable's current value to a fresh clone of its authored default value and notifies listeners.
+        public override void ResetToDefault()
         {
-            if (protectedDontReset) return; // skip reset if protected
-
-            ForceResetState();
+            currentValue = CloningTools.Clone(defaultValue);
+            onValueChanged?.Invoke(currentValue);
         }
 
-        public override void ForceResetState() => CurrentValue = CloningTools.Clone(defaultValue);
+        /// Invoked by StateSnapshotService when restoring state at scenario boundaries.
+        /// Notifies runtime listeners that the value has reverted to its snapshot baseline.
+        public virtual void ClearTransientState()
+        {
+            onValueChanged?.Invoke(currentValue);
+        }
     }
 }

package/Runtime/Base/VariableModifierBaseSO.cs

@@ -12,13 +12,6 @@ namespace Xprees.Variables.Base
         [Space]
         [SerializeField] private BoolReference disableWrite = new(true);
 
-        private void OnEnable()
-        {
-            hideFlags = HideFlags.DontUnloadUnusedAsset;
-            disableWrite?.BackupStartState();
-            ResetState();
-        }
-
         public override T CurrentValue
         {
             get => ModifyValue(variable.CurrentValue);
@@ -36,11 +29,14 @@ namespace Xprees.Variables.Base
 
         protected abstract T ModifyValue(T value);
 
-        public override void ResetState()
+        public override void ResetToDefault()
+        {
+            // Modifiers do not hold independent state; state is owned by the wrapped variable.
+        }
+
+        public override void ClearTransientState()
         {
-            base.ResetState();
-            variable?.ResetState();
-            disableWrite?.ResetState();
+            // Modifiers do not hold independent state; state is owned by the wrapped variable.
         }
     }
 }

package/Runtime/Utils/CloningTools.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections;
 using System.Runtime.CompilerServices;
 using UnityEngine;
@@ -24,6 +24,13 @@ namespace Xprees.Variables.Utils
             var canReturnAsIs = typeof(T).IsValueType && !RuntimeHelpers.IsReferenceOrContainsReferences<T>();
             if (canReturnAsIs) return value;
 
+            // Strings are immutable in .NET, so return directly without JsonUtility
+            if (typeof(T) == typeof(string)) return value;
+
+            // UnityEngine.Object references (ScriptableObjects, MonoBehaviours, Assets, GameObjects)
+            // are reference-assigned; we must not deep-clone or call CreateInstance during serialization.
+            if (typeof(Object).IsAssignableFrom(typeof(T)) || value is Object) return value;
+
             if (value is ICloneable cloneable) return (T) cloneable.Clone();
 
             // Handle collections (List<T>, arrays, etc.) - JsonUtility doesn't support them directly
@@ -96,6 +103,9 @@ namespace Xprees.Variables.Utils
             // Value types are copied by value
             if (itemType.IsValueType) return item;
 
+            // Strings are immutable
+            if (item is string) return item;
+
             // ICloneable
             if (item is ICloneable cloneable) return cloneable.Clone();
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "cz.xprees.variables",
   "displayName": "Variables",
-  "version": "1.0.20",
+  "version": "1.0.23",
   "unity": "2021.3",
   "description": "This package contains a system for creating variables based on ScriptableObjects in Editor.",
   "license": "Apache-2.0",
   "category": "Core",
   "dependencies": {
-    "cz.xprees.core": "1.0.32",
+    "cz.xprees.core": "1.0.40",
     "com.dbrizov.naughtyattributes": "2.1.4"
   },
   "keywords": [