com.wallstop-studios.dxmessaging 2.1.1 → 2.1.3

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)

package/Runtime/Core/Extensions/MessageBusExtensions.cs

@@ -4,7 +4,7 @@ namespace DxMessaging.Core.Extensions
     using DxMessaging.Core;
     using DxMessaging.Core.MessageBus;
     using DxMessaging.Core.Messages;
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
     using UnityEngine;
 #endif
 
@@ -13,6 +13,13 @@ namespace DxMessaging.Core.Extensions
     /// </summary>
     public static class MessageBusExtensions
     {
+        /// <summary>
+        /// Emits an untargeted message instance through the provided message bus.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IUntargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="message">Message instance to send.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitUntargeted<TMessage>(this IMessageBus messageBus, TMessage message)
             where TMessage : class, IUntargetedMessage
         {
@@ -24,6 +31,13 @@ namespace DxMessaging.Core.Extensions
             message.EmitUntargeted(messageBus);
         }
 
+        /// <summary>
+        /// Emits an untargeted struct message through the provided message bus without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IUntargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="message">Reference to the struct message to send.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitUntargeted<TMessage>(
             this IMessageBus messageBus,
             ref TMessage message
@@ -38,6 +52,21 @@ namespace DxMessaging.Core.Extensions
             message.EmitUntargeted(messageBus);
         }
 
