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.

The Bundle In Build option in Project Settings

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:

• Steam

• Epic Online Services

• Azure Playfab

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.

Custom relay (Advanced)

Similar to the Steam relay above, you can create your own custom relay implementation and route traffic via any networking service. The relay implementation consists of three parts, each class implementing one of three interfaces.

• ITransport (Client) - Outgoing connection. Passes messages between the client and the networking service.

• IRelay (Host) - Listens for incoming connections and instantiates IRelayConnections.

• IRelayConnection (Host) - Incoming connection. Passes messages between the Replication Server and the networking service.

Let's say we want to implement a custom relay that uses an API called FoobarNetworkingService. The code here outlines the main points to implement for routing network traffic.

First, we'll create a CustomTransport class to manage the outgoing connection from the client to the host. CustomTransport implements the ITransport interface that provides a few important methods. The Open and Close methods are used to connect and disconnect to/from the networking service. The Send and Receive methods are used to send and receive messages to/from the networking service.

using System;
using System.Collections.Generic;
using System.Net;
using Coherence.Brook;
using Coherence.Common;
using Coherence.Connection;
using Coherence.Transport;

public class CustomTransport : ITransport
{
    // Members required by ITransport
    public event Action OnOpen;
    public event Action<ConnectionException> OnError;
    public TransportState State { get; private set; }
    public bool IsReliable => false;
    public bool CanSend => true;
    public int HeaderSize => 0;
    public string Description => "Custom";

    // In this example, data is routed over a FoobarConnection that is provided by the FoobarNetworkingService
    private FoobarConnection foobarConnection;
        
    // The networking service normally requires some way to identify the host, for example a string or IP-address
    private string hostEndpoint;

    // Instantiates the CustomTransport configured to connect to a specific remote host endpoint
    public CustomTransport(string hostEndpoint)
    {
        this.hostEndpoint = hostEndpoint;
    }

    // This method is called when the client calls CoherenceBridge.Connect
    public void Open(EndpointData _, ConnectionSettings __)
    {
        // Initialize the networking service
        FoobarNetworkingService.Init();

        // Connect to the FoobarNetworkingService
        foobarConnection = FoobarNetworkingService.OpenNewOutgoingConnection(hostEndpoint);

        // Mark the transport as open, i.e. ready to send and receive messages
        State = TransportState.Open;

        // Notify the client that the connection has been opened
        OnOpen?.Invoke();
    }

    // This method is called when the CoherenceBridge disconnects
    public void Close()
    {
        // Mark the transport as closed, i.e., no longer able to send or receive messages
        State = TransportState.Closed;

        // Disconnect from the FoobarNetworkingService
        foobarConnection.Close();

        // Dispose the networking service
        FoobarNetworkingService.Shutdown();
    }

    // This method is not mandatory but can be used e.g., to send a final disconnect message before the connection is closed
    public void PrepareDisconnect() { }

    // This method is called each frame. The buffer should be populated with incoming messages
    public void Receive(List<(IInOctetStream, IPEndPoint)> buffer)
    {
        // If there are any incoming messages, push them to the return buffer
        while (foobarConnection.TryReceiveMessage(out var data))
        {
            buffer.Add((new InOctetStream(data), default));
        }
    }

    // This method is called for each packet that the client wants to send to the Replication Server
    public void Send(IOutOctetStream stream)
    {
        // Convert the stream to a byte-array and send it over the foobarConnection
        foobarConnection.SendMessage(stream.Close().ToArray());
    }

    public void SendTo(IOutOctetStream stream, IPEndPoint endpoint, SessionID sessionID)
    {
        throw new Exception("SendTo not supported on this transport.");
    }
}

The CustomTransport will be instantiated when the client attempts to connect to the host, usually as a result of calling CoherenceBridge.Connect. You can control how the transport is instantiated by implementing an ITransportFactory.

using Coherence.Log;
using Coherence.Stats;
using Coherence.Transport;

public class CustomTransportFactory : ITransportFactory
{
    // The transport factory is a good place to inject the host identifier or endpoint.
    private string hostIdentifier;

    public CustomTransportFactory(string hostIdentifier)
    {
        this.hostIdentifier = hostIdentifier;
    }

    public ITransport Create(IStats stats, Logger logger)
    {
        return new CustomTransport(hostIdentifier);
    }
}

Finally, to configure the client to actually use the CustomTransport, just set the transport factory on CoherenceBridge.

// This is called on the client
CoherenceBridge.SetTransportFactory(new CustomTransportFactory("some host identifier"));

This is everything needed on the client-side.

You can call _SetTransportFactory(null)_ to disable the custom transport and connect as normal.

On the host-side, we need a CustomRelayConnection class to manage the incoming connection. This class implements IRelayConnection and is a mirror image of the CustomTransport. The OnConnectionOpened and OnConnectionClosed methods are called in response to CustomTransport.Open and CustomTransport.Close.

The SendMessageToClient and ReceiveMessagesFromClient methods are responsible for sending and receiving messages over the networking services, similar to CustomTransport.Send and CustomTransport.Receive.

using Coherence.Toolkit.Relay;

public class CustomRelayConnection : IRelayConnection
{
    // In this example, data is routed over a FoobarConnection that is provided by the FoobarNetworkingService
    private FoobarConnection foobarConnection;

    public CustomRelayConnection(FoobarConnection foobarConnection)
    {
        this.foobarConnection = foobarConnection;
    }

    // This is a good place to initialize an opened connection
    public void OnConnectionOpened() { }

    // This is a good place to dispose a closed connection
    public void OnConnectionClosed() { }

    // This method is called each frame. The buffer should be populated with incoming messages.
    public void ReceiveMessagesFromClient(List<ArraySegment<byte>> buffer)
    {
        // If there are any incoming messages, push them to the return buffer
        while (foobarConnection.TryReceiveMessage(out var data))
        {
            buffer.Add(new ArraySegment<byte>(data));
        }
    }

    // This method is called for each packet that the Replication Server wants to send to the client
    public void SendMessageToClient(ArraySegment<byte> packetData)
    {
        // Convert the stream to a byte-array and send it over the foobarConnection
        foobarConnection.SendMessage(packetData.ToArray());
    }
}

Now we just need a CustomRelay class that listens for incoming FoobarConnections and maps them to a corresponding CustomRelayConnection.

using Coherence.Toolkit.Relay;
using System.Collections.Generic;

public class CustomRelay : IRelay
{
    // This property is populated by the CoherenceBridge and provides access to the CoherenceRelayManager.
    public CoherenceRelayManager RelayManager { get; set; }

    // A map to keep track of all existing relay connections
    private Dictionary<FoobarConnection, IRelayConnection> connectionMap = new Dictionary<FoobarConnection, IRelayConnection>();

    // This method is called when the host has connected to the replication server.
    public void Open()
    {
        // Initialize the networking service
        FoobarNetworkingService.Init();

        // Listen for connection events
        FoobarNetworkingService.OnConnectionOpened += HandleFoobarConnectionOpened;
        FoobarNetworkingService.OnConnectionClosed += HandleFoobarConnectionClosed;
    }

    private void HandleFoobarConnectionOpened(FoobarConnection foobarConnection)
    {
        // Create a new relay connection
        var relayConnection = new CustomRelayConnection(foobarConnection);

        // Map the connection for easy access later
        connectionMap[foobarConnection] = relayConnection;

        // Register the new relay connection
        RelayManager.OpenRelayConnection(relayConnection);
    }

    private void HandleFoobarConnectionClosed(FoobarConnection foobarConnection)
    {
        // Use the map to find the corresponding relay connection
        var relayConnection = connectionMap[foobarConnection];

        // Unregister the relay connection
        RelayManager.CloseAndRemoveRelayConnection(relayConnection);

        // Remove the connection from the map
        connectionMap.Remove(foobarConnection);
    }

    // This method is called when the host has disconnected from the replication server.
    public void Close()
    {
        // Dispose the networking service
        FoobarNetworkingService.Shutdown();

        // Unsubscribe event listeners
        FoobarNetworkingService.OnConnectionOpened += HandleFoobarConnectionOpened;
        FoobarNetworkingService.OnConnectionClosed += HandleFoobarConnectionClosed;
    }

    // This method is called every frame.
    public void Update()
    {
        // Tick the networking service
        FoobarNetworkingService.Update();
    }
}

Finally, to configure the host to actually use the CustomRelay, simply set the relay on the CoherenceBridge:

// This is called on the host
CoherenceBridge.SetRelay(new CustomRelay());

You can call SetRelay(null) to disable relaying.

These are all the necessary steps required to configure a custom relay.

For a complete relay code example, please review the Steam Relay source code.