Add JEngine.Util package

Introduce new utility classes package for JEngine framework. Also update
READMEs to document the new built-in package.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: JasonXuDeveloper

README.md

@@ -38,6 +38,7 @@ JEngine is a powerful Unity framework that enables **runtime hot updates** for y
 | Package | Description | Type |
 |---------|-------------|------|
 | **JEngine.Core** | Hot update support with secure, high-performance features | Built-in |
+| **JEngine.Util** | Utility classes for JEngine framework | Built-in |
 
 ### Additional Packages
 | Package | Description | Link |

README_zh_cn.md

@@ -42,6 +42,7 @@ JEngine是针对Unity开发者设计的**开箱即用**的框架，封装了强
 | 包名 | 描述 | 类型 |
 |------|------|------|
 | **JEngine.Core** | 支持运行时热更，附带安全且高性能的功能 | 自带 |
+| **JEngine.Util** | JEngine框架的工具类库 | 自带 |
 
 ### 扩展包
 | 包名 | 描述 | 链接 |

UnityProject/Packages/com.jasonxudeveloper.jengine.util/Runtime.meta

@@ -0,0 +1,120 @@
+// IStateStorage.cs
+// JEngine.Util - Polymorphic state storage interface
+//
+// Author: JasonXuDeveloper
+
+using System;
+using System.Runtime.CompilerServices;
+
+namespace JEngine.Util.Internal
+{
+    /// <summary>
+    /// Interface for polymorphic state storage with typed invocation.
+    /// Enables invoking delegates with correctly-typed state via interface dispatch,
+    /// avoiding boxing allocations for value types.
+    /// </summary>
+    internal interface IStateStorage
+    {
+        /// <summary>
+        /// Invokes an Action delegate with the stored state.
+        /// </summary>
+        /// <param name="action">The delegate to invoke (must be <c>Action&lt;T&gt;</c> where T matches stored type).</param>
+        void InvokeAction(Delegate action);
+
+        /// <summary>
+        /// Invokes an async Func delegate with the stored state.
+        /// </summary>
+        /// <param name="func">The delegate to invoke (must be <c>Func&lt;T, JActionAwaitable&gt;</c>).</param>
+        /// <returns>The awaitable result from the function.</returns>
+        JActionAwaitable InvokeAsyncFunc(Delegate func);
+
+        /// <summary>
+        /// Invokes a condition Func delegate with the stored state.
+        /// </summary>
+        /// <param name="condition">The delegate to invoke (must be <c>Func&lt;T, bool&gt;</c>).</param>
+        /// <returns>The boolean result of the condition.</returns>
+        bool InvokeCondition(Delegate condition);
+
+        /// <summary>
+        /// Returns this storage instance to its type-specific pool.
+        /// </summary>
+        void Return();
+    }
+
+    /// <summary>
+    /// Generic state storage with per-type object pooling via <see cref="JObjectPool{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of state to store.</typeparam>
+    /// <remarks>
+    /// <para>
+    /// This class avoids boxing for value types because the CLR creates a specialized
+    /// version of the generic class for each value type, storing T directly in the class layout.
+    /// </para>
+    /// <para>
+    /// Each type parameter T gets its own dedicated object pool, ensuring efficient reuse.
+    /// </para>
+    /// </remarks>
+    internal sealed class StateStorage<T> : IStateStorage
+    {
+        private static readonly JObjectPool<StateStorage<T>> Pool = new(
+            maxSize: 64,
+            onReturn: static s => s.Value = default
+        );
+
+        /// <summary>
+        /// The stored state value.
+        /// </summary>
+        public T Value;
+
+        /// <summary>
+        /// Rents a storage instance from the pool and initializes it with the specified value.
+        /// </summary>
+        /// <param name="value">The state value to store.</param>
+        /// <returns>A pooled <see cref="StateStorage{T}"/> instance containing the value.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static StateStorage<T> Rent(T value)
+        {
+            var storage = Pool.Rent();
+            storage.Value = value;
+            return storage;
+        }
+
+        /// <inheritdoc/>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Return()
+        {
+            Pool.Return(this);
+        }
+
+        /// <inheritdoc/>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void InvokeAction(Delegate action)
+        {
+            ((Action<T>)action)(Value);
+        }
+
+        /// <inheritdoc/>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public JActionAwaitable InvokeAsyncFunc(Delegate func)
+        {
+            return ((Func<T, JActionAwaitable>)func)(Value);
+        }
+
+        /// <inheritdoc/>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool InvokeCondition(Delegate condition)
+        {
+            return ((Func<T, bool>)condition)(Value);
+        }
+
+        /// <summary>
+        /// Gets the approximate number of pooled instances for this type.
+        /// </summary>
+        public static int PoolCount => Pool.Count;
+
+        /// <summary>
+        /// Clears the pool for this type.
+        /// </summary>
+        public static void ClearPool() => Pool.Clear();
+    }
+}

UnityProject/Packages/com.jasonxudeveloper.jengine.util/Runtime/Internal.meta

@@ -0,0 +1,162 @@
+// JActionRunner.cs
+// PlayerLoop-based driver for JAction main-thread execution (lock-free)
+//
+// Author: JasonXuDeveloper
+
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using UnityEngine;
+using UnityEngine.LowLevel;
+#if UNITY_EDITOR
+using UnityEditor;
+#endif
+
+namespace JEngine.Util.Internal
+{
+    /// <summary>
+    /// Static runner that drives <see cref="JAction"/> execution on the main thread.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Uses Unity's PlayerLoopSystem API in PlayMode and EditorApplication.update in EditMode,
+    /// avoiding any dependency on MonoBehaviour or GameObjects.
+    /// </para>
+    /// <para>
+    /// Lock-free design: uses ConcurrentQueue for thread-safe registration,
+    /// single-threaded consumption on main thread.
+    /// </para>
+    /// </remarks>
+    internal static class JActionRunner
+    {
+        private static readonly ConcurrentQueue<JAction> PendingQueue = new();
+        private static readonly List<JAction> ActiveActions = new(32);
+        private static bool _runtimeInitialized;
+
+#if UNITY_EDITOR
+        private static bool _editorInitialized;
+#endif
+
+        /// <summary>
+        /// Marker struct for identifying our update in the PlayerLoop.
+        /// </summary>
+        private struct JActionUpdate { }
+
+#if UNITY_EDITOR
+        [InitializeOnLoadMethod]
+        private static void InitializeEditor()
+        {
+            if (_editorInitialized) return;
+            _editorInitialized = true;
+
+            EditorApplication.update -= Update;
+            EditorApplication.update += Update;
+            EditorApplication.playModeStateChanged += OnPlayModeStateChanged;
+        }
+
+        private static void OnPlayModeStateChanged(PlayModeStateChange state)
+        {
+            if (state == PlayModeStateChange.ExitingPlayMode)
+            {
+                // Drain the queue
+                while (PendingQueue.TryDequeue(out _)) { }
+                ActiveActions.Clear();
+                _runtimeInitialized = false;
+            }
+        }
+#endif
+
+        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
+        private static void InitializeRuntime()
+        {
+            if (_runtimeInitialized) return;
+            _runtimeInitialized = true;
+
+            var playerLoop = PlayerLoop.GetCurrentPlayerLoop();
+            InsertUpdateSystem(ref playerLoop);
+            PlayerLoop.SetPlayerLoop(playerLoop);
+        }
+
+        private static void InsertUpdateSystem(ref PlayerLoopSystem rootLoop)
+        {
+            var subSystems = rootLoop.subSystemList;
+            if (subSystems == null) return;
+
+            for (int i = 0; i < subSystems.Length; i++)
+            {
+                if (subSystems[i].type == typeof(UnityEngine.PlayerLoop.Update))
+                {
+                    ref var updateLoop = ref subSystems[i];
+                    var updateSubSystems = updateLoop.subSystemList ?? Array.Empty<PlayerLoopSystem>();
+
+                    var newSubSystems = new PlayerLoopSystem[updateSubSystems.Length + 1];
+                    Array.Copy(updateSubSystems, newSubSystems, updateSubSystems.Length);
+
+                    newSubSystems[updateSubSystems.Length] = new PlayerLoopSystem
+                    {
+                        type = typeof(JActionUpdate),
+                        updateDelegate = Update
+                    };
+
+                    updateLoop.subSystemList = newSubSystems;
+                    break;
+                }
+            }
+        }
+
+        /// <summary>
+        /// Registers a <see cref="JAction"/> for main-thread execution.
+        /// </summary>
+        /// <param name="action">The action to register. Null values are ignored.</param>
+        /// <remarks>
+        /// Thread-safe and lock-free via ConcurrentQueue.
+        /// </remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void Register(JAction action)
+        {
+            if (action == null) return;
+            PendingQueue.Enqueue(action);
+        }
+
+        private static void Update()
+        {
+            // Drain pending queue into active list (single-threaded, no lock needed)
+            while (PendingQueue.TryDequeue(out var action))
+            {
+                ActiveActions.Add(action);
+            }
+
+            if (ActiveActions.Count == 0) return;
+
+            // Process in reverse to allow safe removal during iteration
+            for (int i = ActiveActions.Count - 1; i >= 0; i--)
+            {
+                var action = ActiveActions[i];
+                if (action == null)
+                {
+                    ActiveActions.RemoveAt(i);
+                    continue;
+                }
+
+                try
+                {
+                    if (action.Tick())
+                    {
+                        ActiveActions.RemoveAt(i);
+                    }
+                }
+                catch (Exception e)
+                {
+                    Debug.LogException(e);
+                    ActiveActions.RemoveAt(i);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Gets the approximate number of currently active JActions.
+        /// </summary>
+        public static int ActiveCount => ActiveActions.Count + PendingQueue.Count;
+    }
+}