Add verbose debug logging

Author: ahmedkamalio

Assets/UnityEventTimeline/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to UnityEventTimeline will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.5] - 2024-12-23
+
+Verbose debug logging implementation.
+
+### Added
+- Verbose debug logging capabilities (`EVENTTIMELINE_DEBUG_VERBOSE`)
+
 ## [1.0.0] - 2024-12-21
 
 Initial release of the UnityEventTimeline package.
@@ -24,3 +31,4 @@ Initial release of the UnityEventTimeline package.
 - Debug logging capabilities (`EVENTTIMELINE_DEBUG`)
 
 [1.0.0]: https://github.com/ahmedkamalio/UnityEventTimeline/releases/tag/v1.0.0
+[1.0.5]: https://github.com/ahmedkamalio/UnityEventTimeline/releases/tag/v1.0.5

Assets/UnityEventTimeline/Documentation~/UnityEventTimeline.md

@@ -203,14 +203,77 @@ EventTimeline.Instance.SetMaxProcessingTime(8.0f); // milliseconds
 
 ## Debug Support
 
-Enable debug logging by defining the EVENTTIMELINE_DEBUG symbol in your development builds:
+The event timeline system provides two levels of debug logging that can be enabled via compiler symbols:
+
+### Basic Debug Logging
+
+Basic debug logging includes warnings and errors, enabled by defining the `EVENTTIMELINE_DEBUG` symbol. The logging will
+be active in the Unity Editor or development builds when this symbol is defined:
 
 ```csharp
 #if (DEVELOPMENT_BUILD || UNITY_EDITOR) && EVENTTIMELINE_DEBUG
-    // Debug logging will be active
+    // Basic debug logging is enabled in this condition.
 #endif
 ```
 
+### Verbose Debug Logging
+
+Verbose logging includes detailed operational information and requires both `EVENTTIMELINE_DEBUG` and
+`EVENTTIMELINE_DEBUG_VERBOSE` symbols to be defined:
+
+```csharp
+#if EVENTTIMELINE_DEBUG && EVENTTIMELINE_DEBUG_VERBOSE
+    // Verbose debug logging is enabled in this condition.
+#endif
+```
+
+### Configuring Debug Symbols
+
+There are two ways to define these debug symbols:
+
+1. Via Unity's Player Settings:
+    - Open Project Settings -> Player
+    - Under "Other Settings" -> "Script Compilation"
+    - Add to "Scripting Define Symbols":
+      ```
+      EVENTTIMELINE_DEBUG
+      EVENTTIMELINE_DEBUG_VERBOSE
+      ```
+
+2. Via compilation arguments in your build configuration:
+   ```
+   -define:EVENTTIMELINE_DEBUG
+   -define:EVENTTIMELINE_DEBUG_VERBOSE
+   ```
+
+### Debug Output Examples
+
+Basic debug logging (`EVENTTIMELINE_DEBUG`) includes:
+
+- Warnings about invalid operations
+- Error conditions
+- Important state changes
+
+Verbose logging (`EVENTTIMELINE_DEBUG_VERBOSE`) additionally includes:
+
+- Detailed execution timing
+- Event processing steps
+- Pool operations
+- Queue state changes
+- Memory optimization details
+
+For example, event execution with verbose logging enabled:
+
+```
+[TimelineEvent] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+[TimelineEvent] Beginning internal execution of event: CustomEvent
+[TimelineEvent] Successfully executed event: CustomEvent
+[TimelineEvent] Execution time: 1ms
+[TimelineEvent] <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+```
+
+Note: Debug logging is automatically disabled in release builds unless explicitly enabled through compilation symbols.
+
 ## Example Scenarios
 
 ### Quest System

Assets/UnityEventTimeline/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ahmed Kamal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Assets/UnityEventTimeline/LICENSE.meta

@@ -4,6 +4,10 @@
 #define __EVENTTIMELINE_DEBUG
 #endif
 
+#if __EVENTTIMELINE_DEBUG && EVENTTIMELINE_DEBUG_VERBOSE
+#define __EVENTTIMELINE_DEBUG_VERBOSE
+#endif
+
 using UnityEngine;
 using UnityEngine.SceneManagement;
 using UnityEventTimeline.Internal;
@@ -52,11 +56,17 @@ public static EventTimeline Instance
             {
                 if (_instance is not null)
                 {
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+                    Debug.Log("[EventTimeline] Returning existing instance");
+#endif
                     return _instance;
                 }
 
                 lock (SingletonLock)
                 {
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+                    Debug.Log("[EventTimeline] Creating new instance");
+#endif
                     var go = new GameObject(nameof(EventTimeline));
                     _instance = go.AddComponent<EventTimeline>();
                     DontDestroyOnLoad(go);
@@ -95,13 +105,22 @@ protected override void Awake()
             {
                 if (_instance is not null && _instance != this)
                 {
+#if __EVENTTIMELINE_DEBUG
+                    Debug.LogWarning("[EventTimeline] Duplicate instance detected, destroying GameObject");
+#endif
+
                     Destroy(gameObject);
+
                     return;
                 }
 
                 _instance = this;
 
                 DontDestroyOnLoad(gameObject);
+
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+                Debug.Log("[EventTimeline] Instance initialized in Awake");
+#endif
             }
         }
 
@@ -142,6 +161,9 @@ protected override void OnDestroy()
             {
                 if (_instance == this)
                 {
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+                    Debug.Log("[EventTimeline] Clearing singleton instance");
+#endif
                     _instance = null;
                 }
             }
@@ -156,7 +178,15 @@ protected override void OnDestroy()
         /// </remarks>
         private void HandleSceneUnloaded(Scene scene)
         {
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+            Debug.Log($"[EventTimeline] Scene unloaded: {scene.name}");
+#endif
+
             OptimizeMemory();
+
+#if __EVENTTIMELINE_DEBUG_VERBOSE
+            Debug.Log("[EventTimeline] Memory optimization completed after scene unload");
+#endif
         }
     }
 }