Message Types: When and How to Use¶
Back to Index | Getting Started | Patterns | Visual Guide
This guide introduces the three message categories in DxMessaging with concepts, when to use them, and practical code.
Overview¶
- Untargeted: global notifications anyone can listen to (e.g., world regenerated).
- Targeted: directed at one recipient (e.g., heal Player by 10).
- Broadcast: emitted from a source for anyone to observe (e.g., Enemy took 5 damage).
Quick Decision Guide¶
flowchart TD
Start([Choose Message Type])
Start --> Q1{Is it a global<br/>announcement?}
Q1 -->|Yes<br/>e.g., game paused,<br/>settings changed| Untargeted[ Use UNTARGETED<br/>Everyone listens]
Q1 -->|No| Q2{Are you commanding<br/>a specific entity?}
Q2 -->|Yes<br/>e.g., heal Player,<br/>open Chest #3| Targeted[ Use TARGETED<br/>One recipient]
Q2 -->|No| Q3{Is an entity announcing<br/>something happened?}
Q3 -->|Yes<br/>e.g., Enemy died,<br/>Chest opened| Broadcast[ Use BROADCAST<br/>Anyone can observe]
Q3 -->|No| Rethink[Rethink your<br/>message design]
classDef primary stroke-width:3px
class Untargeted primary
classDef warning stroke-width:3px
class Targeted warning
classDef success stroke-width:3px
class Broadcast success
classDef danger stroke-width:2px
class Rethink danger
classDef neutral stroke-width:2px
class Start,Q1,Q2,Q3 neutral Untargeted Messages¶
- Use for cross-cutting notifications: settings changed, scene loaded, world regenerated.
- Any listener can subscribe; no specific sender/recipient required.
- Define as immutable structs; prefer generic interface for zero-boxing.
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
[DxUntargetedMessage]
[DxAutoConstructor]
public readonly partial struct SceneLoaded
{
public readonly int buildIndex;
}
// Emit (bind struct to a variable)
var sceneLoaded = new SceneLoaded(UnityEngine.SceneManagement.SceneManager.GetActiveScene().buildIndex);
sceneLoaded.Emit();
Targeted Messages¶
- Use for commands/events directed at one entity: Heal, EquipWeapon, OpenDoor.
- You address a specific
InstanceId(e.g., a player GameObject/component). - Ideal when only one recipient should act.
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using UnityEngine;
[DxTargetedMessage]
[DxAutoConstructor]
public readonly partial struct Heal
{
public readonly int amount;
}
// Emit to one target (GameObject)
var heal = new Heal(10);
heal.EmitGameObjectTargeted(playerGameObject);
Broadcast Messages¶
- Use for reactionary "facts" about a specific source: TookDamage, PickedUpItem.
- Many systems can observe and react independently.
- Distinct from targeted: the source is the sender; listeners decide if they care.
using DxMessaging.Core.Messages;
using DxMessaging.Core.Attributes;
using DxMessaging.Core.Extensions;
using UnityEngine;
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct TookDamage
{
public readonly int amount;
}
// Emit from this GameObject
var hit = new TookDamage(5);
hit.EmitGameObjectBroadcast(gameObject);
Organizing Messages with Nested Types¶
Group related messages inside a container class for better organization:
using DxMessaging.Core.Attributes;
public enum DamageType
{
Physical,
}
public partial class CombatEvents
{
[DxTargetedMessage]
[DxAutoConstructor]
public readonly partial struct Heal
{
public readonly int amount;
[DxOptionalParameter(false)] // Custom default value
public readonly bool showEffect;
}
[DxBroadcastMessage]
[DxAutoConstructor]
public readonly partial struct TookDamage
{
public readonly int amount;
[DxOptionalParameter(Expression = "DamageType.Physical")] // Enum default
public readonly DamageType type;
}
}
// Usage:
var heal = new CombatEvents.Heal(10, showEffect: true);
heal.EmitComponentTargeted(player);
var damage = new CombatEvents.TookDamage(5); // Uses DamageType.Physical
damage.EmitGameObjectBroadcast(gameObject);
Containing classes, structs, and interfaces must all be partial.
Fixed in v4.0.0
Constructor and message-identity generation also preserve partial interface containers.
using DxMessaging.Core.Attributes;
public partial interface ICombatContract
{
[DxTargetedMessage]
[DxAutoConstructor]
public readonly partial struct DamageRequested
{
public readonly int Amount;
}
}
Generic interface containers can use invariant type parameters. C# does not permit nested classes or structs inside interfaces with in or out type parameters.
Benefits¶
- Reduces namespace pollution
- Makes message relationships clear
- Works with all message types (Untargeted, Targeted, Broadcast)
- Full source generator support
Listening to everything in a category¶
- All targeted of a type (any target):
RegisterTargetedWithoutTargeting<T>or post-process withRegisterTargetedWithoutTargetingPostProcessor<T>. - All broadcast of a type (any source):
RegisterBroadcastWithoutSource<T>or post-process withRegisterBroadcastWithoutSourcePostProcessor<T>.
using DxMessaging.Core;
using DxMessaging.Core.Messages;
// Observe every Heal regardless of target
_ = token.RegisterTargetedWithoutTargeting<Heal>(OnAnyHeal);
void OnAnyHeal(in InstanceId target, in Heal m) => Audit(target, m);
// Observe every TookDamage regardless of source
_ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyTookDamage);
void OnAnyTookDamage(in InstanceId source, in TookDamage m) => Track(source, m);
Choosing the right type¶
- Start with Broadcast for "X happened at Y" facts others may observe.
- Use Targeted when one specific recipient must act.
- Use Untargeted for global state changes anyone might care about.
Generic messages on IL2CPP¶
Generic messages support typed registration and typed emission on Mono and IL2CPP. For an IL2CPP message that can arrive through an untyped API before either typed operation, list each closed type in an assembly attribute (added in 4.0.0):
using DxMessaging.Core.Attributes;
[assembly: DxAotMessage(typeof(SettingRequestMessage<bool>))]
[assembly: DxAotMessage(typeof(SettingRequestMessage<QualityChoice>))]
[DxUntargetedMessage]
public readonly partial struct SettingRequestMessage<T>
{
public readonly T value;
public SettingRequestMessage(T value)
{
this.value = value;
}
}
public enum QualityChoice { Low, High }
Place these assembly attributes before namespace and type declarations in a source file in the consuming assembly. Add an entry for every closed type that needs a startup bridge, including closed generic containing types. The generator handles untargeted, targeted, and broadcast messages, whether attributed or handwritten. Repeated entries generate one bridge per message and route.
Use public or internal message types accessible from the consuming assembly. Selections from another assembly must be accessible there, including their type arguments. Open definitions such as SettingRequestMessage<>, abstract types, and types without a message contract report DXMSG014. Private nested messages can instead register a typed handler or emit through a typed API before the first untyped dispatch.
Ordinary non-generic attributed messages already generate startup bridges. The generator does not discover every closed generic use automatically. A type created only through reflection still needs an explicit closed selection or a prior typed operation. An unlisted first untyped message on IL2CPP throws an InvalidOperationException naming the missing bridge. Mono's reflection fallback does not require these assembly selections.
Do's¶
- Keep messages small, immutable, and specific.
- Use attributes +
DxAutoConstructorfor clarity and onboarding. - Use GameObject/Component helpers (
EmitGameObject*/EmitComponent*) instead of manualInstanceIdcasts. - Organize related messages using nested types for better structure.
- Use internal visibility for implementation-only messages.
Don'ts¶
- Don't use Untargeted for per-entity commands; prefer Targeted.
- Don't overload Broadcast for commands; commands need a recipient (Targeted).
- Avoid deep inheritance trees; messages should be small, flat data.
- Don't emit from temporaries; bind structs to a variable before
Emit*.
Related Documentation¶
Prerequisites¶
- to Getting Started -- Understand the basics first
- to Visual Guide -- See the 3 types visualized
Next Steps¶
- to Patterns -- Real-world examples of each type
- to Listening Patterns -- All the ways to receive messages
- to Interceptors & Ordering -- Control message flow
Try It¶
- to Quick Start -- Working example
- to Mini Combat sample -- See all 3 types in action