com.wallstop-studios.dxmessaging 2.1.2 → 2.1.3

package/Runtime/Unity/MessagingComponent.cs

@@ -3,6 +3,7 @@ namespace DxMessaging.Unity
 {
     using System;
     using System.Collections.Generic;
+    using System.Linq;
     using Core;
     using Core.MessageBus;
     using UnityEngine;
@@ -326,6 +327,98 @@ namespace DxMessaging.Unity
 
             return null;
         }
+
+#if UNITY_EDITOR
+        [ContextMenu("DxMessaging/Dump Registrations")]
+        private void ContextDumpRegistrations()
+        {
+            DumpRegistrations();
+        }
+
+        internal void DumpRegistrations()
+        {
+            if (_registeredListeners.Count == 0)
+            {
+                Debug.Log($"[DxMessaging] {name} has no registered listeners.");
+                return;
+            }
+
+            foreach (
+                KeyValuePair<MonoBehaviour, MessageRegistrationToken> pair in _registeredListeners
+            )
+            {
+                MonoBehaviour listener = pair.Key;
+                MessageRegistrationToken token = pair.Value;
+                Debug.Log(
+                    $"[DxMessaging] Listener '{listener}' (Enabled: {token.Enabled}, Diagnostic: {token.DiagnosticMode}) "
+                        + $"with {token._metadata.Count} registrations on '{name}'."
+                );
+            }
+        }
+
+        [ContextMenu("DxMessaging/Reset Runtime State")]
+        private void ContextResetRuntimeState()
+        {
+            if (EditorResetRuntimeState())
+            {
+                Debug.Log($"[DxMessaging] Cleared runtime state for '{name}'.");
+            }
+            else
+            {
+                Debug.Log($"[DxMessaging] No runtime state to clear on '{name}'.");
+            }
+        }
+
+        internal bool EditorResetRuntimeState()
+        {
+            bool cleared = false;
+
+            if (_registeredListeners.Count > 0)
+            {
+                foreach (MessageRegistrationToken token in _registeredListeners.Values.ToArray())
+                {
+                    try
+                    {
+                        if (token.Enabled)
+                        {
+                            token.Disable();
+                        }
+
+                        token.Dispose();
+                    }
+                    catch (Exception exception)
+                    {
+                        Debug.LogWarning(
+                            $"[DxMessaging] Disposing stale token on {name} failed. {exception}"
+                        );
+                    }
+                }
+
+                _registeredListeners.Clear();
+                cleared = true;
+            }
+
+            if (_messageHandler != null)
+            {
+                _messageHandler = null;
+                cleared = true;
+            }
+
+            if (_messageBusOverride != null)
+            {
+                _messageBusOverride = null;
+                cleared = true;
+            }
+
+            if (_messageBusProvider != null)
+            {
+                _messageBusProvider = null;
+                cleared = true;
+            }
+
+            return cleared;
+        }
+#endif
     }
 }
 #endif

package/Samples~/DI/README.md

@@ -13,18 +13,18 @@ These snippets illustrate how to consume `IMessageRegistrationBuilder` inside co
 
 Each sample shows:
 
-- Registering `IMessageRegistrationBuilder` via the provided shim under `Runtime/Unity/Integrations/`.
+- Registering `IMessageRegistrationBuilder` via the provided shim under [Runtime/Unity/Integrations](../../Runtime/Unity/Integrations/).
 - Constructing a `MessageRegistrationLease` in a container-managed service.
 - Activating/deactivating the lease using the container lifecycle.
 
 ### Structure
 
