Skip to content

reference.md

Latest commit

 

History

History
375 lines (283 loc) · 10.5 KB

reference.md

File metadata and controls

375 lines (283 loc) · 10.5 KB
Raw

API Reference (Practical)

This reference provides a practical overview of the DxMessaging API for Unity developers.

Message Registration (Unity-Friendly)

The MessageRegistrationToken is your primary interface for subscribing to messages in a managed, lifecycle-aware manner.

Token Lifecycle Methods

// Enable/disable all registrations on this token
token.Enable();
token.Disable();

// Remove all registrations
token.UnregisterAll();

// Remove a specific registration
token.RemoveRegistration(handle);

Untargeted Message Registration

Register handlers for messages that have no specific target -- system-wide events.

// Standard handler (allocation-friendly for simple cases)
MessageRegistrationHandle RegisterUntargeted<T>(
    Action<T> handler,
    int priority = 0
);

// Fast handler (zero-allocation, receives message by readonly reference)
MessageRegistrationHandle RegisterUntargeted<T>(
    MessageHandler.FastHandler<T> handler,
    int priority = 0
);

// Post-processor (runs after all handlers)
MessageRegistrationHandle RegisterUntargetedPostProcessor<T>(
    MessageHandler.FastHandler<T> handler,
    int priority = 0
);

Targeted Message Registration

Register handlers for messages directed at specific GameObjects, Components, or InstanceIds.

Specific Target

// GameObject target
MessageRegistrationHandle RegisterGameObjectTargeted<T>(
    GameObject target,
    Action<T> handler,
    int priority = 0
);

// Component target
MessageRegistrationHandle RegisterComponentTargeted<T>(
    Component target,
    Action<T> handler,
    int priority = 0
);

// InstanceId target (low-level)
MessageRegistrationHandle RegisterTargeted<T>(
    InstanceId target,
    Action<T> handler,
    int priority = 0
);

All Targets

// Receive all targeted messages regardless of target
MessageRegistrationHandle RegisterTargetedWithoutTargeting<T>(
    MessageHandler.FastHandlerWithContext<T> handler,
    int priority = 0
);

Post-Processors

// Post-process for specific target
MessageRegistrationHandle RegisterTargetedPostProcessor<T>(
    InstanceId target,
    MessageHandler.FastHandler<T> handler,
    int priority = 0
);

// Post-process all targeted messages
MessageRegistrationHandle RegisterTargetedWithoutTargetingPostProcessor<T>(
    MessageHandler.FastHandlerWithContext<T> handler,
    int priority = 0
);

Broadcast Message Registration

Register handlers for messages broadcast from specific sources.

Specific Source

// From specific GameObject
MessageRegistrationHandle RegisterGameObjectBroadcast<T>(
    GameObject source,
    Action<T> handler,
    int priority = 0
);

// From specific Component
MessageRegistrationHandle RegisterComponentBroadcast<T>(
    Component source,
    Action<T> handler,
    int priority = 0
);

// From specific InstanceId
MessageRegistrationHandle RegisterBroadcast<T>(
    InstanceId source,
    Action<T> handler,
    int priority = 0
);

All Sources

// Receive broadcasts from any source
MessageRegistrationHandle RegisterBroadcastWithoutSource<T>(
    MessageHandler.FastHandlerWithContext<T> handler,
    int priority = 0
);

Post-Processors

// Post-process for specific source
MessageRegistrationHandle RegisterBroadcastPostProcessor<T>(
    InstanceId source,
    MessageHandler.FastHandler<T> handler,
    int priority = 0
);

// Post-process all broadcasts
MessageRegistrationHandle RegisterBroadcastWithoutSourcePostProcessor<T>(
    MessageHandler.FastHandlerWithContext<T> handler,
    int priority = 0
);

Emit Helpers

The DxMessaging.Core.Extensions.MessageExtensions class provides convenient extension methods for emitting messages.

Untargeted Emission

// Emit any message type as untargeted
message.Emit();
message.EmitUntargeted();

Targeted Emission

message.EmitTargeted(targetInstanceId);

// Emit to GameObject target
message.EmitGameObjectTargeted(targetGameObject);

// Emit to Component target
message.EmitComponentTargeted(targetComponent);

Broadcast Emission

// Broadcast from GameObject source
message.EmitGameObjectBroadcast(gameObject);

// Broadcast from Component source
message.EmitComponentBroadcast(this);

For lower-level sources that are already represented by an InstanceId, call EmitBroadcast. Prefer the Unity helpers above when the source is a GameObject or Component.

