com.wallstop-studios.dxmessaging 2.0.0 → 2.1.1

package/Docs/MessageBusProviders.md

@@ -0,0 +1,496 @@
+# Message Bus Providers
+
+DxMessaging provides a flexible provider system that lets you configure which message bus drives your components. This works both at design time (with ScriptableObject providers) and at runtime (with provider handles).
+
+This guide covers:
+
+- The `IMessageBusProvider` interface
+- Built-in ScriptableObject providers
+- The `MessageBusProviderHandle` system
+- How to create custom providers
+- Practical usage patterns
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [IMessageBusProvider Interface](#imessagebusprovider-interface)
+- [Built-in Providers](#built-in-providers)
+  - [Current Global Message Bus Provider](#current-global-message-bus-provider)
+  - [Initial Global Message Bus Provider](#initial-global-message-bus-provider)
+- [MessageBusProviderHandle](#messagebusproviderhandle)
+- [Using Providers with Components](#using-providers-with-components)
+- [Creating Custom Providers](#creating-custom-providers)
+- [Common Patterns](#common-patterns)
+
+---
+
+## Overview
+
+Providers abstract away the details of how a message bus is resolved. This lets you:
+
+- **Swap buses at design time** — Change a ScriptableObject reference without modifying code
+- **Integrate with DI containers** — Resolve buses from your container
+- **Support runtime reconfiguration** — Change which bus a component uses dynamically
+- **Isolate scenes or features** — Use different buses for different parts of your game
+
+If you're using the default global bus everywhere, you probably don't need providers. They're most useful when you need flexibility or are integrating with DI frameworks.
+
+---
+
+## IMessageBusProvider Interface
+
+All providers implement this simple interface:
+
+```csharp
+public interface IMessageBusProvider
+{
+    IMessageBus Resolve();
+}
+```
+
+When a component needs a bus, it calls `Resolve()` on its provider. The provider returns the appropriate bus instance.
+
+**Key insight:** By abstracting bus resolution behind this interface, components don't need to know whether they're using the global bus, a container-managed bus, or something completely custom.
+
+---
+
+## Built-in Providers
+
+DxMessaging ships with two ScriptableObject-based providers. These are assets you can create in the editor and reference in your scenes.
+
+### Current Global Message Bus Provider
+
+`CurrentGlobalMessageBusProvider` returns whatever bus is currently set as the global bus via `MessageHandler.MessageBus`. If you override the global bus at runtime, this provider reflects that change.
+
+#### Creating the asset
+
+Right-click in the Project window:
+
+```text
+Create > Wallstop Studios > DxMessaging > Message Bus Providers > Current Global Message Bus
+```
+
+#### When to use this
+
+- When you want components to follow the global bus, even if it changes
+- In DI scenarios where the global bus is replaced during bootstrap
+- For components that should always use the "active" bus
+
+#### Example
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity;
+using UnityEngine;
+
+[RequireComponent(typeof(MessagingComponent))]
+public sealed class MessagingComponentConfigurator : MonoBehaviour
+{
+    [SerializeField]
+    private CurrentGlobalMessageBusProvider provider;
+
+    private void Awake()
+    {
+        MessagingComponent component = GetComponent<MessagingComponent>();
+        component.Configure(provider, MessageBusRebindMode.RebindActive);
+    }
+}
+```
+
+### Initial Global Message Bus Provider
+
+`InitialGlobalMessageBusProvider` always returns the original startup bus that was created during static initialization. It ignores any calls to `SetGlobalMessageBus()` or `OverrideGlobalMessageBus()`.
+
+#### Creating the asset
+
+Right-click in the Project window:
+
+```text
+Create > Wallstop Studios > DxMessaging > Message Bus Providers > Initial Global Message Bus
+```
+
+#### When to use this
+
+- In diagnostic tools that need a stable reference point
+- When testing with temporary bus overrides but need access to the original
+- For debugging scenarios where you want to compare against the startup bus
+
+#### Example
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+
+public class DiagnosticLogger : MonoBehaviour
+{
+    [SerializeField]
+    private InitialGlobalMessageBusProvider initialProvider;
+
+    private void Start()
+    {
+        // Always logs to the original bus, even if global bus is overridden
+        IMessageBus startupBus = initialProvider.Resolve();
+
+        // Can compare with current global bus
+        bool busWasReplaced = startupBus != MessageHandler.MessageBus;
+        Debug.Log($"Bus replaced: {busWasReplaced}");
+    }
+}
+```
+
+---
+
+## MessageBusProviderHandle
+
+`MessageBusProviderHandle` is a serializable struct that can reference either:
+
+- A ScriptableObject provider (design-time configuration)
+- A runtime provider instance (runtime configuration)
+
+This gives you the best of both worlds: editor-friendly assets and runtime flexibility.
+
+### Key Methods
+
+```csharp
+// Create from a runtime provider
+MessageBusProviderHandle handle = MessageBusProviderHandle.FromProvider(myProvider);
+
+// Associate a runtime provider with an existing handle
+handle = handle.WithRuntimeProvider(myRuntimeProvider);
+
+// Resolve the provider (runtime takes precedence over asset)
+if (handle.TryGetProvider(out IMessageBusProvider provider))
+{
+    IMessageBus bus = provider.Resolve();
+}
+
+// Or resolve the bus directly
+IMessageBus bus = handle.ResolveBus();
+```
+
+### How It Works
+
+The handle has two fields:
+
+1. `Provider` — A serialized reference to a ScriptableObject provider (visible in Inspector)
+1. A runtime provider instance (not serialized)
+
+When you call `TryGetProvider()` or `ResolveBus()`, it checks:
+
+1. Is there a runtime provider? Use that first.
+1. Otherwise, use the serialized ScriptableObject provider.
+1. If neither exists, return null or the global default.
+
+**Why this matters:** You can design your prefabs with ScriptableObject references, then override them at runtime with DI-provided buses. No code changes needed.
+
+### Example: Design Time Configuration
+
+```csharp
+using DxMessaging.Unity;
+using UnityEngine;
+
+public class PlayerController : MessageAwareComponent
+{
+    [SerializeField]
+    private MessageBusProviderHandle providerHandle;
+
+    protected override void Awake()
+    {
+        // Configure with the handle before base.Awake()
+        if (providerHandle.TryGetProvider(out var provider))
+        {
+            ConfigureMessageBus(provider, MessageBusRebindMode.RebindActive);
+        }
+
+        base.Awake();
+    }
+}
+```
+
+In the Inspector, you can drag a `CurrentGlobalMessageBusProvider` or `InitialGlobalMessageBusProvider` asset onto the `providerHandle` field.
+
+### Example: Runtime Override
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity;
+
+public class DynamicConfigurator
+{
+    public void ConfigureWithRuntimeBus(MessageAwareComponent component, IMessageBus runtimeBus)
+    {
+        // Create a runtime provider
+        var provider = new RuntimeMessageBusProvider(runtimeBus);
+
+        // Wrap it in a handle
+        var handle = MessageBusProviderHandle.FromProvider(provider);
+
+        // Configure the component
+        component.ConfigureMessageBus(handle, MessageBusRebindMode.RebindActive);
+    }
+}
+
+// Simple runtime provider implementation
+public class RuntimeMessageBusProvider : IMessageBusProvider
+{
+    private readonly IMessageBus _bus;
+
+    public RuntimeMessageBusProvider(IMessageBus bus)
+    {
+        _bus = bus;
+    }
+
+    public IMessageBus Resolve() => _bus;
+}
+```
+
+---
+
+## Using Providers with Components
+
+### MessagingComponent
+
+`MessagingComponent` has three `Configure()` overloads:
+
+```csharp
+// Direct bus reference
+component.Configure(messageBus, MessageBusRebindMode.RebindActive);
+
+// Provider interface
+component.Configure(provider, MessageBusRebindMode.RebindActive);
+
+// Provider handle (design-time or runtime)
+component.Configure(providerHandle, MessageBusRebindMode.RebindActive);
+```
+
+### MessageAwareComponent
+
+`MessageAwareComponent` exposes `ConfigureMessageBus()` with the same three overloads:
+
+```csharp
+// Direct bus
+ConfigureMessageBus(messageBus, MessageBusRebindMode.RebindActive);
+
+// Provider
+ConfigureMessageBus(provider, MessageBusRebindMode.RebindActive);
+
+// Handle
+ConfigureMessageBus(providerHandle, MessageBusRebindMode.RebindActive);
+```
+
+**Best practice:** Call `ConfigureMessageBus()` in `Awake()` before calling `base.Awake()` to ensure the bus is set before message handlers are registered.
+
+### MessagingComponentInstaller
+
+`MessagingComponentInstaller` configures all `MessagingComponent` descendants in a hierarchy:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity;
+using UnityEngine;
+
+public class SceneSetup : MonoBehaviour
+{
+    [SerializeField]
+    private MessagingComponentInstaller installer;
+
+    [SerializeField]
+    private CurrentGlobalMessageBusProvider provider;
+
+    private void Awake()
+    {
+        // Configure installer with provider
+        installer.SetProvider(MessageBusProviderHandle.FromProvider(provider));
+
+        // Apply to all child MessagingComponents
+        installer.ApplyConfiguration();
+    }
+}
+```
+
+This is useful when you want to configure an entire prefab hierarchy or scene section with a single provider.
+
+---
+
+## Creating Custom Providers
+
+You can create your own providers for advanced scenarios:
+
+### Example: Container-Managed Provider
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+public class ContainerMessageBusProvider : IMessageBusProvider
+{
+    private readonly IDependencyContainer _container;
+
+    public ContainerMessageBusProvider(IDependencyContainer container)
+    {
+        _container = container;
+    }
+
+    public IMessageBus Resolve()
+    {
+        // Resolve from container each time
+        return _container.Resolve<IMessageBus>();
+    }
+}
+```
+
+### Example: ScriptableObject Provider for Specific Bus
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+
+[CreateAssetMenu(menuName = "Game/Messaging/Custom Bus Provider")]
+public class CustomBusProvider : ScriptableObject, IMessageBusProvider
+{
+    [SerializeField]
+    private bool useTestBus;
+
+    private static IMessageBus _testBus;
+    private static IMessageBus _productionBus;
+
+    public IMessageBus Resolve()
+    {
+        if (useTestBus)
+        {
+            return _testBus ??= new MessageBus();
+        }
+        return _productionBus ??= new MessageBus();
+    }
+}
+```
+
+### Example: Lazy-Initialized Provider
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+public class LazyMessageBusProvider : IMessageBusProvider
+{
+    private IMessageBus _cachedBus;
+
+    public IMessageBus Resolve()
+    {
+        // Only create the bus when first requested
+        return _cachedBus ??= new MessageBus();
+    }
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Design-Time Configuration
+
+Set up providers in the editor, no code needed:
+
+1. Create a `CurrentGlobalMessageBusProvider` asset in your project
+1. Add a `MessagingComponent` to your prefab
+1. Add a `MessagingComponentConfigurator` script that references the provider
+1. In Awake, call `component.Configure(provider, ...)`
+
+This lets designers swap providers without touching code.
+
+### Pattern 2: DI Container Integration
+
+Use a provider to resolve buses from your container:
+
+```csharp
+// In your DI installer
+container.RegisterInstance<IMessageBus>(new MessageBus());
+
+// In a bootstrap script
+var provider = new ContainerMessageBusProvider(container);
+MessageHandler.SetGlobalMessageBus(provider.Resolve());
+
+// Now all components use the container bus
+```
+
+### Pattern 3: Scene-Scoped Buses
+
+Create a provider that returns a scene-specific bus:
+
+```csharp
+public class SceneMessageBusManager : MonoBehaviour
+{
+    private IMessageBus _sceneBus;
+
+    private void Awake()
+    {
+        // Create scene-local bus
+        _sceneBus = new MessageBus();
+
+        // Configure all components in this scene
+        var components = GetComponentsInChildren<MessagingComponent>();
+        var provider = new RuntimeMessageBusProvider(_sceneBus);
+
+        foreach (var component in components)
+        {
+            component.Configure(provider, MessageBusRebindMode.RebindActive);
+        }
+    }
+}
+```
+
+Messages sent in this scene stay in this scene.
+
+### Pattern 4: Runtime Provider Override
+
+Start with a design-time provider, override at runtime:
+
+```csharp
+public class RuntimeReconfiguration : MonoBehaviour
+{
+    [SerializeField]
+    private MessageAwareComponent component;
+
+    [SerializeField]
+    private MessageBusProviderHandle designTimeHandle;  // Set in Inspector
+
+    private void Start()
+    {
+        // Use design-time provider initially
+        component.ConfigureMessageBus(designTimeHandle, MessageBusRebindMode.RebindActive);
+    }
+
+    public void SwitchToRuntimeBus(IMessageBus runtimeBus)
+    {
+        // Override with runtime provider
+        var runtimeProvider = new RuntimeMessageBusProvider(runtimeBus);
+        var handle = MessageBusProviderHandle.FromProvider(runtimeProvider);
+        component.ConfigureMessageBus(handle, MessageBusRebindMode.RebindActive);
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+| Type                                   | Purpose                                       | Use Case                          |
+| -------------------------------------- | --------------------------------------------- | --------------------------------- |
+| `IMessageBusProvider`                  | Interface for bus resolution                  | Create custom providers           |
+| `CurrentGlobalMessageBusProvider`      | ScriptableObject returning current global bus | Follow the active global bus      |
+| `InitialGlobalMessageBusProvider`      | ScriptableObject returning startup bus        | Diagnostics, stable reference     |
+| `MessageBusProviderHandle`             | Serializable wrapper for providers            | Design-time + runtime flexibility |
+| `handle.FromProvider(provider)`        | Create handle from runtime provider           | Runtime configuration             |
+| `handle.WithRuntimeProvider(provider)` | Add runtime provider to handle                | Override design-time config       |
+| `handle.TryGetProvider(out provider)`  | Resolve provider from handle                  | Get the actual provider           |
+| `handle.ResolveBus()`                  | Resolve bus directly                          | Shortcut to get bus               |
+
+---
+
+## See Also
+
+- **[Runtime Configuration](RuntimeConfiguration.md)** — Setting and overriding global buses, re-binding registrations
+- **[DI Integration Guides](Integrations/)** — Zenject, VContainer, and Reflex integration patterns
+- **[Unity Integration](UnityIntegration.md)** — MessagingComponent and MessageAwareComponent deep dive
+- **[Back to Documentation Hub](Index.md)** — Browse all docs

package/Docs/MessageBusProviders.md.meta

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

package/Docs/MessageTypes.md

@@ -12,6 +12,33 @@ This guide introduces the three message categories in DxMessaging with concepts,
 - Targeted: directed at one recipient (e.g., heal Player by 10).
 - Broadcast: emitted from a source for anyone to observe (e.g., Enemy took 5 damage).
 
+### Quick Decision Guide
+
+```mermaid
+flowchart TD
+    Start([Choose Message Type])
+
+    Start --> Q1{Is it a global<br/>announcement?}
+
+    Q1 -->|Yes<br/>e.g., game paused,<br/>settings changed| Untargeted[✅ Use UNTARGETED<br/>Everyone listens]
+
+    Q1 -->|No| Q2{Are you commanding<br/>a specific entity?}
+
+    Q2 -->|Yes<br/>e.g., heal Player,<br/>open Chest #3| Targeted[✅ Use TARGETED<br/>One recipient]
+
+    Q2 -->|No| Q3{Is an entity announcing<br/>something happened?}
+
+    Q3 -->|Yes<br/>e.g., Enemy died,<br/>Chest opened| Broadcast[✅ Use BROADCAST<br/>Anyone can observe]
+
+    Q3 -->|No| Rethink[🤔 Rethink your<br/>message design]
+
+    style Untargeted fill:#91d5ff,stroke:#096dd9,stroke-width:3px,color:#000
+    style Targeted fill:#ffd591,stroke:#d46b08,stroke-width:3px,color:#000
+    style Broadcast fill:#95de64,stroke:#237804,stroke-width:3px,color:#000
+    style Rethink fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
+    style Start fill:#f0f0f0,stroke:#595959,stroke-width:2px,color:#000
+```
+
 ## Untargeted Messages
 
 - Use for cross‑cutting notifications: settings changed, scene loaded, world regenerated.

package/Docs/MigrationGuide.md

@@ -431,6 +431,51 @@ Phase them out gradually:
 1. Migrate listeners
 1. Remove references in next refactor pass
 
+### Adopt the DI Registration Builder
+
+Once the bus/provider abstractions are in place, wire listeners through the registration builder instead of hand-rolling handler lifecycles. Benefits:
+
+- Container-managed lifetimes (`IDisposable`, `IInitializable`, `IStartable`, etc.) automatically enable/disable registrations.
+- Centralises diagnostics toggles and message bus selection.
+- Keeps MonoBehaviours and pure C# services on the same path.
+
+```csharp
+public sealed class InventoryService : IStartable, IDisposable
+{
+    private readonly MessageRegistrationLease lease;
+
+    public InventoryService(IMessageRegistrationBuilder registrationBuilder)
+    {
+        lease = registrationBuilder.Build(new MessageRegistrationBuildOptions
+        {
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<InventoryChanged>(OnInventoryChanged);
+            }
+        });
+    }
+
+    public void Start()
+    {
+        lease.Activate();
+    }
+
+    public void Dispose()
+    {
+        lease.Dispose();
+    }
+
+    private static void OnInventoryChanged(ref InventoryChanged message)
+    {
+        // respond to updates
+    }
+}
+```
+
+- **Unity scene code:** Call `MessagingComponent.CreateRegistrationBuilder()` during dependency injection and share the lease across helper services or pooled objects.
+- **Container shims:** Define `ZENJECT_PRESENT`, `VCONTAINER_PRESENT`, or `REFLEX_PRESENT` to enable the built-in installers/extensions that register the builder automatically when those frameworks are present.
+- **Tests:** Prefer the builder to create isolated tokens tied to the test fixture lifecycle.
+
 ### "Should we migrate tests?"
 
 Yes! Tests benefit from isolated message buses: