com.wallstop-studios.dxmessaging 2.0.0-rc27.3 → 2.0.0

package/Runtime/Core/MessageHandler.cs

@@ -1782,6 +1782,7 @@ namespace DxMessaging.Core
             public long version;
             public long lastSeenVersion = -1;
             public long lastSeenEmissionId;
+            internal int prefreezeInvocationCount;
         }
 
         /// <summary>
@@ -1895,39 +1896,16 @@ namespace DxMessaging.Core
             /// <param name="priority">Priority at which to run the handlers.</param>
             public void HandleUntargeted(ref T message, int priority, long emissionId)
             {
-                // Pre-freeze untargeted post-processors for this emission/priority
-                if (
-                    _untargetedPostProcessingFastHandlers != null
-                    && _untargetedPostProcessingFastHandlers.TryGetValue(priority, out var upf)
-                )
-                {
-                    _ = GetOrAddNewHandlerStack(upf, emissionId);
-                }
-                if (
-                    _untargetedPostProcessingHandlers != null
-                    && _untargetedPostProcessingHandlers.TryGetValue(priority, out var up)
-                )
-                {
-                    _ = GetOrAddNewHandlerStack(up, emissionId);
-                }
-                // Pre-freeze post-processors for this emission/priority
-                if (
-                    _untargetedPostProcessingFastHandlers != null
-                    && _untargetedPostProcessingFastHandlers.TryGetValue(
-                        priority,
-                        out var fastCache
-                    )
-                )
-                {
-                    _ = GetOrAddNewHandlerStack(fastCache, emissionId);
-                }
-                if (
-                    _untargetedPostProcessingHandlers != null
-                    && _untargetedPostProcessingHandlers.TryGetValue(priority, out var cache)
-                )
-                {
-                    _ = GetOrAddNewHandlerStack(cache, emissionId);
-                }
+                PrefreezeHandlersForEmission(
+                    _untargetedPostProcessingFastHandlers,
+                    priority,
+                    emissionId
+                );
+                PrefreezeHandlersForEmission(
+                    _untargetedPostProcessingHandlers,
+                    priority,
+                    emissionId
+                );
 
                 RunFastHandlers(_untargetedFastHandlers, ref message, priority, emissionId);
                 RunHandlers(_untargetedHandlers, ref message, priority, emissionId);
@@ -3535,6 +3513,22 @@ namespace DxMessaging.Core
                 return actionCache.cache;
             }
 
