Messenger

The Messenger subsystem provides a typed, callback-driven messaging layer on top of Unity Netcode's CustomMessagingManager. It enables game systems to send and receive strongly-typed network messages without manually managing serialization, routing, or server relay — while supporting targeted delivery to specific clients.

Architecture

Message Flow

Key Concepts

Concept	Description
Handler ID	A string key that groups related messages. Each handler ID maps to one NetworkMessageHandler instance.
Message Header	The AssemblyQualifiedName of the payload type, used to dispatch to the correct callback within a handler.
Server Relay	Clients always send to the server. If the server is not the intended target, it relays the message to the specified target clients.
Payload Types	Messages support primitive types (string, int, byte), Unity vectors (Vector2, Vector3, Vector2Int, Vector3Int), and any INetworkSerializable type.
Unnamed Messages	The system uses Netcode's SendUnnamedMessage API — messages are identified by handler ID in the payload, not by named message registration.

Quick Start

Subscribing to Messages

// Subscribe to a typed message on a handler
NetworkManager.Messenger.SubscribeToMessage<int>("damage", OnDamageReceived);

void OnDamageReceived(int damageAmount)
{
    health -= damageAmount;
}

Sending Messages

// Send to specific clients
NetworkManager.Messenger.SendMessage(
    NetworkManager.ClientId,    // sender
    "damage",                   // handler ID
    25,                         // payload (int)
    targetClientId              // target client(s)
);

// Send to all other clients (omit target list)
NetworkManager.Messenger.SendMessage(
    NetworkManager.ClientId,
    "chat",
    "Hello everyone!"
);

Using Custom Serializable Payloads

public struct SpawnData : INetworkSerializable
{
    public int prefabId;
    public Vector3 position;

    public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
    {
        serializer.SerializeValue(ref prefabId);
        serializer.SerializeValue(ref position);
    }
}

// Subscribe and send
NetworkManager.Messenger.SubscribeToMessage<SpawnData>("spawn", OnSpawnReceived);
NetworkManager.Messenger.SendMessage(NetworkManager.ClientId, "spawn", new SpawnData { prefabId = 1, position = Vector3.zero });

Classes

Class	Description
NetworkMessenger	Central messaging hub — subscribes handlers, sends messages, receives and routes incoming messages.
NetworkMessageHandler	Abstract handler base and generic subclass — manages callbacks and deserializes incoming messages per handler ID.
NetworkMessage<TPayload>	Serializable struct wrapping a typed payload for network transport via INetworkSerializable.

See Also

• NetworkManager — singleton that owns the Messenger instance

• Network System — parent system overview