Skip to content

Guides Migration Guide

Jump to bottom
github-actions[bot] edited this page May 7, 2026 · 3 revisions

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.

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

  1. Install DxMessaging via Package Manager

  2. Read the ..-Getting-Started-Visual-Guide (5 minutes)

  3. Import the Mini Combat sample from Package Manager

  4. Create a throwaway test scene and try:

    [DxUntargetedMessage]
[DxAutoConstructor]
public readonly partial struct TestMessage { public readonly int value; }

public class TestListener : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterUntargeted<TestMessage>(OnTest);
    }
    void OnTest(ref TestMessage m) => Debug.Log($"Got {m.value}");
}

// In another script:
var msg = new TestMessage(42);
msg.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

  • Old code still works (zero risk)
  • 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

  1. UI that references too many systems - Replace with message listeners
  2. Global static event buses - Convert to DxMessaging
  3. 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(ref 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 DxMessagingRuntimeSettings asset. A ScriptableObject loaded via Resources.Load<DxMessagingRuntimeSettings>("DxMessagingRuntimeSettings"). Use Assets > Create > Wallstop Studios > DxMessaging > Runtime Settings (in Resources) to drop the asset under Assets/Resources/. Without an asset the runtime hands out a defaulted instance, so the 2.x out-of-the-box behavior is preserved.
  • New Trim and TrimAll API. IMessageBus.Trim(bool force = false) and the convenience wrapper MessageHandler.TrimAll(bool force = false) reclaim empty slots and pooled collections synchronously. Both return a TrimResult reporting how much was reclaimed.
  • New OccupiedTypeSlots and OccupiedTargetSlots counters on IMessageBus. 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 IdleEvictionSeconds and BufferMaxDistinctEntries for 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. For asset parameters, defaults, and the full diagnostic API, see the ..-Reference-Runtime-Settings.

Coexistence Patterns

Pattern 1: Event-to-Message Bridge

public class LegacyBridge : MonoBehaviour {
    [SerializeField] private LegacySystem legacySystem;

    void Awake() {
        // Old system fires event, we convert to message
        legacySystem.OnSomethingHappened += (args) => {
            var msg = new SomethingHappened(args);
            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(ref 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)

  1. New systems - No refactor needed, immediate win
  2. Analytics/logging - Decoupled observers, zero disruption
  3. UI that needs to listen to many systems - Eliminate reference spaghetti
  4. Global event buses - Direct replacement, clear improvement

Migrate LATER (Lower Priority)

  1. Stable, working code - If it ain't broke, don't rush
  2. Performance-critical paths - Validate overhead first
  3. Code that rarely changes - Low ROI for migration
  4. Third-party integrations - Keep adapters simple

DON'T Migrate (Keep As-Is)

  1. Simple button onClick -> method - UnityEvents are fine
  2. Private implementation details - Internal events are okay
  3. Single-listener, same-GameObject - Direct references are clearer
  4. 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.RegisterBroadcast<HealthChanged>(...);

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

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 (Inspector shows message history)"
  • "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:

  1. Keep references during transition
  2. Emit messages alongside old calls
  3. Migrate listeners
  4. 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.
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:

var testBus = new MessageBus();
var token = MessageRegistrationToken.Create(handler, testBus);
// Test in isolation

"What about mobile performance?"

Enable diagnostics only in Editor:

#if UNITY_EDITOR
IMessageBus.GlobalDiagnosticsMode = true;
#endif

Profile early, measure impact.

Next Steps

  1. Try Phase 0 - Install and experiment (today)
  2. Pick one system - Choose a low-risk, high-value target (this week)
  3. Timebox it - Give yourself 2 weeks to evaluate
  4. Measure results - Did it make life better?
  5. Expand or abort - Based on evidence, not hope

Remember: Migration is a journey, not a destination. Go at your own pace.

Questions? See ..-Reference-Faq | Need patterns? See Patterns

DxMessaging Wiki

Getting Started

Concepts

Guides

Architecture

Advanced

Integrations

Examples

Reference

Links

Clone this wiki locally