Migration Guide: Adopting DxMessaging Incrementally¶
This guide helps you introduce DxMessaging into an existing Unity project gradually and pragmatically. You don't need to rewrite everything at once.
Migrating to 4.0.0¶
Reference the dedicated attributes assembly¶
The seven public attributes move to WallstopStudios.DxMessaging.Attributes with unchanged namespaces and names. Add that assembly reference to each Unity assembly definition that uses a DxMessaging attribute. Keep the WallstopStudios.DxMessaging reference when the same assembly also uses message interfaces or runtime APIs. Predefined assemblies receive both references automatically.
A shared rules assembly that only uses [DxAutoConstructor] and [DxOptionalParameter] can reference just the attributes and set noEngineReferences to true. The existing generator is scoped to this engine-free assembly and assemblies that reference it. Runtime type forwarding preserves legacy attribute lookups; an assembly definition still needs its direct compile reference.
The .net-attributes project prepares a matching NuGet package with compiler inputs included. Local package qualification is not a public feed release; use its package README for the current release status.
Replace selected subscription sets¶
Use registration groups, source retargeting, and explicit state handlers to replace application-owned handle lists and capturing registration callbacks. Existing token lifecycle calls still control activation. Finish a group's pending cleanup before replacing it.
Replace readiness branches with explicit current state¶
Use sticky messages when a listener needs the latest readiness or settings value. Change the publisher to EmitSticky, stage the callback once with replayLatest: true, and keep the existing token lifecycle owner. Preserve pending user edits in the callback. Clear retained service and scene references when their owner ends. Ordinary emission stays uncached.
Generate serialized-field constructors without renaming storage¶
For structs or classes that repeat private [SerializeField] fields in a constructor and getters, use the serialized-field options. Make the type and any containing type partial. Keep the original field names and attributes, remove the handwritten constructor, and enable IncludeSerializedFields. Keep existing getters, or remove them and enable GenerateSerializedProperties to generate both the constructor and getters.
These options are off by default. Check named constructor arguments: opted-in serialized fields omit leading underscores in parameter names. DXMSG016 identifies names that would collide. DXMSG017 identifies field types that cannot appear in the generated public signatures; make the types accessible or retain explicit members.
Choose primary constructor arguments explicitly¶
When [DxAutoConstructor] is applied to a type with primary constructor parameters and selected instance fields, 4.0 reports DXMSG012. Earlier versions generated a secondary constructor that failed to compile. Remove the attribute and write the field constructor with a this(...) initializer that passes the primary constructor arguments your type needs. Non-positional records and types without selected instance fields need no change. Empty primary parameter lists are chained automatically with this().
Preserve record copy behavior¶
A record class with exactly one selected field of its own record type can no longer use [DxAutoConstructor]. The field constructor's signature would replace the record copy constructor and could silently change with results. Version 4.0 reports DXMSG013 and emits no constructor.
Remove the attribute and use an init-only property with an object initializer, or write a construction API with a different signature. The diagnostic reference includes a complete property example that preserves with copying.
Check constructors for split partial types¶
Generated constructor parameters now follow source-file compilation order, then field declaration order within each file. Earlier versions compared file-local offsets across partial files, so padding one file could change positional argument meaning or place an optional parameter before a required parameter.
Check positional calls for types whose public fields span partial files. Keep those fields in one declaration for a positional signature that does not depend on file order, or use named arguments. Optional fields must follow required fields in the resulting order. Each optional default now resolves imports and aliases in its own field's source file.
Rebuild every assembly that calls an affected constructor, including callers that use named arguments. Argument names are resolved when the caller is compiled; they do not protect an existing DLL from a changed parameter order. Old binaries can assign same-typed arguments to different fields or fail to find the constructor when parameter types move. Obtain rebuilt versions of precompiled caller DLLs when their sources are unavailable.
Use compatible comparison arguments¶
InstanceId, MessageRegistrationHandle, and MessageHandler now follow IComparable input rules. Comparing an instance with null returns a positive value. Passing an unrelated non-null type to CompareTo(object) throws ArgumentException. MessageHandler.CompareTo(MessageHandler) also places null before a handler. Earlier versions returned -1 for these inputs.
Pass another value of the same type, or null, when using these methods. Numeric and owner ordering for valid values, equality, hashing, and generic comparisons between non-null values keep their previous behavior.
Construct a new reflexive message to change its signature¶
MethodSignatureKey captures its ordered parameter types at construction. Null and empty type lists both describe a method with no parameters, and default keys support equality and dictionary lookup. The constructor copies each nonempty type list once.
ReflexiveMessage uses that captured signature for reflected overload selection. Changing its public parameterTypes array after construction does not select a different overload. Construct a new message with the intended types instead. The parameters array still supplies the argument values and must remain compatible with the captured signature.
Read serialization metadata from the numeric field¶
InstanceId now places DataMember(Name = "id") on its private numeric field instead of the getter-only Id property. The public getter and numeric wire member name remain unchanged. Code that inspects serialization attributes through reflection must no longer expect DataMemberAttribute on the Id property.
XML and JSON data contract deserialization restore the numeric identity. They do not find or restore a Unity object reference. Retain or resolve that reference separately when it is needed.
Remove the test-only runtime settings override¶
DxMessaging 4.0 removes DxMessagingRuntimeSettingsProvider.Override. Configure Assets/Resources/DxMessagingRuntimeSettings.asset for application settings and read DxMessagingRuntimeSettingsProvider.Current. Keep any fixture configuration and restoration in test assemblies.
When no resource asset exists, reset releases the provider-created default instance. After DxMessagingStaticState.Reset() or an Editor script reload, read Current again instead of retaining the old fallback. Resource assets remain valid across reset. See settings lifetime.
Opt in to inherited string demo handlers¶
MessageAwareComponent no longer registers two targeted StringMessage handlers and one untargeted GlobalStringMessage handler by default. Most components need no migration. If a component overrides the inherited string handler methods, add protected override bool RegisterForStringMessages => true;.
Keep calling base.RegisterMessageHandlers() so registrations declared by parent components run.
Observe callback-driven configuration after the outer call¶
A bus cleanup or provider callback can call MessagingComponent.Configure while another configuration is in progress. In 4.0, that nested call queues its request. Its provider resolution, listener migration, and errors complete through the outermost Configure call, preserving each request's order and rebind mode.
Move work that requires delivery on the newly configured bus outside the callback, after the outermost call returns. Handle queued failures around that outer call: a single error keeps its original exception identity; multiple errors appear in AggregateException.InnerExceptions. See configuration from callbacks.
Use in parameters for fast handlers¶
Fast handlers and post-processors receive read-only message references in DxMessaging 4.0. Change explicit handler parameters from ref to in:
// 3.x
void OnDamageV3(ref ApplyDamage message) { }
// 4.0
void OnDamageV4(in ApplyDamage message) { }
To update project scripts automatically, choose Tools / Wallstop Studios / DxMessaging / Upgrade 3.x Fast Handlers to 4.0. The command previews the number of changes before writing. It scans C# scripts under Assets, updates callbacks used by recognized DxMessaging registrations, explicit FastHandler delegates, and the changed MessageAwareComponent overrides. When it updates an inherited string-handler override, it also adds protected override bool RegisterForStringMessages => true; to preserve the 3.x behavior. It keeps an existing opt-in, opt-out, or computed property unchanged. It does not change package or generated sources, interceptors, emission calls, comments, or strings.
The upgrade tool preserves UTF-8, including an optional byte-order mark, and BOM-marked UTF-16 or UTF-32 encoding. It also keeps line endings unchanged and checks for edits immediately before each replacement. It attempts to restore every earlier write if a later write fails. If a script changes again before rollback, the tool preserves the newer edit and its backup instead of overwriting it. It leaves unsupported encodings, overloads, qualified or cross-file callback declarations, and ambiguous receivers unchanged. It also leaves a callback unchanged when its newly readonly parameter is passed as a ref or out argument, except for the matching base call in a changed MessageAwareComponent override, which it can update safely. The tool detects callbacks passed directly to both a handler and an interceptor in the same script. It lists these cases in the Console for manual review. Partial MessageAwareComponent declarations also require manual review before adding the string-handler opt-in because another part can already declare the property. Review project-wide callback uses, inspect the diff, and let Unity compile before committing the migration.
Apply the same change to both parameters of callbacks that receive a target or source:
Overrides of MessageAwareComponent.HandleStringGameObjectMessage, HandleStringComponentMessage, and HandleGlobalStringMessage must also change their message parameter from ref to in.
Keep interceptor parameters and emitted message variables as ref. Interceptors remain the supported place to mutate a payload or its routing context before handlers observe it.
Rebuild precompiled assemblies and plugins that reference MessageHandler.FastHandler<T>, MessageHandler.FastHandlerWithContext<T>, or the changed MessageAwareComponent virtual methods because their metadata changed. Prefer readonly struct messages and readonly instance members; calling a non-readonly member through an in parameter can make the compiler create a defensive copy. Roslynator rule RCS1242 also reports an in parameter whose concrete struct type is not declared readonly. Mark the message struct readonly when its fields and behavior are already immutable. Keep intentionally mutable messages mutable for interceptor use and configure RCS1242 for those handler declarations instead. For class messages, in protects the reference itself but does not make the referenced object's fields immutable.
Philosophy: Start Small, Prove Value¶
Don't do this¶
- Rip out all C# events and rewrite everything
- Force the whole team to learn it before trying it
- Commit to full adoption before seeing benefits
Do this instead¶
- Pick ONE system to migrate (low risk, high visibility)
- Let old and new approaches coexist
- Expand usage as team comfort grows
- Evaluate after each migration step
Phase 0: Install and Experiment (1-2 hours)¶
Goal: Get comfortable without touching production code¶
- Install DxMessaging via Package Manager
- Read the Visual Guide (5 minutes)
- Import the Mini Combat sample from Package Manager
- Create a throwaway test scene. Save the component classes as
TestListener.csandTestEmitter.cs, each with the shown imports, and attach both to active scene GameObjects. Enter Play Mode to emit fromTestEmitter.Startafter the listener registers:
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using DxMessaging.Unity;
using UnityEngine;
[DxUntargetedMessage]
[DxAutoConstructor]
public readonly partial struct TestMessage
{
public readonly int value;
}
public sealed class TestListener : MessageAwareComponent
{
protected override void RegisterMessageHandlers()
{
base.RegisterMessageHandlers();
_ = Token.RegisterUntargeted<TestMessage>(OnTest);
}
private void OnTest(in TestMessage message)
{
Debug.Log($"Got {message.value}");
}
}
public sealed class TestEmitter : MonoBehaviour
{
private void Start()
{
TestMessage message = new(42);
message.Emit();
}
}
Success criteria: You understand the basic flow and have no build errors.
Phase 1: Add to a New Feature (1 week)¶
Goal: Prove value without refactoring existing code¶
Best candidates for first adoption¶
- New UI system - Add a new settings menu that reacts to game state
- Achievement/analytics system - Listen to existing events without coupling
- New game mode - Implement it with DxMessaging from scratch
Example: Adding an Achievement System¶
// 1. Define messages for interesting events (don't touch existing code yet)
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct EnemyKilled {
public readonly string enemyType;
public readonly int playerLevel;
}
// 2. Make your NEW achievement system listen
public class AchievementSystem : MessageAwareComponent {
protected override void RegisterMessageHandlers() {
base.RegisterMessageHandlers();
_ = Token.RegisterBroadcastWithoutSource<EnemyKilled>(OnEnemyKilled);
}
void OnEnemyKilled(InstanceId source, EnemyKilled msg) {
// Track kills, unlock achievements
if (msg.enemyType == "Boss") UnlockAchievement("BossSlayer");
}
}
// 3. Bridge from existing code (minimal change)
public class Enemy : MonoBehaviour {
public event Action OnDied; // OLD - keep for now
void Die() {
OnDied?.Invoke(); // OLD code still works
// NEW: Emit DxMessage too
var msg = new EnemyKilled(enemyType, PlayerStats.Level);
msg.EmitGameObjectBroadcast(gameObject);
}
}
Why this works¶
- Keep the existing event while adding the message listener; verify that shared listeners do not apply the same effect twice
- New system is decoupled
- Team sees immediate value (achievements without wiring)
- Easy to roll back if needed
Phase 2: Migrate High-Pain Areas (2-4 weeks)¶
Goal: Replace the systems causing the most problems¶
High-value migration targets¶
- UI that references too many systems - Replace with message listeners
- Global static event buses - Convert to DxMessaging
- Memory-leak prone event chains - Eliminate manual unsubscribe
Strategy: Parallel Paths During Transition¶
Step 1: Add DxMessages alongside existing events¶
// Old event (keep for now)
public event Action<int> OnHealthChanged;
// New message
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct HealthChanged { public readonly int newHealth; }
void TakeDamage(int amount) {
health -= amount;
// Fire both during migration
OnHealthChanged?.Invoke(health); // OLD
var msg = new HealthChanged(health);
msg.EmitGameObjectBroadcast(gameObject); // NEW
}
Step 2: Migrate listeners one-by-one¶
// OLD listener (comment out when ready)
// void Awake() { player.OnHealthChanged += UpdateBar; }
// void OnDestroy() { player.OnHealthChanged -= UpdateBar; }
// NEW listener
public class HealthBar : MessageAwareComponent {
[SerializeField] private GameObject playerObject;
protected override void RegisterMessageHandlers() {
base.RegisterMessageHandlers();
_ = Token.RegisterGameObjectBroadcast<HealthChanged>(playerObject, OnHealthChanged);
}
void OnHealthChanged(in HealthChanged msg) => UpdateBar(msg.newHealth);
}
Step 3: Remove old events once all listeners migrated¶
// Delete after confirming no one uses it:
// public event Action<int> OnHealthChanged; L
void TakeDamage(int amount) {
health -= amount;
var msg = new HealthChanged(health);
msg.EmitGameObjectBroadcast(gameObject); // Only this now
}
Migration Checklist Template¶
Use this for each system you migrate:
System: _________________
[ ] Identified all listeners to migrate
[ ] Defined DxMessages for all events
[ ] Added DxMessage emissions (parallel with old events)
[ ] Migrated listeners one-by-one
[ ] Tested thoroughly
[ ] Removed old event declarations
[ ] Updated documentation/comments
Phase 3: Adopt for All New Code (Ongoing)¶
Goal: Make DxMessaging the default for new features¶
Team guidelines¶
- All new cross-system communication uses DxMessaging
- Old code migrates opportunistically (when touched)
- Code reviews check for messaging best practices
Example team policy¶
When to use DxMessaging (for new code):
- Any UI listening to game state -> DxMessaging
- Any analytics/logging -> DxMessaging
- Any cross-scene communication -> DxMessaging
- Any event with 2+ listeners -> DxMessaging
When to use direct references/events:
- Simple UI button -> method call (use UnityEvents)
- Single listener, same GameObject -> direct reference
- Private implementation details -> keep internal
Memory reclamation in 3.0¶
DxMessaging 3.0 adds a memory-reclamation subsystem that resets empty per-message-type and per-context slots so long-running sessions do not retain a slot for every message type or InstanceId ever touched. The 2.x dispatch surface is unchanged; the new pieces are opt-in tuning and diagnostics.
What is new¶
- Optional
DxMessagingRuntimeSettingsasset. A ScriptableObject loaded viaResources.Load<DxMessagingRuntimeSettings>("DxMessagingRuntimeSettings"). UseAssets > Create > Wallstop Studios > DxMessaging > Runtime Settings (in Resources)to drop the asset underAssets/Resources/. Without an asset the runtime hands out a defaulted instance, so the 2.x out-of-the-box behavior is preserved. - New
TrimandTrimAllAPI.IMessageBus.Trim(bool force = false)and the convenience wrapperMessageHandler.TrimAll(bool force = false)reclaim empty slots and pooled collections synchronously. Both return aTrimResultreporting how much was reclaimed. - New
OccupiedTypeSlotsandOccupiedTargetSlotscounters onIMessageBus. Aggregated read-only counters for use in diagnostics and leak-watching tests.
Backward compatibility¶
- The defaults match 2.x behavior with no asset present: idle eviction is on with a 30 second threshold, the explicit Trim API is on, pool retention is LRU at 512 entries.
- No existing dispatch, registration, or interceptor code changes. Active registrations are never reclaimed; the sweep only resets empty slots.
- The settings asset hot-reloads through
DxMessagingRuntimeSettings.SettingsChanged. Existing buses re-apply caps without recreation, so editing the asset during Play mode does not invalidate registrations.
When to adopt¶
- Shipped titles or dedicated servers running for hours. Drop the asset in to bound retained slot memory; tune
IdleEvictionSecondsandBufferMaxDistinctEntriesfor the workload. - Editor sessions across many scene loads. Call
MessageHandler.TrimAll(force: true)at scene unload to keep the occupancy counters honest. - Leak diagnosis. Snapshot
OccupiedTypeSlots/OccupiedTargetSlots, run the operation, force a trim, then compare. Surviving slots correspond to active registrations.
For tuning, scenario tables, and worked examples, see the Memory Reclamation guide. For asset parameters, defaults, and the full diagnostic API, see the Runtime Settings reference.
Coexistence Patterns¶
Pattern 1: Event-to-Message Bridge¶
Subscribe while the bridge is enabled and unsubscribe when it is disabled. Remember the publisher used for the subscription so cleanup still removes the callback if the Inspector reference changes. The new reference takes effect on the next enable. An unassigned reference leaves the bridge inactive.
This example assumes a legacy publisher exposing event Action<int> OnSomethingHappened and an untargeted SomethingHappened(int value) message. DxMessaging tokens manage message subscriptions; they do not remove subscriptions to another object's C# events.
Use ReferenceEquals when removing the C# event. A destroyed Unity publisher can still have a managed wrapper, even though Unity compares it equal to null. Cleanup must remove the callback from that wrapper. The enable check keeps using Unity's null comparison to avoid subscribing to a destroyed publisher.
public class LegacyBridge : MonoBehaviour {
[SerializeField] private LegacySystem legacySystem;
private LegacySystem _subscribedSystem;
void OnEnable() {
if (legacySystem == null) return;
_subscribedSystem = legacySystem;
_subscribedSystem.OnSomethingHappened += OnSomethingHappened;
}
void OnDisable() {
if (!ReferenceEquals(_subscribedSystem, null)) {
_subscribedSystem.OnSomethingHappened -= OnSomethingHappened;
}
_subscribedSystem = null;
}
void OnSomethingHappened(int value) {
var msg = new SomethingHappened(value);
msg.Emit();
}
}
Pattern 2: Message-to-Event Bridge¶
public class ModernBridge : MessageAwareComponent {
public event Action<int> LegacyEvent; // For old code that needs events
protected override void RegisterMessageHandlers() {
base.RegisterMessageHandlers();
_ = Token.RegisterUntargeted<NewMessage>(OnMessage);
}
void OnMessage(in NewMessage msg) {
LegacyEvent?.Invoke(msg.value); // Fire old event
}
}
Pattern 3: Gradual GameObject Migration¶
// Phase 1: Keep old inspector references, emit messages
public class Player : MonoBehaviour {
[SerializeField] private HealthBar healthBar; // OLD - will remove later
void TakeDamage(int amount) {
health -= amount;
healthBar.UpdateHealth(health); // OLD direct call
var msg = new HealthChanged(health);
msg.EmitGameObjectBroadcast(gameObject); // NEW message
}
}
// Phase 2: Remove direct references
public class Player : MonoBehaviour {
// [SerializeField] private HealthBar healthBar; -> DELETED
void TakeDamage(int amount) {
health -= amount;
var msg = new HealthChanged(health);
msg.EmitGameObjectBroadcast(gameObject); // Only this
}
}
What to Migrate First vs. Last¶
Migrate FIRST (High Value, Low Risk)¶
- New systems - No refactor needed, immediate win
- Analytics/logging - Decoupled observers, zero disruption
- UI that needs to listen to many systems - Eliminate reference spaghetti
- Global event buses - Direct replacement, clear improvement
Migrate LATER (Lower Priority)¶
- Stable, working code - If it ain't broke, don't rush
- Performance-critical paths - Validate overhead first
- Code that rarely changes - Low ROI for migration
- Third-party integrations - Keep adapters simple
DON'T Migrate (Keep As-Is)¶
- Simple button onClick -> method - UnityEvents are fine
- Private implementation details - Internal events are okay
- Single-listener, same-GameObject - Direct references are clearer
- Legacy systems about to be deleted - Why bother?
Common Migration Pitfalls¶
L Pitfall 1: Boiling the Ocean¶
Problem: "Let's rewrite the entire codebase!"
Solution: Migrate incrementally. Set a rule: "One system per sprint" or "New features only."
L Pitfall 2: No Rollback Plan¶
Problem: Full commit before proving value.
Solution: Keep old code commented for 1-2 sprints:
// OLD (keep until 2024-02-01)
// player.OnHealthChanged += UpdateBar;
// NEW
_ = Token.RegisterGameObjectBroadcast<HealthChanged>(playerObject, OnHealthChanged);
L Pitfall 3: Mixing Message Types Incorrectly¶
Problem: Using Untargeted for everything because it's "simpler."
Solution: Follow message type guidelines:
- Global state? Untargeted
- Command to one? Targeted
- Event from one? Broadcast
L Pitfall 4: Over-Messaging¶
Problem: Converting every method call to a message.
Solution: Keep simple things simple:
// L OVERKILL - Just call the method!
var msg = new CloseDoorMessage(doorId);
msg.Emit();
// BETTER - Direct reference is fine
door.Close();
L Pitfall 5: Not Training the Team¶
Problem: Team doesn't understand when/how to use it.
Solution¶
- Schedule a 30-minute walkthrough
- Share the Visual Guide
- Pair program on first migrations
- Document team conventions in your wiki
Success Metrics¶
Track these to validate migration is worthwhile:
Quantitative¶
- Lines of event subscribe/unsubscribe code removed
- Number of SerializedField references eliminated
- Memory leaks fixed (profiler)
Qualitative¶
- Time to add new observers (before/after)
- Ease of debugging message flow
- Team satisfaction (survey)
Example¶
to "Before: Adding achievement tracking required touching 12 files. to After: Added achievement system with zero changes to existing code."
Timeline Examples¶
Small Project (10k lines)¶
- Week 1: Experiment + add to one new feature
- Week 2-3: Migrate high-pain UI systems
- Week 4+: New code uses DxMessaging
Medium Project (50k lines)¶
- Month 1: Pilot with 2-3 systems
- Month 2-4: Gradual migration of problem areas
- Month 5+: Standard practice for new code
Large Project (100k+ lines)¶
- Quarter 1: Pilot + evangelize
- Quarter 2-3: Migrate critical systems
- Quarter 4+: Opportunistic refactors
Getting Team Buy-In¶
For Managers¶
- "Reduces memory leaks and hard-to-debug issues"
- "Faster feature development (decoupled systems)"
- "Easier onboarding (clear message contracts)"
For Developers¶
- "No more manual unsubscribe hell"
- "Built-in debugging (Message Monitor shows emissions and Flow Graph shows loaded-scene component routes)"
- "Add features without touching existing code"
For QA¶
- "Easier to reproduce bugs (message logs)"
- "Fewer null reference errors"
- "Clear system boundaries"
FAQ: Migration Edition¶
"Do we need to migrate everything?"¶
No! DxMessaging coexists happily with C# events, UnityEvents, and direct references. Migrate what benefits, leave what works.
"What if we decide it's not for us?"¶
Keep old events during migration. If you hate it, delete the DxMessaging parts and uncomment the old code.
"How do we handle prefabs with Inspector references?"¶
Phase them out gradually:
- Keep references during transition
- Emit messages alongside old calls
- Migrate listeners
- 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:
- Activate and dispose each service's lease from its container startup and disposal callbacks.
- Centralises diagnostics toggles and message bus selection.
- Keeps MonoBehaviours and pure C# services on the same path.
This example uses VContainer's IStartable interface and assumes your application already defines the untargeted InventoryChanged message. Start() activates the lease; Dispose() releases its registrations.
using System;
using DxMessaging.Core.MessageBus;
using VContainer.Unity;
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(in InventoryChanged message)
{
// respond to updates
}
}
In the VContainer scope setup, register this service with builder.RegisterEntryPoint<InventoryService>() after registering the bus and registration builder. VContainer calls Start() near MonoBehaviour.Start() and disposes singleton/scoped entry points with their scope. See VContainer's entry point lifecycle. Use your container's own startup and disposal bindings for other frameworks.
- Unity scene code: Call
MessagingComponent.CreateRegistrationBuilder()to use the component's configured bus/provider. Give each independent service or pooled owner its own lease and dispose it when that owner finishes. The component does not track these leases. - Container shims: Register the bus and builder through your container's installer or registration extensions. The
ZENJECT_PRESENT,VCONTAINER_PRESENT, andREFLEX_PRESENTsymbols enable the optional shims; follow the framework setup to bind their services. - 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:
var testBus = new MessageBus();
var token = MessageRegistrationToken.Create(handler, testBus);
// Test in isolation
"What about mobile performance?"¶
Enable diagnostics only in Editor:
// DiagnosticsTarget.Editor scopes diagnostics to the Unity Editor automatically;
// player builds leave them off, so no #if UNITY_EDITOR guard is needed.
IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Editor;
Profile early, measure impact.
Next Steps¶
- Try Phase 0 - Install and experiment (today)
- Pick one system - Choose a low-risk, high-value target (this week)
- Timebox it - Give yourself 2 weeks to evaluate
- Measure results - Did it make life better?
- Expand or abort - Based on evidence, not hope
Remember: Migration is a journey, not a destination. Go at your own pace.
Questions? See FAQ | Need patterns? See Common Patterns