feat: Add memory management options for scene transitions

- Add optimizeMemoryOnSceneUnload flag to control memory optimization on scene unload
- Add clearOnSceneUnload flag to optionally clear event queue during scene transitions
- Improve Clear() method to properly dispose events and reset internal state
- Fix Schedule<T> method to avoid redundant event creation in configure overload

Author: ahmedkamalio

Assets/UnityEventTimeline/Runtime/EventTimeline.cs

@@ -47,6 +47,28 @@ public class EventTimeline : EventTimelineQueue
         /// </remarks>
         private static readonly object SingletonLock = new();
 
+        /// <summary>
+        /// Determines whether memory optimizations are performed when a scene is unloaded.
+        /// </summary>
+        /// <remarks>
+        /// If enabled, memory resources are optimized after a scene unload, potentially reducing memory usage
+        /// by clearing or recycling unused objects. This setting complements the system's ability to manage
+        /// resources and maintain performance stability during scene transitions.
+        /// </remarks>
+        [SerializeField]
+        private bool optimizeMemoryOnSceneUnload = true;
+
+        /// <summary>
+        /// Determines whether the event queue should be cleared automatically when a scene is unloaded.
+        /// </summary>
+        /// <remarks>
+        /// When enabled, this setting ensures that all scheduled events are removed from the queue during a scene unload process,
+        /// preventing potential memory leaks or unintended execution of events from the previous scene.
+        /// This is particularly useful in scenarios where scene transitions are frequent or where event lifespan is tied to specific scenes.
+        /// </remarks>
+        [SerializeField]
+        private bool clearOnSceneUnload;
+
         /// <summary>
         /// Gets the singleton instance of the EventTimeline.
         /// </summary>
@@ -91,6 +113,30 @@ private EventTimeline()
         {
         }
 
+        /// <summary>
+        /// Configures the memory optimization behavior during scene unloads.
+        /// </summary>
+        /// <param name="optimize">
+        /// Determines whether to enable or disable memory optimizations when unloading a scene.
+        /// If set to true, memory optimization actions are performed to reduce resource usage.
+        /// </param>
+        public void SetOptimizeMemoryOnSceneUnload(bool optimize)
+        {
+            optimizeMemoryOnSceneUnload = optimize;
+        }
+
+        /// <summary>
+        /// Sets whether the event timeline should automatically clear events when the scene is unloaded.
+        /// </summary>
+        /// <param name="clear">
+        /// A boolean indicating if events should be cleared on scene unload.
+        /// If true, events will be cleared; otherwise, they will persist through scene changes.
+        /// </param>
+        public void SetClearOnSceneUnload(bool clear)
+        {
+            clearOnSceneUnload = clear;
+        }
+
         /// <summary>
         /// Unity Awake callback that handles singleton instance setup.
         /// </summary>
@@ -183,11 +229,23 @@ private void HandleSceneUnloaded(Scene scene)
             AsyncLogger.LogFormat("[EventTimeline] Scene unloaded: {0}", scene.name);
 #endif
 
-            OptimizeMemory();
+            if (optimizeMemoryOnSceneUnload)
+            {
+                OptimizeMemory();
+
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+                AsyncLogger.Log("[EventTimeline] Memory optimization completed after scene unload");
+#endif
+            }
+
+            if (clearOnSceneUnload)
+            {
+                Clear();
 
 #if __EVENTTIMELINE_DEBUG_VERBOSE
-            AsyncLogger.Log("[EventTimeline] Memory optimization completed after scene unload");
+                AsyncLogger.Log("[EventTimeline] Queue cleared successfully after scene unload");
 #endif
+            }
         }
     }
 }

Assets/UnityEventTimeline/Runtime/Internal/EventTimelineQueue.cs

@@ -161,8 +161,35 @@ public class EventTimelineQueue : EventTimelinePoolsManager
         /// </remarks>
         public T Schedule<T>(Action<T> configure, float delay = 0) where T : TimelineEvent<T>, new()
         {
-            var evt = Schedule<T>(delay);
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+            AsyncLogger.LogFormat("[EventTimelineQueue] Scheduling event of type {0} with delay {1}s", typeof(T).Name, delay);
+#endif
+
+            var evt = GetFromPool<T>();
+
             configure.Invoke(evt);
+
+            if (IsMainThread)
+            {
+                evt.ScheduledTime = Time.time + delay / timeScale;
+            }
+            else
+            {
+                RunOnMainThread(() => evt.ScheduledTime = Time.time + delay / timeScale);
+
+#if __EVENTTIMELINE_DEBUG
+                AsyncLogger.LogWarningFormat("[EventTimelineQueue] Background event schedule detected. Posting {0} to main thread.", typeof(T));
+#endif
+            }
+
+            evt.IsCancelled = false;
+
+            _eventQueue.Enqueue(evt);
+
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+            AsyncLogger.LogFormat("[EventTimelineQueue] Successfully scheduled event of type {0} for time {1:F3}s", typeof(T).Name, evt.ScheduledTime);
+#endif
+
             return evt;
         }
 
@@ -214,35 +241,57 @@ public Result<T> Reschedule<T>(T evt, float delay) where T : TimelineEvent
         }
 
         /// <summary>
-        /// Clears all scheduled events and event pools.
+        /// Clears all scheduled events, disposes them properly, and cleans up all event pools.
         /// </summary>
         /// <remarks>
-        /// Thread-safe operation protected by a lock.
-        /// Trims excess capacity from event pools after clearing.
+        /// This operation is thread-safe and performs complete cleanup by:
+        /// <list type="bullet">
+        ///     <item>Removing and disposing all events from the main queue</item>
+        ///     <item>Processing any cancelled events awaiting cleanup</item>
+        ///     <item>Clearing and disposing all pooled events</item>
+        ///     <item>Resetting internal state</item>
+        /// </list>
         /// </remarks>
         public void Clear()
         {
 #if __EVENTTIMELINE_DEBUG_VERBOSE
-            AsyncLogger.LogFormat("[EventTimelineQueue] Clearing all events. Current queue size: {0}", _eventQueue.Count);
+    AsyncLogger.LogFormat("[EventTimelineQueue] Beginning full queue cleanup. Current queue size: {0}", _eventQueue.Count);
 #endif
 
+            // Process all events in the main queue
+            var remainingEvents = _eventQueue.DequeueRange(_eventQueue.Count);
+            foreach (var evt in remainingEvents)
+            {
+                evt.Dispose();
+            }
+
             _eventQueue.Clear();
 
             lock (_cancelledEventsLock)
             {
-                // Return cancelled events to pool before clearing
+                // Process any pending cancelled events
                 foreach (var evt in _cancelledEvents)
                 {
-                    ReturnToPool(evt);
+                    evt.Dispose();
                 }
 
                 _cancelledEvents.Clear();
             }
 
+            // Clear all event pools and reset counters
             ClearEventPools();
+            _framesSinceCleanup = 0;
+
+            // Clear temporary storage
+            foreach (var evt in _futureEvents)
+            {
+                evt.Dispose();
+            }
+
+            _futureEvents.Clear();
 
 #if __EVENTTIMELINE_DEBUG_VERBOSE
-            AsyncLogger.Log("[EventTimelineQueue] Successfully cleared all events and pools");
+    AsyncLogger.Log("[EventTimelineQueue] Queue cleanup completed successfully");
 #endif
         }