com.wallstop-studios.dxmessaging 2.0.0-rc27.3.1 → 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/GettingStarted.md

@@ -27,13 +27,31 @@ By the end of this guide, you will:
 
 ## What is DxMessaging?
 
-DxMessaging is a high‑performance, type‑safe messaging system for Unity. It replaces sprawling C# events, brittle UnityEvents, and ad‑hoc global buses with clean, observable, and predictable communication.
+**Picture this:** You're building a Unity game. Your player takes damage. Now you need to:
 
-Think of it as the event system you wish Unity had built‑in:
+- Update the health bar UI
+- Play a damage sound
+- Show a damage number popup
+- Track damage for analytics
+- Check if an achievement unlocked
+- Maybe trigger a tutorial tip
 
-- Decoupled systems without manual subscribe/unsubscribe headaches
-- Predictable execution order with powerful interception and diagnostics
-- Scales from prototypes to large production codebases
+**The old way:** The Player script needs references to all 6 systems. Or they all need references to the Player. It's a tangled mess.
+
+**The DxMessaging way:** The Player emits one message: `TookDamage(25)`. Everyone who cares receives it automatically. Zero coupling, zero leaks, zero hassle.
+
+---
+
+**Technical summary:** DxMessaging is a high-performance, type-safe messaging system that replaces C# events, UnityEvents, and global event buses with a clean, observable, and predictable communication pattern.
+
+**Think of it as:** The event system Unity should have shipped with.
+
+### What you get
+
+- **Decoupled systems** - no manual subscribe/unsubscribe, impossible to leak
+- **Predictable execution** - priority-based ordering, see exactly what runs when
+- **Actually debuggable** - Inspector shows message history with timestamps
+- **Scales effortlessly** - works for prototypes and 100k+ line codebases
 
 ## Quick Start
 
@@ -91,27 +109,76 @@ heal.EmitGameObjectTargeted(playerGameObject);
 
 ## Message Types
 
-- Untargeted: fire‑and‑forget announcements (no specific receiver)
-- Targeted: deliver to a specific receiver (GameObject, InstanceId, etc.)
-- Broadcast: deliver to all listeners (optionally including source metadata)
+### New to messaging? Use this decision tree
+
+```text
+Is it a global announcement? (pause, settings, scene load)
+  → Use UNTARGETED
+
+Are you commanding a specific entity? (heal Player, open Chest #3)
+  → Use TARGETED
+
+Is an entity announcing something happened? (Enemy died, Chest opened)
+  → Use BROADCAST
+```
+
+#### Examples
+
+```csharp
+// Untargeted: "Everyone, the game paused!"
+[DxUntargetedMessage]
+public struct GamePaused { }
+
+// Targeted: "Player, heal yourself by 50!"
+[DxTargetedMessage]
+public struct Heal { public int amount; }
 
-See [MessageTypes](MessageTypes.md) for details and APIs.
+// Broadcast: "I (Enemy #3) just died!"
+[DxBroadcastMessage]
+public struct EnemyDied { public string enemyName; }
+```
+
+**Still confused?** See the [Visual Guide](VisualGuide.md) for beginner-friendly explanations, or [MessageTypes](MessageTypes.md) for technical details.
 
 ## Common Patterns
 
-- UI reacting to gameplay state via targeted messages
-- Cross‑system notifications using broadcast messages
-- Configuration changes/feature toggles via untargeted announcements
+### Want to see real examples? Here's what DxMessaging excels at
+
+- **UI reacting to gameplay** - Health bar updates when player takes damage (without UI knowing about Player)
+- **Achievement systems** - Track ALL kills across ALL enemies with ONE listener
+- **Cross-system coordination** - Scene transitions coordinate audio, save system, and UI automatically
+- **Input handling** - Decouple input system from player controller
+- **Analytics** - Track all events without polluting gameplay code
 
-See [ListeningPatterns](ListeningPatterns.md) and [Patterns](Patterns.md) for deeper examples.
+**Want code examples?** See [Patterns](Patterns.md) for production-ready patterns and [ListeningPatterns](ListeningPatterns.md) for advanced techniques.
 
 ## Troubleshooting
 
-- Nothing happens? Ensure your listener registered in `RegisterMessageHandlers` and the component is enabled.
-- Duplicate behavior? Check for multiple registrations or missing token disposal on custom lifecycles.
-- Ordering issues? Use interceptors/post‑processors to control/inspect flow.
+### "My handler isn't being called!"
+
+✅ Checklist:
+
+1. Did you call `base.RegisterMessageHandlers()` first?
+1. Is your component enabled in the scene?
+1. Are you emitting to the right target? (Check GameObject vs Component)
+1. Check the Inspector - does the registration show up?
+
+#### "My message is firing twice!"
+
+- Check if you accidentally registered the same handler multiple times
+- Make sure you're calling `base.RegisterMessageHandlers()` only once
+
+##### "I get a compile error on `[DxAutoConstructor]`"
+
+- Did you mark the struct as `partial`? (required for code generation)
+- Example: `public readonly partial struct MyMessage`
+
+###### "Which message type should I use?"
+
+- See the decision tree in [Message Types](#message-types) above
+- When in doubt, start with `Broadcast` - it's the most flexible
 
-See [Troubleshooting](Troubleshooting.md) for more.
+**Still stuck?** See [Troubleshooting](Troubleshooting.md) for the complete guide or [FAQ](FAQ.md) for common questions.
 
 ## Next Steps
 

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.