com.wallstop-studios.dxmessaging 2.0.0 → 2.1.1

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]
+[DxAutoConstructor]
+public readonly partial struct ScoreChanged
+{
+    public readonly int 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

@@ -186,34 +186,32 @@ public readonly partial struct ComplexMessage
 
 ## Why Use Attributes Instead of Manual Implementation
 
-### ❌ Manual Way (Verbose, Error-Prone)
+### ✅ Attribute Definition (Clean, Automatic)
 
 ```csharp
-public readonly struct Heal : ITargetedMessage<Heal>
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct Heal
 {
     public readonly int amount;
-
-    // You write this yourself (boring!)
-    public Heal(int amount)
-    {
-        this.amount = amount;
-    }
-
-    // Required plumbing (easy to mess up!)
-    public Type MessageType => typeof(Heal);
 }
 ```
 
-### ✅ Attribute Way (Clean, Automatic)
+### What the generator emits (for reference)
 
 ```csharp
-[DxTargetedMessage]
-[DxAutoConstructor]
-public readonly partial struct Heal
+// Auto-generated by DxMessaging (no need to hand-write this)
+public readonly partial struct Heal : ITargetedMessage<Heal>
 {
     public readonly int amount;
+
+    public Heal(int amount)
+    {
+        this.amount = amount;
+    }
+
+    public Type MessageType => typeof(Heal);
 }
-// Constructor and plumbing generated automatically!
 ```
 
 #### Benefits
@@ -223,14 +221,28 @@ public readonly partial struct Heal
 - ✅ **Cleaner** - Focus on data, not boilerplate
 - ✅ **Refactor-safe** - Add field? Constructor updates automatically!
 
-## Complete Example: Before & After
+## Complete Example: Attribute Definition vs Generated Output
 
-### Before (Manual - 20 lines)
+### Attribute Definition (8 lines)
 
 ```csharp
-using DxMessaging.Core.Messages;
+using DxMessaging.Core.Attributes;
 
-public readonly struct PlayerDamaged : IBroadcastMessage<PlayerDamaged>
+[DxBroadcastMessage]
+[DxAutoConstructor]
+public readonly partial struct PlayerDamaged
+{
+    public readonly int amount;
+    public readonly string damageType;
+    public readonly GameObject source;
+}
+```
+
+### Generated Output (20 lines you never write)
+
+```csharp
+// Auto-generated by DxMessaging (for reference only)
+public readonly partial struct PlayerDamaged : IBroadcastMessage<PlayerDamaged>
 {
     public readonly int amount;
     public readonly string damageType;
@@ -247,65 +259,76 @@ public readonly struct PlayerDamaged : IBroadcastMessage<PlayerDamaged>
 }
 ```
 
-### After (Attributes - 9 lines!)
+### Result
 
-```csharp
-using DxMessaging.Core.Attributes;
+- ✅ Same functionality
+- ✅ Less code to maintain
+- ✅ Automatically updates when you add/remove fields
+- ✅ Works for class messages too
+- ✅ Zero effort once you mark the struct partial
 
-[DxBroadcastMessage]
+## Advanced: Manual Implementation (When Attributes Aren't Enough)
+
+Attributes cover almost every scenario. If you intentionally drop `[DxTargetedMessage]`, `[DxUntargetedMessage]`, or `[DxBroadcastMessage]`, you'll need to hand-write the interface implementations and constructors shown in the “generated output” examples. Keep the attributes unless you have a very specific data-backed reason not to.
+
+### Generic Message Interfaces (Zero-Boxing for Structs)
+
+`readonly struct` messages marked with the attributes already implement the generic interfaces, so emissions stay allocation-free. You get the same performance characteristics as the manual approach without writing any plumbing.
+
+```csharp
+[DxTargetedMessage]
 [DxAutoConstructor]
-public readonly partial struct PlayerDamaged
+public readonly partial struct Heal
 {
     public readonly int amount;
-    public readonly string damageType;
-    public readonly GameObject source;
 }
 ```
 
-**Result:** Same functionality, 55% less code, zero boilerplate!
+### "Do I HAVE to use attributes?"
 
-## Advanced: Manual Implementation (When Attributes Aren't Enough)
+Technically no—but without them you must write the constructor, interface implementation, and `MessageType` property yourself (for speed, you can optionally leave this off, but it might box on certain call paths). Leaving the attributes on keeps everything consistent for the whole team.
 
-Sometimes you might want full control and skip source generators. You can implement interfaces manually:
+```csharp
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct MyMsg { }
+```
 
-### Generic Message Interfaces (Zero-Boxing for Structs)
+### "What if I want custom constructor logic?"
 
-**For performance-critical code**, implement the generic interfaces directly:
+Keep the attributes and add a factory/helper so you still benefit from the generated constructor:
 
 ```csharp
-using DxMessaging.Core.Messages;
-
-public readonly struct Heal : ITargetedMessage<Heal>
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct ComplexMessage
 {
-    public readonly int amount;
+    public readonly int value;
 
-    public Heal(int amount)
+    public static ComplexMessage FromRaw(int rawValue)
     {
-        this.amount = amount;
+        int clamped = Math.Clamp(rawValue, 0, 100);
+        return new ComplexMessage(clamped);
     }
-
-    // Required for IMessage
-    public Type MessageType => typeof(Heal);
 }
 ```
 
-#### Why use generics?
+If you truly must write a custom constructor, drop `[DxAutoConstructor]` for that type but keep the `[DxUntargetedMessage]`/`[DxTargetedMessage]` attribute so the interface plumbing stays consistent.
 
-- Avoids boxing structs (important for performance)
-- Provides stable `MessageType` without `GetType()` calls
-- Same performance as attribute-based approach
+### "Can I mix attribute-based and manual messages?"
 
-##### When to use
+Yes. Attribute-driven messages happily coexist with string messages and any manual implementations you already have. You can migrate gradually by converting one message at a time:
 
-- Hot path messages (sent/received every frame)
-- Very large structs where boxing matters
-- When you want explicit control
-
-###### When to use attributes
+```csharp
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct MessageA
+{
+    public readonly int value;
+}
 
-- 99% of cases (they generate the same code!)
-- Cleaner, less boilerplate
-- Easier to maintain
+// Existing manual message types keep working alongside attribute-driven ones.
+```
 
 ## Extension Methods (Emit Helpers)
 
@@ -355,7 +378,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
@@ -549,50 +572,42 @@ public readonly partial struct MyMessage : IUntargetedMessage<MyMessage>
 
 ### "What if I want custom constructor logic?"
 
-Use manual implementation:
+Keep the attributes and wrap the generated constructor with a helper so you can inject custom logic without losing the source-generated plumbing:
 
 ```csharp
-public readonly struct ComplexMessage : IUntargetedMessage<ComplexMessage>
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct ComplexMessage
 {
     public readonly int value;
 
-    public ComplexMessage(int rawValue)
+    public static ComplexMessage FromRaw(int rawValue)
     {
-        // Custom logic
-        value = Math.Clamp(rawValue, 0, 100);
+        int clamped = Math.Clamp(rawValue, 0, 100);
+        return new ComplexMessage(clamped);
     }
-
-    public Type MessageType => typeof(ComplexMessage);
 }
 ```
 
+If you truly need to hand-craft the constructor, drop `[DxAutoConstructor]` for that specific type but keep the `[DxUntargetedMessage]`/`[DxTargetedMessage]` attribute so the interface implementation is still generated.
+
 ### "Do attributes affect runtime performance?"
 
 **No!** Source generation happens at **compile time**. Generated code is identical to hand-written code. Zero runtime overhead.
 
 ### "Can I mix attributes and manual implementation?"
 
-**Not on the same type**, but you can have:
-
-- Some messages using attributes
-- Other messages using manual implementation
-- Mix and match across your codebase
+Yes. Attribute-driven messages happily coexist with any legacy manual messages or string messages you already emit. Convert types gradually—one message at a time:
 
 ```csharp
-// Message A: Attributes
 [DxUntargetedMessage]
 [DxAutoConstructor]
-public readonly partial struct MessageA { public readonly int value; }
-
-// Message B: Manual
-public readonly struct MessageB : IUntargetedMessage<MessageB>
+public readonly partial struct MessageA
 {
     public readonly int value;
-    public MessageB(int value) { this.value = value; }
-    public Type MessageType => typeof(MessageB);
 }
 
-// Both work perfectly together!
+// Existing manual messages keep working alongside attribute-driven ones.
 ```
 
 ## Troubleshooting Source Generators
@@ -609,7 +624,7 @@ public readonly struct MessageB : IUntargetedMessage<MessageB>
 ##### Fix
 
 ```csharp
-// ❌ Missing partial
+// ❌ Missing partial, will not compile
 [DxAutoConstructor]
 public readonly struct MyMsg { }
 

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.