Skip to content

Reference Glossary

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

Glossary -- DxMessaging Terms Explained

..-Getting-Started | ..-Getting-Started-Getting-Started | ..-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

Memory Reclamation Terms

Idle Eviction

Background reclamation that resets empty per-message-type and per-context slots after they have stayed empty for IdleEvictionSeconds worth of bus activity ticks. Active registrations are never touched. Gated by EvictionEnabled and EvictionTickIntervalSeconds.

Sweep

A single pass of the reclamation algorithm. A sweep walks dirty-tracked slots and pool entries, resets the eligible empty ones, and updates the live occupancy counters. Triggered by emit-time sampling, the Unity PlayerLoop hook, or an explicit Trim call.

Trim

The public API (IMessageBus.Trim / MessageHandler.TrimAll) that runs a sweep synchronously. With force: true it ignores the idle threshold and drains shared pools to zero; with force: false it uses the same idle threshold as scheduled sweeps. Gated by EnableTrimApi.

TrimResult

The struct returned by Trim. Its fields (TypeSlotsEvicted, TargetSlotsEvicted, PooledCollectionsEvicted, LiveTypeSlotsRemaining) report how much state the sweep reclaimed and how much remains live.

Empty Slot

A typed-handler, interceptor, or context slot whose registrations have all been deregistered. Empty slots stay around until reclamation runs because a freshly empty slot is often about to be reused on the next dispatch.

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

Term One-Line Explanation
Message Data saying "something happened" or "do something"
Handler Function that runs when you receive a message
Token Subscription manager (auto-cleanup)
Interceptor Guard that checks/modifies messages before delivery
Post-Processor Code that runs after all handlers (logging/metrics)
Priority Number controlling execution order (lower = earlier)
Emit Send a message
Register Subscribe to receive messages
InstanceId Unique ID for a GameObject or Component
Bus Central message router (like a post office)

Related Documentation

Learn More

Reference

DxMessaging Wiki

Getting Started

Concepts

Guides

Architecture

Advanced

Integrations

Examples

Reference

Links

Clone this wiki locally