Skip to content

Unity Integration

Unity-centric helpers make registration lifecycles explicit and safe.

MessagingComponent

  • Attach to any GameObject that will send or receive messages.
  • Creates a per-owner MessageHandler and offers Create(this) to get a MessageRegistrationToken.
  • Call Configure(IMessageBus, MessageBusRebindMode) before Create if you want the component to use a custom bus (e.g., one resolved from a DI container). Passing MessageBusRebindMode.RebindActive migrates current registrations; PreserveRegistrations defers the swap until the next enable.
  • Optional: set emitMessagesWhenDisabled if you need to emit while disabled.

Fixed in v4.0.0: A token created before host activation starts with delivery suspended unless emitMessagesWhenDisabled is enabled. Token enable state and handler activity are separate; enabling a token does not activate its GameObject.

During Configure(..., RebindActive), a custom bus cleanup callback can release or replace another listener. Remaining owned listeners still migrate. The outer call leaves work accepted independently on a released token under that token's caller; it does not migrate that work. A cleanup exception propagates without discarding the remaining cached owners.

Destroying an initialized MessagingComponent deactivates its shared handler and disposes its owned tokens, including tokens created by plain MonoBehaviour listeners. This also applies when only the MessagingComponent is removed. If a custom bus throws during deregistration, cleanup continues for other listeners and logs the full exception. Retain the component and listener references and retry Release(listener) after the bus recovers. An interceptor whose removal fails remains registered until that retry succeeds.

Release(listener) returns true when cleanup completes and removes the cached token. A nested release of the same token returns false while the owning release is in progress. If a deregistration callback accepts new work on the token, the component keeps that work cached and returns false. Release it after the callback finishes. A cleanup exception also keeps the token cached for a public retry.

Unity only sends OnDestroy to previously active GameObjects. If you create tokens on a host that has never been active, call Release(listener) or dispose each token before discarding it. A manual listener removed while its messaging owner survives must also release its token.

MessageAwareComponent

  • Derive for a batteries-included pattern; it manages a token for you.
  • Override RegisterMessageHandlers() to stage registrations.
  • The token is enabled/disabled with the component's enable state.
  • Call ConfigureMessageBus(IMessageBus, MessageBusRebindMode) before base.Awake() (or shortly after via a DI bootstrapper) to ensure the token is created against your container-provided bus.
C#
using DxMessaging.Unity;
using DxMessaging.Core.Messages;

public sealed class HealthComponent : MessageAwareComponent
{
    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterComponentTargeted<ApplyDamage>(this, OnApplyDamage);
        _ = Token.RegisterUntargeted<WorldRegenerated>(OnWorldRegenerated);
    }

    private void OnApplyDamage(in ApplyDamage m) => Apply(m.amount);
    private void OnWorldRegenerated(in WorldRegenerated m) => Reset();
}

Do's

  • Use MessageAwareComponent when possible to avoid boilerplate.
  • Override RegisterMessageHandlers() and bind to named methods.
  • Keep handlers small and fast; offload heavy work.

Don'ts

  • Don't register in Update; register once and enable/disable with component state.
  • Don't forget to call base.RegisterMessageHandlers() if your subclass relies on base registrations.

Important: Inheritance and base calls

  • MessageAwareComponent uses many virtual methods (e.g., Awake, OnEnable, OnDisable, RegisterMessageHandlers).
  • CRITICAL: If you override any of these, you MUST call the base method: base.Awake(), base.OnEnable(), base.OnDisable(), base.RegisterMessageHandlers().
  • Always call base.RegisterMessageHandlers() first in your override -- this ensures parent class registrations happen before yours.
  • Skipping base calls can break core setup and registrations declared by a parent component.
  • Override RegisterForStringMessages => true when you want the built-in string demos.
  • Don't hide Unity methods with new (e.g., new void OnEnable()); always override and call base.*.

Diagnostics and analyzer: DxMessaging ships a Roslyn analyzer + Inspector overlay that catches missing base calls at compile time and surfaces them as a HelpBox at the top of the offending component's Inspector. See the Inspector Overlay & Base-Call Warnings guide for the day-to-day workflow, or the Roslyn Analyzers & Diagnostics reference for every diagnostic id and the suppression-precedence ordering.

Registration timing

  • Prefer Awake() for registration rather than Start().
  • MessageAwareComponent automatically calls RegisterMessageHandlers() in Awake().
  • Early registration in Awake() ensures handlers are ready before other components' Start() methods run.
  • If you need custom setup before registration, override Awake(), do your setup, then call base.Awake().

Manual token management

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

[RequireComponent(typeof(MessagingComponent))]
public sealed class InventoryUI : UnityEngine.MonoBehaviour
{
    private MessagingComponent _messaging;
    private MessageRegistrationToken _token;

    private void Awake()
    {
        _messaging = GetComponent<MessagingComponent>();
        _token = _messaging.Create(this);
        _ = _token.RegisterUntargeted<WorldRegenerated>(OnWorld);
        _ = _token.RegisterComponentTargeted<ApplyDamage>(this, OnDamage);
    }

    private void OnEnable() => _token.Enable();
    private void OnDisable() => _token.Disable();
    private void OnDestroy() => _messaging.Release(this);

    private void OnWorld(in WorldRegenerated m) { /* update UI */ }
    private void OnDamage(in ApplyDamage m) { /* apply damage */ }
}

Composable lifecycle ownership (4.0.0)

Use MessagingLifecycle when your class already inherits another base, such as RuntimeSingleton<T>, and cannot inherit MessageAwareComponent. The manual example above keeps both the component and token. The helper below owns those references together and keeps failed cleanup available for retry. Keep your existing base class and follow its own base-call requirements.

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

namespace Examples.Inventory
{
    public readonly struct InventoryChanged : IUntargetedMessage<InventoryChanged>
    {
        public System.Type MessageType => typeof(InventoryChanged);
    }

    [RequireComponent(typeof(MessagingComponent))]
    public sealed class InventoryLifecycleUI : MonoBehaviour
    {
        private MessagingLifecycle _messages;

        private void Awake()
        {
            MessagingComponent component = GetComponent<MessagingComponent>();
            _messages = component.CreateLifecycleBound(this);
            _ = _messages.Token.RegisterUntargeted<InventoryChanged>(OnInventoryChanged);
        }

        private void OnEnable() => _messages.Enable();
        private void OnDisable() => _messages?.Disable();
        private void OnDestroy() => _messages?.Dispose();

        private void OnInventoryChanged(in InventoryChanged message)
        {
            Debug.Log("Inventory changed");
        }
    }
}

The helper requires explicit forwarding from all four callbacks; it does not install callbacks. DXMSG015 reports missing initialization, activation, deactivation, or disposal for owned helper fields. It follows source forwarding methods and inherited callbacks, but does not prove conditional reachability, aliases, interface dispatch, or behavior in referenced binaries.

Configure the MessagingComponent bus or provider before creating the helper. Existing Configure calls and active bus migration also apply to its captured token. Disabling keeps staged handlers for pooling; successful disposal removes them and releases the listener cache. Activation stops when component destruction begins. A released or replaced token cannot be re-enabled through a stale helper, and stale disposal never releases its replacement. Keep one lifecycle owner per listener token. A second factory call throws InvalidOperationException until successful disposal or Release removes that token. Failed cleanup keeps ownership reserved.

A custom bus can throw during cleanup. Retain the helper and retry Dispose after the bus recovers. Work accepted by a cleanup callback can also leave IsDisposed false without an exception. Token remains available until final cleanup succeeds. Afterward, Token and Enable throw ObjectDisposedException; Disable and repeated Dispose are harmless. For a never-active host, dispose explicitly because Unity may not send OnDestroy.

Manual enable/disable (advanced)

C#
public sealed class AlwaysListening : MessageAwareComponent
{
    protected override bool MessageRegistrationTiedToEnableStatus => false; // keep token enabled

    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterUntargeted<MyEvent>(OnEvent);
        Token.Enable(); // explicitly enable once
    }

    private void OnEvent(in MyEvent m) { /* ... */ }
}

String message demos (opt-in)

C#
public sealed class StringDemoReceiver : MessageAwareComponent
{
    protected override bool RegisterForStringMessages => true;

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

ReflexiveMessage (bridging legacy SendMessage)

Reflected receiver lookup skips methods with unassigned generic type arguments and keeps callable concrete overloads, including compatible object and interface parameters. It does not infer generic type arguments. The native Unity single-argument path follows Unity's receiver rules.

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

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

Callbacks that reset the bus cancel the current reflexive emission, including callbacks in custom reflection metadata. Eligible zero- or one-argument sends use Unity's GameObject.SendMessage on an active GameObject. If a receiver resets the bus during that call, Unity may still deliver to other receivers on the same GameObject. DxMessaging checks for the reset after Unity finishes that delivery and does not continue the canceled emission. Emit a new message after the reset to deliver it.

Related