Skip to content

DxMessaging Patterns: Real-World Solutions

Back to Index | Getting Started | Message Types | Samples


You're here because: You understand DxMessaging basics, now you want to see "How do I actually build X?"

What you'll find

  • Basic Patterns - Fundamental building blocks (scene transitions, commands, observability)
  • Advanced Patterns - Power user techniques (diagnostics, testing, legacy integration)
  • Scale Patterns - Examples for larger systems (100+ entities, cross-scene systems, large UI)

Reading guide

  • New to DxMessaging? Start with Basic Patterns 1-8
  • Intermediate user? Jump to Advanced Patterns 9-12
  • Building at scale? Go straight to Real-World Scale Patterns
  • Specific problem? Use Ctrl+F / Cmd+F to search

Philosophy: These patterns address common challenges teams face when building messaging systems.


Find your use case, jump to the pattern

I want to... Go to
Make UI react to gameplay Pattern 2: Directed Commands
Coordinate scene transitions Pattern 1: Scene-wide Events
Build an achievement system Pattern 3: Observability + Global Accept-All
Validate input/damage before it happens Pattern 4: Interceptors
Add analytics without touching gameplay Pattern 5: Post-Processors
Track ALL damage from ANY entity Pattern: Managing 100+ Entities
Build a large UI system (20+ panels) Pattern: Large-Scale UI
Make systems run in a specific order Pattern: Priority Ordering
Test in isolation Pattern 6: Local Bus Islands
Migrate from C# events Pattern 9: Bridging Legacy
Handle persistent systems across scene loads Pattern: Cross-Scene Persistent
See what's happening (debug message flow) Pattern 11: Diagnostics
Build a battle royale / large multiplayer Pattern: Battle Royale Example
Use with Scriptable Object Architecture Pattern 14: SOA Compatibility

Table of Contents

Basic Patterns

Advanced Patterns

Real-World Scale Patterns


Important: Inheritance with MessageAwareComponent

  • Many examples derive from MessageAwareComponent. When overriding hooks, you MUST call the base method.
  • Always call base.RegisterMessageHandlers() FIRST in your override to preserve parent class registrations.
  • CRITICAL: Call base.OnEnable() / base.OnDisable() if you override lifecycle methods; otherwise your token may never enable/disable.
  • CRITICAL: Call base.Awake() if you override Awake(); otherwise your token won't be created.
  • To opt in to the built-in string demos, override RegisterForStringMessages => true.
  • Don't use new to hide methods (e.g., new void OnEnable()); always use override and call base.*.

Registration timing (pit of success)

  • Prefer Awake() for all message handler registration -- this is when MessageAwareComponent calls RegisterMessageHandlers().
  • Avoid registering in Start() unless you have a specific order-of-execution reason.
  • Early registration in Awake() ensures your handlers are ready before other components' Start() methods run.

1) Scene-wide Events (Untargeted)

Use untargeted messages for global state changes that any system might care about. Keep messages small and immutable.

C#
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;

[DxUntargetedMessage]
[DxAutoConstructor]
public readonly partial struct SceneLoaded
{
    public readonly int buildIndex;
}

// Sender
var evt = new SceneLoaded(UnityEngine.SceneManagement.SceneManager.GetActiveScene().buildIndex);
evt.Emit();

// Listener
_ = token.RegisterUntargeted<SceneLoaded>(OnSceneLoaded);
void OnSceneLoaded(in SceneLoaded m) => RefreshUI();

2) Directed Commands (Targeted)

Target a specific GameObject/Component when you want direct control.

C#
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;

[DxTargetedMessage]
[DxAutoConstructor]
public readonly partial struct Heal { public readonly int amount; }

// Sender
var heal = new Heal(10);
heal.EmitComponentTargeted(this);

// Listener (on the hero)
_ = token.RegisterComponentTargeted<Heal>(this, OnHeal);
void OnHeal(in Heal m) => ApplyHeal(m.amount);

3) Observability (Broadcast)

Broadcast from a source; any listener can observe.

C#
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using DxMessaging.Core; // InstanceId

[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct TookDamage { public readonly int amount; }

// Sender
var hit = new TookDamage(5);
hit.EmitGameObjectBroadcast(gameObject);

// Listener: observe every source
_ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyTookDamage);
void OnAnyTookDamage(InstanceId src, TookDamage m) => Log(src, m);

4) Validation and Normalization (Interceptors)

Use interceptors to enforce rules before handlers run.

C#
using DxMessaging.Core; // MessageHandler

var bus = MessageHandler.MessageBus;
_ = token.RegisterTargetedInterceptor<ApplyDamage>((ref InstanceId target, ref ApplyDamage m) =>
{
    if (m.amount <= 0) return false; // cancel
    m = new ApplyDamage(Math.Min(m.amount, 999)); // clamp
    return true;
}, priority: 0);

5) Analytics/Logging (Post-Processors)

Post-processors run after handlers -- ideal for metrics.

C#
_ = token.RegisterUntargetedPostProcessor<SceneLoaded>(
    (in SceneLoaded m) => Metrics.RecordProcessedSceneLoad(m.buildIndex));

6) Local Bus Islands

MessageHandler.MessageBus is the global bus. For isolation, use your own MessageBus instance and pass it to the token factory.

C#
using DxMessaging.Core;
using DxMessaging.Core.MessageBus;

var localBus = new MessageBus();
var token = MessageRegistrationToken.Create(handler, localBus);

7) Lifecycle Pattern in Unity

  • Stage registrations in Awake() (preferred) or Start() (only if order-dependent).
  • Call token.Enable() in OnEnable and token.Disable() in OnDisable.
  • Use MessageAwareComponent to avoid boilerplate -- it handles all of this automatically.

Why Awake over Start?

  • Awake() runs before any Start() methods, ensuring your handlers are ready early.
  • Other components may emit messages in their Start() methods -- registering in Awake() ensures you don't miss them.
  • MessageAwareComponent automatically calls RegisterMessageHandlers() in Awake(), following this best practice.

Side-by-side: lifecycle

Before

C#
void Awake() { /* register */ }
void OnDestroy() { /* maybe unregister (often forgotten) */ }

After (token)

C#
void Awake()     { /* stage registrations - PREFERRED */ }
void OnEnable()  { token.Enable(); }
void OnDisable() { token.Disable(); }

8) Cross-Scene Messaging

Untargeted messages flow anywhere; targeted/broadcast require a valid InstanceId. For cross-scene, ensure the target/source object exists when you emit.

9) Bridging Legacy Unity Messaging

ReflexiveMessage mirrors SendMessage* patterns but keeps you in the bus pipeline.

Fixed in v4.0.0: Combine Flat, Upwards, and Downwards to traverse more than one direction. Sends include disabled components and inactive GameObjects unless you also set OnlyIncludeActive. A missing receiver is silent for every argument count. Nested reflexive sends preserve the outer traversal, and receivers destroyed during traversal are skipped. Active single-direction sends with zero or one argument keep Unity's native per-GameObject behavior, so a reset from one receiver completes that GameObject before traversal stops.

C#
using DxMessaging.Core;
using DxMessaging.Core.Messages;

var msg = new ReflexiveMessage("OnHit", ReflexiveSendMode.Upwards, 10);
msg.EmitGameObjectTargeted(someGameObject);

10) Global Accept-All Handlers

Use when building tools or inspectors that want to observe everything.

C#
_ = token.RegisterGlobalAcceptAll(
    (in IUntargetedMessage m) => Debug.Log($"Untargeted {m.MessageType}"),
    (in InstanceId target, in ITargetedMessage m) => Debug.Log($"Targeted {m.MessageType} to {target}"),
    (in InstanceId source, in IBroadcastMessage m) => Debug.Log($"Broadcast {m.MessageType} from {source}")
);

Do's

  • Use global accept-all in tooling and debug inspectors.
  • Prefer specific registrations for gameplay code to avoid surprises.

11) Diagnostics and Tuning

  • Enable IMessageBus.GlobalDiagnosticsTargets (e.g. DiagnosticsTarget.Editor) or per-token.
  • Adjust IMessageBus.GlobalMessageBufferSize for deeper history (Editor settings UI provided).
  • Wire MessagingDebug.LogFunction to Unity's console to see warnings/errors.

12) Testing

  • Construct messages directly and emit via extension helpers.
  • Use a local MessageBus per test to avoid global state.
  • Wrap handlers to increment counters or assert payloads.

13) Real-World Scale: Beyond Toy Examples

Most documentation shows simple, small-scale examples. Here's how DxMessaging behaves at production scale.

Pattern: Managing 100+ Combat Entities

Challenge: Track damage, healing, status effects for a large battlefield without performance collapse.

C#
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using DxMessaging.Core;

// Messages
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct EntityDamaged {
    public readonly int amount;
    public readonly string damageType;
}

[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct EntityHealed { public readonly int amount; }

// Entity: Each of 100+ entities emits events
public class CombatEntity : MessageAwareComponent {
    public void TakeDamage(int amount, string type) {
        health -= amount;
        var msg = new EntityDamaged(amount, type);
        msg.EmitGameObjectBroadcast(gameObject);
    }
}

// Combat UI: Tracks specific enemy (targeted observation)
public class EnemyHealthBar : MessageAwareComponent {
    [SerializeField] private GameObject trackedEnemy;

    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        // Only listens to ONE enemy, not all 100
        _ = Token.RegisterGameObjectBroadcast<EntityDamaged>(trackedEnemy, OnDamaged);
    }

    void OnDamaged(in EntityDamaged msg) => UpdateBar();
}

// Analytics: Observes ALL entities (global observation)
public class CombatAnalytics : MessageAwareComponent {
    private readonly Dictionary<InstanceId, int> totalDamageByEntity = new();

    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        // Listens to all 100+ entities with ONE registration
        _ = Token.RegisterBroadcastWithoutSource<EntityDamaged>(OnAnyDamage);
    }

    void OnAnyDamage(InstanceId source, EntityDamaged msg) {
        if (!totalDamageByEntity.ContainsKey(source))
            totalDamageByEntity[source] = 0;
        totalDamageByEntity[source] += msg.amount;
    }
}

Scale characteristics

  • Each entity broadcasts ~10-50 messages/second -> No GC allocations (struct messages)
  • Targeted listeners (health bars) only receive relevant messages -> O(1) lookup
  • Global listeners (analytics) receive all messages -> Single handler, not N handlers
  • Adding/removing entities doesn't break registrations (no manual wiring)
Performance notes
  • Disable diagnostics in production (IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Off)
  • Use RegisterBroadcastWithoutSource sparingly (it's called for every emit)
  • Profile with Unity Profiler to find hotspots

Pattern: Cross-Scene Persistent Systems

Challenge: Maintain event flow across scene loads (achievements, save system, analytics).

C#
using UnityEngine;
using DxMessaging.Unity;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;

// Persistent singleton that survives scene loads
public class PersistentAchievementSystem : MessageAwareComponent {
    private static PersistentAchievementSystem instance;

    protected override void Awake() {
        base.Awake();
        if (instance != null) {
            Destroy(gameObject);
            return;
        }
        instance = this;
        DontDestroyOnLoad(gameObject);
    }

    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        // Listen to ALL broadcasts from ANY scene
        _ = Token.RegisterBroadcastWithoutSource<EntityDamaged>(OnAnyDamage);
        _ = Token.RegisterUntargeted<LevelCompleted>(OnLevelComplete);
    }

    void OnAnyDamage(InstanceId src, EntityDamaged msg) {
        totalDamage += msg.amount;
        CheckAchievements();
    }

    void OnLevelComplete(in LevelCompleted msg) {
        UnlockAchievement($"Complete_Level_{msg.levelIndex}");
    }
}

// Scene-specific objects emit messages normally
public class Boss : MessageAwareComponent {
    void Die() {
        var msg = new BossDefeated(bossName);
        msg.EmitGameObjectBroadcast(gameObject);
        // PersistentAchievementSystem hears this even though it's in DontDestroyOnLoad
    }
}

Key insight: Persistent listeners (DontDestroyOnLoad) stay registered across scenes. Scene-specific emitters come/go, but the observer remains.

Gotcha: If you emit Targeted or Broadcast messages, ensure the target/source InstanceId is still valid after scene loads. For cross-scene communication, prefer Untargeted messages.

Pattern: Large-Scale UI System (20+ Panels)

Challenge: Coordinate 20+ UI panels reacting to game state without tight coupling.

C#
// Player-owned state snapshots are broadcasts from that player.
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct PlayerStatsChanged {
    public readonly int health;
    public readonly int mana;
    public readonly int gold;
}

[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct InventoryChanged { public readonly int itemCount; }

// Each UI panel listens independently
public class HealthPanel : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSource<PlayerStatsChanged>(OnStats);
    }
    void OnStats(InstanceId player, PlayerStatsChanged msg) => UpdateHealth(player, msg.health);
}

public class ManaPanel : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSource<PlayerStatsChanged>(OnStats);
    }
    void OnStats(InstanceId player, PlayerStatsChanged msg) => UpdateMana(player, msg.mana);
}

