com.wallstop-studios.dxmessaging 2.1.2 → 2.1.4

package/Editor/Settings/DxMessagingSettingsProvider.cs

@@ -2,6 +2,7 @@ namespace DxMessaging.Editor.Settings
 {
 #if UNITY_EDITOR
     using System.Collections.Generic;
+    using Core.MessageBus;
     using UnityEditor;
     using UnityEngine;
 
@@ -21,6 +22,11 @@ namespace DxMessaging.Editor.Settings
         )
             : base(path, scope) { }
 
+        /// <summary>
+        /// Initializes the serialized settings backing store when the settings page is opened.
+        /// </summary>
+        /// <param name="searchContext">Search text provided by the Project Settings window.</param>
+        /// <param name="rootElement">Root visual element for UI Toolkit-based providers.</param>
         public override void OnActivate(
             string searchContext,
             UnityEngine.UIElements.VisualElement rootElement
@@ -29,28 +35,60 @@ namespace DxMessaging.Editor.Settings
             _messagingSettings = DxMessagingSettings.GetSerializedSettings();
         }
 
+        /// <summary>
+        /// Renders the DxMessaging settings UI and persists any modifications.
+        /// </summary>
+        /// <param name="searchContext">Search text provided by the Project Settings window.</param>
         public override void OnGUI(string searchContext)
         {
-            EditorGUILayout.PropertyField(
-                _messagingSettings.FindProperty(
-                    nameof(DxMessagingSettings._enableDiagnosticsInEditor)
-                ),
-                new GUIContent("Global Diagnostics Mode")
+            SerializedProperty targetsProp = _messagingSettings.FindProperty(
+                nameof(DxMessagingSettings._diagnosticsTargets)
             );
+            DiagnosticsTarget currentTargets = (DiagnosticsTarget)targetsProp.enumValueFlag;
+            DiagnosticsTarget updatedTargets = (DiagnosticsTarget)
+                EditorGUILayout.EnumFlagsField(
+                    new GUIContent(
+                        "Diagnostics Targets",
+                        "Select where global diagnostics should be enabled by default. Combine flags for multiple targets."
+                    ),
+                    currentTargets
+                );
+            if (updatedTargets != currentTargets)
+            {
+                targetsProp.enumValueFlag = (int)updatedTargets;
+            }
             EditorGUILayout.PropertyField(
                 _messagingSettings.FindProperty(nameof(DxMessagingSettings._messageBufferSize)),
-                new GUIContent("Message Buffer Size")
+                new GUIContent(
+                    "Message Buffer Size",
+                    "Number of emissions kept per bus/token when diagnostics mode is active."
+                )
+            );
+            EditorGUILayout.PropertyField(
+                _messagingSettings.FindProperty(
+                    nameof(DxMessagingSettings._suppressDomainReloadWarning)
+                ),
+                new GUIContent(
+                    "Suppress Domain Reload Warning",
+                    "Disable the warning shown when Enter Play Mode Options skips domain reload; DxMessaging still resets its statics."
+                )
             );
 
             _messagingSettings.ApplyModifiedProperties();
         }
 
         [SettingsProvider]
+        /// <summary>
+        /// Factory used by Unity to register the DxMessaging project settings page.
+        /// </summary>
+        /// <returns>Configured settings provider instance.</returns>
         public static SettingsProvider CreateDxMessagingSettingsProvider()
         {
             DxMessagingSettingsProvider provider = new("Project/DxMessaging")
             {
-                keywords = new HashSet<string>(new[] { "DxMessaging", "Diagnostics" }),
+                keywords = new HashSet<string>(
+                    new[] { "DxMessaging", "Diagnostics", "MessageBus", "Targets" }
+                ),
             };
 
             return provider;

package/README.md

@@ -52,7 +52,7 @@ Need install instructions for Git URLs, scoped registries, or tarballs? Jump to
 
 1. **Untargeted** - "Everyone listen!" (pause game, settings changed)
 1. **Targeted** - "Tell Player to heal" (commands to specific entities)
-1. **Broadcast** - "Enemy took damage" (events others can observe)
+1. **Broadcast** - "I took damage" (things that happen to _you_ that others can observe)
 
 **One line:** It's the event system Unity should have shipped with - type-safe, leak-proof, and actually debuggable. 🚀
 

package/Runtime/Core/Attributes/DxOptionalParameterAttribute.cs

@@ -31,30 +31,82 @@ namespace DxMessaging.Core.Attributes
         /// Optional default value overloads. Values must be compile-time constants and
         /// will be validated by the source generator against the field type.
         /// </summary>
+        /// <summary>
+        /// Initializes the attribute with the specified default boolean value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(bool value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default character value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(char value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default string value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(string value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default byte value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(byte value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default signed byte value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(sbyte value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default short value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(short value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default unsigned short value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(ushort value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default integer value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(int value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default unsigned integer value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(uint value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default long value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(long value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default unsigned long value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(ulong value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default single-precision floating point value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(float value) { }
 
+        /// <summary>
+        /// Initializes the attribute with the specified default double-precision floating point value.
+        /// </summary>
+        /// <param name="value">Default value used when the constructor parameter is omitted.</param>
         public DxOptionalParameterAttribute(double value) { }
 
         /// <summary>

package/Runtime/Core/DataStructure/CyclicBuffer.cs

@@ -29,6 +29,10 @@ namespace DxMessaging.Core.DataStructure
                 _current = default;
             }
 
+            /// <summary>
+            /// Advances the enumerator to the next element in chronological order.
+            /// </summary>
+            /// <returns><c>true</c> when another element is available; otherwise <c>false</c>.</returns>
             public bool MoveNext()
             {
                 if (++_index < _buffer.Count)
@@ -41,16 +45,25 @@ namespace DxMessaging.Core.DataStructure
                 return false;
             }
 
+            /// <summary>
+            /// Gets the element at the current enumerator position.
+            /// </summary>
             public T Current => _current;
 
             object IEnumerator.Current => Current;
 
+            /// <summary>
+            /// Resets the enumerator to its initial position before the first element.
+            /// </summary>
             public void Reset()
             {
                 _index = -1;
                 _current = default;
             }
 
+            /// <summary>
+            /// Releases resources held by the enumerator.
+            /// </summary>
             public void Dispose() { }
         }
 