-- `Zenject/SampleInstaller.cs`
-- `VContainer/SampleLifetimeScope.cs`
-- `Reflex/SampleInstaller.cs`
-- `Providers/CurrentGlobalMessageBusProvider.asset` — ScriptableObject that resolves whichever bus is currently configured as global.
-- `Providers/InitialGlobalMessageBusProvider.asset` — ScriptableObject that always returns the original startup global bus, ignoring later overrides.
-- `Prefabs/MessagingInstallerSample.prefab` — ready-to-use hierarchy with `MessagingComponentInstaller` configuring a child `MessagingComponent` using the provider asset. Drop it into a scene to see provider-driven wiring without writing setup code.
+- Zenject sample installer: [SampleInstaller.cs](./Zenject/SampleInstaller.cs)
+- VContainer sample lifetime scope: [SampleLifetimeScope.cs](./VContainer/SampleLifetimeScope.cs)
+- Reflex sample installer: [SampleInstaller.cs](./Reflex/SampleInstaller.cs)
+- Current global message bus provider asset: [CurrentGlobalMessageBusProvider.asset](./Providers/CurrentGlobalMessageBusProvider.asset) — ScriptableObject that resolves whichever bus is currently configured as global.
+- Initial global message bus provider asset: [InitialGlobalMessageBusProvider.asset](./Providers/InitialGlobalMessageBusProvider.asset) — ScriptableObject that always returns the original startup global bus, ignoring later overrides.
+- Prefab setup: [MessagingInstallerSample.prefab](./Prefabs/MessagingInstallerSample.prefab) — ready-to-use hierarchy with `MessagingComponentInstaller` configuring a child `MessagingComponent` using the provider asset. Drop it into a scene to see provider-driven wiring without writing setup code.
 
 ## Walkthrough
 
@@ -33,19 +33,19 @@ Each sample shows:
 
 2. **Hook up the container**  
    - **Zenject**:  
-     - Add `DxMessagingRegistrationInstaller` (from `Runtime/Unity/Integrations/`) to your ProjectContext or scene installer list.  
-     - Drop `Zenject/SampleInstaller.cs` into your project and register it alongside other installers. When the scene runs, the installer resolves `IMessageRegistrationBuilder`, stages a `PlayerSpawned` listener, and activates via the Zenject lifecycle.
+     - Add `DxMessagingRegistrationInstaller` (from [Runtime/Unity/Integrations](../../Runtime/Unity/Integrations/)) to your ProjectContext or scene installer list.  
+     - Drop [SampleInstaller.cs](./Zenject/SampleInstaller.cs) into your project and register it alongside other installers. When the scene runs, the installer resolves `IMessageRegistrationBuilder`, stages a `PlayerSpawned` listener, and activates via the Zenject lifecycle.
    - **VContainer**:  
-     - Define `VCONTAINER_PRESENT` and reference the optional extension under `Runtime/Unity/Integrations/VContainerRegistrationExtensions.cs`.  
-     - Add `VContainer/SampleLifetimeScope` to the scene (or derive from it); the sample scope registers the builder and an entry point that emits/consumes `ScoreUpdated` messages each tick.
+     - Define `VCONTAINER_PRESENT` and reference the optional extension under [VContainerRegistrationExtensions.cs](../../Runtime/Unity/Integrations/VContainerRegistrationExtensions.cs).  
+     - Add [SampleLifetimeScope.cs](./VContainer/SampleLifetimeScope.cs) to the scene (or derive from it); the sample scope registers the builder and an entry point that emits/consumes `ScoreUpdated` messages each tick.
    - **Reflex**:  
      - Enable `REFLEX_PRESENT` and install `DxMessagingRegistrationInstaller` into your container bootstrap.  
-     - Include `Reflex/SampleInstaller` in your installer chain. The sample service resolves `IMessageRegistrationBuilder`, subscribes to `PlayerAlert`, and can emit alerts via `EmitAlertFor`.
+     - Include [SampleInstaller.cs](./Reflex/SampleInstaller.cs) in your installer chain. The sample service resolves `IMessageRegistrationBuilder`, subscribes to `PlayerAlert`, and can emit alerts via `EmitAlertFor`.
 
 3. **Emit a message**  
    Use the service exposed by the container (e.g., call into `ScoreboardService` or `PlayerAlertService`) to emit a message. Because the prefab already configured `MessagingComponent` instances via the installer, the listeners run immediately.
 
 4. **Swap providers** (optional)  
