Quick Start - Your First Message in 5 Minutes¶

Back to Index | Getting Started | Visual Guide | Samples

Goal: Get a working message system in 5 minutes. Copy the scripts, add two components, and run.

Stuck? -> Troubleshooting | FAQ

Step 0: Install (30 seconds)¶

Unity Package Manager -> Add package from git URL:

https://github.com/Ambiguous-Interactive/DxMessaging.git

Requirements: Unity 2021.3+ | .NET Standard 2.1 | All render pipelines supported

Your First Message (3 Steps)¶

Step 1: Define a damage command¶

using DxMessaging.Core.Attributes;

[DxTargetedMessage]
[DxAutoConstructor]
public readonly partial struct DamageRequested
{
    public readonly int Amount;
}

The source generator adds the constructor and targeted message identity. The emit helper is a DxMessaging extension method.

Step 2: Receive damage¶

using DxMessaging.Unity;
using UnityEngine;

public sealed class DamageReceiver : MessageAwareComponent
{
    public int Health { get; private set; } = 100;

    protected override void RegisterMessageHandlers()
    {
        base.RegisterMessageHandlers();
        _ = Token.RegisterGameObjectTargeted<DamageRequested>(gameObject, OnDamageRequested);
    }

    private void OnDamageRequested(ref DamageRequested message)
    {
        Health = Mathf.Max(0, Health - Mathf.Max(0, message.Amount));
    }
}

Important: Inheritance and base calls¶

Important

If you override any of the lifecycle methods that DxMessaging hooks, your override must call the matching base method first. Forgetting this is silent: no errors, no compile failure, just dead handlers. The Roslyn analyzer (DXMSG006) and the Inspector overlay will flag the mistake, but they fire after the broken code is already written.

The five guarded methods, with what breaks if you forget the base call:

Start, Update, FixedUpdate, LateUpdate, and OnApplicationQuit are not hooked. You can override them without calling base.

See DXMSG006 in the analyzer reference and the symptom-first troubleshooting guide.

Step 3: Add a hazard¶

using DxMessaging.Core.Extensions;
using UnityEngine;

public sealed class Hazard : MonoBehaviour
{
    public int Damage = 25;

    private void OnTriggerEnter(Collider other)
    {
        DamageRequested request = new DamageRequested(Damage);
        request.EmitGameObjectTargeted(other.gameObject);
    }
}

On the hazard GameObject, enable Is Trigger on its collider and add a kinematic Rigidbody with Use Gravity disabled. Put DamageReceiver and the entering collider on the same target GameObject. The hazard sends the same command to whatever enters the trigger without a player field, receiver lookup, interface, or UnityEvent.

Summary¶

You have:

1. Defined a targeted gameplay command
2. Registered a receiver against its own GameObject
3. Sent the command to the object discovered by a physics event

Registration cleanup is automatic. Messages are type-safe.

What You Built¶

The hazard and damage receiver share only the DamageRequested contract. You can add shields, breakable props, enemies, or test doubles without changing Hazard. Use the message-type guide next to learn when a global announcement or source-bound event fits better than this targeted command.

Next Steps¶

• Understand What You Did
• -> Mental Model (10 min) - Philosophy and first principles
• -> Getting Started Guide (10 min) - Full explanation with examples
• -> Visual Guide (5 min) - Pictures and analogies
• Try Real Examples
• -> Mini Combat sample - Working combat example
• -> UI Buttons + Inspector sample - See diagnostics in action
• Go Deeper
• -> Message Types (10 min) - When to use which type
• -> Common Patterns (15 min) - Real-world solutions
• -> Interceptors & Ordering (10 min) - Advanced control
• Reference
• -> Quick Reference - Cheat sheet
• -> API Reference - Complete API
• -> Troubleshooting - Fix common issues

Quick Tips¶

Do's¶

• Use MessageAwareComponent for Unity components (automatic lifecycle)
• Store the struct in a variable before emitting: var message = new DamageRequested(10); message.EmitGameObjectTargeted(target);
• Call base.RegisterMessageHandlers() when overriding

Don'ts¶

• Don't emit from temporaries: new DamageRequested(10).EmitGameObjectTargeted(target) won't compile (struct emit methods require ref this)
• Don't use Untargeted for commands to one object (use Targeted instead)
• Don't forget using DxMessaging.Core.Extensions; for Emit* methods