+        /// <summary>
+        /// Emits a targeted message to the specified recipient.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="ITargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Recipient of the message.</param>
+        /// <param name="message">Message instance to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
+        /// <example>
+        /// <code>
+        /// InstanceId playerId = GetPlayerId();
+        /// var change = new HealthChanged(5);
+        /// bus.EmitTargeted(playerId, change);
+        /// </code>
+        /// </example>
         public static void EmitTargeted<TMessage>(
             this IMessageBus messageBus,
             InstanceId target,
@@ -53,6 +82,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitTargeted(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a targeted struct message to the specified recipient without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="ITargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Recipient of the message.</param>
+        /// <param name="message">Reference to the struct message to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitTargeted<TMessage>(
             this IMessageBus messageBus,
             InstanceId target,
@@ -68,6 +105,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitTargeted(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a broadcast message sourced from the specified instance.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IBroadcastMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Originating instance for the broadcast.</param>
+        /// <param name="message">Message instance to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitBroadcast<TMessage>(
             this IMessageBus messageBus,
             InstanceId source,
@@ -83,6 +128,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitBroadcast(source, messageBus);
         }
 
+        /// <summary>
+        /// Emits a broadcast struct message sourced from the specified instance without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IBroadcastMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Originating instance for the broadcast.</param>
+        /// <param name="message">Reference to the struct message to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitBroadcast<TMessage>(
             this IMessageBus messageBus,
             InstanceId source,
@@ -98,7 +151,15 @@ namespace DxMessaging.Core.Extensions
             message.EmitBroadcast(source, messageBus);
         }
 
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
+        /// <summary>
+        /// Emits a targeted message to the specified Unity <see cref="GameObject"/>.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="ITargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Unity object that will receive the message.</param>
+        /// <param name="message">Message instance to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitGameObjectTargeted<TMessage>(
             this IMessageBus messageBus,
             GameObject target,
@@ -114,6 +175,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitGameObjectTargeted(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a targeted struct message to the specified Unity <see cref="GameObject"/> without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="ITargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Unity object that will receive the message.</param>
+        /// <param name="message">Reference to the struct message to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitGameObjectTargeted<TMessage>(
             this IMessageBus messageBus,
             GameObject target,
@@ -129,6 +198,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitGameObjectTargeted(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a targeted message to the specified Unity <see cref="Component"/>.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="ITargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Unity component that will receive the message.</param>
+        /// <param name="message">Message instance to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitComponentTargeted<TMessage>(
             this IMessageBus messageBus,
             Component target,
@@ -144,6 +221,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitComponentTargeted(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a targeted struct message to the specified Unity <see cref="Component"/> without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="ITargetedMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Unity component that will receive the message.</param>
+        /// <param name="message">Reference to the struct message to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitComponentTargeted<TMessage>(
             this IMessageBus messageBus,
             Component target,
@@ -159,6 +244,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitComponentTargeted(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a broadcast message from the specified Unity <see cref="GameObject"/>.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IBroadcastMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Unity object that is broadcasting the message.</param>
+        /// <param name="message">Message instance to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitGameObjectBroadcast<TMessage>(
             this IMessageBus messageBus,
             GameObject source,
@@ -174,6 +267,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitGameObjectBroadcast(source, messageBus);
         }
 
+        /// <summary>
+        /// Emits a broadcast struct message from the specified Unity <see cref="GameObject"/> without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IBroadcastMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Unity object that is broadcasting the message.</param>
+        /// <param name="message">Reference to the struct message to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitGameObjectBroadcast<TMessage>(
             this IMessageBus messageBus,
             GameObject source,
@@ -189,6 +290,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitGameObjectBroadcast(source, messageBus);
         }
 
+        /// <summary>
+        /// Emits a broadcast message from the specified Unity <see cref="Component"/>.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IBroadcastMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Unity component that is broadcasting the message.</param>
+        /// <param name="message">Message instance to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitComponentBroadcast<TMessage>(
             this IMessageBus messageBus,
             Component source,
@@ -204,6 +313,14 @@ namespace DxMessaging.Core.Extensions
             message.EmitComponentBroadcast(source, messageBus);
         }
 
+        /// <summary>
+        /// Emits a broadcast struct message from the specified Unity <see cref="Component"/> without copying the payload.
+        /// </summary>
+        /// <typeparam name="TMessage">Concrete message type implementing <see cref="IBroadcastMessage"/>.</typeparam>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Unity component that is broadcasting the message.</param>
+        /// <param name="message">Reference to the struct message to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitComponentBroadcast<TMessage>(
             this IMessageBus messageBus,
             Component source,
@@ -220,6 +337,17 @@ namespace DxMessaging.Core.Extensions
         }
 #endif
 
+        /// <summary>
+        /// Emits a string payload using the string-message utility channel.
+        /// </summary>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="payload">Message text to broadcast globally.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
+        /// <example>
+        /// <code>
+        /// bus.Emit("PlayerJoined");
+        /// </code>
+        /// </example>
         public static void Emit(this IMessageBus messageBus, string payload)
         {
             if (messageBus == null)
@@ -230,6 +358,13 @@ namespace DxMessaging.Core.Extensions
             payload.Emit(messageBus);
         }
 
+        /// <summary>
+        /// Emits a string payload targeted at the specified instance.
+        /// </summary>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="target">Intended recipient of the payload.</param>
+        /// <param name="payload">Message text to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitAt(this IMessageBus messageBus, InstanceId target, string payload)
         {
             if (messageBus == null)
@@ -240,6 +375,13 @@ namespace DxMessaging.Core.Extensions
             payload.Emit(target, messageBus);
         }
 
+        /// <summary>
+        /// Emits a string payload broadcast from the specified instance.
+        /// </summary>
+        /// <param name="messageBus">Bus that should dispatch the message.</param>
+        /// <param name="source">Origin of the payload.</param>
+        /// <param name="payload">Message text to deliver.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public static void EmitFrom(this IMessageBus messageBus, InstanceId source, string payload)
         {
             if (messageBus == null)

package/Runtime/Core/Extensions/MessageExtensions.cs

@@ -37,7 +37,7 @@ namespace DxMessaging.Core.Extensions
     /// </example>
     public static class MessageExtensions
     {
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
         /// <summary>
         /// Emits a TargetedMessage of the given type.
         /// </summary>
@@ -395,7 +395,7 @@ namespace DxMessaging.Core.Extensions
             resolvedBus.SourcedBroadcast(ref source, ref message);
         }
 
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
         /// <summary>
         /// Emits a BroadcastMessage of the given type.
         /// </summary>

package/Runtime/Core/Helper/MessageCache.cs

@@ -33,6 +33,10 @@ namespace DxMessaging.Core.Helper
             }
 
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            /// <summary>
+            /// Advances the enumerator to the next cached value.
+            /// </summary>
+            /// <returns><c>true</c> if another non-null value exists; otherwise <c>false</c>.</returns>
             public bool MoveNext()
             {
                 List<TValue> values = _cache._values;
@@ -55,12 +59,18 @@ namespace DxMessaging.Core.Helper
             object IEnumerator.Current => Current;
 
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            /// <summary>
+            /// Resets the enumerator to the position before the first element.
+            /// </summary>
             public void Reset()
             {
                 _index = -1;
                 _current = default;
             }
 
+            /// <summary>
+            /// Releases resources held by the enumerator.
+            /// </summary>
             public void Dispose() { }
         }
 
@@ -179,6 +189,12 @@ namespace DxMessaging.Core.Helper
             return GetEnumerator();
         }
 
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal void Clear()
+        {
+            _values.Clear();
+        }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         private void FillToIndex(int index)
         {

package/Runtime/Core/Helper/MessageHelperIndexer.cs

@@ -1,8 +1,80 @@
 namespace DxMessaging.Core.Helper
 {
+    using System;
+    using System.Collections.Generic;
+
     public static class MessageHelperIndexer
     {
+        internal readonly struct MessageHelperIndexerState
+        {
+            internal readonly int _totalMessages;
+
+            internal readonly Dictionary<Type, int> _sequentialIds;
+
+            internal MessageHelperIndexerState(
+                int totalMessages,
+                Dictionary<Type, int> sequentialIds
+            )
+            {
+                _totalMessages = totalMessages;
+                _sequentialIds = sequentialIds;
+            }
+        }
+
+        private static readonly object ResetLock = new();
+        private static readonly HashSet<Type> RegisteredTypes = new();
+        private static readonly Dictionary<Type, Func<int, int>> StateManipulationByType = new();
+
         internal static int TotalMessages = 0;
+
+        internal static void RegisterType(Type messageType, Func<int, int> idProducer)
+        {
+            if (messageType == null)
+            {
+                return;
+            }
+
+            lock (ResetLock)
+            {
+                if (!RegisteredTypes.Add(messageType))
+                {
+                    return;
+                }
+
+                StateManipulationByType[messageType] = idProducer;
+            }
+        }
+
+        internal static MessageHelperIndexerState CaptureState()
+        {
+            lock (ResetLock)
+            {
+                Dictionary<Type, int> snapshot = new(RegisteredTypes.Count);
+                return new MessageHelperIndexerState(TotalMessages, snapshot);
+            }
+        }
+
+        internal static void RestoreState(MessageHelperIndexerState state)
+        {
+            lock (ResetLock)
+            {
+                TotalMessages = state._totalMessages;
+                foreach (KeyValuePair<Type, Func<int, int>> entry in StateManipulationByType)
+                {
+                    Type type = entry.Key;
+                    Func<int, int> manipulationAction = entry.Value;
+                    if (
+                        state._sequentialIds == null
+                        || !state._sequentialIds.TryGetValue(type, out int value)
+                    )
+                    {
+                        value = -1;
+                    }
+
+                    manipulationAction(value);
+                }
+            }
+        }
     }
 
     public static class MessageHelperIndexer<TMessage>
@@ -10,5 +82,10 @@ namespace DxMessaging.Core.Helper
     {
         // ReSharper disable once StaticMemberInGenericType
         internal static int SequentialId = -1;
+
+        static MessageHelperIndexer()
+        {
+            MessageHelperIndexer.RegisterType(typeof(TMessage), value => SequentialId = value);
+        }
     }
 }