Client connections

Overview

The client connection system lets you uniquely identify users connected to the same session, find any user by his ID, spawn objects whenever a new user joins the session, and send messages between those users.

To achieve this a special connection entity is automatically created by the replication server for each connected client, including a simulator. Those entities are subject to a different rule set than standard entities. Connection entities:

• Can't be created or destroyed by the client - they are always replication server-driven

• Are global - they are replicated across clients regardless of the in-simulation distance or LiveQuery radius

Client connections shine whenever there's a need to communicate something to all the connected players. Usage examples:

• Global chat

• Game state changes: game started, game ended, map changed

• Server announcements

• Server-wide leaderboard

• Server-wide events

Enabling client connections

The globality of client connection doesn't fit all game types - for example, it rarely makes sense to keep every client informed about the presence of all players on the server in an MMORPG game (think World Of Warcraft). Due to this client connections are turned off by default.

To enable client connections turn on the global query in the MonoBridge (the Global Query On toggle):

MonoBridge component

Disabling global query on one client doesn't affect other clients, i.e. connection entity of this client will still be visible to other clients that have the global query turned on.

Connection management

Most of the client connection functionality is accessible through the CoherenceMonoBridge.ClientConnections object:

using System.Collections.Generic;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class GameManager : NetBehaviour
{
    public CoherenceMonoBridge MonoBridge;

    void Start()
    {   
        // IMPORTANT: All of the connection retrieving calls may return null 
        // if the connection system was not turned on, not initialized yet,
        // or simply if the connection was not found.

        // Raised whenever a new connection is made (including the local one).
        MonoBridge.ClientConnections.OnCreated += connection =>
        {
            Debug.Log($"Connection #{connection.ClientId} " +
                      $"of type {connection.Type} created.");
        };
        
        // Raised whenever a connection is destroyed.
        MonoBridge.ClientConnections.OnDestroyed += connection =>
        {
            Debug.Log($"Connection #{connection.ClientId} " +
                      $"of type {connection.Type} destroyed.");
        };

        // Specifies how many clients are in this session (room or world).
        int clientCount = MonoBridge.ClientConnections.ClientConnectionCount;

        // Returns connection objects for all connections in this session.
        IEnumerable<CoherenceClientConnection> allConnections 
            = MonoBridge.ClientConnections.GetAll();

        // Returns all connections except for the local one.
        IEnumerable<CoherenceClientConnection> otherConnections 
            = MonoBridge.ClientConnections.GetOther();

        // Returns connection object of the local user.
        CoherenceClientConnection myConnection 
            = MonoBridge.ClientConnections.GetMine();
        
        // Returns connection object of the simulator (if one is connected).
        CoherenceClientConnection simulatorConnection 
            = MonoBridge.ClientConnections.GetSimulator();

        // Retrieves a connection by its ClientID.
        CoherenceClientConnection selectedConnection 
            = MonoBridge.ClientConnections.Get(myConnection.ClientId);
        
        // Retrieves a connection by its EntityID (warning: requires
        // connection prefab with a CoherenceSync attached).
        if (myConnection.Sync != null)
        {
            selectedConnection 
                = MonoBridge.ClientConnections.Get(myConnection.Sync.EntityID);
        }
        
        // Specifies if this is a client or a simulator connection.
        ConnectionType connectionType = selectedConnection.Type;
        
        // Specifies if this is a local connection (belonging to the
        // local user).
        bool isMine = selectedConnection.IsMyConnection;
        
        // Returns a GameObject associated with this connection.
        // Applicable only if connection prefabs are used.
        GameObject connectionGameObject = selectedConnection.GameObject;
    }
}

Each connection is represented by a plain C# CoherenceClientConnection object. It contains all the important information about a connection - its ClientID, Type, whether it IsMyConnection, and a reference to the GameObject and Coherence Sync associated with it.

The CoherenceClientConnection.ClientID is guaranteed to not change during connection's lifetime. However, if client disconnects and then connects again to the same room/world, a new ClientID will be assigned (since a new connection was established).

Connection objects

Each client connection can have a GameObject with CoherenceSync automatically being spawned and associated with it. Those objects, like any other objects with CoherenceSync, can be used for syncing properties or sending messages, with a little twist - they are global and thus not limited by the live query radius. That makes them perfect candidates for operations like:

• Syncing global information - name, stats, tags, etc.

• Sending global messages - chat, server interaction

To enable connection objects:

1. Create a client connection prefab

This step is described in detail in the Prefab setup section. In short, a prefab with a CoherenceSync and a custom component (PlayerConnection in this example) must be created and placed in the Resources directory:

PlayerConnection prefab

2. Link a connection prefab to the MonoBridge

For the system to know which object to create for every new client connection, we have to link our prefab to the MonoBridge. Simply drag the prefab to the Client field in the MonoBridge inspector:

MonoBridge with linked connection prefab

From now on every new connection will be assigned an instance of this prefab, which can be accessed through the CoherenceClientConnection.GameObject property.

Prefab selection

Note that there's a separate field for the Simulator Connection Prefab. It can be used to spawn a completely different object for the simulator connection that may contain simulator specific commands and replicated properties. If the field is left empty, no object will be created for the simulator connection.

The prefab selection process can be also controlled from code using the CoherenceMonoBridge.ClientConnections.ProvidePrefab callback:

using System.Collections.Generic;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class GameManager : NetBehaviour
{
    public CoherenceMonoBridge MonoBridge;
    public CoherenceSync CustomConnectionPrefab;

    void Start()
    {
        MonoBridge = FindObjectOfType<CoherenceMonoBridge>();
        MonoBridge.ClientConnections.ProvidePrefab += (clientId, connectionType) =>
        {
            return CustomConnectionPrefab;
        };
    }
}

A prefab provided through the ProvidePrefab callback takes precedence over prefabs linked in the inspector.

Client messages

Client messages are commands sent between the client connection objects. Implementing client messages is as simple as adding a new method to the component used by our connection prefab and binding it in the configuration:

public class PlayerConnection : MonoBehaviour
{
    // My chat command
    public void OnChatMessage(string message)
    {
        Debug.Log($"Received chat message: {message}");
    }
}

Don't forget to bind the new command:

Binding a client message

Client messages can be sent using the CoherenceClientConnection.SendClientMessage method:

using Coherence;
using Coherence.Toolkit;
using UnityEngine;

public class PlayerConnection : MonoBehaviour
{
    void Start()
    {
        var monoBridge = FindObjectOfType<CoherenceMonoBridge>();
        CoherenceClientConnection myConnection = monoBridge.ClientConnections.GetMine();
        
        myConnection.SendClientMessage<PlayerConnection>(nameof(OnChatMessage), 
            MessageTarget.Other, "Hello!");
    }
    
    // My chat command
    public void OnChatMessage(string message)
    {
        Debug.Log($"Received chat message: {message}");
    }
}

If the ClientID of the message recipient is known we can use the CoherenceMonoBridge.ClientConnections directly to send a client message:

private int lastClientId;

private void OnConnectionCreated(CoherenceClientConnection clientConnection)
{
    if (!clientConnection.IsMyConnection)
    {
        lastClientId = clientConnection.ClientId;
    }
}

public void SendMessageToLastConnection(string message)
{
    MonoBridge.ClientConnections.SendMessage<PlayerConnection>("OnChatMessage",
        lastClientId, MessageTarget.AuthorityOnly, "Hello!");
}