-   Duplicate `Providers/CurrentGlobalMessageBusProvider.asset`, modify it to return a custom bus, assign it on the prefab root, and observe how builder-created leases now resolve that bus instead.
+   Duplicate [CurrentGlobalMessageBusProvider.asset](./Providers/CurrentGlobalMessageBusProvider.asset), modify it to return a custom bus, assign it on the prefab root, and observe how builder-created leases now resolve that bus instead.
 
 Feel free to duplicate these scripts into your own project and adjust lifecycles or message types as needed.

package/Samples~/Mini Combat/README.md

@@ -83,11 +83,11 @@ Here's what each script does:
 
 | File | Purpose | Message Type |
 |------|---------|--------------|
-| **Messages.cs** | Defines all message types | Contains `VideoSettingsChanged`, `Heal`, and `TookDamage` |
-| **Player.cs** | Handles receiving healing | Listens for `Heal` (Targeted) |
-| **Enemy.cs** | Announces when damaged | Emits `TookDamage` (Broadcast) |
-| **UIOverlay.cs** | Updates UI based on events | Listens to settings and `TookDamage` (Broadcast) |
-| **Boot.cs** | Starts the demo | Simulates message flow |
+| **[Messages.cs](./Messages.cs)** | Defines all message types | Contains `VideoSettingsChanged`, `Heal`, and `TookDamage` |
+| **[Player.cs](./Player.cs)** | Handles receiving healing | Listens for `Heal` (Targeted) |
+| **[Enemy.cs](./Enemy.cs)** | Announces when damaged | Emits `TookDamage` (Broadcast) |
+| **[UIOverlay.cs](./UIOverlay.cs)** | Updates UI based on events | Listens to settings and `TookDamage` (Broadcast) |
+| **[Boot.cs](./Boot.cs)** | Starts the demo | Simulates message flow |
 
 ---
 
@@ -126,10 +126,10 @@ For **each GameObject**, you need TWO components:
    - Click GameObject → Add Component → "MessagingComponent"
 
 1. **Add the sample script**:
-   - **Player** GameObject → Add `Player.cs` script
-   - **Enemy** GameObject → Add `Enemy.cs` script
-   - **UIOverlay** GameObject → Add `UIOverlay.cs` script
-   - **Boot** GameObject → Add `Boot.cs` script
+   - **Player** GameObject → Add [Player.cs](./Player.cs) script
+   - **Enemy** GameObject → Add [Enemy.cs](./Enemy.cs) script
+   - **UIOverlay** GameObject → Add [UIOverlay.cs](./UIOverlay.cs) script
+   - **Boot** GameObject → Add [Boot.cs](./Boot.cs) script
 
 #### Step 3: Run and Observe
 
@@ -147,11 +147,11 @@ Press Play! The Boot script will automatically:
 
 ### The Message Flow
 
-#### Boot.cs sends messages:
+#### [Boot.cs](./Boot.cs) sends messages:
 
-1. `VideoSettingsChanged` (Untargeted) → UIOverlay.cs receives
-2. `Heal` (Targeted to Player) → Player.cs receives
-3. `TookDamage` (Broadcast from Enemy) → UIOverlay.cs receives
+1. `VideoSettingsChanged` (Untargeted) → [UIOverlay.cs](./UIOverlay.cs) receives
+2. `Heal` (Targeted to Player) → [Player.cs](./Player.cs) receives
+3. `TookDamage` (Broadcast from Enemy) → [UIOverlay.cs](./UIOverlay.cs) receives
 
 ### Understanding Message Types
 
