cz.xprees.core 1.0.39 → 1.0.40

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

@@ -1,6 +1,6 @@
 {
   "name": "cz.xprees.core.editor",
-  "rootNamespace": "Xprees.Core",
+  "rootNamespace": "Xprees.Core.Editor",
   "references": [
     "GUID:999c2ca78ab34358a1222750376a501c"
   ],

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/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/StateSnapshotService.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
+using System.Linq;
 using System.Reflection;
 using UnityEngine;
 using Object = UnityEngine.Object;
@@ -12,8 +13,9 @@ 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 between scenario runs.
+    /// of ScriptableObject serialized state across scenario and session boundaries.
     public static class StateSnapshotService
     {
         private readonly static Dictionary<int, string> snapshots = new();
@@ -99,6 +101,33 @@ namespace Xprees.Core
             }
         }
 
+        /// 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()
         {
@@ -236,39 +265,6 @@ namespace Xprees.Core
         /// 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 ResetStatics() => ClearAll();
-
-#if UNITY_EDITOR
-        [InitializeOnLoadMethod]
-        private static void InitEditorLifecycle()
-        {
-            EditorApplication.playModeStateChanged -= OnPlayModeStateChanged;
-            EditorApplication.playModeStateChanged += OnPlayModeStateChanged;
-        }
-
-        private static void OnPlayModeStateChanged(PlayModeStateChange change)
-        {
-            // When exiting Play Mode, restore before scene objects begin tearing down
-            if (change == PlayModeStateChange.ExitingPlayMode)
-            {
-                RestoreAll();
-                return;
-            }
-
-            // Once fully transitioned back to Edit Mode, all scene unload and OnDisable/OnDestroy
-            // lifecycle calls have finished. Re-run RestoreAll() to guarantee any mutations occurring
-            // during teardown are cleanly reverted, then clear the snapshot tracking.
-            if (change == PlayModeStateChange.EnteredEditMode)
-            {
-                var count = RestoreAll();
-                if (count > 0)
-                {
-                    Debug.Log($"[StateSnapshotService] Restored {count} stateful ScriptableObjects back to pre-play baseline.");
-                }
-
-                ClearAll();
-            }
-        }
-#endif
+        private static void ResetStaticFields() => ClearAll();
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cz.xprees.core",
   "displayName": "Core Classes",
-  "version": "1.0.39",
+  "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",