cz.xprees.core 1.0.34 → 1.0.40

package/Editor/DescriptionTextAreaDrawer.cs

@@ -0,0 +1,82 @@
+using UnityEditor;
+using UnityEngine;
+using Xprees.Core.DescriptionAttribute;
+
+namespace Xprees.Core.Editor
+{
+    /// Draws a string field as a foldout: a single-line preview when collapsed,
+    /// and a full-text area when expanded.
+    [CustomPropertyDrawer(typeof(DescriptionTextAreaAttribute))]
+    public class DescriptionTextAreaDrawer : PropertyDrawer
+    {
+        // Tweak this to change the font size of both the expanded text area and the collapsed preview.
+        private const int textFontSize = 12;
+
+        // Separator line drawn below the field, separating it from the next one in the Inspector.
+        private const float separatorHeight = 1f;
+        private const float separatorSpacing = 4f;
+        private readonly static Color separatorColor = new(0.5f, 0.5f, 0.5f, 0.5f);
+
+        private static float LineHeight => EditorGUIUtility.singleLineHeight;
+        private static float SeparatorTotalHeight => separatorSpacing + separatorHeight;
+
+        public override void OnGUI(Rect position, SerializedProperty property, GUIContent label)
+        {
+            if (property.propertyType != SerializedPropertyType.String)
+            {
+                EditorGUI.PropertyField(position, property, label, true);
+                return;
+            }
+
+            var foldoutRect = new Rect(position.x, position.y, position.width, LineHeight);
+            property.isExpanded = EditorGUI.Foldout(foldoutRect, property.isExpanded, label, true);
+
+            var contentRect = new Rect(position.x, foldoutRect.yMax, position.width,
+                position.height - LineHeight - SeparatorTotalHeight);
+            if (property.isExpanded)
+            {
+                var textAreaStyle = new GUIStyle(EditorStyles.textArea) { fontSize = textFontSize };
+
+                EditorGUI.BeginChangeCheck();
+                var newValue = EditorGUI.TextArea(contentRect, property.stringValue, textAreaStyle);
+                if (EditorGUI.EndChangeCheck())
+                {
+                    property.stringValue = newValue;
+                }
+            }
+            else if (!string.IsNullOrEmpty(property.stringValue))
+            {
+                var previewStyle = new GUIStyle(EditorStyles.wordWrappedMiniLabel) { fontSize = textFontSize };
+                EditorGUI.LabelField(contentRect, GetPreview(property.stringValue), previewStyle);
+            }
+
+            var separatorRect = new Rect(position.x, position.yMax - separatorHeight, position.width, separatorHeight);
+            EditorGUI.DrawRect(separatorRect, separatorColor);
+        }
+
+        public override float GetPropertyHeight(SerializedProperty property, GUIContent label)
+        {
+            if (property.propertyType != SerializedPropertyType.String)
+            {
+                return EditorGUI.GetPropertyHeight(property, label, true);
+            }
+
+            if (!property.isExpanded)
+            {
+                var previewLines = string.IsNullOrEmpty(property.stringValue) ? 1 : 2;
+                return previewLines * LineHeight + SeparatorTotalHeight;
+            }
+
+            var textAreaAttribute = (DescriptionTextAreaAttribute) attribute;
+            var lineCount = string.IsNullOrEmpty(property.stringValue) ? 1 : property.stringValue.Split('\n').Length;
+            lineCount = Mathf.Clamp(lineCount + 1, textAreaAttribute.expandedMinLines, textAreaAttribute.expandedMaxLines);
+            return LineHeight + lineCount * LineHeight + SeparatorTotalHeight;
+        }
+
+        private static string GetPreview(string value)
+        {
+            var firstLine = value.Split('\n')[0];
+            return firstLine.Length > 100 ? firstLine[..100] + "…" : firstLine;
+        }
+    }
+}

package/Editor/DescriptionTextAreaDrawer.cs.meta

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

package/Editor/StatePlayModeLifecycleHook.cs