@@ -318,6 +318,6 @@ protected override void OnEnable() {
 ## Quick Reference
 
 **Enable Diagnostics**: Select MessagingComponent in Inspector → Enable Diagnostics
-**Message Types**: See `Messages.cs` for all available messages
-**Modify Behavior**: Edit handler methods in Player.cs, Enemy.cs, or UIOverlay.cs
+**Message Types**: See [Messages.cs](./Messages.cs) for all available messages
+**Modify Behavior**: Edit handler methods in [Player.cs](./Player.cs), [Enemy.cs](./Enemy.cs), or [UIOverlay.cs](./UIOverlay.cs)
 **Extend Scripts**: Always call `base.RegisterMessageHandlers()` and other `base.*` methods

package/Samples~/Mini Combat/Walkthrough.md

@@ -17,7 +17,7 @@
 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
+2. **How the code flows** - step-by-step from [Boot.cs](./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
@@ -43,7 +43,7 @@ After reading this walkthrough, you'll know:
 
 Let's understand what each script does:
 
-### Messages.cs
+### [Messages.cs](./Messages.cs)
 
 **Purpose**: Defines all message types used in the sample
 
@@ -56,7 +56,7 @@ Let's understand what each script does:
 
 **Why separate file?** Keeping messages in one place makes them easy to find and prevents circular dependencies.
 
-### Player.cs
+### [Player.cs](./Player.cs)
 
 **What it does**: Listens for healing messages targeted specifically at this player
 
@@ -68,7 +68,7 @@ Let's understand what each script does:
 
 **Real-world analogy**: Like having your name called in a doctor's office—only you respond.
 
-### Enemy.cs
+### [Enemy.cs](./Enemy.cs)
 
 **What it does**: Broadcasts when it takes damage
 
@@ -80,7 +80,7 @@ Let's understand what each script does:
 
 **Real-world analogy**: Like ringing a bell—anyone nearby can hear it.
 
-### UIOverlay.cs
+### [UIOverlay.cs](./UIOverlay.cs)
 
 **What it does**: Monitors game events and updates the UI
 
@@ -92,7 +92,7 @@ Let's understand what each script does:
 
 **Real-world analogy**: Like a news reporter watching everything and reporting it.
 
-### Boot.cs
+### [Boot.cs](./Boot.cs)
 
 **What it does**: Starts the demo by simulating a sequence of events
 
@@ -141,8 +141,8 @@ Settings changes are **global events**—they don't target anyone specifically.
 
 ### The Code Flow
 
-1. **Boot.cs** calls: `MessageHub.Publish(new VideoSettingsChanged())`
-1. **UIOverlay.cs** receives it through its registered handler
+1. **[Boot.cs](./Boot.cs)** calls: `MessageHub.Publish(new VideoSettingsChanged())`
+1. **[UIOverlay.cs](./UIOverlay.cs)** receives it through its registered handler
 1. **UIOverlay** rebuilds the UI with new settings
 
 ### Developer Notes
@@ -178,9 +178,9 @@ We want to heal **one specific player**, not all players in the scene.
 
 ### The Code Flow
 
-1. **Boot.cs** finds the Player Component reference
-1. **Boot.cs** calls: `MessageHub.Publish(new Heal(amount), targetComponent)`
-1. **Only the targeted Player.cs** receives it through its handler
+1. **[Boot.cs](./Boot.cs)** finds the Player Component reference
+1. **[Boot.cs](./Boot.cs)** calls: `MessageHub.Publish(new Heal(amount), targetComponent)`
+1. **Only the targeted [Player.cs](./Player.cs)** receives it through its handler
 1. **Player** increases its HP
 
 ### Developer Notes
@@ -216,7 +216,7 @@ The Enemy doesn't know (or care) who needs to know about the damage. It just ann
 
 ### The Code Flow
 
-1. **Enemy.cs** detects it took damage
+1. **[Enemy.cs](./Enemy.cs)** detects it took damage
 1. **Enemy** calls: `this.EmitBroadcast(new TookDamage(amount))`
 1. **UIOverlay** receives it via `RegisterBroadcastWithoutSource`
 1. **UIOverlay** displays the damage event

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

@@ -120,7 +120,7 @@ MessageHandler.MessageBus.DiagnosticsMode = true;
 
 - Multiple buttons: Add more UI Buttons, add more `UIButtonEmitter`s, and give each a unique `buttonId`.
 - Targeted vs. untargeted: Notice the sample also sends a targeted `StringMessage` to the emitter’s `gameObject`.
-- Your own message type: Open `Messages.cs` to see how `ButtonClicked` is declared using attributes:
+- Your own message type: Open [Messages.cs](./Messages.cs) to see how `ButtonClicked` is declared using attributes:
 
 ```csharp
 [DxUntargetedMessage]
@@ -202,8 +202,8 @@ public class MyObserver : MessageAwareComponent {
 
 ## Next Steps
 
-- Quick tour: `Docs/GettingStarted.md`
-- Patterns and recipes: `Docs/Patterns.md`
-- Explore another sample: `../Mini%20Combat/README.md`
+- Quick tour: [Getting Started guide](../../Docs/GettingStarted.md)
+- Patterns and recipes: [Common Patterns](../../Docs/Patterns.md)
+- Explore another sample: [Mini Combat sample](../Mini%20Combat/README.md)
 
 You now have an easy, inspector-first way to publish and observe messages. Build up from here by swapping in your own message types and listeners.

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators/DxAutoConstructorGenerator.cs

@@ -56,6 +56,10 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             ImmutableArray<IFieldSymbol> FieldsToInject // Public readonly non-static fields
         );
 
+        /// <summary>
+        /// Configures the incremental generator pipeline that discovers annotated types and emits constructors.
+        /// </summary>
+        /// <param name="context">Initialization context provided by Roslyn.</param>
         public void Initialize(IncrementalGeneratorInitializationContext context)
         {
             // Find all class/struct/record declarations that have attribute lists

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators/DxMessageIdGenerator.cs

@@ -70,6 +70,10 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             bool HasConflictingMessageAttributes
         );
 
+        /// <summary>
+        /// Configures the incremental generator pipeline that assigns deterministic message identifiers.
+        /// </summary>
+        /// <param name="context">Initialization context provided by Roslyn.</param>
         public void Initialize(IncrementalGeneratorInitializationContext context)
         {
             // Find all class/struct/record declarations with attributes

package/Tests/Runtime/Core/DiagnosticsTests.cs

@@ -51,11 +51,11 @@ namespace DxMessaging.Tests.Runtime.Core
         [UnityTest]
         public IEnumerator MessageBusDiagnosticsRespectBufferSize()
         {
-            bool originalDiagnostics = IMessageBus.GlobalDiagnosticsMode;
+            DiagnosticsTarget originalDiagnostics = IMessageBus.GlobalDiagnosticsTargets;
             int originalBufferSize = IMessageBus.GlobalMessageBufferSize;
             try
             {
-                IMessageBus.GlobalDiagnosticsMode = true;
+                IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.All;
                 IMessageBus.GlobalMessageBufferSize = 2;
 
                 GameObject host = new(nameof(MessageBusDiagnosticsRespectBufferSize));
@@ -90,7 +90,7 @@ namespace DxMessaging.Tests.Runtime.Core
             }
             finally
             {
-                IMessageBus.GlobalDiagnosticsMode = originalDiagnostics;
+                IMessageBus.GlobalDiagnosticsTargets = originalDiagnostics;
                 IMessageBus.GlobalMessageBufferSize = originalBufferSize;
             }
 

package/Tests/Runtime/Core/DxMessagingStaticStateTests.cs

@@ -0,0 +1,69 @@
+#if UNITY_2021_3_OR_NEWER
+namespace DxMessaging.Tests.Runtime.Core
+{
+    using System;
+    using System.Reflection;
+    using DxMessaging.Core;
+    using DxMessaging.Core.Helper;
+    using DxMessaging.Core.MessageBus;
+    using DxMessaging.Core.Messages;
+    using NUnit.Framework;
+
+    public sealed class DxMessagingStaticStateTests
+    {
+        [Test]
+        public void ResetRestoresDefaultStaticState()
+        {
+            DxMessagingStaticState.Reset();
+            IMessageBus baselineBus = MessageHandler.MessageBus;
+            MessageRegistrationHandle baselineHandle =
+                MessageRegistrationHandle.CreateMessageRegistrationHandle();
+
+            MessageRegistrationHandle.CreateMessageRegistrationHandle();
+            MessagingDebug.enabled = true;
+            MessagingDebug.LogFunction = (logLevel, message) => { };
+
+            IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.All;
+            IMessageBus.GlobalMessageBufferSize = 128;
+            IMessageBus.GlobalSequentialIndex = 7;
+
+            Type builderType = typeof(MessageRegistrationBuilder);
+            FieldInfo syntheticOwnerField = builderType.GetField(
+                "_syntheticOwnerCounter",
+                BindingFlags.NonPublic | BindingFlags.Static
+            );
+            Assert.IsNotNull(syntheticOwnerField);
+            syntheticOwnerField.SetValue(null, 3);
+
+            MessageCache<object> cache = new MessageCache<object>();
+            cache.GetOrAdd<DummyUntargetedMessage>();
+
+            MessageHandler.SetGlobalMessageBus(new MessageBus());
+
+            DxMessagingStaticState.Reset();
+
+            Assert.IsFalse(MessagingDebug.enabled);
+            Assert.IsNull(MessagingDebug.LogFunction);
+            Assert.AreEqual(DiagnosticsTarget.Off, IMessageBus.GlobalDiagnosticsTargets);
+            Assert.AreEqual(0, IMessageBus.GlobalMessageBufferSize);
+            Assert.AreEqual(-1, IMessageBus.GlobalSequentialIndex);
+
+            MessageRegistrationHandle resetHandle =
+                MessageRegistrationHandle.CreateMessageRegistrationHandle();
+            Assert.AreEqual(baselineHandle, resetHandle);
+
+            object syntheticOwnerValue = syntheticOwnerField.GetValue(null);
+            Assert.AreEqual(0, (int)syntheticOwnerValue);
+
+            Assert.AreEqual(0, MessageHelperIndexer.TotalMessages);
+            Assert.AreEqual(-1, MessageHelperIndexer<DummyUntargetedMessage>.SequentialId);
+            Assert.AreSame(MessageHandler.InitialGlobalMessageBus, MessageHandler.MessageBus);
+            Assert.AreSame(baselineBus, MessageHandler.MessageBus);
+
+            DxMessagingStaticState.Reset();
+        }
+
+        private struct DummyUntargetedMessage : IUntargetedMessage { }
+    }
+}
+#endif

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.wallstop-studios.dxmessaging",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "displayName": "DxMessaging",
   "description": "Synchronous Event Bus for Unity",
   "unity": "2021.3",

package/Tests/Runtime/WallstopStudios.DxMessaging.Tests.Runtime.csproj

@@ -1,20 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <Nullable>disable</Nullable>
-    <ImplicitUsings>disable</ImplicitUsings>
-    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
-    <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
-    <IsPackable>false</IsPackable>
-    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
-    <NoWarn>1701;1702</NoWarn>
-  </PropertyGroup>
-  <ItemGroup>
-    <None Include="Benchmarks\**\*.cs" LinkBase="Benchmarks" />
-    <None Include="Core\**\*.cs" LinkBase="Core" />
-    <None Include="Integrations\**\*.cs" LinkBase="Integrations" />
-    <None Include="Scripts\**\*.cs" LinkBase="Scripts" />
-    <None Include="TestUtilities\**\*.cs" LinkBase="TestUtilities" />
-    <None Include="Unity\**\*.cs" LinkBase="Unity" />
-  </ItemGroup>
-</Project>

package/Tests/Runtime/WallstopStudios.DxMessaging.Tests.Runtime.csproj.meta

@@ -1,7 +0,0 @@
-fileFormatVersion: 2
-guid: 939c668fdbd24a74591e482310e0e40f
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: