Glossary — DxMessaging Terms Explained¶

← Back to Index | Getting Started | Visual Guide

New to messaging systems? This glossary explains key terms in plain English.

Core Concepts¶

Message¶

A data structure that represents something that happened or should happen. Think of it like a letter or announcement containing information.

Example: Heal { amount: 10 } is a message saying "heal for 10 points."

Message Type¶

The category of message that determines who receives it:

• Untargeted: Everyone hears it (like a megaphone announcement)
• Targeted: One specific recipient gets it (like a letter to an address)
• Broadcast: Comes from one source, anyone can listen (like a news broadcast)

Handler¶

A function that runs when a message is received. Your game logic goes here.

Example:

void OnHeal(ref Heal msg) {
    health += msg.amount; // This is the handler
}

Token¶

A registration handle that manages the lifecycle of your message handlers. It automatically enables/disables handlers when your component is active/inactive.

Think of it like a subscription card — when you destroy it, all your subscriptions end automatically.

MessageAwareComponent¶

A Unity MonoBehaviour base class that handles all the lifecycle management for you. Inherit from this and you get automatic setup/cleanup.

public class MyComponent : MessageAwareComponent {
    // Token is created automatically!
}

Message Pipeline¶

Interceptor¶

Code that runs before handlers. Can validate, modify, or cancel messages before anyone else sees them.

Example: "Only allow damage between 1 and 999"

// Use the type-specific interceptor variant based on your message type:
// - RegisterUntargetedInterceptor<T> for IUntargetedMessage
// - RegisterTargetedInterceptor<T> for ITargetedMessage
// - RegisterBroadcastInterceptor<T> for IBroadcastMessage
_ = token.RegisterBroadcastInterceptor<Damage>((ref InstanceId source, ref Damage msg) => {
    if (msg.amount <= 0) return false; // Cancel
    if (msg.amount > 999) msg = new Damage(999); // Clamp
    return true; // Allow
});

Post-Processor¶

Code that runs after all handlers. Perfect for logging, analytics, or metrics that shouldn't affect gameplay.

Example: "Track every damage event for statistics"

// Use the type-specific post-processor variant based on your message type:
// - RegisterUntargetedPostProcessor<T> for IUntargetedMessage
// - RegisterBroadcastWithoutSourcePostProcessor<T> for IBroadcastMessage from any source
_ = token.RegisterBroadcastWithoutSourcePostProcessor<Damage>((InstanceId source, Damage msg) => {
    Analytics.LogDamage(source, msg.amount);
});

Priority¶

A number that controls execution order. Lower numbers run first.

Example:

_ = token.RegisterUntargeted<GameExit>(SaveGame, priority: 0);  // Runs first
_ = token.RegisterUntargeted<GameExit>(FadeAudio, priority: 5); // Runs second
_ = token.RegisterUntargeted<GameExit>(ShowUI, priority: 10);   // Runs third

Unity Integration¶

InstanceId¶

A unique identifier for a GameObject or Component. Used internally to route messages to the right place.

You rarely use this directly — use the GameObject/Component helpers instead:

msg.EmitGameObjectTargeted(gameObject); // Helper (use this)
// vs
msg.EmitTargeted(gameObject.GetInstanceID()); // Manual InstanceId (avoid)

MessagingComponent¶

The base Unity component that provides messaging infrastructure. MessageAwareComponent inherits from this.

Emit¶

To send a message. Like hitting "send" on an email.

var heal = new Heal(10);
heal.Emit(); // Send it!

Register¶

To sign up to receive messages. Like subscribing to a newsletter.

_ = Token.RegisterUntargeted<Heal>(OnHeal); // Subscribe

Advanced Terms¶

Message Bus¶

The central routing system that delivers messages. Think of it like a post office.

There's a global bus (MessageHandler.MessageBus) that most code uses, but you can create local buses for testing or isolation.

Local Bus / Bus Island¶

A separate message bus used to isolate subsystems or tests. Messages sent to a local bus don't affect the global bus.

var testBus = new MessageBus(); // Create island
var token = MessageRegistrationToken.Create(handler, testBus); // Use it

Global Accept-All¶

A special handler that receives every single message regardless of type. Used for tools, debuggers, and analytics.

_ = Token.RegisterGlobalAcceptAll(
    (ref IUntargetedMessage m) => Debug.Log("Untargeted: " + m),
    (ref InstanceId t, ref ITargetedMessage m) => Debug.Log("Targeted: " + m),
    (ref InstanceId s, ref IBroadcastMessage m) => Debug.Log("Broadcast: " + m)
);

Diagnostics Mode¶

A debug feature that tracks message history and handler statistics. Enable in Editor, disable in builds for performance.

IMessageBus.GlobalDiagnosticsMode = true; // See message history

Attributes (Source Generation)¶

[DxUntargetedMessage]¶

Marks a struct as an Untargeted message (global announcement).

[DxTargetedMessage]¶

Marks a struct as a Targeted message (command to one recipient).

[DxBroadcastMessage]¶

Marks a struct as a Broadcast message (event from a source).

[DxAutoConstructor]¶

Auto-generates a constructor for your message struct so you don't have to write it manually.

[DxTargetedMessage]
[DxAutoConstructor] // Generates: public Heal(int amount) { this.amount = amount; }
public readonly partial struct Heal {
    public readonly int amount;
}

Common Patterns¶

Lifecycle¶

The creation and destruction of components and their message registrations.

DxMessaging handles this automatically via MessageAwareComponent:

• Awake(): Token created, handlers registered
• OnEnable(): Token enabled, handlers active
• OnDisable(): Token disabled, handlers inactive
• OnDestroy(): Token destroyed, everything cleaned up

Decoupling¶

Making systems independent so they don't need references to each other.

Before DxMessaging¶

public class UI : MonoBehaviour {
    [SerializeField] Player player; // Tight coupling!
    [SerializeField] EnemySpawner spawner;
    [SerializeField] AudioManager audio;
}

With DxMessaging¶

public class UI : MessageAwareComponent {
    // No references needed! Just listen for messages.
    protected override void RegisterMessageHandlers() {
        _ = Token.RegisterBroadcastWithoutSource<PlayerDamaged>(OnDamage);
    }
}

Quick Reference Table¶

Related Documentation¶

Learn More¶

• → Visual Guide — See these concepts visualized
• → Getting Started — Full introduction with examples
• → Message Types — When to use each type

Reference¶

• → Quick Reference — API cheat sheet

• → API Reference — Complete API documentation

• → Mini Combat sample — See concepts in action

• → Patterns — Real-world usage patterns