@@ -0,0 +1,78 @@
+using System;
+using System.Collections.Concurrent;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+
+namespace Xprees.Core.Editor
+{
+    /// Centralized Editor runner that coordinates Play Mode entry and exit transitions for stateful ScriptableObjects.
+    /// Resets objects marked with [ResetOnPlayMode] and restores mutated assets upon exiting Play Mode.
+    /// Can be migrated to future Unity lifecycle hooks in future versions.
+    [InitializeOnLoad]
+    public static class StatePlayModeLifecycleHook
+    {
+        private readonly static ConcurrentDictionary<Type, PlayModeResetTiming> timingCache = new();
+
+        static StatePlayModeLifecycleHook()
+        {
+            EditorApplication.playModeStateChanged -= OnPlayModeStateChanged;
+            EditorApplication.playModeStateChanged += OnPlayModeStateChanged;
+        }
+
+        private static void OnPlayModeStateChanged(PlayModeStateChange change)
+        {
+            switch (change)
+            {
+                case PlayModeStateChange.EnteredPlayMode:
+                    ResetPlayModeObjects(PlayModeResetTiming.EnterPlayMode);
+                    break;
+
+                case PlayModeStateChange.ExitingPlayMode:
+                    // Automatically revert all mutated ScriptableObjects to baseline before returning to Edit Mode
+                    StateSnapshotService.RestoreAll();
+                    ResetPlayModeObjects(PlayModeResetTiming.ExitPlayMode);
+                    break;
+
+                case PlayModeStateChange.EnteredEditMode:
+                    StateSnapshotService.ClearAll();
+                    break;
+            }
+        }
+
+        /// Resets loaded ScriptableObjects decorated with [ResetOnPlayMode] matching the specified timing.
+        /// Respects StateLifetime (skips StateLifetime.Persistent).
+        public static void ResetPlayModeObjects(PlayModeResetTiming timing)
+        {
+            var loadedObjects = Resources.FindObjectsOfTypeAll<ScriptableObject>();
+            foreach (var so in loadedObjects)
+            {
+                if (!so || so.IsStateless() || so.GetStateLifetime() == StateLifetime.Persistent) continue;
+
+                var type = so.GetType();
+                var configuredTiming = GetPlayModeTiming(type);
+                if ((configuredTiming & timing) == 0) continue;
+
+                var resetMethod = type.GetMethod("ResetToDefault", BindingFlags.Public | BindingFlags.Instance);
+                if (resetMethod != null)
+                {
+                    resetMethod.Invoke(so, null);
+                }
+                else if (so is IRuntimeStateOwner stateOwner)
+                {
+                    stateOwner.ClearTransientState();
+                }
+            }
+        }
+
+        public static PlayModeResetTiming GetPlayModeTiming(Type type)
+        {
+            if (timingCache.TryGetValue(type, out var timing)) return timing;
+
+            var attr = type.GetCustomAttribute<ResetOnPlayModeAttribute>(true);
+            timing = attr?.Timing ?? PlayModeResetTiming.None;
+            timingCache[type] = timing;
+            return timing;
+        }
+    }
+}

package/Editor/StatePlayModeLifecycleHook.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: fc5682634fa047ffba504454cebd6951
+timeCreated: 1789122780

package/Editor/cz.xprees.core.editor.asmdef

@@ -0,0 +1,18 @@
+{
+  "name": "cz.xprees.core.editor",
+  "rootNamespace": "Xprees.Core.Editor",
+  "references": [
+    "GUID:999c2ca78ab34358a1222750376a501c"
+  ],
+  "includePlatforms": [
+    "Editor"
+  ],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": false,
+  "precompiledReferences": [],
+  "autoReferenced": true,
+  "defineConstraints": [],
+  "versionDefines": [],
+  "noEngineReferences": false
+}

package/Editor/cz.xprees.core.editor.asmdef.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 04cd20f0ff664149a4d1159fb40a8c7c
+timeCreated: 1788342224

package/Editor.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: bd2a029389794301a94059f13fdd90f5
+timeCreated: 1788342207

package/README.md

@@ -1,15 +1,12 @@
-# Unity Core classes
+# Unity Core classes - cz.xprees.core
 
 [![NPM Version](https://img.shields.io/npm/v/cz.xprees.core)](https://www.npmjs.com/package/cz.xprees.core)
 
-
-This is base package containing a few common classes for all of my Unity projects.
+Base package containing core systems, state lifecycle orchestration, and ScriptableObject utilities for Unity projects.
 
 ## 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
 {
@@ -19,7 +16,83 @@ Install the package using npm scoped registry in `Project Settings > Package Man
         "cz.xprees"
     ]
 }
+```
+
+Then install `cz.xprees.core` via the Unity Package Manager.
+
+---
+
+## State Management & Lifecycle Architecture
+
+The package provides automated, zero-boilerplate state snapshotting and restoration for ScriptableObjects across scenario boundaries and Editor play
+mode transitions.
+
+### 1. State Lifetime (`StateLifetime`)
+
+Every stateful ScriptableObject inherits from `DescriptionBaseSO` or declares its lifecycle scope via `[StatefulLifetime]`:
+
+- **`StateLifetime.Scenario` (Default)**:
+  Scoped strictly to the active scenario. Captured before mutations and automatically restored to its baseline on scenario start/restart.
+- **`StateLifetime.Session`**:
+  Persists across scenarios throughout a play session. Restored only on game/session boundaries or play mode exit.
+- **`StateLifetime.Persistent`**:
+  Excluded from state snapshots. Ideal for immutable databases, user settings, or content saved externally to disk.
+
+```csharp
+// Per-instance: Set the "Lifetime" dropdown in the Inspector.
+// Per-class: Override via attribute:
+[StatefulLifetime(StateLifetime.Persistent)]
+public class GlobalPlayerConfigSO : DescriptionBaseSO { }
+```
+
+### 2. State Snapshot Service (`StateSnapshotService`)
+
+A centralized, pure runtime service that handles:
+
+- **`EnsureCaptured(ScriptableObject target)`**: Serializes the baseline JSON state prior to the first mutation.
+- **`Restore(ScriptableObject target)`**: Reverts serialized fields in-place from baseline JSON and triggers
+  `IRuntimeStateOwner.ClearTransientState()`.
+- **`RestoreAll(IEnumerable<ScriptableObject> targets, StateLifetime maxLifetime)`**: Multi-pass restoration that ensures all targets are
+  baseline-captured before restoring, preventing inter-object dependency races.
+- **`[SnapshotIgnore]`**: Decorate fields to preserve their values across snapshot restorations.
 
+### 3. Editor PlayMode Lifecycle (`StatePlayModeLifecycleHook`)
+
+Located in `cz.xprees.core.editor`, this centralized runner hooks into `EditorApplication.playModeStateChanged`:
+
+- **`EnteredPlayMode`**: Resets stateful objects decorated with `[ResetOnPlayMode(PlayModeResetTiming.EnterPlayMode)]` (skips `Persistent` objects).
+- **`ExitingPlayMode`**: Restores all mutated ScriptableObjects in-place back to their baseline via `StateSnapshotService.RestoreAll()` and clears
+  editor dirty flags before returning to edit mode.
+- **`EnteredEditMode`**: Purges snapshot dictionaries.
+
+### 4. Play Mode Reset Attribute (`ResetOnPlayModeAttribute`)
+
+Control Play Mode transition resets declaratively on classes:
+
+```csharp
+[Flags]
+public enum PlayModeResetTiming
+{
+    None = 0,
+    EnterPlayMode = 1 << 0,
+    ExitPlayMode = 1 << 1,
+    Both = EnterPlayMode | ExitPlayMode
+}
+
+// Example: opt-out of play mode reset
+[ResetOnPlayMode(PlayModeResetTiming.None)]
+public class PersistentSettingsSO : ScriptableObject { }
+```
+
+### 5. Runtime State Ownership (`IRuntimeStateOwner`)
+
+Implement `IRuntimeStateOwner` on objects with non-serialized runtime state (active handles, listeners, temporary collections):
+
+```csharp
+public interface IRuntimeStateOwner
+{
+    void ClearTransientState();
+}
 ```
 
-Then simply install the package using the Unity Package Manager using the _NPM - xprees_ scope or by the package name `cz.xprees.core`.
+Invoked automatically after serialized fields are restored by `StateSnapshotService`.

package/Runtime/DescriptionAttribute/DescriptionTextAreaAttribute.cs

@@ -0,0 +1,18 @@
+using UnityEngine;
+
+namespace Xprees.Core.DescriptionAttribute
+{
+    /// Marks a multiline string field to be drawn as a collapsible foldout in the Inspector,
+    /// showing a single-line preview when collapsed and a full text area when expanded.
+    public class DescriptionTextAreaAttribute : PropertyAttribute
+    {
+        public readonly int expandedMinLines;
+        public readonly int expandedMaxLines;
+
+        public DescriptionTextAreaAttribute(int expandedMinLines = 3, int expandedMaxLines = 10)
+        {
+            this.expandedMinLines = expandedMinLines;
+            this.expandedMaxLines = expandedMaxLines;
+        }
+    }
+}

package/Runtime/DescriptionAttribute/DescriptionTextAreaAttribute.cs.meta

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

package/Runtime/DescriptionAttribute.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: e9640b44188041f08d1606fdedf41f63
+timeCreated: 1788342764

package/Runtime/DescriptionBaseSO.cs

@@ -1,16 +1,30 @@
 using UnityEngine;
+using Xprees.Core.DescriptionAttribute;
 
 namespace Xprees.Core
 {
     /// Base class for ScriptableObjects with a public description field visible only in Editor.
+    /// Supports lifecycle-scoped state management.
     public class DescriptionBaseSO : ScriptableObject, IResettable
     {
 #if UNITY_EDITOR
+        [SnapshotIgnore]
         [Tooltip("Description of the ScriptableObject. Editor only.")]
-        [TextArea]
+        [DescriptionTextArea]
         public string description;
 #endif
 
+        [Tooltip("Defines how long this ScriptableObject's runtime state persists before being automatically restored.")]
+        [SerializeField] private StateLifetime lifetime = StateLifetime.Scenario;
+
+        public StateLifetime ConfiguredLifetime => lifetime;
+
+        public StateLifetime Lifetime
+        {
+            get => this.GetStateLifetime();
+            set => lifetime = value;
+        }
+
         public virtual void ResetState()
         {
         }

package/Runtime/IRuntimeStateOwner.cs

@@ -0,0 +1,11 @@
+namespace Xprees.Core
+{
+    /// Implemented by objects that have transient, non-serialized runtime state
+    /// (e.g., event subscriptions, CancellationTokenSources, active caches, UI transient variables)
+    /// that should be cleared during a scenario reset.
+    public interface IRuntimeStateOwner
+    {
+        /// Clears transient non-serialized state (subscriptions, cancellation tokens, transient caches).
+        void ClearTransientState();
+    }
+}

package/Runtime/IRuntimeStateOwner.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 21282b591a2e4051ae4ed0d387c70a35
+timeCreated: 1788207906

package/Runtime/PlayModeStateTracker.cs

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using UnityEditor;
+#endif
+
+namespace Xprees.Core
+{
+    /// Thread-safe and serialization-safe tracker for play mode state.
+    /// Accessing Unity's Application.isPlaying during ISerializationCallbackReceiver throws UnityException.
+    /// This pure C# static field can be safely read from any thread or serialization callback.
+    public static class PlayModeStateTracker
+    {
+#if UNITY_EDITOR
+        public static bool IsPlaying { get; private set; }
+
+        [InitializeOnLoadMethod]
+        private static void Init()
+        {
+            IsPlaying = EditorApplication.isPlaying;
+            EditorApplication.playModeStateChanged -= OnPlayModeChanged;
+            EditorApplication.playModeStateChanged += OnPlayModeChanged;
+        }
+
+        private static void OnPlayModeChanged(PlayModeStateChange change)
+        {
+            IsPlaying = change is
+                PlayModeStateChange.EnteredPlayMode or PlayModeStateChange.ExitingEditMode;
+        }
+#else
+        // We must have runtime fallback to code to compile
+        public static bool IsPlaying => true;
+#endif
+    }
+}

package/Runtime/PlayModeStateTracker.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 353d734366454cd28c38cd72c8edf9a0
+timeCreated: 1788207957

package/Runtime/ResetOnPlayModeAttribute.cs

@@ -0,0 +1,33 @@
+using System;
+
+namespace Xprees.Core
+{
+    [Flags]
+    public enum PlayModeResetTiming
+    {
+        /// No reset will occur on Play Mode transitions
+        None = 0,
+
+        /// Reset state when entering Play Mode
+        EnterPlayMode = 1 << 0,
+
+        /// Reset state when exiting Play Mode
+        ExitPlayMode = 1 << 1,
+
+        /// Reset state on both entering and exiting Play Mode
+        Both = EnterPlayMode | ExitPlayMode,
+    }
+
+    /// Controls whether and when a stateful ScriptableObject (such as a Variable) resets to its authored default value during Editor Play Mode transitions.
+    /// Hooked and executed centrally by StateSnapshotService.
+    [AttributeUsage(AttributeTargets.Class, Inherited = true)]
+    public sealed class ResetOnPlayModeAttribute : Attribute
+    {
+        public PlayModeResetTiming Timing { get; }
+
+        public ResetOnPlayModeAttribute(PlayModeResetTiming timing = PlayModeResetTiming.EnterPlayMode)
+        {
+            Timing = timing;
+        }
+    }
+}

package/Runtime/ResetOnPlayModeAttribute.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 83876b95fdaf4120a761253103ef2bbc
+timeCreated: 1789121968

package/Runtime/StateLifetime.cs

@@ -0,0 +1,55 @@
+using System;
+
+namespace Xprees.Core
+{
+    /// Defines the retention lifecycle and reset scope of a ScriptableObject's runtime state.
+    public enum StateLifetime
+    {
+        /// Scoped strictly to the active Scenario.
+        /// Automatically captured and restored to its pristine baseline every time a Scenario starts or restarts.
+        /// Example: Scenario-specific variables, emails, dialog progression, and interactables.
+        Scenario = 0,
+
+        /// Persists across multiple scenarios during the entire game execution session,
+        /// restored only when quitting the application or starting a new game session from the Main Menu.
+        /// Example: global player profile, per session settings etc.
+        Session = 1,
+
+        /// Completely ignored by the runtime state snapshot system.
+        /// Represents purely static/constant authored content or data persisted externally (e.g., disk save files / cloud saves).
+        /// Example: Audio clips, localization tables, immutable item database definitions.
+        Persistent = 2,
+    }
+
+    /// Explicitly declares the state lifetime for an entire ScriptableObject type.
+    /// Overrides per-instance serialized lifetime fields.
+    [AttributeUsage(AttributeTargets.Class, Inherited = true)]
+    public sealed class StatefulLifetimeAttribute : Attribute
+    {
+        public StateLifetime Lifetime { get; }
+
+        public StatefulLifetimeAttribute(StateLifetime lifetime)
+        {
+            Lifetime = lifetime;
+        }
+    }
+
+    /// Marks a field on a ScriptableObject to be excluded from automated state snapshots.
+    [AttributeUsage(AttributeTargets.Field)]
+    public sealed class SnapshotIgnoreAttribute : Attribute
+    {
+    }
+
+    /// Marks a ScriptableObject type as entirely stateless/immutable, skipping it from state snapshots and scenario resetting.
+    [AttributeUsage(AttributeTargets.Class, Inherited = true)]
+    public sealed class StatelessAssetAttribute : Attribute
+    {
+    }
+
+    /// Marks a ScriptableObject type or field as entirely stateless/immutable, skipping it from state snapshots and scenario resetting.
+    /// Convenient alias for [StatelessAsset].
+    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Field, Inherited = true)]
+    public sealed class StatelessAttribute : Attribute
+    {
+    }
+}

package/Runtime/StateLifetime.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: b81684bb25be421382c9f5ad7cc88f30
+timeCreated: 1788207904

package/Runtime/StateLifetimeExtensions.cs

@@ -0,0 +1,91 @@
+using System;
+using System.Collections.Concurrent;
+using System.Reflection;
+using UnityEngine;
+#if UNITY_EDITOR
+using UnityEditor;
+#endif
+
+namespace Xprees.Core
+{
+    /// Utility extensions for resolving lifecycle and stateless status of ScriptableObjects.
+    public static class StateLifetimeExtensions
+    {
+        private readonly static ConcurrentDictionary<Type, StateLifetime?> _lifetimeCache = new();
+        private readonly static ConcurrentDictionary<Type, bool> _statelessCache = new();
+
+        public static StateLifetime GetStateLifetime(this ScriptableObject so)
+        {
+            if (!so) return StateLifetime.Persistent;
+
+            var type = so.GetType();
+            if (_lifetimeCache.TryGetValue(type, out var cached) && cached.HasValue)
+            {
+                return cached.Value;
+            }
+
+#if UNITY_EDITOR
+            var attrTypes = TypeCache.GetTypesWithAttribute<StatefulLifetimeAttribute>();
+            if (attrTypes.Contains(type))
+            {
+                var attr = (StatefulLifetimeAttribute) Attribute.GetCustomAttribute(type, typeof(StatefulLifetimeAttribute), true);
+                if (attr != null)
+                {
+                    _lifetimeCache[type] = attr.Lifetime;
+                    return attr.Lifetime;
+                }
+            }
+#endif
+            var fallbackAttr = type.GetCustomAttribute<StatefulLifetimeAttribute>(true);
+            if (fallbackAttr != null)
+            {
+                _lifetimeCache[type] = fallbackAttr.Lifetime;
+                return fallbackAttr.Lifetime;
+            }
+
+            if (so is DescriptionBaseSO descSo)
+            {
+                return descSo.ConfiguredLifetime;
+            }
+
+            _lifetimeCache[type] = StateLifetime.Persistent;
+            return StateLifetime.Persistent;
+        }
+
+        public static bool IsStateless(this ScriptableObject so)
+        {
+            if (!so) return true;
+
+            var type = so.GetType();
+            if (_statelessCache.TryGetValue(type, out var cached))
+            {
+                return cached;
+            }
+
+#if UNITY_EDITOR
+            var statelessTypes = TypeCache.GetTypesWithAttribute<StatelessAssetAttribute>();
+            var statelessTypesAlt = TypeCache.GetTypesWithAttribute<StatelessAttribute>();
+            if (statelessTypes.Contains(type) || statelessTypesAlt.Contains(type))
+            {
+                _statelessCache[type] = true;
+                return true;
+            }
+#endif
+            var hasStatelessAttr = type.GetCustomAttribute<StatelessAssetAttribute>(true) != null ||
+                                   type.GetCustomAttribute<StatelessAttribute>(true) != null;
+            if (hasStatelessAttr)
+            {
+                _statelessCache[type] = true;
+                return true;
+            }
+
+            // Assets are only stateful if they inherit from DescriptionBaseSO or are explicitly marked with StatefulLifetime
+            var hasStatefulAttr = type.GetCustomAttribute<StatefulLifetimeAttribute>(true) != null;
+            var isStateful = so is DescriptionBaseSO || hasStatefulAttr;
+
+            var isStateless = !isStateful;
+            _statelessCache[type] = isStateless;
+            return isStateless;
+        }
+    }
+}

package/Runtime/StateLifetimeExtensions.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 1c425e1e2dd7408aa8a37b4a17e7b530
+timeCreated: 1788514835

package/Runtime/StateSnapshotService.cs

@@ -0,0 +1,270 @@
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using UnityEngine;
+using Object = UnityEngine.Object;
+#if UNITY_EDITOR
+using UnityEditor;
+#endif
+
+namespace Xprees.Core
+{
+    // TODO later consider adding limits to not blow up memory - probably not an issue
+    // TODO consider using OdinSerializer for more robust serialization in future
+
+    /// Core engine service for zero-boilerplate capturing and in-place restoration
+    /// of ScriptableObject serialized state across scenario and session boundaries.
+    public static class StateSnapshotService
+    {
+        private readonly static Dictionary<int, string> snapshots = new();
+        private readonly static HashSet<int> restoringEntities = new();
+        private readonly static ConcurrentDictionary<Type, FieldInfo[]> snapshotIgnoreFieldsCache = new();
+#if UNITY_EDITOR
+        private readonly static Dictionary<int, ScriptableObject> trackedTargets = new();
+#endif
+
+        /// Total number of currently tracked baseline snapshots in memory.
+        public static int SnapshotCount => snapshots.Count;
+
+        /// Captures the baseline-serialized state of the ScriptableObject if not already captured.
+        public static bool EnsureCaptured(ScriptableObject target)
+        {
+            if (!target || target.IsStateless() || target.GetStateLifetime() == StateLifetime.Persistent)
+            {
+                return false;
+            }
+
+            var entityId = target.GetEntityId();
+            if (snapshots.ContainsKey(entityId))
+            {
+                return false;
+            }
+
+            try
+            {
+                var json = JsonUtility.ToJson(target);
+                snapshots[entityId] = json;
+#if UNITY_EDITOR
+                trackedTargets[entityId] = target;
+#endif
+                return true;
+            }
+            catch (Exception ex)
+            {
+                Debug.LogError($"[StateSnapshotService] Failed to capture snapshot for '{target.name}' ({target.GetType().Name}): {ex.Message}",
+                    target);
+                return false;
+            }
+        }
+
+        /// Restores the ScriptableObject to its captured baseline state in-place.
+        /// If no baseline has been captured yet, the current state is captured as baseline.
+        public static bool Restore(ScriptableObject target)
+        {
+            if (!target || target.IsStateless() || target.GetStateLifetime() == StateLifetime.Persistent)
+            {
+                return false;
+            }
+
+            var entityId = target.GetEntityId();
+            if (!snapshots.TryGetValue(entityId, out var json))
+            {
+                EnsureCaptured(target);
+                return false;
+            }
+
+            // Re-entrancy guard to prevent infinite mutual recursion (e.g. scenario resetting itself)
+            if (!restoringEntities.Add(entityId)) return false;
+
+            try
+            {
+                RestoreFromJson(json, target);
+
+                if (target is IRuntimeStateOwner stateOwner)
+                {
+                    stateOwner.ClearTransientState();
+                }
+
+                return true;
+            }
+            catch (Exception ex)
+            {
+                Debug.LogError($"[StateSnapshotService] Failed to restore snapshot for '{target.name}' ({target.GetType().Name}): {ex.Message}",
+                    target);
+                return false;
+            }
+            finally
+            {
+                restoringEntities.Remove(entityId);
+            }
+        }
+
+        /// Restores a collection of ScriptableObjects to their baseline state up to the specified max lifetime.
+        /// Multi-pass restoration:
+        /// Pass 1 captures the baseline for any uncaptured objects before modifying state.
+        /// Pass 2 restores serialized fields and triggers IRuntimeStateOwner.ClearTransientState.
+        public static void RestoreAll(IEnumerable<ScriptableObject> targets, StateLifetime maxLifetime = StateLifetime.Scenario)
+        {
+            if (targets == null) return;
+
+            var targetsList = targets as ScriptableObject[] ?? targets.ToArray();
+
+            // Pass 1: Ensure baseline is captured for ALL objects before any object is restored
+            foreach (var so in targetsList)
+            {
+                if (!so || so.IsStateless() || so.GetStateLifetime() > maxLifetime) continue;
+
+                EnsureCaptured(so);
+            }
+
+            // Pass 2: Restore all objects to baseline (and clear transient state via Restore)
+            foreach (var so in targetsList)
+            {
+                if (!so || so.IsStateless() || so.GetStateLifetime() > maxLifetime) continue;
+
+                Restore(so);
+            }
+        }
+
+        /// Restores all currently tracked ScriptableObjects to their baseline state.
+        public static int RestoreAll()
+        {
+            var restoredCount = 0;
+#if UNITY_EDITOR
+            foreach (var kvp in trackedTargets)
+            {
+                var target = kvp.Value;
+                if (!target)
+                {
+                    target = EditorUtility.EntityIdToObject(kvp.Key) as ScriptableObject;
+                }
+
+                if (!target || !snapshots.TryGetValue(kvp.Key, out var json)) continue;
+                if (!restoringEntities.Add(kvp.Key)) continue;
+
+                try
+                {
+                    RestoreFromJson(json, target);
+
+                    if (target is IRuntimeStateOwner stateOwner)
+                    {
+                        stateOwner.ClearTransientState();
+                    }
+
+                    EditorUtility.ClearDirty(target);
+                    restoredCount++;
+                }
+                catch (Exception ex)
+                {
+                    Debug.LogError($"[StateSnapshotService] Failed to restore target '{target.name}': {ex.Message}", target);
+                }
+                finally
+                {
+                    restoringEntities.Remove(kvp.Key);
+                }
+            }
+#endif
+            return restoredCount;
+        }
+
+        /// Restores serialized fields from JSON while preserving fields marked with [SnapshotIgnore].
+        private static void RestoreFromJson(string json, ScriptableObject target)
+        {
+            var ignoredFields = GetSnapshotIgnoreFields(target.GetType());
+            object[] preservedValues = null;
+            if (ignoredFields.Length > 0)
+            {
+                preservedValues = new object[ignoredFields.Length];
+                for (var i = 0; i < ignoredFields.Length; i++)
+                {
+                    preservedValues[i] = ignoredFields[i].GetValue(target);
+                }
+            }
+
+            JsonUtility.FromJsonOverwrite(json, target);
+            if (ignoredFields.Length <= 0 || preservedValues == null) return;
+
+            for (var i = 0; i < ignoredFields.Length; i++)
+            {
+                ignoredFields[i].SetValue(target, preservedValues[i]);
+            }
+        }
+
+        private static FieldInfo[] GetSnapshotIgnoreFields(Type type)
+        {
+            if (snapshotIgnoreFieldsCache.TryGetValue(type, out var fields))
+            {
+                return fields;
+            }
+
+            var list = new List<FieldInfo>();
+            var current = type;
+            while (current != null && current != typeof(ScriptableObject) && current != typeof(Object) && current != typeof(object))
+            {
+                var currentFields =
+                    current.GetFields(BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.DeclaredOnly);
+                foreach (var field in currentFields)
+                {
+                    if (Attribute.IsDefined(field, typeof(SnapshotIgnoreAttribute)))
+                    {
+                        list.Add(field);
+                    }
+                }
+
+                current = current.BaseType;
+            }
+
+            var result = list.Count > 0 ? list.ToArray() : Array.Empty<FieldInfo>();
+            snapshotIgnoreFieldsCache[type] = result;
+            return result;
+        }
+
+        /// Checks whether a baseline snapshot currently exists for the specified ScriptableObject.
+        public static bool HasSnapshot(ScriptableObject target) => target && snapshots.ContainsKey(target.GetEntityId());
+
+        /// Gets the raw JSON snapshot string for debugging / state inspector inspection.
+        public static string GetSnapshotJson(ScriptableObject target)
+        {
+            if (target && snapshots.TryGetValue(target.GetEntityId(), out var json))
+            {
+                return json;
+            }
+
+            return null;
+        }
+
+        /// Evicts a specific ScriptableObject snapshot from memory.
+        public static void Evict(ScriptableObject target)
+        {
+            if (target == null) return;
+            var entityId = target.GetEntityId();
+            snapshots.Remove(entityId);
+            restoringEntities.Remove(entityId);
+#if UNITY_EDITOR
+            trackedTargets.Remove(entityId);
+#endif
+        }
+
+        /// Clears all stored state snapshots.
+        public static void ClearAll()
+        {
+            snapshots.Clear();
+            restoringEntities.Clear();
+#if UNITY_EDITOR
+            trackedTargets.Clear();
+#endif
+        }
+
+        /// Alias for ClearAll to provide clear naming.
+        public static void ClearAllSnapshots() => ClearAll();
+
+        /// Automatically called by Unity when Enter Play Mode Options (Disable Domain Reload) is active,
+        /// or when the game initializes.
+        /// SubsystemRegistration executes before any Awake/OnEnable calls when entering Play Mode,
+        /// ensuring static state dictionaries from previous play sessions or editor runs are completely purged.
+        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
+        private static void ResetStaticFields() => ClearAll();
+    }
+}

package/Runtime/StateSnapshotService.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: ca7bd4657354461e804f3287821da35c
+timeCreated: 1788207914

package/Tests/Editor/StateSnapshotServiceTests.cs

@@ -0,0 +1,195 @@
+using NUnit.Framework;
+using UnityEngine;
+
+namespace Xprees.Core.Tests
+{
+    public class StateSnapshotServiceTests
+    {
+        [StatefulLifetime(StateLifetime.Scenario)]
+        private class TestStatefulSO : ScriptableObject, IRuntimeStateOwner
+        {
+            public int intValue = 10;
+            public string stringValue = "initial";
+            public bool transientFlag = false;
+
+            public void ClearTransientState()
+            {
+                transientFlag = false;
+            }
+        }
+
+        [StatefulLifetime(StateLifetime.Scenario)]
+        private class TestSnapshotIgnoreSO : ScriptableObject
+        {
+            public int capturedValue = 10;
+            [SnapshotIgnore] public string ignoredValue = "initial";
+        }
+
+        private class TestPlainSO : ScriptableObject
+        {
+            public int count = 5;
+        }
+
+        [StatelessAsset]
+        private class TestStatelessSO : ScriptableObject
+        {
+            public int count = 5;
+        }
+
+        [Stateless]
+        private class TestStatelessAliasSO : ScriptableObject
+        {
+            public int count = 5;
+        }
+
+        [StatefulLifetime(StateLifetime.Persistent)]
+        private class TestPersistentSO : ScriptableObject
+        {
+            public int score = 100;
+        }
+
+        [SetUp]
+        public void Setup()
+        {
+            StateSnapshotService.ClearAllSnapshots();
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            StateSnapshotService.ClearAllSnapshots();
+        }
+
+        [Test]
+        public void EnsureCaptured_And_Restore_RevertsMutatedState()
+        {
+            var so = ScriptableObject.CreateInstance<TestStatefulSO>();
+            so.intValue = 42;
+            so.stringValue = "pristine";
+
+            StateSnapshotService.EnsureCaptured(so);
+            Assert.IsTrue(StateSnapshotService.HasSnapshot(so));
+
+            // Mutate
+            so.intValue = 999;
+            so.stringValue = "corrupted";
+
+            // Restore
+            StateSnapshotService.Restore(so);
+
+            Assert.AreEqual(42, so.intValue);
+            Assert.AreEqual("pristine", so.stringValue);
+
+            Object.DestroyImmediate(so);
+        }
+
+        [Test]
+        public void SnapshotIgnore_PreservesFieldValueAcrossRestore()
+        {
+            var so = ScriptableObject.CreateInstance<TestSnapshotIgnoreSO>();
+            so.capturedValue = 10;
+            so.ignoredValue = "before_capture";
+
+            StateSnapshotService.EnsureCaptured(so);
+
+            // Mutate both
+            so.capturedValue = 99;
+            so.ignoredValue = "mutated_after_capture";
+
+            StateSnapshotService.Restore(so);
+
+            // capturedValue should be restored to baseline (10)
+            Assert.AreEqual(10, so.capturedValue);
+            // ignoredValue was excluded from overwrite, so it retains its mutated value ("mutated_after_capture")
+            Assert.AreEqual("mutated_after_capture", so.ignoredValue);
+
+            Object.DestroyImmediate(so);
+        }
+
+        [Test]
+        public void RestoreAll_RestoresAllTrackedTargets()
+        {
+            var so1 = ScriptableObject.CreateInstance<TestStatefulSO>();
+            so1.intValue = 10;
+            so1.stringValue = "first";
+
+            var so2 = ScriptableObject.CreateInstance<TestStatefulSO>();
+            so2.intValue = 20;
+            so2.stringValue = "second";
+
+            StateSnapshotService.EnsureCaptured(so1);
+            StateSnapshotService.EnsureCaptured(so2);
+
+            // Mutate both
+            so1.intValue = 111;
+            so2.intValue = 222;
+
+            // RestoreAll
+            var restored = StateSnapshotService.RestoreAll();
+            Assert.AreEqual(2, restored);
+            Assert.AreEqual(10, so1.intValue);
+            Assert.AreEqual(20, so2.intValue);
+
+            Object.DestroyImmediate(so1);
+            Object.DestroyImmediate(so2);
+        }
+
+        [Test]
+        public void PlainScriptableObject_WithoutAttributeOrDescriptionBaseSO_IsStatelessAndIgnored()
+        {
+            var so = ScriptableObject.CreateInstance<TestPlainSO>();
+            Assert.IsTrue(so.IsStateless());
+            Assert.AreEqual(StateLifetime.Persistent, so.GetStateLifetime());
+            Assert.IsFalse(StateSnapshotService.EnsureCaptured(so));
+            Object.DestroyImmediate(so);
+        }
+
+        [Test]
+        public void StatelessAsset_IsIgnoredBySnapshotEngine()
+        {
+            var so = ScriptableObject.CreateInstance<TestStatelessSO>();
+            so.count = 50;
+
+            StateSnapshotService.EnsureCaptured(so);
+            Assert.IsFalse(StateSnapshotService.HasSnapshot(so));
+
+            Object.DestroyImmediate(so);
+        }
+
+        [Test]
+        public void StatelessAttribute_IsIgnoredBySnapshotEngine()
+        {
+            var so = ScriptableObject.CreateInstance<TestStatelessAliasSO>();
+            so.count = 50;
+
+            StateSnapshotService.EnsureCaptured(so);
+            Assert.IsFalse(StateSnapshotService.HasSnapshot(so));
+
+            Object.DestroyImmediate(so);
+        }
+
+        [Test]
+        public void PersistentLifetime_IsIgnoredBySnapshotEngine()
+        {
+            var so = ScriptableObject.CreateInstance<TestPersistentSO>();
+            so.score = 200;
+
+            StateSnapshotService.EnsureCaptured(so);
+            Assert.IsFalse(StateSnapshotService.HasSnapshot(so));
+
+            Object.DestroyImmediate(so);
+        }
+
+        [Test]
+        public void ClearTransientState_ResetsNonSerializedFlags()
+        {
+            var so = ScriptableObject.CreateInstance<TestStatefulSO>();
+            so.transientFlag = true;
+
+            so.ClearTransientState();
+            Assert.IsFalse(so.transientFlag);
+
+            Object.DestroyImmediate(so);
+        }
+    }
+}

package/Tests/Editor/StateSnapshotServiceTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 372c79cab401438cbcb3acb2d207e388
+timeCreated: 1788208202

package/Tests/Editor/cz.xprees.core.Tests.Editor.asmdef

@@ -0,0 +1,24 @@
+{
+  "name": "cz.xprees.core.Tests.Editor",
+  "rootNamespace": "Xprees.Core.Tests",
+  "references": [
+    "cz.xprees.core",
+    "UnityEngine.TestRunner",
+    "UnityEditor.TestRunner"
+  ],
+  "includePlatforms": [
+    "Editor"
+  ],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": true,
+  "precompiledReferences": [
+    "nunit.framework.dll"
+  ],
+  "autoReferenced": false,
+  "defineConstraints": [
+    "UNITY_INCLUDE_TESTS"
+  ],
+  "versionDefines": [],
+  "noEngineReferences": false
+}

package/Tests/Editor/cz.xprees.core.Tests.Editor.asmdef.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 0e8276ba88644ade9d2e1b915a633ef5
+timeCreated: 1788208198

package/Tests/Editor.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: a6549e6501ce4edf9760028c767f654a
+timeCreated: 1788208198

package/Tests.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 0f91d1411ac146c38a51780ec1158bea
+timeCreated: 1788208198

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cz.xprees.core",
   "displayName": "Core Classes",
-  "version": "1.0.34",
+  "version": "1.0.40",
   "unity": "2021.3",
   "description": "This package contains core classes and interfaces for Unity projects. It is intended to be used as a dependency for other packages. By providing base classes in a separate package, you can easily update them across all your projects.",
   "license": "Apache-2.0",