String Message Conveniences

// Quick string message emission
"PlayerDied".EmitFrom(gameObject);
"ApplyDamage".Emit(targetInstanceId);

Interceptors (Bus-Level)

Interceptors allow you to intercept and potentially modify or cancel messages at the bus level before they reach handlers.

// Intercept untargeted messages
Action RegisterUntargetedInterceptor<T>(
    UntargetedInterceptor<T> interceptor,
    int priority = 0
);

// Intercept targeted messages
Action RegisterTargetedInterceptor<T>(
    TargetedInterceptor<T> interceptor,
    int priority = 0
);

// Intercept broadcast messages
Action RegisterBroadcastInterceptor<T>(
    BroadcastInterceptor<T> interceptor,
    int priority = 0
);

// Global observer for all messages
Action RegisterGlobalAcceptAll(MessageHandler handler);

Diagnostics

DxMessaging provides diagnostic tools for debugging and monitoring message flow.

Global Settings

// Enable/disable diagnostics globally (DiagnosticsTarget is a [Flags] enum:
// Off, Editor, Runtime, All)
IMessageBus.GlobalDiagnosticsTargets = DiagnosticsTarget.All;

// Configure global message buffer size
IMessageBus.GlobalMessageBufferSize = 1024;

Per-Instance Settings

// Per-bus: IMessageBus.DiagnosticsMode is read-only; it reflects GlobalDiagnosticsTargets
// when the bus is created or reset. Read it to check whether diagnostics are active.
if (messageBus.DiagnosticsMode) { /* diagnostics are active on this bus */ }

// Per-token diagnostics
token.DiagnosticMode = true;

Registration Logging

// Enable registration logging
bus.Log.Enabled = true;

// Get log output
string logOutput = bus.Log.ToString();

Key Types

Type Description
DxMessaging.Core.InstanceId Value type identity for GameObjects, Components, or custom owners
DxMessaging.Core.MessageHandler Per-owner callback runner that manages message dispatch
DxMessaging.Core.MessageBus.MessageBus Instanced bus; global instance at MessageHandler.MessageBus
DxMessaging.Core.Messages.* Untargeted/Targeted/Broadcast interfaces and built-in string messages

💡 Tip: String Messages

For lightweight string-based messaging, see String Messages.

Unity Bridge Types

MessagingComponent

Unity owner component that hosts registrations and message dispatch for other MonoBehaviour components on the same GameObject. MessageAwareComponent adds it automatically.

public sealed class MessagingComponent : MonoBehaviour
{
    // When true, messages can be emitted even when component is disabled:
    // OnEnable/OnDisable leave the handler untouched while this is set
    public bool emitMessagesWhenDisabled;

    // Create a registration token for a listener on this GameObject
    public MessageRegistrationToken Create(MonoBehaviour listener);

    // Toggle the message handler on/off; explicit calls always win,
    // even while emitMessagesWhenDisabled is true
    public void ToggleMessageHandler(bool newActive);
}

MessageAwareComponent

Base component for objects that both emit and receive messages.

// Requires a MessagingComponent on the same GameObject ([RequireComponent]).
public abstract class MessageAwareComponent : MonoBehaviour
{
    // The registration token for this component
    public MessageRegistrationToken Token { get; }

    // When true, registrations are enabled/disabled with OnEnable/OnDisable
    protected virtual bool MessageRegistrationTiedToEnableStatus { get; }

    // When true (default false), enabling after MessagingComponent.Release
    // re-creates the token and replays RegisterMessageHandlers
    protected virtual bool ReregisterOnEnableAfterRelease { get; }

    // When true, registers string message demos (default false)
    protected virtual bool RegisterForStringMessages { get; }

    // Override to register your message handlers
    protected virtual void RegisterMessageHandlers() { }
}

Warning: Inheritance Tip

If you override any lifecycle hooks (Awake, OnDestroy, OnEnable, OnDisable) or RegisterMessageHandlers, always call the base method:

protected override void RegisterMessageHandlers()
{
    base.RegisterMessageHandlers();
    // Your registrations here
}

protected override void OnEnable()
{
    base.OnEnable();
    // Your logic here
}

Skipping base calls may prevent token setup and registrations declared by parent components.

Source Files

For deeper exploration, browse the source code:

Component Source
Message Bus Interface IMessageBus.cs
Message Bus MessageBus.cs
Message Handler MessageHandler.cs
Registration Token MessageRegistrationToken.cs
Emit Helpers MessageExtensions.cs
Attributes Attributes/