Skip to content

Latest commit

 

History

History
365 lines (274 loc) · 9.43 KB

reference.md

File metadata and controls

365 lines (274 loc) · 9.43 KB

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 ref)
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>(
    FastHandlerWithContext<T> handler,
    int priority = 0
)

Post-Processors

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

// Post-process all targeted messages
MessageRegistrationHandle RegisterTargetedWithoutTargetingPostProcessor<T>(
    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>(
    FastHandlerWithContext<T> handler,
    int priority = 0
)

Post-Processors

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

// Post-process all broadcasts
MessageRegistrationHandle RegisterBroadcastWithoutSourcePostProcessor<T>(
    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

// Emit to specific target (by InstanceId)
message.EmitTargeted(InstanceId target);

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

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

Broadcast Emission

// Broadcast from specific source (by InstanceId)
message.EmitBroadcast(InstanceId source);

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

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

String Message Conveniences

// Quick string message emission
"PlayerDied".Emit();
"DamageDealt".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
IMessageBus.GlobalDiagnosticsMode = true;

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

Per-Instance Settings

// Per-bus diagnostics
messageBus.DiagnosticsMode = true;

// 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

Base component for objects that emit messages.

public class MessagingComponent : MonoBehaviour
{
    // When true, messages can be emitted even when component is disabled
    public bool emitMessagesWhenDisabled;

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

    // Toggle the message handler on/off
    public void ToggleMessageHandler(bool enabled);
}

MessageAwareComponent

Base component for objects that both emit and receive messages.

public abstract class MessageAwareComponent : MessagingComponent
{
    // 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, registers for string messages automatically
    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 default string-message registrations.

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/