NetworkMessageHandler

Abstract base class and generic implementation for handling incoming network messages. Each handler is identified by a handlerId string and manages a set of typed callbacks. The generic subclass NetworkMessageHandler<TMessage> deserializes incoming messages, checks client targeting, invokes registered callbacks, and — on the server — relays messages to remaining target clients.

Definition

Namespace: Paragon.Core.Network Assembly: Paragon.dll

public abstract class NetworkMessageHandler

public class NetworkMessageHandler<TMessage> : NetworkMessageHandler

Remarks

The handler is the middle layer of the Messenger subsystem:

1. NetworkMessenger routes an incoming unnamed message to the correct handler by handlerId.

2. The handler reads the target client IDs and message header from the buffer.

3. If the local client is among the targets, it looks up and invokes the matching callback.

4. If the local peer is the server and other targets remain, it relays the message to those clients via the NetworkMessenger.

Callbacks are keyed by the payload type's AssemblyQualifiedName (the "message header"), allowing a single handler to support multiple message types under the same handler ID.

Quick Lookup

Goal	How
Register a callback	handler.AddMessageCallback(myCallback) (on generic subclass)
Handle incoming data	Automatic — ReceiveMessage() is called by NetworkMessenger
Create a handler	Typically done internally by NetworkMessenger.SubscribeToMessage()

---

NetworkMessageHandler (Abstract Base)

Fields

handlerId

The unique identifier for this handler, used as a lookup key in the NetworkMessenger.

protected readonly string handlerId;

Constructor

protected NetworkMessageHandler(string handlerId)

Parameter	Type	Description
handlerId	string	Unique handler identifier

Methods

ReceiveMessage

Processes an incoming message from the network buffer. Abstract — implemented by the generic subclass.

public abstract void ReceiveMessage(ulong clientId, FastBufferReader reader);

Parameter	Type	Description
clientId	ulong	The Netcode client ID of the sender
reader	FastBufferReader	The buffer containing the message data

---

NetworkMessageHandler<TMessage> (Generic)

Constructor

public NetworkMessageHandler(string handlerId)

Parameter	Type	Description
handlerId	string	Unique handler identifier

Methods

AddMessageCallback

Registers a callback to be invoked when a message of type TMessage is received. Multiple callbacks can be registered for the same message type — they are combined as a multicast delegate.

public void AddMessageCallback(Action<TMessage> callback)

Parameter	Type	Description
callback	Action<TMessage>	The callback to invoke with the deserialized payload

ReceiveMessage

Reads target client IDs and the message header from the buffer, deserializes the NetworkMessage<TPayload>, and:

1. If the local client is in the target list → invokes the registered callback.

2. If the local peer is the server and other targets remain → relays the message to those clients.

public override void ReceiveMessage(ulong clientId, FastBufferReader reader)

Parameter	Type	Description
clientId	ulong	The Netcode client ID of the sender
reader	FastBufferReader	The buffer containing target IDs, header, and payload

Receive Flow

ReceiveMessage(clientId, reader)
  ├─ Read targetClientIds (ulong[])
  ├─ Read messageHeader (string)
  ├─ Read NetworkMessage<TMessage>
  ├─ If local client is in targets:
  │    └─ Invoke callback(message.Payload)
  └─ If IsServer AND remaining targets exist:
       └─ Relay via NetworkMessenger.SendMessage()

Common Pitfalls

Missing callback throws exception If a message is received with a header that has no registered callback, ReceiveMessage() throws an Exception. Always register callbacks before messages can be received.

Handler ID must match between sender and receiver The handlerId used in SubscribeToMessage() must exactly match the one used in SendMessage(). Mismatched IDs cause the messenger to throw an exception when looking up the handler.

Server relay behavior On the server, ReceiveMessage() both processes the message locally (if the server is a target) and relays to remaining targets. This means the server's callback may fire before the relay, and the relay uses NetworkMessenger.SendMessage() which re-serializes the message.

See Also

• NetworkMessenger — creates handlers and routes messages to them

• NetworkMessage<TPayload> — the serializable message struct

• Messenger Subsystem — subsystem overview