Messaging

Messages are the most basic way of communicating information between clients in the same session. Messages allow you to send a payload of bytes (max 1200 per message) which can take advantage of different message behaviors.

In order to send a message, you first must define the message in your project. This is so the multiplayer relay server knows how to handle your message. To be able to receive the message you will need to set up a handler.

Sending a message is done via the network client, once you are connected. The example belows shows how to send a simple message with a payload of bytes.

// Basic send message implementation
ImmerseMultiplayer.Client.SendMessage(_messageDefinition, messageId, new byte[] { 1, 2, 3, 4 });

The payload of bytes can be replaced with whatever information you wish to communicate. You just need to be able to serialize it. Extensions for the INetworkClient are included in the multiplayer package that can serialize and deserialize simple types or strings using UTF8 encoding.

// Send a message with a string payload
ImmerseMultiplayer.Client.SendMessage(_messageDefinition, messageId, "Hello World");

// Message handler that deserializes the payload to a string
private void MessageHandler(IMessage message)
{
    Debug.Log(message.PayloadAsString());
}

Message IDs are helpful for differentiating between multiple sources that could be sending messages of the same type.

For example, when sending messages for NetworkBehaviours, internally, we reuse the component’s unique ID as the message ID to ensure that each instance maintains a own state.

When a message definition is marked with the is-persisted behaviour, it means that when new users connect or reconnect to a session, they will receive those messages that were previously sent. Messages are stored by their type and ID, meaning that you can have many persisted messages for each message definition, as long as they are using unique message IDs.

To delete the stored value of a persisted message, sending a null payload will delete the stored message matching that type and ID. All connected users will receive the empty message so they can perform any required clean up they may require.

// Delete the stored value from the server
ImmerseMultiplayer.Client.SendMessage(_messageDefinition, messageId, null);

The broadcast to self behaviour means that when a message is sent to the relay server, it will also be broadcast back to the local user. Using this, rather than acting locally and sending an update to remote users, ensures that all users are receiving the same sequence of events.