public class GoldPanel : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSource<PlayerStatsChanged>(OnStats);
    }
    void OnStats(InstanceId player, PlayerStatsChanged msg) => UpdateGold(player, msg.gold);
}

public class InventoryPanel : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSource<InventoryChanged>(OnInventory);
    }
    void OnInventory(InstanceId player, InventoryChanged msg) => Refresh(player);
}

// Game systems emit once, all panels update
public class PlayerStats : MonoBehaviour {
    void UpdateStats() {
        var msg = new PlayerStatsChanged(health, mana, gold);
        msg.EmitGameObjectBroadcast(gameObject); // All 3 panels update automatically
    }
}

Benefits at scale

  • Add/remove panels without touching game logic
  • Panels can be enabled/disabled freely (tokens handle lifecycle)
  • Easy to add "observer panels" (e.g., debug overlays) without modifying existing code
Anti-pattern to avoid
C#
//  DON'T: Separate message per UI element (too granular)
[DxBroadcastMessage] public partial struct HealthChanged { public int health; }
[DxBroadcastMessage] public partial struct ManaChanged { public int mana; }
[DxBroadcastMessage] public partial struct GoldChanged { public int gold; }
// This creates 3x message traffic and registration overhead

//  DO: Batch related updates into one message
[DxBroadcastMessage] public partial struct PlayerStatsChanged {
    public int health;
    public int mana;
    public int gold;
}

Pattern: Priority-Ordered Execution for Complex Systems

Challenge: Invoke save, audio and UI handlers in a chosen order.

Save each component class in a matching .cs file with the shown imports. Attach and enable the three listeners before calling ExitController.RequestExit. This example logs handler invocation; replace each log with the corresponding application work. All components use the global bus here.

C#
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using DxMessaging.Unity;
using UnityEngine;

[DxUntargetedMessage]
[DxAutoConstructor]
public readonly partial struct GameExit { }

public sealed class SaveSystem : MessageAwareComponent
{
    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterUntargeted<GameExit>(OnExit, priority: 0);
    }

    private void OnExit(in GameExit message)
    {
        Debug.Log("Save handler: priority 0");
    }
}

public sealed class AudioSystem : MessageAwareComponent
{
    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterUntargeted<GameExit>(OnExit, priority: 5);
    }

    private void OnExit(in GameExit message)
    {
        Debug.Log("Audio handler: priority 5");
    }
}

public sealed class UISystem : MessageAwareComponent
{
    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterUntargeted<GameExit>(OnExit, priority: 10);
    }

    private void OnExit(in GameExit message)
    {
        Debug.Log("UI handler: priority 10");
    }
}

public sealed class ExitController : MonoBehaviour
{
    public void RequestExit()
    {
        GameExit message = new();
        message.Emit();
    }
}

Key insight: Lower priority numbers run first. Priority orders these synchronous callback invocations; asynchronous or deferred work needs its own completion coordination.

  • -100 to -50: Critical systems (save, validation)
  • -10 to 0: Core gameplay logic
  • 0 to 10: UI updates
  • 10 to 20: Visual effects
  • 20+: Analytics, logging, non-critical

Pattern: Efficient Interception at Scale

Challenge: Validate 1000s of messages without duplicating logic.

C#
[DxTargetedMessage]
[DxAutoConstructor]
public readonly partial struct ApplyDamage {
    public readonly int amount;
    public readonly DamageType damageType;
}

// Single interceptor validates ALL targeted damage commands
public class DamageValidator : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        // Interceptors run BEFORE handlers
        _ = Token.RegisterTargetedInterceptor<ApplyDamage>(ValidateDamage, priority: -100);
    }

    bool ValidateDamage(ref InstanceId target, ref ApplyDamage msg) {
        // Validation logic runs once per message, not per handler
        if (msg.amount <= 0) return false; // Cancel invalid
        if (msg.amount > 9999) {
            msg = new ApplyDamage(9999, msg.damageType); // Clamp
        }
        return true; // Allow to proceed to handlers
    }
}

// Handlers can trust data is valid (no duplicate checks needed)
public class CombatEntity : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterComponentTargeted<ApplyDamage>(this, OnApplyDamage);
    }

    void OnApplyDamage(in ApplyDamage msg) {
        // No need to validate - interceptor already did it
        health -= msg.amount;
        var fact = new EntityDamaged(msg.amount, msg.damageType);
        fact.EmitComponentBroadcast(this);
    }
}