@@ -107,6 +120,9 @@ namespace DxMessaging.Core.DataStructure
             }
         }
 
+        /// <summary>
+        /// Creates an enumerator that iterates from the oldest element to the most recently added.
+        /// </summary>
         public CyclicBufferEnumerator GetEnumerator()
         {
             return new CyclicBufferEnumerator(this);

package/Runtime/Core/Diagnostics/MessageEmissionData.cs

@@ -12,7 +12,7 @@ namespace DxMessaging.Core.Diagnostics
     /// Captures a snapshot of a message emission for diagnostics.
     /// </summary>
     /// <remarks>
-    /// When diagnostics are enabled (see <see cref="MessageBus.IMessageBus.GlobalDiagnosticsMode"/>),
+    /// When diagnostics are enabled (see <see cref="MessageBus.IMessageBus.GlobalDiagnosticsTargets"/>),
     /// the bus and tokens record recent emissions in ring buffers along with a trimmed stack trace
     /// that excludes DxMessaging internals for easier debugging.
     ///

package/Runtime/Core/Diagnostics/MessageRegistrationType.cs

@@ -1,21 +1,83 @@
 namespace DxMessaging.Core.Diagnostics
 {
+    /// <summary>
+    /// Categories used when recording registrations in diagnostics logs.
+    /// </summary>
     public enum MessageRegistrationType
     {
+        /// <summary>
+        /// No registration type was captured.
+        /// </summary>
         None = 0,
+
+        /// <summary>
+        /// A targeted handler that listens for messages addressed to a specific <see cref="Core.InstanceId"/>.
+        /// </summary>
         Targeted = 1,
+
+        /// <summary>
+        /// A global untargeted handler that receives all messages of a given type.
+        /// </summary>
         Untargeted = 2,
+
+        /// <summary>
+        /// A broadcast handler that listens for messages emitted from a source <see cref="Core.InstanceId"/>.
+        /// </summary>
         Broadcast = 3,
+
+        /// <summary>
+        /// A broadcast post-processor that runs after broadcast handlers complete.
+        /// </summary>
         BroadcastPostProcessor = 4,
+
+        /// <summary>
+        /// A targeted post-processor that runs after targeted handlers complete.
+        /// </summary>
         TargetedPostProcessor = 5,
+
+        /// <summary>
+        /// A targeted handler that ignores the concrete target during invocation.
+        /// </summary>
         TargetedWithoutTargeting = 6,
+
+        /// <summary>
+        /// A post-processor for handlers registered without a concrete target.
+        /// </summary>
         TargetedWithoutTargetingPostProcessor = 7,
+
+        /// <summary>
+        /// A broadcast handler registered without an explicit source identity.
+        /// </summary>
         BroadcastWithoutSource = 8,
+
+        /// <summary>
+        /// A post-processor for broadcast handlers registered without an explicit source.
+        /// </summary>
         BroadcastWithoutSourcePostProcessor = 9,
+
+        /// <summary>
+        /// A post-processor that runs after untargeted handlers complete.
+        /// </summary>
         UntargetedPostProcessor = 10,
+
+        /// <summary>
+        /// A global catch-all registration that observes every message.
+        /// </summary>
         GlobalAcceptAll = 11,
+
+        /// <summary>
+        /// An untargeted interceptor that can mutate or cancel global messages.
+        /// </summary>
         UntargetedInterceptor = 12,
+
+        /// <summary>
+        /// A targeted interceptor that can mutate or cancel messages bound to a specific recipient.
+        /// </summary>
         TargetedInterceptor = 13,
+
+        /// <summary>
+        /// A broadcast interceptor that can mutate or cancel messages emitted from a source.
+        /// </summary>
         BroadcastInterceptor = 14,
     }
 }

package/Runtime/Core/DxMessagingStaticState.cs

@@ -0,0 +1,108 @@
+namespace DxMessaging.Core
+{
+    using System;
+    using Helper;
+    using MessageBus;
+
+    /// <summary>
+    /// Centralised utility for resetting DxMessaging static state when Domain Reload is disabled.
+    /// </summary>
+    public static class DxMessagingStaticState
+    {
+        private static readonly object ResetLock = new object();
+        private static readonly BaselineState Baseline;
+
+        static DxMessagingStaticState()
+        {
+            Baseline = CaptureBaseline();
+        }
+
+        /// <summary>
+        /// Resets all static variables in DxMessaging to their default values.
+        /// </summary>
+        public static void Reset()
+        {
+            lock (ResetLock)
+            {
+                MessagingDebug.enabled = Baseline.MessagingDebugEnabled;
+                MessagingDebug.LogFunction = Baseline.MessagingDebugLogFunction;
+
+                IMessageBus.GlobalDiagnosticsTargets = Baseline.GlobalDiagnosticsTargets;
+                IMessageBus.GlobalMessageBufferSize = Baseline.GlobalMessageBufferSize;
+                IMessageBus.GlobalSequentialIndex = Baseline.GlobalSequentialIndex;
+
+                MessageHelperIndexer.RestoreState(Baseline.HelperState);
+
+                MessageRegistrationHandle.SetIdSeed(Baseline.MessageRegistrationHandleSeed);
+                MessageRegistrationBuilder.SetSyntheticOwnerCounter(Baseline.SyntheticOwnerCounter);
+
+                MessageHandler.ResetStatics();
+                IMessageBus.GlobalSequentialIndex = Baseline.GlobalSequentialIndex;
+            }
+        }
+
+        private static BaselineState CaptureBaseline()
+        {
+            bool messagingDebugEnabled = MessagingDebug.enabled;
+            Action<LogLevel, string> messagingDebugLogFunction = MessagingDebug.LogFunction;
+            DiagnosticsTarget globalDiagnosticsTargets = IMessageBus.GlobalDiagnosticsTargets;
+            int globalMessageBufferSize = IMessageBus.GlobalMessageBufferSize;
+            int globalSequentialIndex = IMessageBus.GlobalSequentialIndex;
+            long messageRegistrationHandleSeed = MessageRegistrationHandle.GetCurrentIdSeed();
+            int syntheticOwnerCounter = MessageRegistrationBuilder.GetSyntheticOwnerCounter();
+            MessageHelperIndexer.MessageHelperIndexerState helperState =
+                MessageHelperIndexer.CaptureState();
+
+            return new BaselineState(
+                messagingDebugEnabled,
+                messagingDebugLogFunction,
+                globalDiagnosticsTargets,
+                globalMessageBufferSize,
+                globalSequentialIndex,
+                messageRegistrationHandleSeed,
+                syntheticOwnerCounter,
+                helperState
+            );
+        }
+
+        private sealed class BaselineState
+        {
+            internal BaselineState(
+                bool messagingDebugEnabled,
+                Action<LogLevel, string> messagingDebugLogFunction,
+                DiagnosticsTarget globalDiagnosticsTargets,
+                int globalMessageBufferSize,
+                int globalSequentialIndex,
+                long messageRegistrationHandleSeed,
+                int syntheticOwnerCounter,
+                MessageHelperIndexer.MessageHelperIndexerState helperState
+            )
+            {
+                MessagingDebugEnabled = messagingDebugEnabled;
+                MessagingDebugLogFunction = messagingDebugLogFunction;
+                GlobalDiagnosticsTargets = globalDiagnosticsTargets;
+                GlobalMessageBufferSize = globalMessageBufferSize;
+                GlobalSequentialIndex = globalSequentialIndex;
+                MessageRegistrationHandleSeed = messageRegistrationHandleSeed;
+                SyntheticOwnerCounter = syntheticOwnerCounter;
+                HelperState = helperState;
+            }
+
+            internal bool MessagingDebugEnabled { get; }
+
+            internal Action<LogLevel, string> MessagingDebugLogFunction { get; }
+
+            internal DiagnosticsTarget GlobalDiagnosticsTargets { get; }
+
+            internal int GlobalMessageBufferSize { get; }
+
+            internal int GlobalSequentialIndex { get; }
+
+            internal long MessageRegistrationHandleSeed { get; }
+
+            internal int SyntheticOwnerCounter { get; }
+
+            internal MessageHelperIndexer.MessageHelperIndexerState HelperState { get; }
+        }
+    }
+}

package/Runtime/Core/DxMessagingStaticState.cs.meta

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

package/Runtime/Core/Extensions/IListExtensions.cs

@@ -5,6 +5,22 @@ namespace DxMessaging.Core.Extensions
 
     internal static class IListExtensions
     {
+        /// <summary>
+        /// Rotates the list contents in-place by the specified offset.
+        /// </summary>
+        /// <typeparam name="T">Element type held by the list.</typeparam>
+        /// <param name="list">List to rotate. Must have at least two elements to perform work.</param>
+        /// <param name="amount">
+        /// Number of positions to rotate. Positive values move elements toward the end (wrapping),
+        /// negative values move them toward the start.
+        /// </param>
+        /// <example>
+        /// <code>
+        /// var numbers = new List&lt;int&gt; { 1, 2, 3, 4 };
+        /// numbers.Shift(1); // numbers becomes { 4, 1, 2, 3 }
+        /// numbers.Shift(-2); // numbers becomes { 2, 3, 4, 1 }
+        /// </code>
+        /// </example>
         public static void Shift<T>(this IList<T> list, int amount)
         {
             if (list is not { Count: > 1 })
@@ -26,6 +42,14 @@ namespace DxMessaging.Core.Extensions
             Reverse(list, amount, count - 1);
         }
 
+        /// <summary>
+        /// Reverses the order of elements in-place within the inclusive range.
+        /// </summary>
+        /// <typeparam name="T">Element type held by the list.</typeparam>
+        /// <param name="list">List whose segment should be reversed.</param>
+        /// <param name="start">Zero-based index of the first element in the range.</param>
+        /// <param name="end">Zero-based index of the last element in the range.</param>
+        /// <exception cref="ArgumentException">Thrown when the start or end value is outside the list bounds.</exception>
         public static void Reverse<T>(this IList<T> list, int start, int end)
         {
             if (start < 0 || list.Count <= start)