com.wallstop-studios.dxmessaging 2.0.0 → 2.1.0

package/README.md

@@ -113,6 +113,57 @@ msg.EmitComponentTargeted(chestComponent);
 
 ---
 
+## 🔧 Dependency Injection (DI) Compatible
+
+**Using Zenject, VContainer, or Reflex?** DxMessaging is fully DI-compatible out of the box!
+
+```csharp
+// Inject IMessageBus in any class
+public class PlayerService : IInitializable, IDisposable
+{
+    private readonly MessageRegistrationLease _lease;
+
+    public PlayerService(IMessageRegistrationBuilder builder)
+    {
+        // Builder automatically resolves your container-managed bus
+        _lease = builder.Build(new MessageRegistrationBuildOptions
+        {
+            Configure = token => token.RegisterUntargeted<PlayerSpawned>(OnSpawn)
+        });
+    }
+
+    public void Initialize() => _lease.Activate();
+    public void Dispose() => _lease.Dispose();
+}
+```
+
+### Why use DI + Messaging?
+
+- **DI for construction** — Inject services, repositories, managers via constructors
+- **Messaging for events** — Reactive, decoupled communication for gameplay events
+- **Best of both worlds** — Clean architecture with testable, isolated buses
+
+#### Automatic integration for
+
+- ✅ **Zenject/Extenject** — Full-featured DI with extensive Unity support
+- ✅ **VContainer** — Lightweight, high-performance DI with scoped lifetimes
+- ✅ **Reflex** — Minimal API, blazing-fast dependency injection
+
+##### Get started
+
+- [Zenject Integration Guide](Docs/Integrations/Zenject.md) — Complete setup with examples
+- [VContainer Integration Guide](Docs/Integrations/VContainer.md) — Scoped buses for scene isolation
+- [Reflex Integration Guide](Docs/Integrations/Reflex.md) — Minimal, lightweight patterns
+
+##### Core DI concepts
+
+- [Runtime Configuration](Docs/RuntimeConfiguration.md) — Setting message buses at runtime, re-binding registrations
+- [Message Bus Providers](Docs/MessageBusProviders.md) — Provider system for design-time and runtime bus configuration
+
+**Not using DI?** No problem! DxMessaging works perfectly standalone with zero dependencies.
+
+---
+
 ## Is DxMessaging Right for You
 
 ### ✅ Use DxMessaging When
@@ -123,6 +174,7 @@ msg.EmitComponentTargeted(chestComponent);
 - **You value observability** - Need to debug "what fired when?" or track message flow
 - **Teams/long-term maintenance** - Multiple developers, or you'll maintain this code for years
 - **You want decoupling** - Hate when UI classes need references to 15 different game systems
+- **You're using DI frameworks** - Seamless integration with Zenject/VContainer/Reflex (see [DI Compatible](#-dependency-injection-di-compatible))
 
 ### ❌ Don't Use DxMessaging When
 
@@ -359,9 +411,9 @@ flowchart LR
     P[Producer] --> I[Interceptors<br/>validate/mutate]
     I --> H[Handlers<br/>main logic]
     H --> PP[Post-Processors<br/>analytics/logging]
-    style I fill:#fff4e5,stroke:#f0b429
-    style H fill:#e6f7ff,stroke:#1890ff
-    style PP fill:#eef7ee,stroke:#52c41a
+    style I fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
+    style H fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+    style PP fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
 ```
 
 ### 🎭 Global Observers: Listen to EVERYTHING (Unique Feature!)
@@ -431,27 +483,22 @@ void OnDamage(ref TookDamage msg) {
 
 **DxMessaging solution:** Click any `MessageAwareComponent` in the Inspector:
 
-```text
-┌─────────────────────────────────────────────────────┐
-│ Message History (last 50)                           │
-├─────────────────────────────────────────────────────┤
-│ [12:34:56.123] HealthChanged                        │
-│   → amount: 25                                       │
-│   → priority: 0                                      │
-│   → handlers: 3                                      │
-│                                                      │
-│ [12:34:55.987] ItemAdded                            │
-│   → itemId: 42, count: 1                            │
-│   → priority: 5                                      │
-│   → handlers: 2                                      │
-├─────────────────────────────────────────────────────┤
-│ Active Registrations                                │
-├─────────────────────────────────────────────────────┤
-│ ✓ HealthChanged (priority: 0, called: 847 times)   │
-│ ✓ ItemAdded (priority: 5, called: 23 times)        │
-│ ✓ TookDamage (priority: 10, called: 1,203 times)   │
-└─────────────────────────────────────────────────────┘
-```
+#### Message History (last 50)
+
+- `[12:34:56.123] HealthChanged`
+  - amount: 25
+  - priority: 0
+  - handlers: 3
+- `[12:34:55.987] ItemAdded`
+  - itemId: 42, count: 1
+  - priority: 5
+  - handlers: 2
+
+##### Active Registrations
+
+- ✓ HealthChanged (priority: 0, called: 847 times)
+- ✓ ItemAdded (priority: 5, called: 23 times)
+- ✓ TookDamage (priority: 10, called: 1,203 times)
 
 #### Real-world debugging scenarios
 
@@ -473,7 +520,7 @@ void OnDamage(ref TookDamage msg) {
 public void TestAchievementSystem() {
     // Create isolated bus - zero global state
     var testBus = new MessageBus();
-    var handler = new MessageHandler(new InstanceId(1)) { active = true };
+    var handler = new MessageHandler(new InstanceId(1), testBus) { active = true };
     var token = MessageRegistrationToken.Create(handler, testBus);
 
     // Test in isolation
@@ -524,9 +571,64 @@ Important: Inheritance with MessageAwareComponent
 - If you need to opt out of string demos, override `RegisterForStringMessages => false` instead of skipping the base call.
 - Don’t hide Unity methods with `new` (e.g., `new void OnEnable()`); always `override` and call `base.*`.
 
+### 🧩 DI Framework Integrations
+
+DxMessaging works standalone (zero dependencies) or with any major DI framework. For detailed setup guides and code examples:
+
+- **[Zenject Integration Guide](Docs/Integrations/Zenject.md)** — Full-featured DI with extensive Unity support
+- **[VContainer Integration Guide](Docs/Integrations/VContainer.md)** — Lightweight DI with scoped lifetimes for scene isolation
+- **[Reflex Integration Guide](Docs/Integrations/Reflex.md)** — Minimal API, blazing-fast performance
+
+#### Core DI concepts
+
+- **[Runtime Configuration](Docs/RuntimeConfiguration.md)** — Setting and overriding message buses at runtime, re-binding registrations
+- **[Message Bus Providers](Docs/MessageBusProviders.md)** — Provider system and MessageBusProviderHandle for flexible bus configuration
+
+Each guide includes:
+
+- ✅ Complete setup instructions with installers
+- ✅ Multiple usage patterns (plain classes, MonoBehaviours, direct injection)
+- ✅ Testing examples with isolated buses
+- ✅ Advanced patterns (pooling, scene scopes, signal bridges)
+
+See the [🔧 DI Compatible section](#-dependency-injection-di-compatible) above for a quick overview.
+
 ### 🆚 Comparisons
 
-- [Compare with C# events, UnityEvents, and SendMessage](Docs/Comparisons.md)
+- [Compare with Other Unity Messaging Frameworks](Docs/Comparisons.md) — In-depth comparison with UniRx, MessagePipe, Zenject Signals, C# events, UnityEvents, and more
+- [Scriptable Object Architecture (SOA) Compatibility](Docs/Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) — Migration patterns and interoperability with SOA
+
+#### Quick Framework Comparison
+
+| Framework           | Best For                          | Key Strength                     | Unity Support      | Learning Curve |
+| ------------------- | --------------------------------- | -------------------------------- | ------------------ | -------------- |
+| **DxMessaging**     | Unity pub/sub with lifecycle mgmt | Inspector debugging + control    | ✅ Built for Unity | ⭐⭐⭐         |
+| **UniRx**           | Complex event stream transforms   | Reactive operators (LINQ)        | ✅ Built for Unity | ⭐⭐           |
+| **MessagePipe**     | High-performance DI messaging     | Highest throughput (97M ops/sec) | ✅ Built for Unity | ⭐⭐⭐⭐       |
+| **Zenject Signals** | DI-integrated messaging           | Zenject ecosystem                | ✅ Built for Unity | ⭐⭐           |
+| **C# Events**       | Simple, local communication       | Minimal overhead                 | ✅ Native C#       | ⭐⭐⭐⭐⭐     |
+
+##### Choose DxMessaging when you want
+
+- Unity-first design with GameObject/Component targeting
+- Automatic lifecycle management (zero memory leaks)
+- Inspector debugging to see message flow and history
+- Execution order control (priority-based handlers)
+- Message validation/interception pipeline
+- Global observers (listen to all message instances)
+- Post-processing stage (analytics, logging after handlers)
+- No dependencies, plug-and-play setup
+
+See [full comparison](Docs/Comparisons.md) for detailed analysis with code examples, performance benchmarks, and decision guides.
+
+> **📦 Using Scriptable Object Architecture (SOA)?**
+>
+> DxMessaging can work alongside or replace SOA patterns. See [SOA Compatibility Guide](Docs/Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for:
+>
+> - Fair comparison of SOA vs. DxMessaging
+> - Migration patterns from GameEvent/FloatVariable to DxMessaging
+> - How to use both systems together (SOs for configs, DxMessaging for events)
+> - When to keep using ScriptableObjects (immutable design data)
 
 ### 📖 Reference
 
@@ -599,6 +701,26 @@ For OS-specific benchmark tables generated by PlayMode tests, see [Performance B
 
 ## Comparison Table
 
+### Comparison with Unity Messaging Frameworks
+
+| Feature                  | DxMessaging        | UniRx              | MessagePipe        | Zenject Signals    |
+| ------------------------ | ------------------ | ------------------ | ------------------ | ------------------ |
+| **Unity Compatibility**  | ✅ Built for Unity | ✅ Built for Unity | ✅ Built for Unity | ✅ Built for Unity |
+| **Decoupling**           | ✅ Full            | ✅ Full            | ✅ Full            | ✅ Full            |
+| **Lifecycle Safety**     | ✅ Auto            | ⚠️ Manual          | ⚠️ Manual          | ⚠️ DI-managed      |
+| **Execution Order**      | ✅ Priority        | ❌ None            | ❌ None            | ❌ None            |
+| **Type Safety**          | ✅ Strong          | ✅ Strong          | ✅ Strong          | ✅ Strong          |
+| **Inspector Debug**      | ✅ Built-in        | ❌ No              | ❌ No              | ❌ No              |
+| **GameObject Targeting** | ✅ Yes             | ❌ No              | ❌ No              | ❌ No              |
+| **Global Observers**     | ✅ Yes             | ❌ No              | ❌ No              | ❌ No              |
+| **Interceptors**         | ✅ Pipeline        | ❌ No              | ⚠️ Filters         | ❌ No              |
+| **Post-Processing**      | ✅ Dedicated       | ❌ No              | ⚠️ Filters         | ❌ No              |
+| **Stream Operators**     | ❌ No              | ✅ Extensive       | ❌ No              | ⚠️ With UniRx      |
+| **Performance**          | ✅ Good (14M)      | ✅ Good (18M)      | ✅ Best (97M)      | ⚠️ Moderate (2.5M) |
+| **Dependencies**         | ✅ None            | ⚠️ UniTask         | ✅ None            | ⚠️ Zenject         |
+
+### Comparison with Traditional Approaches
+
 | Feature                | DxMessaging   | C# Events    | UnityEvents   | Static Event Bus |
 | ---------------------- | ------------- | ------------ | ------------- | ---------------- |
 | **Decoupling**         | ✅ Full       | ❌ Tight     | ⚠️ Hidden     | ✅ Yes           |

package/Runtime/AssemblyInfo.cs

@@ -5,3 +5,7 @@ using System.Runtime.CompilerServices;
     AllInternalsVisible = true
 )]
 [assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Editor")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.Reflex")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.VContainer")]
+[assembly: InternalsVisibleTo("WallstopStudios.DxMessaging.Tests.Runtime.Zenject")]

package/Runtime/Core/Extensions/MessageBusExtensions.cs

@@ -0,0 +1,253 @@
+namespace DxMessaging.Core.Extensions
+{
+    using System;
+    using DxMessaging.Core;
+    using DxMessaging.Core.MessageBus;
+    using DxMessaging.Core.Messages;
+#if UNITY_2017_1_OR_NEWER
+    using UnityEngine;
+#endif
+
+    /// <summary>
+    /// <see cref="IMessageBus"/> helpers that mirror the message-centric shorthands in <see cref="MessageExtensions"/>.
+    /// </summary>
+    public static class MessageBusExtensions
+    {
+        public static void EmitUntargeted<TMessage>(this IMessageBus messageBus, TMessage message)
+            where TMessage : class, IUntargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitUntargeted(messageBus);
+        }
+
+        public static void EmitUntargeted<TMessage>(
+            this IMessageBus messageBus,
+            ref TMessage message
+        )
+            where TMessage : struct, IUntargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitUntargeted(messageBus);
+        }
+
+        public static void EmitTargeted<TMessage>(
+            this IMessageBus messageBus,
+            InstanceId target,
+            TMessage message
+        )
+            where TMessage : class, ITargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitTargeted(target, messageBus);
+        }
+
+        public static void EmitTargeted<TMessage>(
+            this IMessageBus messageBus,
+            InstanceId target,
+            ref TMessage message
+        )
+            where TMessage : struct, ITargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitTargeted(target, messageBus);
+        }
+
+        public static void EmitBroadcast<TMessage>(
+            this IMessageBus messageBus,
+            InstanceId source,
+            TMessage message
+        )
+            where TMessage : class, IBroadcastMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitBroadcast(source, messageBus);
+        }
+
+        public static void EmitBroadcast<TMessage>(
+            this IMessageBus messageBus,
+            InstanceId source,
+            ref TMessage message
+        )
+            where TMessage : struct, IBroadcastMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitBroadcast(source, messageBus);
+        }
+
+#if UNITY_2017_1_OR_NEWER
+        public static void EmitGameObjectTargeted<TMessage>(
+            this IMessageBus messageBus,
+            GameObject target,
+            TMessage message
+        )
+            where TMessage : class, ITargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitGameObjectTargeted(target, messageBus);
+        }
+
+        public static void EmitGameObjectTargeted<TMessage>(
+            this IMessageBus messageBus,
+            GameObject target,
+            ref TMessage message
+        )
+            where TMessage : struct, ITargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitGameObjectTargeted(target, messageBus);
+        }
+
+        public static void EmitComponentTargeted<TMessage>(
+            this IMessageBus messageBus,
+            Component target,
+            TMessage message
+        )
+            where TMessage : class, ITargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitComponentTargeted(target, messageBus);
+        }
+
+        public static void EmitComponentTargeted<TMessage>(
+            this IMessageBus messageBus,
+            Component target,
+            ref TMessage message
+        )
+            where TMessage : struct, ITargetedMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitComponentTargeted(target, messageBus);
+        }
+
+        public static void EmitGameObjectBroadcast<TMessage>(
+            this IMessageBus messageBus,
+            GameObject source,
+            TMessage message
+        )
+            where TMessage : class, IBroadcastMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitGameObjectBroadcast(source, messageBus);
+        }
+
+        public static void EmitGameObjectBroadcast<TMessage>(
+            this IMessageBus messageBus,
+            GameObject source,
+            ref TMessage message
+        )
+            where TMessage : struct, IBroadcastMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitGameObjectBroadcast(source, messageBus);
+        }
+
+        public static void EmitComponentBroadcast<TMessage>(
+            this IMessageBus messageBus,
+            Component source,
+            TMessage message
+        )
+            where TMessage : class, IBroadcastMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitComponentBroadcast(source, messageBus);
+        }
+
+        public static void EmitComponentBroadcast<TMessage>(
+            this IMessageBus messageBus,
+            Component source,
+            ref TMessage message
+        )
+            where TMessage : struct, IBroadcastMessage
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            message.EmitComponentBroadcast(source, messageBus);
+        }
+#endif
+
+        public static void Emit(this IMessageBus messageBus, string payload)
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            payload.Emit(messageBus);
+        }
+
+        public static void EmitAt(this IMessageBus messageBus, InstanceId target, string payload)
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            payload.Emit(target, messageBus);
+        }
+
+        public static void EmitFrom(this IMessageBus messageBus, InstanceId source, string payload)
+        {
+            if (messageBus == null)
+            {
+                throw new ArgumentNullException(nameof(messageBus));
+            }
+
+            payload.EmitFrom(source, messageBus);
+        }
+    }
+}

package/Runtime/Core/Extensions/MessageBusExtensions.cs.meta

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