com.wallstop-studios.dxmessaging 2.0.0 → 2.1.0

package/Docs/Integrations/VContainer.md

@@ -0,0 +1,324 @@
+# DxMessaging + VContainer
+
+[← Back to Integrations Overview](../README.md#-integrations)
+
+---
+
+## Overview
+
+**VContainer** is a fast, lightweight dependency injection framework for Unity with minimal overhead. DxMessaging integrates seamlessly with VContainer, allowing you to:
+
+- **Inject `IMessageBus`** in any class with deterministic lifetimes
+- **Create per-scope buses** for scene isolation (perfect for additive scenes)
+- **Use DI for construction** + DxMessaging for events (best of both worlds)
+- **Minimal performance overhead** — VContainer + DxMessaging = blazing fast
+
+**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected). VContainer's scoped lifetimes make it perfect for per-scene message buses.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- DxMessaging installed via UPM
+- VContainer installed (Git URL or OpenUPM)
+
+### 1. Create a LifetimeScope with DxMessaging
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+using VContainer;
+using VContainer.Unity;
+
+public sealed class MessagingLifetimeScope : LifetimeScope
+{
+    protected override void Configure(IContainerBuilder builder)
+    {
+        // Register MessageBus as both concrete and interface
+        builder.Register<MessageBus>(Lifetime.Singleton).As<IMessageBus>();
+
+        // Optional: Enable automatic IMessageRegistrationBuilder binding
+        // Requires VCONTAINER_PRESENT define (auto-added by DxMessaging when VContainer detected)
+        #if VCONTAINER_PRESENT
+        builder.RegisterMessageRegistrationBuilder();
+        #endif
+    }
+}
+```
+
+#### Add to your scene
+
+1. Create an empty GameObject in your scene
+1. Add the `MessagingLifetimeScope` component
+1. This creates a singleton bus for the entire scene
+
+**Tip:** Use `Lifetime.Singleton` for project-wide buses, or `Lifetime.Scoped` for isolated scene/feature buses.
+
+---
+
+## 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;
+using VContainer.Unity;
+
+// Define a message
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct PlayerSpawned
+{
+    public readonly int playerId;
+}
+
+// Service that listens to messages
+public sealed class PlayerService : IStartable, IDisposable
+{
+    private readonly MessageRegistrationLease _lease;
+
+    // Builder is injected automatically when using the scope
+    public PlayerService(IMessageRegistrationBuilder registrationBuilder)
+    {
+        var options = new MessageRegistrationBuildOptions
+        {
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<PlayerSpawned>(OnPlayerSpawned);
+            }
+        };
+
+        _lease = registrationBuilder.Build(options);
+    }
+
+    public void Start()
+    {
+        _lease.Activate();  // Start listening when container starts
+    }
+
+    public void Dispose()
+    {
+        _lease.Dispose();   // Clean up when container disposes
+    }
+
+    private static void OnPlayerSpawned(ref PlayerSpawned message)
+    {
+        UnityEngine.Debug.Log($"Player {message.playerId} spawned!");
+    }
+}
+```
+
+#### Register the service in your scope
+
+```csharp
+protected override void Configure(IContainerBuilder builder)
+{
+    builder.Register<MessageBus>(Lifetime.Singleton).As<IMessageBus>();
+    #if VCONTAINER_PRESENT
+    builder.RegisterMessageRegistrationBuilder();
+    #endif
+
+    // Register your service
+    builder.RegisterEntryPoint<PlayerService>();
+}
+```
+
+---
+
+### Pattern 2: Configure MessagingComponents (For Existing MonoBehaviours)
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity;
+using UnityEngine;
+using VContainer;
+using VContainer.Unity;
+
+[RequireComponent(typeof(MessagingComponent))]
+public sealed class MessagingComponentConfigurator : MonoBehaviour, IStartable
+{
+    [Inject]
+    private readonly IMessageBus _messageBus;
+
+    private MessagingComponent _messagingComponent;
+
+    private void Awake()
+    {
+        _messagingComponent = GetComponent<MessagingComponent>();
+    }
+
+    public void Start()
+    {
+        _messagingComponent.Configure(_messageBus, MessageBusRebindMode.RebindActive);
+    }
+}
+```
+
+#### Usage
+
+1. Add `MessagingComponentConfigurator` alongside any `MessagingComponent` in your prefabs
+1. VContainer will inject the bus via `IStartable.Start()` 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 GameInitializer : IStartable
+{
+    private readonly IMessageBus _messageBus;
+
+    public GameInitializer(IMessageBus messageBus)
+    {
+        _messageBus = messageBus;
+    }
+
+    public void Start()
+    {
+        var message = new GameStarted();
+        _messageBus.EmitUntargeted(ref message);
+    }
+}
+```
+
+---
+
+## Advanced: Scene Scopes and Isolation
+
+VContainer's scoped lifetimes make it perfect for per-scene message buses. This is useful for additive scenes or isolated gameplay features:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using VContainer;
+using VContainer.Unity;
+
+public sealed class LevelLoader
+{
+    private readonly LifetimeScope _parentScope;
+
+    public LevelLoader(LifetimeScope parentScope)
+    {
+        _parentScope = parentScope;
+    }
+
+    public LifetimeScope LoadLevel(GameObject lifetimeScopePrefab)
+    {
+        // Create a child scope with its own MessageBus
+        return _parentScope.CreateChildFromPrefab(lifetimeScopePrefab, builder =>
+        {
+            builder.Register<MessageBus>(Lifetime.Singleton).As<IMessageBus>();
+            #if VCONTAINER_PRESENT
+            builder.RegisterMessageRegistrationBuilder();
+            #endif
+        });
+    }
+}
+```
+
+### Benefits
+
+- Each scene gets its own isolated message bus
+- Messages don't leak between scenes
+- Perfect for multiplayer lobbies, mini-games, or feature-scoped events
+
+---
+
+## Testing with VContainer
+
+### Unit Tests
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using VContainer;
+using VContainer.Unity;
+using NUnit.Framework;
+
+[TestFixture]
+public class GameInitializerTests
+{
+    [Test]
+    public void Initialize_EmitsGameStarted()
+    {
+        // Arrange
+        var builder = new ContainerBuilder();
+        var bus = new MessageBus();
+        builder.RegisterInstance<IMessageBus>(bus);
+        builder.RegisterEntryPoint<GameInitializer>();
+        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<GameStarted>(ref msg => messageReceived = true);
+        token.Enable();
+
+        // Act
+        container.Resolve<GameInitializer>().Start();
+
+        // Assert
+        Assert.IsTrue(messageReceived);
+    }
+}
+```
+
+### Play-Mode Tests
+
+For play-mode tests, create a temporary `LifetimeScope`:
+
+```csharp
+[UnityTest]
+public IEnumerator PlayMode_MessageBusIsolation()
+{
+    // Create isolated scope for this test
+    var scope = LifetimeScope.Create(builder =>
+    {
+        builder.Register<MessageBus>(Lifetime.Singleton).As<IMessageBus>();
+    });
+
+    var bus = scope.Container.Resolve<IMessageBus>();
+    // ... test logic ...
+
+    scope.Dispose();  // Clean up
+    yield return null;
+}
+```
+
+---
+
+## Checklist
+
+### Initial Setup
+
+- [ ] Install DxMessaging and VContainer
+- [ ] Create `MessagingLifetimeScope` with `builder.Register<MessageBus>().As<IMessageBus>()`
+- [ ] Add scope to your scene as a GameObject component
+- [ ] Add `#if VCONTAINER_PRESENT` check and call `builder.RegisterMessageRegistrationBuilder()`
+
+### Integration
+
+- [ ] Use `IMessageRegistrationBuilder` in plain classes with `IStartable`/`IDisposable`
+- [ ] Add `MessagingComponentConfigurator` to prefabs with `MessagingComponent`
+- [ ] Replace `MessageHandler.MessageBus` references with injected `IMessageBus`
+- [ ] Consider using scoped buses for scene isolation
+
+### Testing
+
+- [ ] Create isolated `ContainerBuilder` instances in tests
+- [ ] Use `builder.RegisterInstance<IMessageBus>(new MessageBus())` for test buses
+- [ ] Dispose scopes after tests to ensure clean teardown
+
+---
+
+## Next Steps
+
+- **[Zenject Integration](Zenject.md)** — Full-featured DI with extensive Unity support
+- **[Reflex Integration](Reflex.md)** — Minimal DI framework
+- **[Back to Documentation Hub](../Index.md)** — Browse all docs