Scale benefit: Validation runs O(1) per message, not O(N) per handler. For 100 handlers, this saves 99 validation calls per message.

Pattern: Post-Processing for Analytics at Scale

Challenge: Track metrics without polluting gameplay code.

C#
public class GameAnalytics : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        // Record completed dispatch after gameplay handlers have run.
        _ = Token.RegisterBroadcastWithoutSourcePostProcessor<EntityDamaged>(
            RecordProcessedDamageMessage,
            priority: 100);
        _ = Token.RegisterUntargetedPostProcessor<LevelCompleted>(
            RecordProcessedLevelCompletion,
            priority: 100);
    }

    void RecordProcessedDamageMessage(InstanceId source, EntityDamaged msg) {
        SendAnalyticsEvent("damage_message_processed", new {
            source = source.ToString(),
            amount = msg.amount,
            type = msg.damageType
        });
    }

    void RecordProcessedLevelCompletion(in LevelCompleted msg) {
        SendAnalyticsEvent("level_completion_message_processed", new { level = msg.levelIndex });
    }
}

Key insight: Handlers own gameplay and presentation state. Post-processors let you add analytics, logging, and telemetry without modifying those handlers. A post-processor sees the processed message, not proof that a handler changed health or any other state.

Performance Optimization Patterns at Scale

Optimization 1: Disable Diagnostics in Builds

C#
#if UNITY_EDITOR
IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.All;
IMessageBus.GlobalMessageBufferSize = 100; // Keep history for debugging
#else
IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.Off; // Production builds
#endif

Impact: Diagnostics adds ~5-10% overhead per message. Disable in production.

Optimization 2: Use Specific Registrations Over GlobalAcceptAll

C#
//  SLOW: Receives ALL messages, even irrelevant ones
_ = Token.RegisterGlobalAcceptAll(
    (in IUntargetedMessage m) => { /* called for every untargeted */ },
    (in InstanceId t, in ITargetedMessage m) => { /* called for every targeted */ },
    (in InstanceId s, in IBroadcastMessage m) => { /* called for every broadcast */ }
);

//  FAST: Only receives relevant messages
_ = Token.RegisterBroadcastWithoutSource<EntityDamaged>(OnDamage);
_ = Token.RegisterUntargeted<LevelCompleted>(OnLevelComplete);

Impact: Specific registrations use type-indexed lookups (O(1)). GlobalAcceptAll checks every message (O(N)).

Optimization 3: Batch Message Emissions

C#
//  WASTEFUL: Emit after every tiny change
void TakeDamage(int amount) {
    health -= amount;
    var msg = new HealthChanged(health);
    msg.EmitGameObjectBroadcast(gameObject); // Emits every frame
}
C#
//  EFFICIENT: Batch updates, emit once per frame
private bool healthDirty = false;

void TakeDamage(int amount) {
    health -= amount;
    healthDirty = true;
}

void LateUpdate() {
    if (healthDirty) {
        healthDirty = false;
        var msg = new HealthChanged(health);
        msg.EmitGameObjectBroadcast(gameObject);
    }
}

This example coalesces changes made before LateUpdate into one emission from that callback. Clear the dirty flag before emitting: dispatch is synchronous, so a listener can call TakeDamage and mark the next batch dirty. Those changes are emitted on the next LateUpdate instead of being lost when the current emission returns. Intermediate health values are omitted. The reduction depends on how many changes occur between flushes; this example does not measure throughput.

Scaling Guidelines

Measure representative workloads on the target hardware, Unity backend and build configuration. Record subscriber fan-out and callback work alongside the message rate:

Workload Measurements to collect
Many active entities Registrations per entity, subscriber fan-out and retained memory
Frequent emissions Delivery rate, callback time, latency and frame budget
Spawn, despawn or pooling Registration work, cleanup work and managed allocations
Diagnostics enabled Capture mode, recording cost and retained history

Compare results within the scope recorded by the performance benchmarks. Use the measurement methodology when collecting new results.

Example: Battle Royale UI

Scenario: 100 players, each with health/armor/weapons. UI needs to show:

  • Your health/armor
  • Teammate health (4 players)
  • Kill feed (all 100 players)
  • Match stats (damage dealt, kills, etc.)
C#
// Messages
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct PlayerDamaged {
    public readonly int playerId;
    public readonly int newHealth;
    public readonly int newArmor;
}

[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct PlayerKilled {
    public readonly int victimId;
    public readonly int killerId;
}

// YOUR health bar (targeted observation)
public class SelfHealthUI : MessageAwareComponent {
    [SerializeField] private GameObject localPlayerObject;

    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterGameObjectBroadcast<PlayerDamaged>(localPlayerObject, OnDamage);
    }

    void OnDamage(in PlayerDamaged msg) => UpdateHealthBar(msg.newHealth, msg.newArmor);
}

// TEAMMATE health bars (selective observation)
public class TeamHealthUI : MessageAwareComponent {
    [SerializeField] private List<GameObject> teammateObjects;

    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        foreach (var teammate in teammateObjects) {
            _ = Token.RegisterGameObjectBroadcast<PlayerDamaged>(teammate, OnTeammateDamage);
        }
    }

    void OnTeammateDamage(in PlayerDamaged msg) => UpdateTeammateBar(msg.playerId, msg.newHealth);
}

// KILL FEED (global observation)
public class KillFeedUI : MessageAwareComponent {
    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSource<PlayerKilled>(OnAnyKill);
    }

    void OnAnyKill(InstanceId source, PlayerKilled msg) {
        ShowKillFeedEntry(msg.killerId, msg.victimId);
    }
}

// MATCH STATS (analytics)
public class MatchStats : MessageAwareComponent {
    private readonly Dictionary<int, int> processedDamageMessagesByPlayer = new();

    protected override void RegisterMessageHandlers() {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSourcePostProcessor<PlayerDamaged>(
            CountProcessedDamageMessage);
    }

    void CountProcessedDamageMessage(InstanceId source, PlayerDamaged msg) {
        processedDamageMessagesByPlayer.TryGetValue(msg.playerId, out int count);
        processedDamageMessagesByPlayer[msg.playerId] = count + 1;
    }
}

Example traffic assumptions

Assume each of the 100 players emits 10 damage messages per second and the match emits 5 kill messages per second:

  • Self health UI: 1 source-filtered registration observes 10 damage messages/sec.
  • Team health UI: 4 source-filtered registrations observe 40 damage messages/sec in total.
  • Kill feed UI: 1 registration observes all 5 kill messages/sec.
  • Match stats: 1 post-processor observes all 1000 damage messages/sec and counts processed payloads.

These assumed rates describe message volume and filtering. They do not measure dispatch cost, UI updates, dictionary growth, allocations or frame time. Measure the complete workload on the target hardware and backend; the published benchmarks cover their named dispatch scenarios with minimal handler work.


Use source-filtered observation for specific entities, global observation for analytics, and post-processors for metrics. Batch emissions only when omitting intermediate values is acceptable, and measure diagnostics overhead in the configuration you plan to ship.


14) Compatibility with Scriptable Object Architecture (SOA)

Scriptable Object Architecture uses shared assets for data, variables, event channels or runtime sets. DxMessaging can carry notifications between systems that use those assets.

Unity's architecture guide demonstrates both mutable runtime variables and asset-based events. ScriptableObjects are not restricted to immutable configuration. The Unity 2021.3 manual distinguishes shared data loaded from assets from saving asset changes: a deployed player needs its own save system for persistent runtime changes.

What is Scriptable Object Architecture?

Ryan Hipple's Unite Austin 2017 talk describes assets used as shared variables, event channels and runtime collections. Serialized references let multiple components access the same asset. The asset's implementation defines its payload, mutation and listener behavior.

Choose Ownership and Reset Rules

Decide these responsibilities before connecting an asset to the bus:

  • State owner: Identify which asset or service owns health, scores or collection membership. A notification reports a change; it does not replace that state or answer a current-state query.
  • Initial state: Give new listeners a current snapshot when they need one. A listener that subscribes after a change cannot reconstruct it from future notifications alone.
  • Reset: Define what resets at a new game, scene boundary and play session. Test the domain reload configuration used by the project.
  • Subscription lifetime: Pair asset listeners and bus registrations with their actual owners. A bridge owns subscriptions on both sides.
  • Persistence: Separate authored defaults, runtime values and saved-game data. Decide which changes should survive a session and which storage writes them.
  • Testing: Restore shared asset state and dispose subscriptions between tests. Local buses isolate message routing; they do not isolate a shared asset's data.

Anti-ScriptableObject Architecture is a critique of these patterns. Evaluate its arguments alongside Unity's examples and the needs of your project; it does not establish that every runtime asset use is invalid.

Can DxMessaging Work with SOA?