+            private static void PrefreezeHandlersForEmission<THandler>(
+                Dictionary<int, HandlerActionCache<THandler>> handlers,
+                int priority,
+                long emissionId
+            )
+            {
+                if (
+                    handlers != null
+                    && handlers.TryGetValue(priority, out HandlerActionCache<THandler> cache)
+                )
+                {
+                    cache.prefreezeInvocationCount++;
+                    _ = GetOrAddNewHandlerStack(cache, emissionId);
+                }
+            }
+
             private static Action AddHandler<TU>(
                 InstanceId context,
                 ref Dictionary<

package/Runtime/Core/MessageRegistrationToken.cs

@@ -59,6 +59,7 @@ namespace DxMessaging.Core
 
         private readonly Dictionary<MessageRegistrationHandle, Action> _registrations = new();
         private readonly Dictionary<MessageRegistrationHandle, Action> _deregistrations = new();
+        private readonly List<Action> _deregistrationQueue = new();
         internal readonly Dictionary<
             MessageRegistrationHandle,
             MessageRegistrationMetadata
@@ -1878,13 +1879,11 @@ namespace DxMessaging.Core
 
             if (_deregistrations is { Count: > 0 })
             {
-                Dictionary<
-                    MessageRegistrationHandle,
-                    Action
-                >.ValueCollection.Enumerator enumerator = _deregistrations.Values.GetEnumerator();
-                while (enumerator.MoveNext())
+                _deregistrationQueue.Clear();
+                _deregistrationQueue.AddRange(_deregistrations.Values);
+                foreach (Action deregistration in _deregistrationQueue)
                 {
-                    enumerator.Current();
+                    deregistration?.Invoke();
                 }
             }
 
@@ -1905,15 +1904,13 @@ namespace DxMessaging.Core
         /// </example>
         public void UnregisterAll()
         {
-            if (_enabled && _deregistrations is { Count: > 0 })
+            if (_deregistrations is { Count: > 0 })
             {
-                Dictionary<
-                    MessageRegistrationHandle,
-                    Action
-                >.ValueCollection.Enumerator enumerator = _deregistrations.Values.GetEnumerator();
-                while (enumerator.MoveNext())
+                _deregistrationQueue.Clear();
+                _deregistrationQueue.AddRange(_deregistrations.Values);
+                foreach (Action deregistration in _deregistrationQueue)
                 {
-                    enumerator.Current();
+                    deregistration?.Invoke();
                 }
             }
 
@@ -1934,16 +1931,10 @@ namespace DxMessaging.Core
         /// </example>
         public void RemoveRegistration(MessageRegistrationHandle handle)
         {
-            if (
-                _deregistrations != null
-                && _deregistrations.TryGetValue(handle, out Action deregistrationAction)
-            )
+            if (_deregistrations?.Remove(handle, out Action deregistrationAction) == true)
             {
-                deregistrationAction();
-                _ = _deregistrations.Remove(handle);
+                deregistrationAction?.Invoke();
             }
-
-            _ = _registrations?.Remove(handle);
         }
 
         /// <summary>

package/Runtime/Unity/MessageAwareComponent.cs

@@ -124,8 +124,14 @@ namespace DxMessaging.Unity
         /// </summary>
         protected virtual void OnDestroy()
         {
+            if (_messagingComponent != null)
+            {
+                _messagingComponent.Release(this);
+            }
+
             _messageRegistrationToken?.Disable();
             _messageRegistrationToken = null;
+            _messagingComponent = null;
         }
 
         /// <summary>

package/Runtime/Unity/MessagingComponent.cs

@@ -73,6 +73,30 @@ namespace DxMessaging.Unity
             return createdToken;
         }
 
+        /// <summary>
+        /// Releases the registration token previously created for <paramref name="listener"/>.
+        /// </summary>
+        /// <param name="listener">Listener whose token should be released.</param>
+        /// <remarks>
+        /// Invokes <see cref="MessageRegistrationToken.Disable"/> and removes the listener from the internal cache.
+        /// Safe to call multiple times.
+        /// </remarks>
+        public bool Release(MonoBehaviour listener)
+        {
+            if (listener is null)
+            {
+                return false;
+            }
+
+            if (_registeredListeners.Remove(listener, out MessageRegistrationToken token))
+            {
+                token?.Disable();
+                return true;
+            }
+
+            return false;
+        }
+
         /// <summary>
         /// Ensures the underlying <see cref="Core.MessageHandler"/> exists.
         /// </summary>

package/Samples~/Mini Combat/README.md

@@ -1,16 +1,79 @@
 # Mini Combat Sample
 
-> **What You'll Learn**: This sample demonstrates a simple combat system using DxMessaging to show how components communicate through messages. Perfect for beginners learning the messaging system!
+> **Perfect for:** First-time users who want to see messaging in action with a working combat example
 
-## Overview
+## What You'll Learn in 10 Minutes
 
-This mini-sample showcases a basic combat loop using DxMessaging with Unity-friendly APIs. You'll see how different game objects (Player, Enemy, UI) communicate without direct references to each other.
+**Stop reading documentation and start seeing it work!** This sample shows:
 
-### Key Concepts Demonstrated:
+1. How Player heals without UI knowing about Player (**zero coupling**)
+2. How Enemy broadcasts damage without knowing who cares (**observer pattern**)
+3. How settings changes update everything automatically (**global events**)
 
-- **Untargeted Messages**: Global messages anyone can listen to (like game settings)
-- **Targeted Messages**: Messages sent to a specific component (like healing a player)
-- **Broadcast Messages**: Messages announced to all listeners (like damage events)
+**No prior messaging experience needed** - this sample walks you through everything.
+
+---
+
+## Why This Sample Matters
+
+### Before DxMessaging:
+
+```csharp
+public class Player {
+    [SerializeField] private UI ui;          // Coupling!
+    [SerializeField] private AudioManager audio; // More coupling!
+
+    void Heal(int amount) {
+        health += amount;
+        ui.UpdateHealth(health);     // Manual call
+        audio.PlayHealSound();        // Manual call
+    }
+}
+```
+
+#### Every new system = another SerializeField + another manual call.
+
+##### With DxMessaging:
+
+```csharp
+public class Player : MessageAwareComponent {
+    void Heal(int amount) {
+        health += amount;
+        new PlayerHealed(amount).EmitBroadcast(this);
+        // Done! UI, audio, analytics all react automatically.
+    }
+}
+```
+
+###### Zero coupling. Zero manual wiring. That's the power of messaging.
+
+---
+
+## Key Concepts (3 Message Types)
+
+### 1. Untargeted - "Everyone, listen up!"
+
+**Example:** Game settings changed
+
+- Like a stadium announcement - everyone hears it
+- No specific target
+- Perfect for: settings, pause, scene transitions
+
+### 2. Targeted - "Hey YOU, do this!"
+
+**Example:** Heal this specific player
+
+- Like mailing a letter to one address
+- Only the target receives it
+- Perfect for: commands, direct actions
+
+### 3. Broadcast - "I did something!"
+
+**Example:** Enemy took damage
+
+- Like ringing a bell - anyone nearby can hear
+- Source announces, observers react
+- Perfect for: events, notifications, analytics
 
 ---
 
@@ -28,25 +91,22 @@ Here's what each script does:
 
 ---
 
-## Quick Start Guide
+## Quick Start Guide (2 Minutes to Working Demo)
 
-### Method 1: Import from Package Manager (Recommended)
+### Import & Run (Fastest Way)
 
-1. **Open Package Manager**:
-   - Window → Package Manager
+#### Want to see it work immediately?
 
-1. **Find DxMessaging**:
-   - Look for "DxMessaging" in the package list
-   - Click on it to select
+1. **Open Package Manager**: Window → Package Manager
+2. **Find DxMessaging** in the package list
+3. **Scroll to Samples** section → Find "Mini Combat" → Click **Import**
+4. **Navigate to** Assets/Samples/DxMessaging/.../Mini Combat/
+5. **Open the scene**
+6. **Press Play** 🎮
 
-1. **Import the Sample**:
-   - In the Package Manager details view, scroll down to find the "Samples" section
-   - Find "Mini Combat" and click **Import**
-   - The sample files will be imported into your Assets/Samples folder
+**That's it!** Watch the Console logs as messages flow.
 
-1. **Open the Scene**:
-   - Navigate to Assets/Samples/DxMessaging/.../Mini Combat/
-   - Open the sample scene or create a new scene and follow Step 1 below
+**Pro tip:** Enable diagnostics in the Inspector (MessagingComponent → Enable Diagnostics) to see message traffic in real-time.
 
 ### Method 2: Manual Setup in Your Scene
 

package/Samples~/Mini Combat/Walkthrough.md

@@ -1,6 +1,28 @@
 # Mini Combat Walkthrough
 
-> **Deep Dive**: This walkthrough explains the implementation details and shows how all the sample scripts work together at runtime. Great for understanding the "why" behind the code!
+> **Deep Dive**: Ready to understand HOW it works? This walkthrough explains every line of code and shows the complete message flow.
+
+## Who This Is For
+
+- ✅ **You've imported and run the sample** - now you want to understand it
+- ✅ **You want to build your own** - need to see the patterns in action
+- ✅ **You're debugging something** - need to understand the flow
+
+**Haven't run the sample yet?** Go back to [the sample README](README.md) and press Play first. Come back when you've seen it work.
+
+---
+
+## What You'll Understand By The End
+
+After reading this walkthrough, you'll know:
+
+1. **Why each message type was chosen** - the reasoning behind Untargeted vs Targeted vs Broadcast
+2. **How the code flows** - step-by-step from Boot.cs through every script
+3. **Common patterns** - Observer, Broadcaster, Orchestrator, and more
+4. **Debugging strategies** - how to find and fix issues
+5. **How to extend it** - add your own messages and handlers
+
+**Estimated time:** 20-30 minutes for thorough understanding
 
 ---
 

package/Samples~/UI Buttons + Inspector/README.md

@@ -1,21 +1,64 @@
-# UI Buttons + Inspector (Sample)
+# UI Buttons + Inspector Sample
 
-Make a Unity UI Button send a message with a single OnClick hook — no plumbing, no scene-wide singletons, and easy to understand even if you’re new to event systems.
+> **Perfect for:** Seeing DxMessaging work with Unity UI in 60 seconds
 
-## What You’ll Learn
+## What You'll Learn (No Code Required!)
 
-- How to wire a UI Button to emit a DxMessaging message from the Inspector.
-- How to observe messages in the Console with a tiny listener component.
-- How to turn on diagnostics to see message traffic while you click.
+**Stop writing button click handlers!** This sample shows you how to:
 
-## Import The Sample (60 seconds)
+1. **Wire UI Buttons to messages** - directly from the Inspector (drag & drop)
+2. **See messages flow in real-time** - watch the Console as you click
+3. **Enable diagnostics** - see every message with timestamps and payloads
 
-1. Open `Window > Package Manager` in Unity.
-1. Select `com.wallstop-studios.dxmessaging`.
-1. In Samples, import “UI Buttons + Inspector”.
-1. Open the sample scene (created under your project’s `Assets/Samples/...`).
+**Why this matters:** You can add new systems (analytics, audio, achievements) that react to button clicks WITHOUT touching existing code.
 
-That’s it — the scene includes everything you need to click and see messages.
+---
+
+## The Power Move
+
+### Before DxMessaging:
+
+```csharp
+public class PlayButton : MonoBehaviour {
+    [SerializeField] private GameManager gameManager;   // Coupling
+    [SerializeField] private AudioManager audio;        // Coupling
+    [SerializeField] private Analytics analytics;       // Coupling
+
+    public void OnClick() {
+        gameManager.StartGame();     // Manual call
+        audio.PlayClickSound();       // Manual call
+        analytics.LogButtonClick();   // Manual call
+    }
+}
+```
+
+#### Every new system = update PlayButton script. Exhausting.
+
+##### With DxMessaging:
+
+```csharp
+public class PlayButton : MonoBehaviour {
+    public void OnClick() {
+        new ButtonClicked("Play").Emit();
+        // Done! Everything reacts automatically.
+    }
+}
+```
+
+###### GameManager, Audio, and Analytics listen independently. Zero coupling.
+
+## Import & Run (30 Seconds)
+
+### Want to see it immediately?
+
+1. **Window → Package Manager**
+2. **Find DxMessaging** → Scroll to **Samples**
+3. **"UI Buttons + Inspector"** → Click **Import**
+4. **Navigate to** Assets/Samples/.../UI Buttons + Inspector/
+5. **Open the scene** → **Press Play** 🎮
+6. **Click the buttons** → Watch Console logs
+
+**Done!** You're seeing DxMessaging in action.
 
 ## Click-To-Message: The Quick Path
 

package/Tests/Runtime/Core/MessagingComponentLifecycleTests.cs

@@ -0,0 +1,89 @@
+namespace DxMessaging.Tests.Runtime.Core
+{
+    using System.Collections;
+    using DxMessaging.Core;
+    using DxMessaging.Tests.Runtime.Scripts.Components;
+    using DxMessaging.Unity;
+    using NUnit.Framework;
+    using UnityEngine;
+    using UnityEngine.TestTools;
+
+    public sealed class MessagingComponentLifecycleTests : MessagingTestBase
+    {
+        [UnityTest]
+        public IEnumerator ReleasesListenerOnDestroy()
+        {
+            GameObject go = new(
+                "Lifecycle",
+                typeof(MessagingComponent),
+                typeof(SimpleMessageAwareComponent)
+            );
+            _spawned.Add(go);
+
+            MessagingComponent messaging = go.GetComponent<MessagingComponent>();
+            SimpleMessageAwareComponent listener = go.GetComponent<SimpleMessageAwareComponent>();
+
+            yield return null;
+
+            Assert.AreEqual(
+                1,
+                messaging._registeredListeners.Count,
+                "Expected initial listener registration."
+            );
+
+            Object.Destroy(listener);
+            yield return null;
+
+            Assert.AreEqual(
+                0,
+                messaging._registeredListeners.Count,
+                "Listener dictionary should be cleared after destroy."
+            );
+
+            SimpleMessageAwareComponent replacement =
+                go.AddComponent<SimpleMessageAwareComponent>();
+            yield return null;
+
+            Assert.AreEqual(
+                1,
+                messaging._registeredListeners.Count,
+                "Replacement listener should be tracked."
+            );
+            Assert.IsTrue(messaging._registeredListeners.ContainsKey(replacement));
+        }
+
+        [UnityTest]
+        public IEnumerator ManualReleaseRemovesListenerAndDisablesToken()
+        {
+            GameObject go = new(
+                "ManualRelease",
+                typeof(MessagingComponent),
+                typeof(ManualListenerComponent)
+            );
+            _spawned.Add(go);
+
+            MessagingComponent messaging = go.GetComponent<MessagingComponent>();
+            ManualListenerComponent listener = go.GetComponent<ManualListenerComponent>();
+
+            MessageRegistrationToken token = listener.RequestToken(messaging);
+            Assert.AreEqual(
+                1,
+                messaging._registeredListeners.Count,
+                "Token request should register listener."
+            );
+
+            token.Enable();
+            Assert.IsTrue(token.Enabled, "Token should enable successfully.");
+
+            messaging.Release(listener);
+            yield return null;
+
+            Assert.AreEqual(
+                0,
+                messaging._registeredListeners.Count,
+                "Manual release should remove listener."
+            );
+            Assert.IsFalse(token.Enabled, "Released token should be disabled.");
+        }
+    }
+}

package/Tests/Runtime/Core/MessagingComponentLifecycleTests.cs.meta

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

package/Tests/Runtime/Core/ReflexiveMessageWarningTests.cs

@@ -0,0 +1,86 @@
+namespace DxMessaging.Tests.Runtime.Core
+{
+    using System;
+    using System.Collections;
+    using System.Collections.Generic;
+    using System.Linq;
+    using DxMessaging.Core;
+    using DxMessaging.Core.MessageBus;
+    using DxMessaging.Core.Messages;
+    using DxMessaging.Tests.Runtime.Scripts.Components;
+    using NUnit.Framework;
+    using UnityEngine;
+    using UnityEngine.TestTools;
+
+    public sealed class ReflexiveMessageWarningTests : MessagingTestBase
+    {
+        [UnityTest]
+        public IEnumerator LogsWarningOncePerBus()
+        {
+            List<(LogLevel level, string message)> logs = new();
+            var previousLogFunction = MessagingDebug.LogFunction;
+            try
+            {
+                MessagingDebug.LogFunction = (level, message) => logs.Add((level, message));
+                MessagingDebug.enabled = true;
+                logs.Clear();
+
+                GameObject go = new("ReflexiveReceiver", typeof(ReflexiveReceiverComponent));
+                _spawned.Add(go);
+                ReflexiveReceiverComponent receiver = go.GetComponent<ReflexiveReceiverComponent>();
+
+                MessageBus bus = new();
+                ReflexiveMessage message = new("OnReflexive", ReflexiveSendMode.Flat);
+
+                int warningsBefore = CountWarnings(logs);
+                InstanceId target = receiver;
+                bus.TargetedBroadcast(ref target, ref message);
+                Assert.AreEqual(1, receiver.InvocationCount);
+                int warningsAfter = CountWarnings(logs);
+                Assert.Greater(
+                    warningsAfter,
+                    warningsBefore,
+                    "First reflexive dispatch should log a warning."
+                );
+                StringAssert.Contains("ReflexiveMessage", logs[^1].message);
+
+                warningsBefore = warningsAfter;
+                target = receiver;
+                bus.TargetedBroadcast(ref target, ref message);
+                Assert.AreEqual(2, receiver.InvocationCount);
+                warningsAfter = CountWarnings(logs);
+                Assert.AreEqual(
+                    warningsBefore,
+                    warningsAfter,
+                    "Second dispatch on the same bus should not emit additional warnings."
+                );
+
+                MessageBus secondBus = new();
+                warningsBefore = warningsAfter;
+                target = receiver;
+                secondBus.TargetedBroadcast(ref target, ref message);
+                Assert.AreEqual(3, receiver.InvocationCount);
+                warningsAfter = CountWarnings(logs);
+                Assert.AreEqual(
+                    warningsBefore + 1,
+                    warningsAfter,
+                    "A new bus should emit its own warning."
+                );
+            }
+            finally
+            {
+                MessagingDebug.LogFunction = previousLogFunction;
+            }
+
+            yield break;
+        }
+
+        private static int CountWarnings(List<(LogLevel level, string message)> logs)
+        {
+            return logs.Count(entry =>
+                entry.level == LogLevel.Warn
+                && entry.message.IndexOf("ReflexiveMessage dispatch", StringComparison.Ordinal) >= 0
+            );
+        }
+    }
+}

package/Tests/Runtime/Core/ReflexiveMessageWarningTests.cs.meta

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

package/Tests/Runtime/Core/SourceGeneratorNestedTests.cs

@@ -39,7 +39,7 @@ namespace DxMessaging.Tests.Runtime.Core
             public readonly string c;
 
             [DxOptionalParameter(Expression = "null")]
-            public readonly string? d;
+            public readonly string d;
         }
     }