package/Docs/Integrations/VContainer.md.meta

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

package/Docs/Integrations/Zenject.md

@@ -0,0 +1,333 @@
+# DxMessaging + Zenject
+
+[← Back to Integrations Overview](../README.md#-integrations)
+
+---
+
+## Overview
+
+**Zenject** (also known as Extenject) is a powerful dependency injection framework for Unity. DxMessaging integrates seamlessly with Zenject, allowing you to:
+
+- **Inject `IMessageBus`** as a singleton dependency in any class
+- **Use DI for construction** + DxMessaging for events (best of both worlds)
+- **Create per-scope message buses** for scene or gameplay isolation
+- **Bridge to SignalBus** for gradual migration from Zenject Signals
+
+**Why combine DI + Messaging?** Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected). This keeps your architecture clean and testable.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- DxMessaging installed via UPM
+- Zenject/Extenject installed (source or UPM)
+
+### 1. Create an Installer
+
+Create a `DxMessagingInstaller` to bind the message bus to your Zenject container:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using Zenject;
+
+public sealed class DxMessagingInstaller : MonoInstaller
+{
+    public override void InstallBindings()
+    {
+        // Bind MessageBus as a singleton and expose IMessageBus interface
+        Container.BindInterfacesAndSelfTo<MessageBus>().AsSingle();
+
+        // Optional: Enable automatic IMessageRegistrationBuilder binding
+        // Requires ZENJECT_PRESENT define (auto-added by DxMessaging when Zenject detected)
+        #if ZENJECT_PRESENT
+        Container.RegisterMessageRegistrationBuilder();
+        #endif
+    }
+}
+```
+
+#### Add to your ProjectContext
+
+1. Select (or create) your `ProjectContext` prefab
+1. Add `DxMessagingInstaller` as a MonoInstaller
+1. Save the prefab
+
+---
+
+## 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;
+using Zenject;
+
+// Define a message
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct PlayerSpawned
+{
+    public readonly int playerId;
+}
+
+// Service that listens to messages
+public sealed class PlayerController : IInitializable, IDisposable
+{
+    private readonly MessageRegistrationLease _lease;
+
+    // Builder is injected automatically when using the installer
+    public PlayerController(IMessageRegistrationBuilder registrationBuilder)
+    {
+        var options = new MessageRegistrationBuildOptions
+        {
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<PlayerSpawned>(OnPlayerSpawned);
+            }
+        };
+
+        _lease = registrationBuilder.Build(options);
+    }
+
+    public void Initialize()
+    {
+        _lease.Activate();  // Start listening when container initializes
+    }
+
+    public void Dispose()
+    {
+        _lease.Dispose();   // Clean up when container disposes
+    }
+
+    private static void OnPlayerSpawned(ref PlayerSpawned message)
+    {
+        UnityEngine.Debug.Log($"Player {message.playerId} spawned!");
+    }
+}
+```
+
+#### Register the service in your installer
+
+```csharp
+public sealed class GameInstaller : MonoInstaller
+{
+    public override void InstallBindings()
+    {
+        Container.BindInterfacesAndSelfTo<PlayerController>().AsSingle();
+    }
+}
+```
+
+---
+
+### Pattern 2: Configure MessagingComponents (For Existing MonoBehaviours)
+
+If you have existing `MessageAwareComponent` scripts, you can inject the container-managed bus into them:
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using DxMessaging.Unity;
+using UnityEngine;
+using Zenject;
+
+[RequireComponent(typeof(MessagingComponent))]
+public sealed class MessagingComponentConfigurator : MonoBehaviour
+{
+    [Inject]
+    private IMessageBus _messageBus;
+
+    private void Awake()
+    {
+        MessagingComponent component = GetComponent<MessagingComponent>();
+        component.Configure(_messageBus, MessageBusRebindMode.RebindActive);
+    }
+}
+```
+
+#### Usage
+
+1. Add `MessagingComponentConfigurator` alongside any `MessagingComponent` in your prefabs
+1. Zenject will inject the bus before `RegisterMessageHandlers` is called
+1. Your message handlers now use the container-managed bus
+
+**Alternative approach:** Extend `MessageAwareComponent` and override `Awake`:
+
+```csharp
+public class ZenjectAwareComponent : MessageAwareComponent
+{
+    [Inject]
+    private IMessageBus _messageBus;
+
+    protected override void Awake()
+    {
+        Configure(_messageBus, MessageBusRebindMode.RebindActive);
+        base.Awake();
+    }
+}
+```
+
+---
+
+### Pattern 3: Inject IMessageBus Directly
+
+For simple cases, inject `IMessageBus` and emit messages directly:
+
+```csharp
+public sealed class GameInitializer : IInitializable
+{
+    private readonly IMessageBus _messageBus;
+
+    public GameInitializer(IMessageBus messageBus)
+    {
+        _messageBus = messageBus;
+    }
+
+    public void Initialize()
+    {
+        var message = new GameStarted();
+        _messageBus.EmitUntargeted(ref message);
+    }
+}
+```
+
+---
+
+## Advanced: Bridging to Zenject Signals
+
+If you're gradually migrating from Zenject Signals to DxMessaging, you can create a bridge:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+using System;
+using Zenject;
+
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct SceneTransition
+{
+    public readonly string sceneName;
+}
+
+public sealed class DxToSignalBridge : IInitializable, IDisposable
+{
+    private readonly IMessageBus _messageBus;
+    private readonly SignalBus _signalBus;
+    private MessageRegistrationToken _token;
+
+    public DxToSignalBridge(IMessageBus messageBus, SignalBus signalBus)
+    {
+        _messageBus = messageBus;
+        _signalBus = signalBus;
+    }
+
+    public void Initialize()
+    {
+        // Create a handler to listen to DxMessaging events
+        var handler = new MessageHandler(new InstanceId(0), _messageBus)
+        {
+            active = true
+        };
+        _token = MessageRegistrationToken.Create(handler, _messageBus);
+
+        // Bridge DxMessaging → Zenject Signals
+        _ = _token.RegisterUntargeted<SceneTransition>(OnSceneTransition);
+        _token.Enable();
+    }
+
+    public void Dispose()
+    {
+        _token?.Disable();
+    }
+
+    private void OnSceneTransition(ref SceneTransition message)
+    {
+        // Forward to SignalBus for legacy consumers
+        _signalBus.Fire(message);
+    }
+}
+```
+
+### Register the bridge in your installer
+
+```csharp
+public override void InstallBindings()
+{
+    Container.BindInterfacesAndSelfTo<DxToSignalBridge>().AsSingle();
+    Container.DeclareSignal<SceneTransition>();
+}
+```
+
+---
+
+## Testing with Zenject
+
+### Unit Tests
+
+```csharp
+using DxMessaging.Core.MessageBus;
+using Zenject;
+using NUnit.Framework;
+
+[TestFixture]
+public class GameInitializerTests : ZenjectUnitTestFixture
+{
+    [Test]
+    public void Initialize_EmitsGameStarted()
+    {
+        // Arrange
+        var bus = new MessageBus();
+        Container.Bind<IMessageBus>().FromInstance(bus).AsSingle();
+        Container.BindInterfacesAndSelfTo<GameInitializer>().AsSingle();
+
+        bool messageReceived = false;
+        var handler = new MessageHandler(new InstanceId(1), bus) { active = true };
+        var token = MessageRegistrationToken.Create(handler, bus);
+        _ = token.RegisterUntargeted<GameStarted>(ref msg => messageReceived = true);
+        token.Enable();
+
+        // Act
+        var initializer = Container.Resolve<GameInitializer>();
+        initializer.Initialize();
+
+        // Assert
+        Assert.IsTrue(messageReceived);
+    }
+}
+```
+
+---
+
+## Checklist
+
+### Initial Setup
+
+- [ ] Install DxMessaging and Zenject/Extenject
+- [ ] Create `DxMessagingInstaller` with `Container.BindInterfacesAndSelfTo<MessageBus>()`
+- [ ] Add installer to your `ProjectContext`
+- [ ] Add `#if ZENJECT_PRESENT` check and call `Container.RegisterMessageRegistrationBuilder()`
+
+### Integration
+
+- [ ] Use `IMessageRegistrationBuilder` in plain classes with `IInitializable`/`IDisposable`
+- [ ] Add `MessagingComponentConfigurator` to prefabs with `MessagingComponent`
+- [ ] Replace `MessageHandler.MessageBus` references with injected `IMessageBus`
+- [ ] Consider bridging to SignalBus if migrating from Zenject Signals
+
+### Testing
+
+- [ ] Inject `IMessageBus` in tests using `FromInstance(new MessageBus())`
+- [ ] Verify messages flow through the container-provided bus
+
+---
+
+## Next Steps
+
+- **[VContainer Integration](VContainer.md)** — Lightweight alternative to Zenject
+- **[Reflex Integration](Reflex.md)** — Minimal DI framework
+- **[Back to Documentation Hub](../Index.md)** — Browse all docs

package/Docs/Integrations/Zenject.md.meta

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

package/{Editor/Analyzers/WallstopStudios.DxMessaging.SourceGenerators.pdb.meta → Docs/Integrations.meta}

@@ -1,5 +1,6 @@
 fileFormatVersion: 2
-guid: f3c8044ad004aee409e169cdae65a86d
+guid: b7f8fcdfff069bc4ead3d4df106dd46b
+folderAsset: yes
 DefaultImporter:
   externalObjects: {}
   userData: