Debug events by displaying stack traces for events (#159)

* Add stack trace toggled via user prefs

* Add docs regarding preferences

* Rename color getter functions

* Fix minior order of execution bug

* Use GUID + improved styling of detailed stack view

* - Changed the AddStackTrace method to be conditional (from one of your initial suggestions).
- Removed the implicit conversion operator in StackTraceEntry and is instead using ToString explicitly when needed.
- Improved implementation of GetFirstLine
- Simplified Equals implementation of the StackTraceEntry class

Packages/Core/Editor/Editors/Events/AtomEventEditor.cs

@@ -19,18 +19,21 @@ namespace UnityAtoms.Editor
             IMGUIContainer defaultInspector = new IMGUIContainer(() => DrawDefaultInspector());
             root.Add(defaultInspector);
 
+            E atomEvent = target as E;
+
             var runtimeWrapper = new VisualElement();
             runtimeWrapper.SetEnabled(Application.isPlaying);
             runtimeWrapper.Add(new Button(() =>
             {
-                E e = target as E;
-                e.Raise(e.InspectorRaiseValue);
+                atomEvent.Raise(atomEvent.InspectorRaiseValue);
             })
             {
                 text = "Raise"
             });
             root.Add(runtimeWrapper);
 
+            StackTraceEditor.RenderStackTrace(root, atomEvent.GetInstanceID());
+
             return root;
         }
     }

Packages/Core/Editor/Editors/StackTraceEditor.cs