Use an asset or service to own state and DxMessaging to report changes. Choose event assets when serialized asset references suit the authoring workflow. Choose typed bus registrations when code needs DxMessaging routing, interception, priorities or diagnostics. A bridge can connect the two.

Responsibility ScriptableObject-based design DxMessaging
State An asset can hold shared configuration or mutable runtime values Messages report changes; the application owns state
Authoring Serialized asset references and project-specific Inspector tooling Message types, registrations and optional component setup
Payload contract Defined by the event or variable implementation Typed message interfaces and handler signatures
Lifetime The application manages asset state and listeners Tokens, leases and components manage registrations when disposed or released
Diagnostics Asset Inspector and project tooling Bus and token diagnostics
Cost Depends on the asset implementation and listener work Depends on routes, handlers and diagnostics; measure the complete workload

Pattern Overview

Pattern What it shows When to use SOA involvement
A SOA Events (GameEvent) forwarding to DxMessaging Designer-created event assets, modern code downstream Yes - SOA Event pattern
B ScriptableObjects for configs + DxMessaging for events Shared authored config, typed runtime notifications No event-asset bridge

Pattern A: SOA -> DxMessaging (Event Forwarding)

Use case: Designer-created SOA events, but you want DxMessaging benefits downstream.

Strategy: SOA GameEventListener forwards to DxMessaging.

This uses the SOA GameEvent pattern: If you're NOT using designer-created GameEvent assets with Raise()/listener management, you don't need this pattern. For immutable config data, see Pattern B instead.

Example: Scene Transitions

C#
using System.Collections.Generic;
using DxMessaging.Core.Messages;
using DxMessaging.Unity;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using UnityEngine;
using UnityEngine.Events;

// Traditional SOA event
[CreateAssetMenu(menuName = "Events/Game Event")]
public class GameEvent : ScriptableObject
{
    private readonly List<UnityAction> listeners = new();

    public void Raise()
    {
        UnityAction[] snapshot = listeners.ToArray();
        for (int i = snapshot.Length - 1; 0 <= i; i--)
        {
            snapshot[i]?.Invoke();
        }
    }

    public void RegisterListener(UnityAction listener) => listeners.Add(listener);
    public void UnregisterListener(UnityAction listener) => listeners.Remove(listener);
}

// DxMessaging message (modern, type-safe)
[DxUntargetedMessage]
public readonly partial struct SceneTransitionRequested { }

// Bridge: SOA Event -> DxMessaging
public class SoaEventBridge : MonoBehaviour
{
    [SerializeField] private GameEvent onSceneTransitionSO; // Designer-created asset
    private EventSubscription subscription;

    private sealed class EventSubscription
    {
        private readonly SoaEventBridge owner;
        public GameEvent Publisher { get; }
        public UnityAction Callback { get; }

        public EventSubscription(SoaEventBridge owner, GameEvent publisher)
        {
            this.owner = owner;
            Publisher = publisher;
            Callback = Forward;
        }

        private void Forward()
        {
            if (ReferenceEquals(owner.subscription, this))
            {
                owner.OnSoaEvent();
            }
        }
    }

    void OnEnable()
    {
        OnDisable();
        if (onSceneTransitionSO == null)
        {
            return;
        }

        EventSubscription binding = new(this, onSceneTransitionSO);
        subscription = binding;
        binding.Publisher.RegisterListener(binding.Callback);
    }

    void OnDisable()
    {
        EventSubscription binding = subscription;
        subscription = null;
        if (binding != null)
        {
            binding.Publisher.UnregisterListener(binding.Callback);
        }
    }

    void OnSoaEvent()
    {
        // Forward to DxMessaging
        var message = new SceneTransitionRequested();
        message.Emit();
    }
}

// Modern DxMessaging listeners (no SO dependency)
public class AudioSystem : MessageAwareComponent
{
    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterUntargeted<SceneTransitionRequested>(OnTransition);
    }

    void OnTransition(in SceneTransitionRequested msg)
    {
        Debug.Log("Scene transition requested; start the application audio fade here.");
    }
}

Each Raise() uses a snapshot in reverse registration order. Listener edits affect later raises; a nested raise uses the updated list. Null callbacks are skipped, and an exception stops the current raise. RegisterListener permits duplicates; UnregisterListener removes the first matching entry. A nonempty listener list creates an array for each raise. Include that allocation when profiling this custom channel.

