The MonoBridge is a system that makes sure every GameObject is linked to its networked representation. It essentially interfaces between the GameObject world and the DOTS/ECS-based coherence SDK code running "under the hood".

When you place a GameObject in your scene, the MonoBridge detects it and makes sure all the synchronization can be done via the CoherenceSync component.

LiveQuery

The way you get information about the world is through LiveQueries. We set criteria for what part of the world we are interested in at each given moment. That way, the replicator won’t send information about everything that is going on in the game world everywhere, at all times.

Instead, we will just get information about what’s within a certain area, kind of like moving a torch around to look in a dark cave.

Adding a LiveQuery to the scene

A LiveQuery is a cube that defines the area of interest in a particular part of the world. It is defined by its position and its radius (half the side of the cube). There can be multiple LiveQueries in a single scene.

Moving a LiveQuery

A classic approach is to put a LiveQuery on the camera and set the radius to correspond to the far clipping plane or visibility distance.

Moving the GameObject containing the LiveQuery will also notify the replication server that the query for that particular game client has moved.

The coherence Sample UI prefab that comes bundled with the coherence SDK contains some basic UI controls that allows you to easily connect to and disconnect from servers.

The connect dialog lists all available servers for your game. If the list is empty, please make sure you have setup your game on the coherence portal and deployed a replication server. Also make sure you have selected the correct region from the Region dropdown menu.

The connect dialog comes in two flavors, one is for Rooms and the other is for Worlds. The Connect Dialog Rooms is enabled by default. If your project is configured for Worlds, you'll need to select the coherence Sample UI in the Hierarchy window and activate the Connect Dialog Worlds.

Connect Dialog Rooms allows you to create or join rooms on the selected region.

Connect Dialog Worlds allows you to join worlds on the selected region, but you can only create new worlds from the coherence portal.

Refer to the Level of detail section for more information.

SDK Overview

The coherence SDK is a set of prefabs & scripts to help you create multiplayer games super fast.

It makes it easy for anyone to create a multiplayer game by having flexible, intuitive and powerful visual components.

Here are the main building blocks of the SDK.

CoherenceSync (Component)

CoherenceSync is a component that should be attached to every networked Game Object. It may be your player, an NPC or an inanimate object such as a ball, a projectile or a banana. Anything that needs to be synchronized over the network. You can select which of the attached components you would like to sync across the network as well as individual public properties.

Settings (Window)

The coherence Settings window is located in Project Settings -> coherence and lets you launch a local replication server, upload your server to the cloud via the access token and bakes your schemas for more optimized data transfer of our Networked GameObjects.

LiveQuery (Component)

LiveQuery, as the name suggests, queries a location set by the developer so that coherence can simulate anything within its radius. In our Starter Project, the LiveQuery position is static with a radius large enough to cover the entire playable level. If the world was very large and potentially set over multiple simulation servers, the LiveQuery could be attached to the playable character or camera.

MonoBridge (Component)

The coherence MonoBridge passes information between the coherenceSync component and the networked ECS components.

Sample UI

The sample UI Prefab holds all of the UI and connection functionality to connect to the running project locally or via a server. You can completely rewrite this if you like, it's there to get you up and running quickly.

Build and Run Server

The coherence Settings window is located in Project Settings -> coherence and lets you launch a local replication server, upload your server to the cloud via the access token and bakes your Schemas for more optimized data transfer of Networked GameObjects.

Enable CoherenceSync support

Uncheck Enable CoherenceSync support to go pure ECS and use none of the visual tools.

Bake Schemas

When CoherenceSync variables/components are turned into ECS to send over the network, C# reflection is used to sync all the data at runtime. Whilst this is really useful for prototyping quickly and getting things working, it can be quite slow and poorly performing. A way to combat this is to bake the CoherenceSync component into a Schema.

The Schema is a text file that defines which data types in your project are synced over the network. It is the source from which coherence SDK generates C# struct types (and helper functions) that are used by the rest of your game. The coherence Replication Server also reads the Schema file to know about those types and to communicate them with all of its clients efficiently.

The Schema must be baked in the coherence Settings window, before the check box to bake this prefab can be clicked.

When the CoherenceSync component is baked, it generates a new file in the Inspector of that Game Object called NameOfGameObject_Sync.

Active Schemas

Select the Schema files you want to use.

• CoherenceSync (runtime reflection, slow)

• CoherenceSync (baked, fast)

Bake Output Folder

Defines where to store the baked Schema files.

Portal

Upload your Schema files to your server.

• Status - Current Status of your cloud server

• Token - Cloud token

Local Replication Server

Run a local replication server.

• Port - The port access

• Frequency - Frequency of server.

CustomBindingProviders are editor classes that tell coherence how a specific component should expose its bindings and how it generates baked scripts.

For example, we could create a custom binding provider for our Health component:

using UnityEngine;

public class Health : MonoBehaviour
{
    public int health;
}

using UnityEngine;
using Coherence.Toolkit;

[CustomBindingProvider(typeof(Health))]
public class HealthBindingProvider : CustomBindingProvider
{
    // check the CustomBindingProvider base class to
    // explore the possibilities!
}

We can add additional (custom) bindings:

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

[CustomBindingProvider(typeof(Health))]
public class CustomTransformBindingProvider : CustomBindingProvider
{
    public override void FetchDescriptors(Component component, List<CustomBinding.Descriptor> descriptors)
    {
        base.FetchDescriptors(component, descriptors);
        descriptors.Add(new CustomBinding.Descriptor("myCustomBinding", typeof(int))
        {
            bakedSyncScriptGetter = "myCustomBindingGet",
            bakedSyncScriptSetter = "myCustomBindingSet",
            coherenceComponentName = "MyCustomBinding",
            coherenceComponentFieldName = "value",
            schemaComponentFieldName = "value",
        });
        descriptors.Add(new CustomBinding.Descriptor("debugBinding", typeof(bool))
        {
            bakedSyncScriptGetter = "debugBindingGet",
            bakedSyncScriptSetter = "debugBindingSet",
            coherenceComponentName = "DebugBinding",
            coherenceComponentFieldName = "value",
            schemaComponentFieldName = "value",
        });
    }
}

Check the CustomBinding.Descriptor API for further properties, like interpolation or marking the binding as required.

CustomBindingRuntimeSerializer

For custom bindings to work on reflected mode, we need to implement how their values are serialized and deserialized at runtime:

using UnityEngine;
using Coherence.Toolkit;
using Coherence.Entity;
using Coherence.SimulationFrame;

// this class defines how reflected mode serializes and deserializes Health's custom bindings

public class HealthRuntimeSerializer : CustomBindingRuntimeSerializer
{
    public override void Serialize(CustomBinding customBinding, ICoherenceComponentData componentData)
    {
        var health = customBinding.component as Health;

        if (customBinding.descriptor.name == "debugBinding")
        {
            Debug.Log("[HEALTH] Serializing debugBinding");
        }
        else if (customBinding.descriptor.name == "myCustomBinding")
        {
            // in this example, lets send myCustomBinding as "health" over the network
            var fi = componentData.GetType().GetField("value");
            fi.SetValue(componentData, health.health);
        }
    }

    public override void Deserialize(CoherenceMonoBridge monoBridge, CustomBinding customBinding, ICoherenceComponentData componentData)
    {
        var health = customBinding.component as Health;

        if (customBinding.descriptor.name == "debugBinding")
        {
            Debug.Log("[HEALTH] Deserializing debugBinding");
        }
        else if (customBinding.descriptor.name == "myCustomBinding")
        {
            var fi = componentData.GetType().GetField("value");
            var v = (float)fi.GetValue(componentData);
            // we take the value of myCustomBinding, which we know we serialized with the valeu of health
            // in this example, we just do some custom logic: updating the isAlive bool with it
            health.isAlive = v > 0;
        }
    }

    public override void PerformInterpolation(CoherenceMonoBridge monoBridge, CustomBinding customBinding, AbsoluteSimulationFrame localFrame, float deltaTime)
    {
    }

    public override void ChangeInterpolationSetup(CustomBinding customBinding, string setupName)
    {
    }

    public override void ResetInterpolation(CustomBinding customBinding)
    {
    }
}

Once we have our runtime serializer, we need to make our binding provider use it:

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

[CustomBindingProvider(typeof(Health))]
public class CustomTransformBindingProvider : CustomBindingProvider
{
    // here
    public override CustomBindingRuntimeSerializer CustomBindingRuntimeSerializer => new HealthRuntimeSerializer();

    public override void FetchDescriptors(Component component, List<CustomBinding.Descriptor> descriptors)
    {
        base.FetchDescriptors(component, descriptors);
        descriptors.Add(new CustomBinding.Descriptor("myCustomBinding", typeof(int))
        {
            bakedSyncScriptGetter = "myCustomBindingGet",
            bakedSyncScriptSetter = "myCustomBindingSet",
            coherenceComponentName = "MyCustomBinding",
            coherenceComponentFieldName = "value",
            schemaComponentFieldName = "value",
        });
        descriptors.Add(new CustomBinding.Descriptor("debugBinding", typeof(bool))
        {
            bakedSyncScriptGetter = "debugBindingGet",
            bakedSyncScriptSetter = "debugBindingSet",
            coherenceComponentName = "DebugBinding",
            coherenceComponentFieldName = "value",
            schemaComponentFieldName = "value",
        });
    }
}

Extending and inheriting CustomBindingProviders

You can extend an already existing CustomBindingProvider. For example, coherence ships with a CustomBindingProvider for Transforms:

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

[CustomBindingProvider(typeof(Transform))]
public class CustomTransformBindingProvider : TransformBindingProvider
{
    public override void FetchDescriptors(Component component, List<CustomBinding.Descriptor> descriptors)
    {
        base.FetchDescriptors(component, descriptors);
        // your changes
    }
    
    // ...
}

This way, you can define additional rules on how you want to treat your Transforms, for example.

Any amount of CustomBindingProviders can be registered over the same component, but only one being used. The one being used, is resolved by a priority integer that you can specify in the CustomBindingProvider attribute. The class with the higher priority defined in the attribute will be the only provider taken into account:

[CustomBindingProvider(typeof(Transform), 1)]

The default priority is set at 0, and coherence's internal CustomBindingProviders have a priority of -1.

To understand how these APIs are used, check out TransformBindingProvider and AnimatorBindingProvider, both shipped with the coherence SDK (<package>/Coherence.Editor/Toolkit/CustomBindingProviders).

CoherenceSync is a component that should be attached to every networked Game Object. It may be your player, an NPC or an inanimate object such as a ball, a projectile or a banana. Anything that needs to be synchronized over the network and turned into an Entity. You can select which of the attached components you would like to sync across the network as well as individual public properties.

Synced Variables and Commands

Any scripts attached to the component with CoherenceSync that have public variables will be shown here and can be synced across the network. Enable the script + the variable to sync, it's that easy. Those variables with a lightning bolt next to them signify a public method that can be activated via commands.

Persistence and Authority

Ownership Transfer

When you create a networked game object, you automatically become the owner of that game object. That means only you are allowed to update or destroy it. But sometimes it is necessary to pass ownership from one player to another. For example, you could snatch the football in a soccer game or throw a mind control spell in a strategy game. In this case, you will need to transfer ownership from one client to another.

Entity Lifetime Type

When a player disconnects, all the game objects created by that player are usually destroyed. If you want any game objects to stay in the game world after the owner disconnects, you need to set Entity lifetime type of that game object to Persistent.

• Session Based - Will be removed when the client disconnects

• Persistence - Entities with this option will persist as long as the server is running. Auto Generate Persistance UUID should be checked so that a unique identification string will be used to regenerate the object when you reconnect to the server. When the entity is spawned with this checked it will generate its own UUID.

Entity Simulation Type

• Client Side - Simulates everything on the local client and passes the information to the Replication Server to distribute that information to the other clients.

• Other forms of simulation (Server; Server with Client Input) coming soon.

Authority Transfer Style

• Not Transferable - The default value is Not Transferable because most often objects are not meant to be transferred.

• Stealing - Allows the game object to be transferred to another client.

• Request - This option is intended for conditional transfers, which is not yet supported.

Orphaned Entities

By making the game object persistent, you ensure that it remains in the game world even after its owner disconnects. But once the game object has lost its owner, it will remain frozen in place because no client is allowed to update or delete it. This is called an orphaned game object.

In order to make the orphaned game object interactive again, another client needs to take ownership of it. To do this, you need to set When orphaned to Auto Adopt.

Transfer Request

Once you have set the transfer style to stealing, any client can request ownership by calling the RequestAuthority() method on the CoherenceSync component of that game object:

someGameObject.GetComponent<CoherenceSync>().RequestAuthority();

A request will be sent to the game object's current owner. The current owner will then accept the request and complete the transfer.

You are now the new owner of the game object. This means the isSimulated flag has been set to true, indicating that you are now in full control of the game object. The previous owner is no longer allowed to update or destroy it.

Connection Status

When this object is synchronized over the network lets you set if you instantiate the specific prefab or an alternative one by giving its name path (Make sure it's in the Resources folder). Very useful if you are setting up a local player (with controls, camera etc) and a variant without those components.

Event system for handling user connection and disconnection. Destroy Component Only is really useful for session based objects that you want to keep "semi persistent" which would be removed when all the clients disconnect.

Bake/Optimize Script

When CoherenceSync variables/components are turned into ECS to send over the network, C# reflection is used to sync all the data at runtime. Whilst this is really useful for prototyping quickly and getting things working, it can be quite slow and unperformant. A way to combat this is to bake the CoherenceSync component into a Schema.

The schema is a text file that defines which data types in your project are synced over the network. It is the source from which coherence SDK generates C# struct types (and helper functions) that are used by the rest of your game. The coherence Replication Server also reads the Schema file so that it knows about those types and communicates them with all of its clients efficiently.

The Schema must be baked in the coherence Settings window before the check box to bake this prefab can be clicked.

When the CoherenceSync component is baked, it generates a new file in the Inspector of that Game Object called NameOfGameObject_Sync.

OnNetworkedInstantiation and OnNetworkedDestruction

OnNetworkedInstantiation is called when the network entity is instantiated by coherence. This is the best moment to make sure you prepare the GameObject the way you need. For example, disabling colliders or swapping materials.

OnNetworkedDestruction is called when the network entity is going to be destroyed by coherence. The boolean parameter it takes reports if the destruction behavior is set to just destroy CoherenceSync rather than the Game Object.

Commands

Refer to the commands section.