Implementing Client-hosting

Bundling the Replication Server

To bundle a Replication Server with the build of your game, go to coherence > Settings and tick the Local Replication Server > Bundle In Build checkbox.

Currently, coherence supports bundling on Windows, MacOS, and Linux. We are working on adding support for more platforms in the future.

If your game uses a custom build process where the automatic bundling doesn't work well, you can also use a manual approach.

Here's a code example:

void CustomBuildStep(BuildTarget targetPlatform)
{
    Coherence.Editor.ReplicationServerBundler.BundleWithStreamingAssets(targetPlatform);
}

The BundleWithStreamingAssets method will copy the Replication Server and a combined schema (which contains all active schemas) for the target platform into the streaming assets folder.

Starting a local Replication Server

To start the bundled Replication Server from within your game, you can use the Launcher and ReplicationServer classes provided by the coherence Unity SDK. It will make sure that the correct parameters are passed to the Replication Server at startup, and it will also help you manage the child process.

Here's a simple code example of how to start and stop the Replication Server using the coherence API:

using Coherence.Toolkit.ReplicationServer;
using UnityEngine;

public class SelfHostingLauncher
{
    IReplicationServer replicationServer;

    public void StartReplicationServer()
    {
        var config = new ReplicationServerConfig
        {
            Mode = Mode.World,
            APIPort = 64002,
            UDPPort = 32001,
            SignallingPort = 32002,
            SendFrequency = 20,
            ReceiveFrequency = 60,
        };

        replicationServer = Launcher.Create(config, $"--env dev");
        replicationServer.OnLog += message => Debug.Log($"Server log: {message}");
        replicationServer.OnExit += code => Debug.Log($"Server exited with code: {code}");
        replicationServer.Start();
    }

    public void StopReplicationServer()
    {
        replicationServer.Stop();
        replicationServer = null;
    }
}

It is very important to keep track of your child process (via the IReplicationServer object) and close it down properly, or else you will leave the Replication Server running on the user's machine. Note that it's only the person hosting a game that needs to start an instance of the Replication Server, players joining a game should connect normally.

In case your game crashes, and your child processes are not cleaned up, it might be useful to set a AutoShutdownTimeout so that the Replication Server (RS) will automatically shut down after certain amount of milliseconds when no Clients are connected to it. By default AutoShutdownTimeout is set to 0, which means the Replication Server will never shut down automatically.

Replication Server log output

By default, the coherence Replication Server will output its logs to the standard output. Use OnLog event in the ReplicationServer class to receive log events in your Unity application. If you configure the LogTargets in the ReplicationServerConfig object, make sure to add a LogTarget.Console target or OnLog event will not work as expected.

var config = new ReplicationServerConfig
{
    Mode = Mode.World,
    APIPort = 64002,
    UDPPort = 32001,
    // ...
    LogTargets = new LogTargetConfig[]
    {
        new()
        {
            Target = LogTarget.Console,
            Format = LogFormat.Plain,
            LogLevel = LogLevel.Debug,
        },
    },
};

Relays

For players to communicate with one another over the Internet, a networking service is required. The networking service provides features such as setting up games, establishing connections, and sending data.

By default, coherence provides all of these networking services out-of-the-box. In this scenario, players all communicate with one another via a Replication Server that is hosted in the coherence Cloud, so you don't have to worry about anything.

In a Client-hosted scenario however, the Replication Server runs on the hosting player's machine. Therefore, the connectivity between clients and host must be provided via an external networking service. In the context of Client-hosting, we call such networking service a relay, since it is used to relay traffic between the Clients and the Replication Server running on the host's machine. You can also think of a relay as tunneling traffic between clients and host.

To make things easy, coherence has created a number of relays for popular on-line services. Click to read more:

If you have a custom solution or coherence does not provide one for on-line service there is the ability to create your own custom relay.

Last updated 12 days ago

Was this helpful?