FAQ -- Frequently Asked Questions¶
Back to Index | Troubleshooting | Getting Started | Glossary
Do I need to use attributes or source generators¶
- No. You can implement
IUntargetedMessage<T>,ITargetedMessage<T>, orIBroadcastMessage<T>directly (recommended for structs). Attributes are optional and help tooling/source-gen.
Do I need an assembly definition for the source generator to work?¶
No. The package's generators reach Unity's default Assembly-CSharp and assemblies that directly reference WallstopStudios.DxMessaging.Attributes in 4.0. Keep the runtime reference when using messaging APIs. Apply a route attribute and mark the message and its containing declarations partial when you want generated members. A handwritten route-interface implementation without generator attributes does not require partial. See Troubleshooting for missing interfaces, constructors or emission helpers.
Which message type should I use?¶
- Untargeted - global notifications (any listener).
- Targeted - commands/events for a specific recipient.
- Broadcast - facts emitted from a source that others may observe.
Does DxMessaging allocate memory? Is dispatch zero-GC?¶
Ordinary typed steady-state struct dispatch has a regression contract of zero managed allocations. This assumes the selected route, registrations, callbacks and required buffers have warmed up and stay stable. A first message of a type is not a universal warmup boundary. Adding registrations can invalidate cached snapshots; a later emission may build a new snapshot or interceptor array after that message type has already emitted. Compiling with IL2CPP does not remove those data structures.
The readonly by-reference (FastHandler) overloads pass the struct by reference. The by-value Action<T> overloads pass a value copy; copying a struct does not itself box it. Constructing a class message allocates its instance. A struct is boxed when it reaches a global accept-all handler or user code upcasts it to a non-generic interface. Emission-site stack-trace capture allocates while enabled. User callbacks can also allocate independently of the bus.
Registration and deregistration have separate allocation and retained memory costs. Register long-lived subscriptions during setup instead of recreating them every frame. See Performance for measured scenario results and Troubleshooting for allocation checks.
How do I enforce ordering?¶
- Use the
priorityparameter at registration; lower runs earlier. Interceptors run before handlers; post-processors run after.
Can I observe all targets/sources for a type?¶
- Yes. Use
RegisterTargetedWithoutTargeting<T>orRegisterBroadcastWithoutSource<T>(and their post-processor counterparts).
How do I diagnose what's happening?¶
Enable Editor diagnostics, then choose the view that answers your question:
- Use Message Monitor to confirm that a message emitted, inspect its route kind and context, and open its captured call site.
- For loaded-scene
MessagingComponentreceivers, use Flow Graph to check whether a receiver registered for that message and whether the route has delivered calls. Direct bus or token registrations outside those components require bus logs or registration counters instead. - Use the Inspector overlay when a
MessageAwareComponentmay have missed a required base lifecycle call.
Start with Message Monitor. If the emission exists but a loaded-scene component receiver does not, move to Flow Graph to distinguish a missing registration from a route that has not delivered. The Diagnostics guide explains the tool scope, toggles, filters, trace capture, and release-build cost.
My MessageAwareComponent subclass does not receive messages. What is wrong?¶
The most common cause is forgetting to call base.Awake() (or base.OnEnable(), base.OnDisable(), base.OnDestroy(), base.RegisterMessageHandlers()) when you override one of those methods. The framework's setup runs in those base calls; without them, your registration token is never created or your handlers never enable. The Roslyn analyzer flags this as DXMSG006. See Inheritance and base calls for the full list of guarded methods.
What happens if I register a listener inside a message handler?¶
- The newly registered listener will not run for the current message emission. It will only become active starting with the next message emission.
- This is called "snapshot semantics" -- when a message is emitted, DxMessaging takes a snapshot of all current listeners and uses that frozen list for the entire emission.
- This applies to all listener types (handlers, interceptors, post-processors) and all message categories (Untargeted, Targeted, Broadcast).
- This behavior prevents infinite loops and ensures predictable execution order. See Interceptors & Ordering for details and examples.
Do I need a global bus?¶
- A global bus is provided (
MessageHandler.MessageBus). You can also create and pass your ownMessageBusinstance to isolate subsystems and tests.
Can I use DxMessaging with a dependency injection container?¶
- Yes. Installers ship for VContainer, Zenject, and Reflex; see Integrations. They wire the message bus into the container so your message-aware types resolve and register through it instead of reaching for the global bus.
How do I unit-test code that sends or receives messages?¶
- Construct a dedicated
MessageBusper test and pass it to the participants instead of using the global bus. Enable the registration token before emitting, assert that your handler observed the message, and dispose the token during cleanup. A local bus isolates routing; it does not make the runtime thread-safe. Run Unity messaging tests on the main thread and avoid concurrent access to shared settings or pools.
Is this compatible with Unity's SendMessage/UnityEvents¶
- Yes. You can integrate with legacy patterns via
ReflexiveMessage. Prefer DxMessaging for new code.
Why is my game retaining memory across scenes?¶
- Each scene introduces new
InstanceIds and sometimes new message types, which add empty slots on the bus when their handlers tear down. Idle eviction will reclaim them eventually; for deterministic cleanup callMessageHandler.TrimAll(force: true)on scene unload (orbus.Trim(force: true)for a non-global bus). See the Memory Reclamation guide for the full pattern.
Related Documentation¶
- New to DxMessaging?
- to Visual Guide -- Beginner-friendly introduction
- to Getting Started -- Complete guide
- to Glossary -- All terms explained
- Common Issues
- to Troubleshooting -- Solutions to common problems
- to Common Patterns -- See how to use it correctly
- Reference
- to Quick Reference -- API cheat sheet
- to Message Types -- Which type to use when