DxMessaging + VContainer¶
Overview¶
VContainer is a fast, lightweight dependency injection framework for Unity with minimal overhead. DxMessaging integrates with VContainer, allowing you to:
- Inject
IMessageBusin 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)
- Compatible -- VContainer and DxMessaging can be used together
Why combine DI + Messaging? Use constructor injection for service dependencies (repositories, managers) and messaging for reactive events (damage taken, item collected), combining both approaches. VContainer's scoped lifetimes support per-scene message buses.
Quick Start¶
Prerequisites¶
- DxMessaging installed via UPM
- VContainer installed (Git URL or OpenUPM)
These examples require VContainer. DxMessaging's integration assembly uses VCONTAINER_PRESENT as an assembly-local Version Define. Call the helpers directly from these framework-specific examples. If your application needs conditional code, configure Version Defines on its own assembly.
For a custom application asmdef, reference WallstopStudios.DxMessaging, WallstopStudios.DxMessaging.Attributes, WallstopStudios.DxMessaging.VContainer, VContainer, and VContainer.Unity for these examples.
1. Create a LifetimeScope with DxMessaging¶
using DxMessaging.Core.MessageBus;
using DxMessaging.Unity.Integrations.VContainer; // Required for RegisterDxMessagingBus()
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 through the safe helper.
builder.RegisterDxMessagingBus();
// Register the builder for services that request it.
builder.RegisterMessageRegistrationBuilder();
}
}
Note: You must import the DxMessaging.Unity.Integrations.VContainer namespace to access the registration extension methods.
Add to your scene¶
- Create an empty GameObject in your scene
- Add the
MessagingLifetimeScopecomponent - 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:
using System;
using DxMessaging.Core.MessageBus;
using DxMessaging.Core.Attributes;
using DxMessaging.Core;
using VContainer.Unity;
// Define a message
[DxBroadcastMessage]
[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.RegisterBroadcastWithoutSource<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(InstanceId player, PlayerSpawned message)
{
UnityEngine.Debug.Log($"Player {message.playerId} spawned!");
}
}
Register the service in your scope¶
using DxMessaging.Unity.Integrations.VContainer; // Required for extension method
// ...
protected override void Configure(IContainerBuilder builder)
{
builder.RegisterDxMessagingBus();
builder.RegisterMessageRegistrationBuilder();
// Register your service
builder.RegisterEntryPoint<PlayerService>();
}
Pattern 2: Configure MessagingComponents (For Existing MonoBehaviours)¶
Configure the messaging component from an injected method. The container must register and inject the configurator; the scope below registers one from its scene hierarchy. Save each component class in a .cs file with the same name.
using DxMessaging.Core.MessageBus;
using DxMessaging.Unity;
using UnityEngine;
using VContainer;
[RequireComponent(typeof(MessagingComponent))]
public sealed class MessagingComponentConfigurator : MonoBehaviour
{
[Inject]
public void Construct(IMessageBus messageBus)
{
GetComponent<MessagingComponent>().Configure(
messageBus,
MessageBusRebindMode.RebindActive
);
}
}
Use this scope for the example, or add its component registration to your existing scope after registering the bus:
using DxMessaging.Unity.Integrations.VContainer;
using VContainer;
using VContainer.Unity;
public sealed class ConfiguredMessagingScope : LifetimeScope
{
protected override void Configure(IContainerBuilder builder)
{
builder.RegisterDxMessagingBus();
builder.RegisterComponentInHierarchy<MessagingComponentConfigurator>();
}
}
Usage¶
- Add
ConfiguredMessagingScopeto the scene and place oneMessagingComponentConfiguratoralongside theMessagingComponentto configure. - Building the scope injects the bus and calls
Construct. For multiple components, register each explicit component reference withbuilder.RegisterComponent(configurator). - Emit through the same injected
IMessageBusto reach listeners on that bus.
MessageAwareComponent stages handlers in Awake() and normally enables them in OnEnable(). Injection can happen after those callbacks. RebindActive moves existing active registrations to the injected bus and selects it for future registrations. Messages emitted before configuration are not replayed. Configuring a receiving component does not change the global bus used by parameterless emission helpers.
See VContainer's method injection and scene component registration.
Pattern 3: Inject IMessageBus Directly¶
For simple emission without listening, inject IMessageBus directly:
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using DxMessaging.Core.MessageBus;
using VContainer.Unity;
[DxUntargetedMessage]
public readonly partial struct GameStarted { }
public sealed class GameInitializer : IStartable
{
private readonly IMessageBus _messageBus;
public GameInitializer(IMessageBus messageBus)
{
_messageBus = messageBus;
}
public void Start()
{
GameStarted message = new();
_messageBus.EmitUntargeted(ref message);
}
}
Advanced: Scene Scopes and Isolation¶
VContainer's scoped lifetimes support per-scene message buses. This is useful for additive scenes or isolated gameplay features:
Pass the prefab's LifetimeScope component to LoadLevel. Retain the returned child scope and dispose it when the level unloads. See VContainer's child scope creation.
using DxMessaging.Core.MessageBus;
using DxMessaging.Unity.Integrations.VContainer; // Required for extension method
using VContainer;
using VContainer.Unity;
public sealed class LevelLoader
{
private readonly LifetimeScope _parentScope;
public LevelLoader(LifetimeScope parentScope)
{
_parentScope = parentScope;
}
public LifetimeScope LoadLevel(LifetimeScope lifetimeScopePrefab)
{
// Create a child scope with its own MessageBus
return _parentScope.CreateChildFromPrefab(lifetimeScopePrefab, builder =>
{
builder.RegisterDxMessagingBus();
builder.RegisterMessageRegistrationBuilder();
});
}
}
Benefits¶
- Each scene gets its own isolated message bus
- Messages don't leak between scenes
- Suitable for multiplayer lobbies, mini-games, or feature-scoped events
Testing with VContainer¶
Unit Tests¶
With GameStarted and GameInitializer from Pattern 3 in scope, register the concrete class to check constructor injection and a direct Start() call. This test does not install VContainer's player-loop dispatcher or verify automatic entry-point startup. Use RegisterEntryPoint in the application's lifetime scope when you want that startup lifecycle.
using DxMessaging.Core;
using DxMessaging.Core.MessageBus;
using NUnit.Framework;
using VContainer;
[TestFixture]
public sealed class GameInitializerTests
{
[Test]
public void StartEmitsGameStarted()
{
ContainerBuilder builder = new();
MessageBus bus = new();
builder.RegisterInstance<IMessageBus>(bus);
builder.Register<GameInitializer>(Lifetime.Singleton);
using IObjectResolver container = builder.Build();
bool messageReceived = false;
MessageHandler handler = new(new InstanceId(1), bus) { active = true };
using MessageRegistrationToken token = MessageRegistrationToken.Create(handler, bus);
_ = token.RegisterUntargeted<GameStarted>(
(in GameStarted message) => messageReceived = true
);
token.Enable();
container.Resolve<GameInitializer>().Start();
Assert.That(messageReceived, Is.True);
}
}
Play-Mode Tests¶
Put the following fixture in a PlayMode test assembly with the Unity Test Framework, VContainer, and DxMessaging integration references. It uses GameStarted from Pattern 3. Each scope owns its container and native GameObject; disposing the listener token before the scopes removes its subscription. The test checks bus separation directly and needs no frame delay:
using DxMessaging.Core;
using DxMessaging.Core.MessageBus;
using DxMessaging.Unity.Integrations.VContainer;
using NUnit.Framework;
using VContainer;
using VContainer.Unity;
[TestFixture]
public sealed class MessageBusPlayModeTests
{
[Test]
public void ScopesKeepMessageBusesSeparate()
{
using LifetimeScope first = LifetimeScope.Create(
builder => builder.RegisterDxMessagingBus()
);
using LifetimeScope second = LifetimeScope.Create(
builder => builder.RegisterDxMessagingBus()
);
IMessageBus firstBus = first.Container.Resolve<IMessageBus>();
IMessageBus secondBus = second.Container.Resolve<IMessageBus>();
Assert.That(firstBus, Is.Not.SameAs(secondBus));
int received = 0;
MessageHandler handler = new(new InstanceId(1), firstBus) { active = true };
using MessageRegistrationToken token = MessageRegistrationToken.Create(handler, firstBus);
_ = token.RegisterUntargeted<GameStarted>(
(in GameStarted message) => ++received
);
token.Enable();
GameStarted message = new();
secondBus.UntargetedBroadcast(ref message);
Assert.That(received, Is.Zero);
firstBus.UntargetedBroadcast(ref message);
Assert.That(received, Is.EqualTo(1));
token.Dispose();
firstBus.UntargetedBroadcast(ref message);
Assert.That(received, Is.EqualTo(1));
}
}
Checklist¶
Initial Setup¶
- Install DxMessaging and VContainer
- Create
MessagingLifetimeScopewithbuilder.RegisterDxMessagingBus() - Add scope to your scene as a GameObject component
- Import
DxMessaging.Unity.Integrations.VContainernamespace for extension methods - Call
builder.RegisterMessageRegistrationBuilder()inside the scope'sConfiguremethod
Integration¶
- Use
IMessageRegistrationBuilderin plain classes withIStartable/IDisposable - Register each
MessagingComponentConfiguratorwith its scope to inject and configure itsMessagingComponent - Replace
MessageHandler.MessageBusreferences with injectedIMessageBus - Consider using scoped buses for scene isolation
Testing¶
- Create isolated
ContainerBuilderinstances in tests - Use
builder.RegisterInstance<IMessageBus>(new MessageBus())for test buses - Dispose scopes after tests to ensure clean teardown
Next Steps¶
- Zenject Integration -- Full-featured DI with extensive Unity support
- Reflex Integration -- Minimal DI framework
- Back to Documentation Hub -- Browse all docs