@@ -0,0 +1,211 @@
+#if UNITY_2019_1_OR_NEWER
+using System;
+using System.Collections.ObjectModel;
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEditor;
+using UnityEngine.UIElements;
+
+namespace UnityAtoms.Editor
+{
+    public static class StackTraceEditor
+    {
+        public static VisualElement RenderStackTrace(VisualElement parent, int instanceId)
+        {
+            if (!AtomPreferences.IsDebugModeEnabled) return null;
+            var stackTraces = StackTraces.GetStackTraces(instanceId);
+
+            var foldout = GetOrCreate<Foldout>(parent, "STACK_TRACES_FOLDOUT", (element) =>
+            {
+                element.style.marginTop = 4;
+                element.style.marginBottom = 4;
+                element.text = "Stack traces";
+            });
+
+            var wrapper = GetOrCreate<VisualElement>(foldout, "STACK_TRACES_ROOT", (element) =>
+            {
+                element.style.flexDirection = FlexDirection.Column;
+            });
+
+            var header = GetOrCreate<VisualElement>(wrapper, "HEADER", (element) =>
+            {
+                element.style.flexDirection = FlexDirection.Row;
+                element.style.justifyContent = Justify.SpaceBetween;
+                element.style.alignItems = Align.Center;
+                element.style.backgroundColor = GetHeaderColor();
+                element.style.paddingLeft = 4;
+                element.style.paddingRight = 4;
+                element.style.paddingTop = 2;
+                element.style.paddingBottom = 2;
+            });
+
+            var title = GetOrCreate<Label>(header, "TITLE", (label) =>
+            {
+                label.text = "Overview";
+                label.style.unityFontStyleAndWeight = FontStyle.Bold;
+            });
+
+            var clearButton = GetOrCreate<Button>(header, "CLEAR_BUTTON", (button) =>
+            {
+                button.text = "Clear";
+                button.clicked += () =>
+                {
+                    SetSelectedStackTraceId(instanceId, -1);
+                    StackTraces.ClearStackTraces(instanceId);
+                };
+            });
+
+            // All stack traces
+            RenderStackTracesOverview(wrapper, stackTraces, instanceId);
+            RenderStackTraceDetails(wrapper, stackTraces, instanceId);
+
+            // Rerender on change
+            stackTraces.CollectionChanged += (sender, e) =>
+            {
+                RenderStackTracesOverview(wrapper, stackTraces, instanceId);
+                RenderStackTraceDetails(wrapper, stackTraces, instanceId);
+            };
+
+            return wrapper;
+        }
+
+        private static void RenderStackTraceDetails(VisualElement parent, ObservableCollection<StackTraceEntry> stackTraces, int instanceId)
+        {
+            var selectedStackTraceId = GetSelectedStackTraceId(instanceId);
+
+            var wrapper = GetOrCreate<VisualElement>(parent, "STACK_TRACES_DETAILS_WRAPPER");
+
+            var header = GetOrCreate<VisualElement>(wrapper, "HEADER", (element) =>
+            {
+                element.style.flexDirection = FlexDirection.Row;
+                element.style.justifyContent = Justify.FlexStart;
+                element.style.alignItems = Align.Center;
+                element.style.backgroundColor = GetHeaderColor();
+                element.style.paddingLeft = 4;
+                element.style.paddingRight = 4;
+                element.style.paddingTop = 6;
+                element.style.paddingBottom = 6;
+                element.style.display = selectedStackTraceId != -1 ? DisplayStyle.Flex : DisplayStyle.None;
+            });
+
+            var title = GetOrCreate<Label>(header, "TITLE", (label) =>
+            {
+                label.text = "Details";
+                label.style.unityFontStyleAndWeight = FontStyle.Bold;
+            });
+
+            var stackTracesDetails = GetOrCreate<ScrollView>(wrapper, "SCROLL_VIEW", (scrollView) =>
+            {
+                scrollView.style.maxHeight = 100;
+                scrollView.style.height = 100;
+                scrollView.style.backgroundColor = GetBodyColor();
+                scrollView.showVertical = true;
+                scrollView.style.display = selectedStackTraceId != -1 ? DisplayStyle.Flex : DisplayStyle.None;
+            });
+
+            var details = GetOrCreate<TextField>(stackTracesDetails, "DETAILS", (field) =>
+            {
+                field.isReadOnly = true;
+                field.multiline = true;
+                field.value = selectedStackTraceId != -1 ? stackTraces[selectedStackTraceId].ToString() : "";
+                field.style.borderLeftWidth = 0;
+                field.style.borderRightWidth = 0;
+                field.style.borderTopWidth = 0;
+                field.style.borderBottomWidth = 0;
+                field.style.marginLeft = 1;
+                field.style.marginRight = 1;
+                field.style.marginTop = 1;
+                field.style.marginBottom = 1;
+            });
+        }
+
+        private static void RenderStackTracesOverview(VisualElement parent, ObservableCollection<StackTraceEntry> stackTraces, int instanceId)
+        {
+            var selectedStackTraceId = GetSelectedStackTraceId(instanceId);
+
+            var stackTracesOverview = GetOrCreate<ScrollView>(parent, "STACK_TRACES_OVERVIEW_SCROLL_VIEW", (scrollView) =>
+            {
+                scrollView.style.maxHeight = 100;
+                scrollView.style.height = 100;
+                scrollView.style.backgroundColor = GetBodyColor();
+                scrollView.showVertical = true;
+            });
+            var stackTracesOverviewRowContainer = GetOrCreate<VisualElement>(stackTracesOverview, "STACK_TRACES_OVERVIEW_ROW_CONTAINER");
+            stackTracesOverviewRowContainer.style.flexDirection = FlexDirection.Column;
+
+            stackTracesOverviewRowContainer.Clear();
+            for (var i = 0; i < stackTraces.Count; ++i)
+            {
+                var index = i;
+                var stackTrace = stackTraces[index];
+                var row = new Label()
+                {
+                    text = stackTrace.ToString().GetFirstLine(),
+                    style =
+                    {
+                        paddingTop = 4,
+                        paddingBottom = 4,
+                        paddingLeft = 4,
+                        paddingRight = 4,
+                    }
+                };
+
+                if (selectedStackTraceId == index)
+                {
+                    row.style.color = Color.yellow;
+                }
+
+                row.RegisterCallback<MouseDownEvent>((e) =>
+                {
+                    SetSelectedStackTraceId(instanceId, index);
+                    RenderStackTracesOverview(parent, stackTraces, instanceId);
+                    RenderStackTraceDetails(parent, stackTraces, instanceId);
+                });
+
+                stackTracesOverviewRowContainer.Add(row);
+            }
+        }
+
+        private static T GetOrCreate<T>(VisualElement parent, string name, Action<T> initializer = null) where T : VisualElement, new()
+        {
+            var element = (T)parent.Query<VisualElement>(name: name).First() ?? new T() { name = name };
+            if (initializer != null)
+            {
+                initializer(element);
+            }
+            if (!parent.Contains(element))
+                parent.Add(element);
+            return element;
+        }
+
+        private static Color GetHeaderColor()
+        {
+            var proColor = new Color(44f / 255f, 44f / 255f, 44f / 255f);
+            var basicColor = new Color(154f / 255f, 154f / 255f, 154f / 255f);
+            return EditorGUIUtility.isProSkin ? proColor : basicColor;
+        }
+
+        private static Color GetBodyColor()
+        {
+            var proColor = new Color(83f / 255f, 83f / 255f, 83f / 255f);
+            var basicColor = new Color(174f / 255f, 174f / 255f, 174f / 255f);
+            return EditorGUIUtility.isProSkin ? proColor : basicColor;
+        }
+
+        private static Dictionary<int, int> _stackTraceIdSelectedPerInstanceId = new Dictionary<int, int>();
+        private static int GetSelectedStackTraceId(int instanceId)
+        {
+            if (!_stackTraceIdSelectedPerInstanceId.ContainsKey(instanceId)) _stackTraceIdSelectedPerInstanceId.Add(instanceId, -1);
+
+            return _stackTraceIdSelectedPerInstanceId[instanceId];
+        }
+
+        private static void SetSelectedStackTraceId(int instanceId, int selectedIndex)
+        {
+            if (!_stackTraceIdSelectedPerInstanceId.ContainsKey(instanceId)) _stackTraceIdSelectedPerInstanceId.Add(instanceId, -1);
+
+            _stackTraceIdSelectedPerInstanceId[instanceId] = selectedIndex;
+        }
+    }
+}
+#endif

Packages/Core/Editor/Editors/StackTraceEditor.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 69145147a656949229be9569b5a22f17
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Packages/Core/Editor/Extensions/StringExtensions.cs

@@ -1,4 +1,4 @@
-using System;
+using System.Linq;
 using System.Text;
 
 namespace UnityAtoms
@@ -43,5 +43,11 @@ namespace UnityAtoms
             a[0] = char.ToUpper(a[0]);
             return new string(a);
         }
+
+        public static string GetFirstLine(this string str)
+        {
+            var indexFirstNewLineChar = str.IndexOfAny(new char[] { '\r', '\n' });
+            return indexFirstNewLineChar == -1 ? str : str.Substring(0, indexFirstNewLineChar);
+        }
     }
 }

Packages/Core/Runtime/Events/AtomEvent.cs

@@ -61,6 +61,8 @@ namespace UnityAtoms
         /// <param name="item">The value associated with the Event.</param>
         public void Raise(T item)
         {
+
+            StackTraces.AddStackTrace(GetInstanceID(), StackTraceEntry.Create(item));
             base.Raise();
             _onEvent?.Invoke(item);
             AddToReplayBuffer(item);

Packages/Core/Runtime/Events/AtomEventBase.cs

@@ -15,8 +15,10 @@ namespace UnityAtoms
         /// </summary>
         public event Action OnEventNoValue;
 
+
         public virtual void Raise()
         {
+            StackTraces.AddStackTrace(GetInstanceID(), StackTraceEntry.Create());
             OnEventNoValue?.Invoke();
         }
 

Packages/Core/Runtime/Preferences.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 8c417762459b24f8fa4d95ee48545136
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Packages/Core/Runtime/Preferences/AtomsPreferences.cs

@@ -0,0 +1,99 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEditor;
+using UnityEngine.UIElements;
+
+namespace UnityAtoms
+{
+    /// <summary>
+    /// Class to set preferences for Unity Atoms.
+    /// </summary>
+    public static class AtomPreferences
+    {
+        public abstract class Preference<T>
+        {
+            public T DefaultValue { get; set; }
+            public string Key { get; set; }
+
+            public abstract T Get();
+            public abstract void Set(T value);
+        }
+
+        public class BoolPreference : Preference<bool>
+        {
+            public override bool Get()
+            {
+                if (!EditorPrefs.HasKey(Key))
+                {
+                    EditorPrefs.SetBool(Key, DefaultValue);
+                }
+
+                return EditorPrefs.GetBool(Key);
+            }
+
+            public override void Set(bool value)
+            {
+                EditorPrefs.SetBool(Key, value);
+            }
+        }
+
+        public static bool IsDebugModeEnabled { get => DEBUG_MODE_PREF.Get(); }
+
+        private static BoolPreference DEBUG_MODE_PREF = new BoolPreference() { DefaultValue = false, Key = "UnityAtoms.DebugMode" };
+
+#if UNITY_2019_1_OR_NEWER
+        [SettingsProvider]
+        public static SettingsProvider CreateMyCustomSettingsProvider()
+        {
+            // First parameter is the path in the Settings window.
+            // Second parameter is the scope of this setting: it only appears in the Settings window for the User scope.
+            return new SettingsProvider("Preferences/UnityAtoms", SettingsScope.User)
+            {
+                label = "Unity Atoms",
+                // activateHandler is called when the user clicks on the Settings item in the Settings window.
+                activateHandler = (searchContext, rootElement) =>
+                {
+                    var wrapper = new VisualElement()
+                    {
+                        style =
+                        {
+                        marginBottom = 2,
+                        marginTop = 2,
+                        marginLeft = 8,
+                        marginRight = 8,
+                        flexDirection = FlexDirection.Column,
+                        }
+                    };
+
+                    var title = new Label()
+                    {
+                        text = "Unity Atoms",
+                        style =
+                        {
+                        fontSize = 20,
+                        marginBottom = 12,
+                        unityFontStyleAndWeight = FontStyle.Bold,
+                        },
+                    };
+                    wrapper.Add(title);
+
+                    var enableDebug = new Toggle()
+                    {
+                        label = "Debug mode",
+                        value = DEBUG_MODE_PREF.Get(),
+                        tooltip = "Enables debug functionality in Unity Atoms, for example Stack Traces for Events. Performance will decrease using this option, but could be switched on for debugging purposes.",
+                    };
+                    enableDebug.RegisterValueChangedCallback((changeEvt) => DEBUG_MODE_PREF.Set(changeEvt.newValue));
+                    wrapper.Add(enableDebug);
+
+                    rootElement.Add(wrapper);
+                },
+
+                keywords = new HashSet<string>(new[] { "Atoms", "Unity Atoms" })
+            };
+        }
+#endif
+    }
+}
+#endif

Packages/Core/Runtime/Preferences/AtomsPreferences.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 4feb4f5f51e1d4d7da67a1913ca9c267
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Packages/Core/Runtime/StackTrace.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 21a43636827564e26888e12f7c21a6bf
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Packages/Core/Runtime/StackTrace/StackTraceEntry.cs

@@ -0,0 +1,55 @@
+using System;
+using System.Diagnostics;
+using UnityEngine;
+
+namespace UnityAtoms
+{
+    public class StackTraceEntry : IEquatable<StackTraceEntry>
+    {
+        private readonly Guid _id;
+        private readonly int _frameCount;
+        private readonly string _stackTrace;
+        private readonly object _value;
+        private readonly bool _constructedWithValue = false;
+
+        private StackTraceEntry(string stackTrace)
+        {
+            _id = Guid.NewGuid();
+            _stackTrace = stackTrace;
+
+            if (Application.isPlaying)
+            {
+                _frameCount = Time.frameCount;
+            }
+        }
+        private StackTraceEntry(string stackTrace, object value)
+        {
+            _value = value;
+            _constructedWithValue = true;
+            _id = Guid.NewGuid();
+            _stackTrace = stackTrace;
+
+            if (Application.isPlaying)
+            {
+                _frameCount = Time.frameCount;
+            }
+        }
+
+        public static StackTraceEntry Create(object obj, int skipFrames = 0) => new StackTraceEntry(new StackTrace(skipFrames).ToString(), obj);
+
+        public static StackTraceEntry Create(int skipFrames = 0) => new StackTraceEntry(new StackTrace(skipFrames).ToString());
+
+
+        public override bool Equals(object obj) => Equals(obj as StackTraceEntry);
+
+        public bool Equals(StackTraceEntry other) => other?._id == _id;
+
+        public override int GetHashCode() => _id.GetHashCode();
+
+
+        public override string ToString() =>
+            _constructedWithValue ?
+                $"{_frameCount}   [{(_value == null ? "null" : _value.ToString())}] {_stackTrace}" :
+                $"{_frameCount} {_stackTrace}";
+    }
+}

Packages/Core/Runtime/StackTrace/StackTraceEntry.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 891dace9210764def9ca5ed8ba06c539
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Packages/Core/Runtime/StackTrace/StackTraces.cs

@@ -0,0 +1,38 @@
+#if UNITY_EDITOR
+using System.Diagnostics;
+using System.Collections.ObjectModel;
+using System.Collections.Generic;
+
+namespace UnityAtoms
+{
+    public static class StackTraces
+    {
+        private static Dictionary<int, ObservableCollection<StackTraceEntry>> _stackTracesById = new Dictionary<int, ObservableCollection<StackTraceEntry>>();
+
+        [Conditional("UNITY_EDITOR")]
+        public static void AddStackTrace(int id, StackTraceEntry stackTrace)
+        {
+            if (AtomPreferences.IsDebugModeEnabled)
+            {
+                GetStackTraces(id).Insert(0, stackTrace);
+            }
+        }
+
+        public static void ClearStackTraces(int id) => GetStackTraces(id).Clear();
+
+        public static ObservableCollection<StackTraceEntry> GetStackTraces(int id)
+        {
+            if (!_stackTracesById.ContainsKey(id))
+            {
+                _stackTracesById.Add(id, new ObservableCollection<StackTraceEntry>());
+            }
+            else if (_stackTracesById[id] == null)
+            {
+                _stackTracesById[id] = new ObservableCollection<StackTraceEntry>();
+            }
+
+            return _stackTracesById[id];
+        }
+    }
+}
+#endif

Packages/Core/Runtime/StackTrace/StackTraces.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 531ff10a724314a198b061e26e2c1559
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

docs/README.md

@@ -7,6 +7,7 @@
     -   [Usage with UniRX](./introduction/unirx.md)
     -   [Level up using the Generator](./introduction/generator.md)
     -   [Advanced example](./introduction/advanced-example.md)
+    -   [Preferences](./introduction/preferences.md)
 -   API
     -   [UnityAtoms](./api/unityatoms.md)
     -   [UnityAtoms.Editor](./api/unityatoms.editor.md)

docs/introduction/preferences.md

@@ -0,0 +1,20 @@
+---
+id: preferences
+title: Preferences
+hide_title: true
+sidebar_label: Preferences
+---
+
+# Preferences
+
+Preferences can be reached via `Unity/Preferences`.
+
+![preferences-location](assets/preferences-location.png)
+
+And it looks like this:
+
+![preferences-overview](assets/preferences-overview.png)
+
+## Debug mode
+
+Enables debug functionality in Unity Atoms, for example Stack Traces for Events. Performance will decrease using this option, but could be switched on for debugging purposes.

website/i18n/en.json

@@ -77,6 +77,10 @@
         "title": "Overview and philosopy",
         "sidebar_label": "Overview and philosopy"
       },
+      "introduction/preferences": {
+        "title": "Preferences",
+        "sidebar_label": "Preferences"
+      },
       "introduction/quick-start": {
         "title": "Quick start",
         "sidebar_label": "Quick start"

website/sidebars.json

@@ -5,7 +5,9 @@
       "introduction/overview",
       "introduction/basic-tutorial",
       "introduction/generator",
-      "introduction/unirx"
+      "introduction/unirx",
+      "introduction/advanced-example",
+      "introduction/preferences"
     ],
     "API Reference": [
       "api/unityatoms",