Assign the event asset before enabling the bridge. Each enable replaces the previous binding and creates a callback for that binding. Teardown invalidates it before unregistering from the cached asset, so a callback captured by an earlier raise cannot forward after that binding ends. Editing or clearing the Inspector field affects the next enable; cleanup still uses the subscribed asset. The audio listener logs the notification; replace that log with the application's fade operation.

Benefits
  • Designers create events in Inspector (SOA workflow preserved)
  • Code uses DxMessaging (type-safe, lifecycle-safe)
Drawbacks
  • Bridge boilerplate for each SOA event
  • Double registration (SOA listener + DxMessaging handler)

Pattern B: Configuration Assets and Runtime Messages

Use case: ScriptableObjects for immutable config data, DxMessaging for runtime events.

Strategy: Read shared configuration from assets and emit runtime notifications through the bus. No event-asset bridge is needed for this arrangement. This example leaves the configuration unchanged during play; that is an application choice, not a ScriptableObject restriction.

Example: Combat with Designer-Tunable Data

C#
using DxMessaging.Core;
using DxMessaging.Core.Extensions;
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Unity;
using UnityEngine;

// ScriptableObject: Designer-tunable balance data (immutable at runtime)
// This example reads configuration without changing it during play.
[CreateAssetMenu(menuName = "Config/Weapon Stats")]
public class WeaponStats : ScriptableObject
{
    public int baseDamage = 10;      // Designer tweaks in Inspector
    public float critMultiplier = 2f;
}

// DxMessaging: Runtime event (code-driven)
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct DamageDealt
{
    public readonly int amount;
    public readonly bool wasCrit;
}

// Combat system: Reads immutable SO data, emits DxMessaging events
public class Weapon : MessageAwareComponent
{
    [SerializeField] private WeaponStats stats; // Shared configuration read by this component

    public void Fire()
    {
        bool crit = Random.value < 0.1f;
        int damage = Mathf.RoundToInt(stats.baseDamage * (crit ? stats.critMultiplier : 1f));

        var msg = new DamageDealt(damage, crit);
        msg.EmitComponentBroadcast(this); // Runtime event via DxMessaging
    }
}

// Analytics: Pure DxMessaging (no SOA dependency)
public class CombatAnalytics : MessageAwareComponent
{
    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterBroadcastWithoutSource<DamageDealt>(OnDamage);
    }

    void OnDamage(InstanceId source, DamageDealt msg)
    {
        Debug.Log($"{source} dealt {msg.amount} damage (crit: {msg.wasCrit})");
    }
}
Responsibilities
  • Keep authored weapon settings separate from per-player mutable state.
  • Register analytics with the bus used by the sender and release registrations with their owner.
  • Measure any configuration lookup, message dispatch and listener work in the target application.

When to Use Each Pattern

Pattern Use when Ownership to define
A: SOA -> DxMessaging Existing event assets must notify bus listeners Asset listeners, bridge lifetime and bus registrations
B: Configs + messages Shared authored settings feed code that emits messages Configuration, runtime state and bus registrations
No bridge The application already uses one event system State, listener lifetime and reset rules in that system

These examples do not measure or rank the alternatives' performance.

Migration Path: SOA -> DxMessaging

Migrate a notification channel separately from the state it describes:

  1. Identify event producers, listeners, payloads and lifetime boundaries.
  2. Define equivalent typed messages and choose the bus each participant uses.
  3. Add a bridge for the event channels that must coexist during migration.
  4. Move listeners incrementally, checking that a transition does not produce duplicate delivery.
  5. Remove a bridge or asset only after every remaining reference and owner has been accounted for.

For shared variables, keep an explicit state owner. An asset or service can hold the current value while messages report changes. Preserve initialization, reset and save behavior if you move that state to another owner.

For runtime sets, retain a membership collection or service with queries for current members. Messages can announce additions and removals, but a new observer still needs an initial snapshot and a defined ordering between that snapshot and subsequent changes. A RegisterBroadcastWithoutSource subscription alone is not a replacement for a runtime set.

Final Recommendations

  • Keep existing asset workflows that meet the project's authoring and ownership needs.
  • Use Pattern A when existing event assets need to reach DxMessaging listeners.
  • Use Pattern B when shared configuration and runtime messages are sufficient for the application.
  • Test reset, subscription cleanup, initial-state delivery and persistence for the chosen design.
  • Compare measured workload costs before choosing an architecture for performance reasons.

Resources


Learn the Basics First?

Try Real Examples

Deep Dives

Reference