com.wallstop-studios.dxmessaging 2.0.0-rc27.3.1 → 2.1.0

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: 

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: