Replication Server API

This page illustrates a few API you can use to interact with the Replication Server.

Connection to a Replication Server

When the Replication Server is running, you connect to it using the Connect method.

Connect to a local Replication Server

using Coherence;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class ConnectToLocal : MonoBehaviour
{
    void Start()
    {
        var Bridge = FindAnyObjectByType<CoherenceBridge>();
        
        var endpoint = new EndpointData
        {
            region = EndpointData.LocalRegion,
            host = "127.0.0.1",
            port = 32001,
            schemaId = RuntimeSettings.instance.SchemaID,
        };

        Bridge.Connect(endpoint);
    }
}

After trying to connect you might be interested in knowing whether the connection succeeded. The Connect call will run asynchronously and take around 100 ms to finish, or longer if you connect to a remote Server.

Respond to connection events

using Coherence;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class ConnectToLocal : MonoBehaviour
{
    private CoherenceBridge Bridge;

    void Start()
    {
        Bridge = FindAnyObjectByType<CoherenceBridge>();
        Bridge.onConnected.AddListener(HandleConnected);
        Bridge.onDisconnected.AddListener(HandleDisconnected);
        Bridge.onLiveQuerySynced.AddListener(HandleLiveQuerySynced);

        var endpoint = new EndpointData
        {
            region = EndpointData.LocalRegion,
            host = "127.0.0.1",
            port = 32001,
            schemaId = RuntimeSettings.instance.SchemaID,
        };

        Bridge.Connect(endpoint);
    }

    private void HandleConnected(CoherenceBridge _) { /* ... */ }

    private void HandleLiveQuerySynced(CoherenceBridge _) { /* ... */ }

    private void HandleDisconnected(CoherenceBridge _, ConnectionCloseReason reason) { /* ... */ }

    private void OnDestroy()
    {
        Bridge.onConnected.RemoveListener(HandleConnected);
        Bridge.onDisconnected.RemoveListener(HandleDisconnected);
        Bridge.onLiveQuerySynced.RemoveListener(HandleLiveQuerySynced);
    }
}

The OnLiveQuerySynced event is triggered when the initial game state has been synced to the client. More specifically, it is fired when all entities found by the Client's first Live Query have finished replicating. This is the last step of the connection process and is usually a good place to start the game simulation.

To connect to Cloud-hosted Servers, see Rooms API and Worlds API documentation.

Check Run in Background in the Unity settings under Project Settings > Player so that the Clients continue to run even when they're not the active window.

To connect with multiple Clients locally, publish a build for your platform (File > Build and Run, details in Unity docs). Run the Replication Server and launch the build any number of times. You can also enter Play Mode in the Unity Editor.

For Mac Users: You can open new instances of an application from the Terminal:

open -n <path to .app>

Unlock token

By default, the number of players that can connect to a locally hosted Replication Server is limited to 100.

By definition, a locally hosted Replication Server is one that is not managed by coherence, for example if it has been started from a Unity editor or by a game client in the self-hosting scenario. Replication Servers running in the coherence Cloud have no player limit.

This restriction can be lifted by supplying the SDK with an unlock token. The token can be generated in the Settings section of your project dashboard at coherence.io.

Once you have the token, it needs to be added to the coherence RuntimeSettings (Assets/coherence/RuntimeSettings.asset):

The unlock token will now be automatically passed to all the Replication Server instances started via Unity editor or the Coherence.Toolkit.ReplicationServer API.

If you plan to execute the Replication Server manually the token can be supplied via the --token <token> command line argument.