Replication Server

The Replication Server replicates the state of the world to all connected Clients and Simulators.

To understand what is happening in the Game World, and to be able to contribute your simulated values, you need to connect to a Replication Server. The Replication Server acts as a central place where data is received from and distributed to interested Clients.

You can connect to a Replication Server in the cloud, but we recommend that you first start one locally on your computer. coherence is designed so you can easily develop everything locally first, before deploying to the cloud.

Replication Servers replicate data defined in schema files. The schema's inspector provides all the tools needed to start a Replication Server.

1. Run the Replication Server by clicking the Run button or copy the run command to the clipboard via clicking the copy run-command icon located to the right of it.

2. A terminal/command line will pop up, running your Server locally.

3. The port the Replication Server will use. Rooms: 42001 Worlds: 32001

4. The web port used for webGL connections. Rooms: 42001 Worlds: 32002

5. The Replication Server send frequency. Default: 20 packets / s

6. The Replication Server receive frequency. Default: 60 packets / s

You can also start the Replication Server from the coherence menu or by pressing Ctrl+Shift+Alt+N.

Replication Server send and receive frequencies

The Replication Server supports different packet frequencies for sending and receiving data.

The send frequency is the frequency that the Replication Server uses to send packets to a given Client. Each Client can be sent packets at different times, but the packet receive frequency for any Client will not exceed the Replication Server's send frequency.

The receive frequency is the maximum frequency at which the Replication Server expects to receive packets from any Client, before throttling. If a Client sends packets to the Replication Server at a higher than expected frequency, that Client will receive a command to slow down sending. If the Client doesn't respect the command to throttle packet sending then the Client is disconnected after a time. All extra packets received by the Replication Server, after a threshold based on the receive frequency, are dropped and not processed. This is to prevent malicious Clients from flooding the Replication Server. The Unity SDK handles throttling automatically.

It is possible for the Replication Server to temporarily request Clients to reduce their packet send rates if the processing load of the Replication Server is too high. This is automatic and send rates from the affected Clients are commanded to resume once the load is reduced.

Low and consistent send rates from the Replication Server allow for optimal bandwidth use and still support a smooth stream of updates to Clients. Try different rates during local replication tests to see what works well for your game.

Currently, there is no support in the project dashboard to set the rates for your project in the cloud, but you can send a request to [e-mail] to configure your project's Replication Server packet rates. This feature will be added in the future.

Connecting 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.Common;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

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

        monoBridge.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 CoherenceMonoBridge monoBridge;

    void Start()
    {
        monoBridge = FindObjectOfType<CoherenceMonoBridge>();
        monoBridge.onConnected.AddListener(HandleConnected);
        monoBridge.OnLiveQuerySynced += HandleLiveQuerySynced;
        monoBridge.onDisconnected.AddListener(HandleDisconnected);

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

        monoBridge.Connect(endpoint);
    }

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

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

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

    private void OnDestroy()
    {
        monoBridge.onConnected.RemoveListener(HandleConnected);
        monoBridge.onDisconnected.RemoveListener(HandleDisconnected);
    }

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 a 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>