com.wallstop-studios.dxmessaging 2.0.0 → 2.1.0

package/Docs/Compatibility.md

@@ -15,3 +15,30 @@ Notes
 
 - RP‑agnostic: DxMessaging does not depend on rendering APIs; it works equally across Built‑In, URP, and HDRP.
 - Minimum version is governed by the package manifest (`unity`: 2021.3). Newer LTS versions are expected to work.
+
+## Architecture Pattern Compatibility
+
+### Scriptable Object Architecture (SOA)
+
+DxMessaging can work alongside Scriptable Object Architecture patterns, though SOA has documented limitations. See [Pattern 14: SOA Compatibility](Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for detailed integration strategies, code examples, and migration paths.
+
+#### Quick summary
+
+- ✅ **Compatible** - DxMessaging can bridge with SOA systems
+- ⚠️ **Not recommended** - SOA has scalability and maintainability concerns ([detailed critique](https://github.com/cathei/AntiScriptableObjectArchitecture))
+- ✅ **Best practice** - Use ScriptableObjects for immutable design data, DxMessaging for runtime events
+- → See [SOA Integration Patterns](Patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for three coexistence strategies with code examples
+
+### Dependency Injection (DI) Frameworks
+
+DxMessaging integrates seamlessly with popular DI frameworks:
+
+- **Zenject** - See [Zenject Integration Guide](Integrations/Zenject.md)
+- **VContainer** - See [VContainer Integration Guide](Integrations/VContainer.md)
+- **Reflex** - See [Reflex Integration Guide](Integrations/Reflex.md)
+
+DI and DxMessaging complement each other: DI manages dependencies/services, DxMessaging handles event communication.
+
+### Other Unity Frameworks
+
+For comparisons with other messaging/event frameworks (UniRx, MessagePipe, Zenject Signals, etc.), see [Framework Comparisons](Comparisons.md).

package/Docs/DesignAndArchitecture.md

@@ -49,42 +49,49 @@ DxMessaging was built with these principles:
 
 ## Architecture Overview
 
-```text
-┌─────────────────────────────────────────────────────────────┐
-│                        Application                           │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
-│  │ Component A  │  │ Component B  │  │ Component C  │      │
-│  │              │  │              │  │              │      │
-│  │ Token.Reg()  │  │ Token.Reg()  │  │ Token.Reg()  │      │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
-│         │                 │                 │               │
-│         └─────────────────┼─────────────────┘               │
-│                           ▼                                 │
-│              ┌─────────────────────────┐                    │
-│              │ MessageRegistrationToken│                    │
-│              │                         │                    │
-│              │ • Stages registrations  │                    │
-│              │ • Enable/Disable        │                    │
-│              │ • Lifecycle management  │                    │
-│              └────────────┬────────────┘                    │
-│                           ▼                                 │
-│              ┌─────────────────────────┐                    │
-│              │     MessageHandler      │                    │
-│              │                         │                    │
-│              │ • Per-component handler │                    │
-│              │ • Active/Inactive state │                    │
-│              └────────────┬────────────┘                    │
-│                           ▼                                 │
-│              ┌─────────────────────────┐                    │
-│              │        MessageBus       │                    │
-│              │                         │                    │
-│              │ • Interceptors          │                    │
-│              │ • Handlers              │                    │
-│              │ • Post-Processors       │                    │
-│              └─────────────────────────┘                    │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#2563eb','secondaryColor':'#fff','tertiaryColor':'#fff','edgeLabelBackground':'#fff'}}}%%
+flowchart TB
+    subgraph App["<b>Application Layer</b>"]
+        CompA[Component A<br/>Token.Reg]
+        CompB[Component B<br/>Token.Reg]
+        CompC[Component C<br/>Token.Reg]
+    end
+
+    subgraph Token["<b>Registration Layer</b>"]
+        MRT[MessageRegistrationToken<br/>• Stages registrations<br/>• Enable/Disable<br/>• Lifecycle management]
+    end
+
+    subgraph Handler["<b>Handler Layer</b>"]
+        MH[MessageHandler<br/>• Per-component handler<br/>• Active/Inactive state]
+    end
+
+    subgraph Bus["<b>Message Bus Layer</b>"]
+        MB[MessageBus<br/>• Interceptors<br/>• Handlers<br/>• Post-Processors]
+    end
+
+    CompA ==> MRT
+    CompB ==> MRT
+    CompC ==> MRT
+    MRT ==> MH
+    MH ==> MB
+
+    style App fill:#bae7ff,stroke:#0050b3,stroke-width:3px,color:#000
+    style Token fill:#ffe7ba,stroke:#d48806,stroke-width:3px,color:#000
+    style Handler fill:#d3adf7,stroke:#531dab,stroke-width:3px,color:#000
+    style Bus fill:#b7eb8f,stroke:#389e0d,stroke-width:3px,color:#000
+    style MRT fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
+    style MH fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
+    style MB fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
 ```
 
+### Layer Responsibilities
+
+1. **Application Layer** - Your Unity components register message handlers
+1. **Registration Layer** - Token manages handler lifecycle (enable/disable/cleanup)
+1. **Handler Layer** - Per-component state management (active/inactive)
+1. **Message Bus Layer** - Routes messages through interceptors → handlers → post-processors
+
 ## Performance Optimizations
 
 - Struct messages passed by `ref` to avoid copying and GC.

package/Docs/EmitShorthands.md

@@ -45,6 +45,40 @@ var damage = new TookDamage(5);
 damage.EmitFrom(enemy); // Broadcast: listeners interested in enemy damage receive this
 ```
 
+### Bus-First Helpers
+
+Prefer injecting `IMessageBus` (or `IMessageRegistrationBuilder`) in DI scenarios and use the bus-first extensions for parity with the shorthands:
+
+```csharp
+using DxMessaging.Core.Extensions;
+using DxMessaging.Core.Attributes;
+
+public sealed class ScoreReporter
+{
+    private readonly IMessageBus messageBus;
+
+    public ScoreReporter(IMessageBus messageBus)
+    {
+        this.messageBus = messageBus;
+    }
+
+    public void Report(int value)
+    {
+        ScoreChanged message = new ScoreChanged(value);
+        messageBus.EmitUntargeted(ref message);
+    }
+}
+
+[DxUntargetedMessage]
+public readonly struct ScoreChanged
+{
+    public readonly int Value;
+    public ScoreChanged(int value) => Value = value;
+}
+```
+
+These helpers mirror the struct/class/targeted/broadcast overloads available on message instances. They keep DI-friendly services aligned with the same dispatch path as Unity shorthands.
+
 ## Understanding Each Shorthand
 
 ### `Emit()` — Global Broadcast (Untargeted)

package/Docs/Helpers.md

@@ -355,7 +355,7 @@ using DxMessaging.Core.MessageBus;
 
 // Create isolated bus
 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);
 
 // Register on isolated bus

package/Docs/Index.md

@@ -4,28 +4,18 @@
 
 ## Visual Documentation Map
 
-```text
-                    ┌─────────────────┐
-                    │   START HERE    │
-                    │  Visual Guide   │
-                    │   (5 minutes)   │
-                    └────────┬────────┘
-                             │
-          ┌──────────────────┼──────────────────┐
-          │                  │                  │
-    ┌─────▼──────┐    ┌─────▼──────┐    ┌─────▼──────┐
-    │   Quick    │    │  Getting   │    │  Overview  │
-    │   Start    │    │  Started   │    │            │
-    │ (5 min)    │    │ (10 min)   │    │ (5 min)    │
-    └─────┬──────┘    └─────┬──────┘    └─────┬──────┘
-          │                  │                  │
-          └──────────────────┼──────────────────┘
-                             │
-                      ┌──────▼──────┐
-                      │   Patterns  │
-                      │  & Samples  │
-                      │ (Hands-on!) │
-                      └─────────────┘
+```mermaid
+graph TD
+    Start[START HERE<br/>Visual Guide<br/>5 minutes]
+    Start --> Quick[Quick Start<br/>5 min]
+    Start --> Getting[Getting Started<br/>10 min]
+    Start --> Overview[Overview<br/>5 min]
+    Quick --> Patterns[Patterns & Samples<br/>Hands-on!]
+    Getting --> Patterns
+    Overview --> Patterns
+
+    style Start fill:#91d5ff,stroke:#096dd9,stroke-width:3px,color:#000
+    style Patterns fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
 ```
 
 ## Table of Contents
@@ -108,6 +98,8 @@
 ### Tools & Utilities
 
 - **[Helpers](Helpers.md)** — Source generators, attributes, extensions
+- **[Message Bus Providers](MessageBusProviders.md)** — Provider system and MessageBusProviderHandle for flexible bus configuration
+- **[Runtime Configuration](RuntimeConfiguration.md)** — Setting message buses at runtime, re-binding registrations
 - **[Emit Shorthands](EmitShorthands.md)** — `Emit`/`EmitAt`/`EmitFrom` usage and pitfalls
 - **[String Messages](StringMessages.md)** — Prototyping and debugging
 - **[Compatibility](Compatibility.md)** — Unity versions and render pipelines
@@ -159,6 +151,9 @@ From [Common Patterns](Patterns.md):
 - **Debug message flow** → Use [Diagnostics](Diagnostics.md)
 - **Optimize performance** → Read [Performance Tips](DesignAndArchitecture.md#performance-tuning-tips)
 - **Isolate tests** → Create [Local Bus Islands](DesignAndArchitecture.md#local-bus-islands)
+- **Use dependency injection** → [DxMessaging + Zenject](Integrations/Zenject.md), [DxMessaging + VContainer](Integrations/VContainer.md), [DxMessaging + Reflex](Integrations/Reflex.md)
+- **Configure buses at runtime** → See [Runtime Configuration](RuntimeConfiguration.md)
+- **Use message bus providers** → Learn [Message Bus Providers](MessageBusProviders.md)
 
 ## 📊 Visual: Message Pipeline
 
@@ -169,9 +164,9 @@ flowchart LR
     P[Producer] --> I[Interceptors<br/>validate/mutate/cancel]
     I --> H[Handlers<br/>main logic by priority]
     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
 ```
 
 ## 🎓 Learning Resources
@@ -269,6 +264,14 @@ From [Comparisons](Comparisons.md):
 - [FAQ](FAQ.md)
 - [Troubleshooting](Troubleshooting.md)
 
+### Dependency Injection
+
+- [Runtime Configuration](RuntimeConfiguration.md) — Setting and overriding message buses, re-binding registrations
+- [Message Bus Providers](MessageBusProviders.md) — Provider system and MessageBusProviderHandle
+- [DxMessaging + Zenject](Integrations/Zenject.md) — Zenject integration guide
+- [DxMessaging + VContainer](Integrations/VContainer.md) — VContainer integration guide
+- [DxMessaging + Reflex](Integrations/Reflex.md) — Reflex integration guide
+
 ### Miscellaneous
 
 - [String Messages](StringMessages.md)

package/Docs/Install.md

@@ -2,34 +2,57 @@
 
 This page helps you install DxMessaging into a Unity 2021.3+ project using the Unity Package Manager (UPM).
 
-Fast path
+## Methods
+
+### Fast path
 
 - Unity Package Manager > Add package from git URL...
 - Paste:
 
 ```text
-https://github.com/wallstop/DxMessaging.git?path=/Packages/com.wallstop-studios.dxmessaging
+https://github.com/wallstop/DxMessaging.git
 ```
 
 - Click Add. Unity imports the package and its analyzers/generators.
 
-Manifest.json (alternative)
+### To Install as Unity Package
+
+1. Open Unity Package Manager
+1. (Optional) Enable Pre-release packages to get the latest, cutting-edge builds
+1. Open the Advanced Package Settings
+1. Add an entry for a new "Scoped Registry"
+   - Name: `NPM`
+   - URL: `https://registry.npmjs.org`
+   - Scope(s): `com.wallstop-studios.dxmessaging`
+1. Resolve the latest `DxMessaging`
+
+⭐ Bonus of Unity Package way - Unity will tell you of version updates
+
+### From Releases
+
+Check out the latest [Releases](https://github.com/wallstop/DxMessaging/releases) to grab the Unity Package and import to your project.
+
+### From Source
+
+Grab a copy of this repo (either `git clone` [this repo](https://github.com/wallstop/DxMessaging) or [download a zip of the source](https://github.com/wallstop/DxMessaging/archive/refs/heads/master.zip)) and copy the contents to your project's `Assets` directory.
+
+### Manual - Manifest.json (alternative, not recommended)
 
 - Open your project’s `Packages/manifest.json` and add:
 
 ```json
 {
   "dependencies": {
-    "com.wallstop-studios.dxmessaging": "https://github.com/wallstop/DxMessaging.git?path=/Packages/com.wallstop-studios.dxmessaging"
+    "com.wallstop-studios.dxmessaging": "https://github.com/wallstop/DxMessaging.git"
   }
 }
 ```
 
-Minimum requirements
+## Minimum requirements
 
 - Unity 2021.3+ (LTS recommended). See [Compatibility](Compatibility.md) for Unity × Render Pipeline support (Built‑In, URP, HDRP).
 
-After install
+## After install
 
 - In your project, create a GameObject and add `MessagingComponent` to start sending/receiving.
 - Optional: enable diagnostics in Editor from the MessagingComponent inspector to see live emissions.

package/Docs/Integrations/Reflex.md

@@ -0,0 +1,292 @@
+# DxMessaging + Reflex
+
+[← Back to Integrations Overview](../README.md#-integrations)
+
+---
+
+## Overview
+
+**Reflex** is a minimal, lightweight dependency injection framework for Unity with blazing-fast performance. DxMessaging integrates seamlessly with Reflex, allowing you to:
+
+- **Inject `IMessageBus`** in any class with minimal overhead
+- **Use DI for construction** + DxMessaging for events (best of both worlds)
+- **Minimal API surface** — easy to learn, easy to use
+- **High performance** — Reflex + DxMessaging = minimal allocations
+
+**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected). Reflex's minimal API makes integration simple and straightforward.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- DxMessaging installed via UPM
+- Reflex installed (`gustavopsantos/Reflex`) via source or UPM
+
+### 1. Create a Reflex Installer
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using Reflex.Core;
+
+public sealed class DxMessagingInstaller : Installer
+{
+    public override void InstallBindings(ContainerDescriptor descriptor)
+    {
+        // Bind MessageBus as both concrete and interface
+        descriptor.AddSingleton(typeof(MessageBus), typeof(MessageBus));
+        descriptor.AddSingleton(typeof(IMessageBus), c => c.Resolve<MessageBus>());
+
+        // Optional: Enable automatic IMessageRegistrationBuilder binding
+        // Requires REFLEX_PRESENT define (auto-added by DxMessaging when Reflex detected)
+        #if REFLEX_PRESENT
+        descriptor.AddMessageRegistrationBuilder();
+        #endif
+    }
+}
+```
+
+#### Add to your scene
+
+1. Create a `SceneContext` or `ProjectContext` in your scene
+1. Add `DxMessagingInstaller` to the installers list
+1. Reflex will now inject `IMessageBus` automatically
+
+---
+
+## Usage Patterns
+
+### Pattern 1: Inject into Plain Classes (Recommended for Services)
+
+Use `IMessageRegistrationBuilder` to create message handlers in non-MonoBehaviour classes:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Core.Attributes;
+
+// Define a message
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct PlayerDamaged
+{
+    public readonly int damage;
+}
+
+// Service that listens to messages
+public sealed class DamageService
+{
+    private readonly MessageRegistrationLease _lease;
+
+    // Builder is injected automatically when using the installer
+    public DamageService(IMessageRegistrationBuilder registrationBuilder)
+    {
+        var options = new MessageRegistrationBuildOptions
+        {
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<PlayerDamaged>(OnPlayerDamaged);
+            }
+        };
+
+        _lease = registrationBuilder.Build(options);
+    }
+
+    public void Initialize()
+    {
+        _lease.Activate();  // Start listening
+    }
+
+    public void Dispose()
+    {
+        _lease.Dispose();   // Clean up
+    }
+
+    private static void OnPlayerDamaged(ref PlayerDamaged message)
+    {
+        UnityEngine.Debug.Log($"Player took {message.damage} damage!");
+    }
+}
+```
+
+#### Register the service in your installer
+
+```csharp
+public override void InstallBindings(ContainerDescriptor descriptor)
+{
+    descriptor.AddSingleton<DamageService>();
+    // Call Initialize() from a bootstrap MonoBehaviour
+}
+```
+
+**Note:** Reflex doesn't have lifecycle interfaces like `IInitializable`. Call `Initialize()` and `Dispose()` manually from a controlling MonoBehaviour or bootstrap script.
+
+---
+
+### Pattern 2: Configure MessagingComponents (For Existing MonoBehaviours)
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity;
+using Reflex.Attributes;
+using UnityEngine;
+
+[DisallowMultipleComponent]
+[RequireComponent(typeof(MessagingComponent))]
+public sealed class MessagingComponentConfigurator : MonoBehaviour
+{
+    [Inject]
+    private IMessageBus _messageBus;
+
+    private void Awake()
+    {
+        GetComponent<MessagingComponent>().Configure(
+            _messageBus,
+            MessageBusRebindMode.RebindActive
+        );
+    }
+}
+```
+
+#### Usage
+
+1. Add `MessagingComponentConfigurator` alongside any `MessagingComponent` in your prefabs
+1. Reflex will inject the bus in `Awake()` before handlers are registered
+1. Your message handlers now use the container-managed bus
+
+---
+
+### Pattern 3: Inject IMessageBus Directly
+
+For simple emission without listening, inject `IMessageBus` directly:
+
+```csharp
+public sealed class GameBootstrap : MonoBehaviour
+{
+    [Inject]
+    private IMessageBus _messageBus;
+
+    private void Start()
+    {
+        var message = new GameStarted();
+        _messageBus.EmitUntargeted(ref message);
+    }
+}
+```
+
+---
+
+## Advanced: Object Pooling
+
+When using object pooling with Reflex:
+
+```csharp
+public sealed class EnemyPool
+{
+    private readonly Container _container;
+    private readonly Queue<Enemy> _pool = new();
+
+    public EnemyPool(Container container)
+    {
+        _container = container;
+    }
+
+    public Enemy Spawn()
+    {
+        Enemy enemy;
+        if (_pool.Count > 0)
+        {
+            enemy = _pool.Dequeue();
+        }
+        else
+        {
+            enemy = Object.Instantiate(enemyPrefab);
+            _container.Inject(enemy);  // Inject dependencies
+        }
+        return enemy;
+    }
+
+    public void Return(Enemy enemy)
+    {
+        _pool.Enqueue(enemy);
+    }
+}
+```
+
+---
+
+## Testing with Reflex
+
+### Unit Tests
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using Reflex.Core;
+using NUnit.Framework;
+
+[TestFixture]
+public class DamageServiceTests
+{
+    [Test]
+    public void Initialize_ListensToMessages()
+    {
+        // Arrange
+        var builder = new ContainerBuilder();
+        var bus = new MessageBus();
+        builder.AddSingleton<IMessageBus>(bus);
+        builder.AddSingleton<DamageService>();
+        var container = builder.Build();
+
+        bool messageReceived = false;
+        var handler = new MessageHandler(new InstanceId(1), bus) { active = true };
+        var token = MessageRegistrationToken.Create(handler, bus);
+        _ = token.RegisterUntargeted<PlayerDamaged>(ref msg => messageReceived = true);
+        token.Enable();
+
+        // Act
+        var service = container.Resolve<DamageService>();
+        service.Initialize();
+        var message = new PlayerDamaged(25);
+        bus.EmitUntargeted(ref message);
+
+        // Assert
+        Assert.IsTrue(messageReceived);
+    }
+}
+```
+
+---
+
+## Checklist
+
+### Initial Setup
+
+- [ ] Install DxMessaging and Reflex
+- [ ] Create `DxMessagingInstaller` with bus bindings
+- [ ] Add installer to your `SceneContext` or `ProjectContext`
+- [ ] Add `#if REFLEX_PRESENT` check and call `descriptor.AddMessageRegistrationBuilder()`
+
+### Integration
+
+- [ ] Use `IMessageRegistrationBuilder` in plain classes
+- [ ] Call `Initialize()` and `Dispose()` manually from a bootstrap script
+- [ ] Add `MessagingComponentConfigurator` to prefabs with `MessagingComponent`
+- [ ] Replace `MessageHandler.MessageBus` references with injected `IMessageBus`
+
+### Pooling
+
+- [ ] Use `container.Inject(instance)` for pooled objects
+- [ ] Ensure injection happens before message handlers are registered
+
+### Testing
+
+- [ ] Create isolated `ContainerBuilder` instances in tests
+- [ ] Use `builder.AddSingleton<IMessageBus>(new MessageBus())` for test buses
+
+---
+
+## Next Steps
+
+- **[Zenject Integration](Zenject.md)** — Full-featured DI with extensive Unity support
+- **[VContainer Integration](VContainer.md)** — Lightweight alternative with scoped lifetimes
+- **[Back to Documentation Hub](../Index.md)** — Browse all docs

package/Docs/Integrations/Reflex.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 42871dfbdf4daa14c80c05d47f380c96
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: