Overview

coherence is a network engine, platform and a series of tools to help anyone create a multiplayer game.

• Fast network engine with cloud scaling, state replication, persistence and auto load balancing.

• Easy to develop, iterate and operate connected games and experiences.

• SDK allows developers to make multiplayer games using Windows, Linux or Mac, targeting desktop, console, mobile, VR or the web.

• Game engine plugins and visual tools will help even non-coders create and quickly iterate on a connected game idea.

• Scalable from small games to large virtual worlds running on hundreds of servers.

• Game-service features like user account, key-value stores and matchmaking.

Network Engine

At the core of coherence lies a fast network engine based on bitstreams and a data-oriented architecture, with numerous optimization techniques like delta compression, quantization and network LOD-ing ("Level of Detail") to minimize bandwidth and maximize performance.

Authority Models

The network engine supports multiple authority models:

• Client authority

• Server authority

• Server authority with client prediction

• Authority handover (request, steal)

• Distributed authority (multiple simulators with seamless transition)

• Deterministic client prediction with rollback ("GGPO"): coming in a future release

Persistence

coherence supports persistence out of the box.

This means that the state of the world is preserved no matter if clients or simulators are connected to it or not. This way, you can create shared worlds where visitors have a lasting impact.

Engine Support

coherence is currently in private preview. Some stability and performance issues may still be present and being ironed out. Additionally, more features are planned for the public release later this year.

Current features

General

• Custom UDP transport layer using bit streams with reliability

• Smooth state replication

• Server-side, client-side, distributed authority

• Connected entity support

• Fast authority transfer

• Remote messaging (RPC)

• Persistence

• Multiple examples and showcases

• Support for Windows, Mac, Linux, Android, iOS, etc.

SDK

• Unity SDK with intuitive no-code layer

• Per-field adjustable interpolation and extrapolation

• Input queues

• ECS/DOTS support

• Easy deployment into the cloud

• SDK source included, no 3rd-party libraries

Optimization and performance

• Per-field compression and quantization

• Per-field sampling frequency adjustable at runtime

• Unlimited per-field levels of detail

• Areas of interest

Online

• Developer portal with server and service configurator

• Multiple regions (US East, EU Central)

• Player accounts

• Key-value store

• Matchmaking

• Ability to deploy one replication server and one simulation server per environment

• Prometheus and Grafana integration

Coming soon

General

• Removed reliance on Entities package

• Performance improvements

• WebGL / WebAssembly support

• WebRTC support

• Accurate SimulationFrame tracking

SDK

• Better support for in-scene networked entities (decoupling uniqueness and persistence)

• Support for lean pure C# clients and simulators without Unity

• Faster input queues

• Network Profiler

Online

• Additional regions

• Support for multiple simulators and replicators in a single project

• Dashboard with usage statistics

Mid-term roadmap

• Peer-to-peer (without replication server) with NAT punch-through

• TCP fallback support

• WebSockets support

• MTU detection

• Packet replay

• Ability to deploy multiple simulation servers per environment

• Player analytics

• Additional packet compression

• Developer portal graphs and analytics

• Simulator authentication

Roadmap

• JavaScript SDK

• Unreal Engine SDK

• Multiple replication servers per game world

• Customer-specific serialization

• User-space load-balancing (SDK framework)

• Game world map with admin interface

• Anti-cheat functionality

• Advanced transaction logs (audit trail)

• Schema versioning (hot updates)

Install Video Tutorial

Unity Package Manager

1. Add a scoped registry

First, open Project Settings.

Under Package Manager, add a new Scoped Registry with the following fields:

• Name: coherence

• URL: https://registry.npmjs.org

• Scope(s): io.coherence.sdk

• Enable Preview Packages: checked

• Show Dependencies: checked

Click Apply.

2. Find and install the coherence package

Now open the Package Manager.

Click Packages and My Registries.

Under coherence, click Install.

Alternative Method: Edit manifest.json manually

If you want to install coherence manually, go to the folder of your project and open the file /Packages/manifest.json.

Copy paste the lines surrounded by comments that look like this:/* comment */.

{
  "dependencies": {
    "com.unity.collab-proxy": "1.3.9",
    "com.unity.ide.rider": "2.0.7",
    "com.unity.ide.visualstudio": "2.0.7",
    "com.unity.ide.vscode": "1.2.3",
    "com.unity.test-framework": "1.1.24",
    "com.unity.textmeshpro": "3.0.1",
    "com.unity.timeline": "1.4.6",
    "com.unity.ugui": "1.0.0",

    /*** ADD THIS START ***/
    "io.coherence.sdk": "0.4.14",
    /*** ADD THIS END ***/
        
    "com.unity.modules.ai": "1.0.0",
    "com.unity.modules.androidjni": "1.0.0",
    "com.unity.modules.animation": "1.0.0",
    "com.unity.modules.assetbundle": "1.0.0",
    "com.unity.modules.audio": "1.0.0",
    "com.unity.modules.cloth": "1.0.0",
    "com.unity.modules.director": "1.0.0",
    "com.unity.modules.imageconversion": "1.0.0",
    "com.unity.modules.imgui": "1.0.0",
    "com.unity.modules.jsonserialize": "1.0.0",
    "com.unity.modules.particlesystem": "1.0.0",
    "com.unity.modules.physics": "1.0.0",
    "com.unity.modules.physics2d": "1.0.0",
    "com.unity.modules.screencapture": "1.0.0",
    "com.unity.modules.terrain": "1.0.0",
    "com.unity.modules.terrainphysics": "1.0.0",
    "com.unity.modules.tilemap": "1.0.0",
    "com.unity.modules.ui": "1.0.0",
    "com.unity.modules.uielements": "1.0.0",
    "com.unity.modules.umbra": "1.0.0",
    "com.unity.modules.unityanalytics": "1.0.0",
    "com.unity.modules.unitywebrequest": "1.0.0",
    "com.unity.modules.unitywebrequestassetbundle": "1.0.0",
    "com.unity.modules.unitywebrequestaudio": "1.0.0",
    "com.unity.modules.unitywebrequesttexture": "1.0.0",
    "com.unity.modules.unitywebrequestwww": "1.0.0",
    "com.unity.modules.vehicles": "1.0.0",
    "com.unity.modules.video": "1.0.0",
    "com.unity.modules.vr": "1.0.0",
    "com.unity.modules.wind": "1.0.0",
    "com.unity.modules.xr": "1.0.0"
  }, /* add this comma if not already present */
  
  /*** ADD THIS SECTION START ***/
  "scopedRegistries": [
    {
      "name": "coherence",
      "url": "https://registry.npmjs.org",
      "scopes": [
        "io.coherence.sdk"
      ]
    }
  ]
  /*** ADD THIS SECTION END ***/
  
}

When you install the coherence Unity Package, all the services for the SDK are installed in the background as well.

You will then see this package in the Package Manager under "My Registries".

The coherence SDK has some dependencies on other Unity packages you can see in the image above. If you're already using these in your project, you might have to adjust their version number (Unity will tell you about this).

When you successfully install the coherence SDK you'll get this quickstart winodow pop-up and you'll be good to go.

Basic Terms

Replication Server ("Replicator")

A lean and performant server that keeps the state of the world and replicates it efficiently between various simulators and game clients. The Replicator usually runs in the coherence Cloud, but developers can start it locally from the command line or the Unity Editor.

Game Client

A build of the game. To connect to coherence, it will use the coherence SDK.

Simulation Server ("Simulator")

A version of the game client without the graphics ("headless client") optimized and configured to perform server-side simulation of the game world. When we say something is simulated on the server, we mean it is simulated on one or several simulators.

Schema

A text file defining the structure of the world from the network's point of view. The schema is shared between the replicators, simulators and game clients. The world is generally divided in components and archetypes.

Code Generation

The process of generating code specific to the game engine that takes care of network synchronization and other network-specific code. This is done using a CLI tool called Protocol Code Generator that takes the schema file and generates code for various engines (e.g. C# for Unity).

State Replication

The process of making sure the state of the world is eventually the same on the replicator, simulators and game clients, depending on their areas of interest.

State Replication

coherence works by sharing game world data via a Replication Server in the cloud and passing it to the connected clients.

The clients and simulators can define areas of interest (LiveQueries), levels of detail, varying simulation and replication frequencies and other optimization techniques to control how much bandwidth and CPU power is used in different situations.

The game world can be run using multiple simulators that split up simulation functions or areas of the world accordingly.

Fast authority transfer, remote commands, and events allow different authority models, including client authority, server authority, distributed authority and combinations like client prediction with input queues.

The platform handles scaling, synchronization, persistence and load balancing automatically.

Get started

coherence is a network engine, platform and a series of tools to help anyone create a multiplayer game. Our mission is to give any game developer, regardless of how technical they are, the power to make a connected game.

Tutorial project

The Network Playground is a collection of scenes showing you how to use various features of the coherence Unity SDK. It shows you how to synchronize transforms, physics, persistence, animations, AI navigation and send network commands and events.

Existing or new Unity project

You can follow our step-by-step guide to learn how to install coherence in Unity, set up your scene, prefabs, interactions, as well as deploy your project to be shared with your friends.

Join the community

Join our community Discord for community chatter and support.

• Join our official Developer

• Contact us at

Setup Video Tutorial

It's quick and easy to set up a networked scene from scratch using the coherence SDK. This example will show you the basic steps to sync up some moving characters.

Add these components to your scene to prepare it for network synchronization.

1. Add MonoBridge

coherence -> Scene Setup -> Create MonoBridge

This object takes care of connected GameObject lifetimes and allows us to develop using traditional MonoBehaviour scripts.

2. Add LiveQuery - Hierarchy

coherence -> Scene Setup -> Create LiveQuery

3. Add the Sample UI

coherence -> Scene Setup -> Add Sample UI

Creates a Canvas (and Event System if not already present in the scene) with a sample UI that helps you connect to a local or remote replication server. You can create your own connection dialog, this one is just a quick way to get started.

Baking Video Tutorial

Overview

Out of the box, coherence will use C# Reflection to sync all the data at runtime. This is a great way to get started but it is very costly performance-wise.

For optimal runtime performance, we need to create a schema and perform code generation specific to our project.

coherence offers an automatic way of doing that called baking.

Bake schemas

Click on coherence -> Bake Schemas.

This will go through all CoherenceSync components in the project and generate a schema file based on the selected variables, commands and other settings. It will also take into account any CoherenceArchetype components.

For every prefab with a CoherenceSync object, the baking process will generate a bespoke C# file in the coherence/baked folder in the project.

Adding that file to the prefab will make that prefab use bespoke generated code instead of C# reflection.

Activate baked schema on prefab

Once the Schema has been baked, you will be able to activate the baked script in the Configuration section of the CoherenceSync component.

The name of the baked script will be CoherenceSync[prefabName].

Now we can build the project and try out network replication locally.

This example will show you how to launch a local replication server and connect multiple instances.

Running a Replication Server Locally

You can run a local replication server from the coherence menu by clicking:

coherence -> Server -> Run Local Server.

This will open a new terminal window with the replication server.

Build and Connect

Now it's time to make a standalone build an test network replication.

Open the Build Settings window (File -> Build Settings). Click on Add Open Scenes to add the current scene to the build. Click Build and Run.

Select a folder (e.g. builds) and click OK.

When the build is done, start another instance of the executable (or run the project in the Game Window in Unity).

Click Connect on both clients. Now try focusing one and using WSAD keys. You will see the box move on the other side as well.

Connect across the local network

If you want to connect to the local replication server from another local device (such as another PC, Mac, Mobile or VR device), you can find your IPv4 address and use that as your server address in the Connect dialog. These devices need to be connected to the same network.

You can find your IPv4 address by going to your command line tool and type ipconfig . Remember to include the port number, for example 192.168.1.185:32001.

In this section, we will learn how to prepare a prefab for network replication.

1. Create a prefab and move it to Resources

Add an asset and create a prefab of it. Make sure the prefab is in a Resources folder in your Unity project.

Here is an example:

1.1 Create a simple Cube in the scene

GameObject -> 3D Object -> Cube

1.2 Convert the Cube into a prefab

Create a Resources folder in your Project. Drag the Cube into the Resources folder to turn it into a prefab.

2. Add CoherenceSync to the prefab

The CoherenceSync component will help you prepare an object for network synchronization during design time. It also exposes an API that allows us to manipulate the object during runtime.

CoherenceSync will query all public variables and methods on any of the attached components, for example Unity components such as Transform, Animator , etc.. This will include any custom scripts such as PlayerInput and even scripts that came with Asset Store packages you may have downloaded.

3. Select variables to replicate

Select which variables you would like to sync across the network. Initially, this will probably be the Transform settings; position, rotation, scale.

Under Synchronization, click Select fields and methods.

In the Bindings dialog, select position, rotation and scale.

Close the Bindings dialog.

4. Add an input script

This simple input script will use WASD or the Arrow keys to move the prefab around the scene.

Click on Assets -> Create -> C# Script.

Name it Move.cs. Copy-paste the following content into the file.

Wait for Unity to compile the file, then add it onto the prefab.

5. Disable Input on replicated object

We have added a Move script to the prefab. This means that if we just run the scene, we will be able to use the keyboard to move the object around.

But what happens on another client where this object is not authoritative, but rather replicated? We will want the position to be replicated over the network, without the keyboard input interfering with it.

Open the Events section in CoherenceSync. Add a new On Network Instantiation handler by clicking on the plus sign next to it.

Pull the Cube prefab into the Runtime Only / None (Object) field.

Now click the dropdown No Function and select Move -> bool enabled.

Leave the Boolean field unchecked.

6. Additional CoherenceSync settings

From the CoherenceSync component you can configure settings for Lifetime (Session-based or Persistent, Authority transfer (Request or Steal), Authority model (Client Side or Server Side with Client Input) and Adoption settings for when local persistent entities are orphaned.

• On Networked Instantiation (when the GameObject is instantiated)

• On Networked Destruction (when the GameObject is destroyed)

• On Before Authority Transfer (before authority over the GameObject is transferred from one client/simulator to another)

• On After Authority Transfer (after the GameObject's Authority has been transferred to another client/simulator).

Extras

Some extra scripts that are part of the Network Playground that may be useful.

Game Engine Support

coherence currently supports Unity. For custom engine integration,. For updates regarding Unreal Engine support, please check the page.

Unity Requirements

• Unity 2020.1.9f1 or later.

• A Windows, Linux or Mac system.

Networked entities can be simulated either on a game client ("client authority") or a simulation server ("server authority).

Client Authority

Client authority is the easiest to set up initially, but it has some drawbacks:

• Higher latency. Because both clients have a non-zero ping to the replication server, the minimum latency for data replication, commands and events is the combined ping (client 1 to replications server and replication server to client 2).

• Higher exposure to cheating. Because we trust game clients to simulate their own entities, there is a risk that one such client is tampered with and sends out unrealistic data.

In many cases, especially when not working on a competitive PvP game, these are not really issues and are a perfectly fine choice for the game developer.

Client authority does have a few advantages:

• Easier to set up. No client vs. server logic separation in the code, no building and uploading of simulation servers, everything just works out of the box.

• Cheaper. Depending on how optimized the simulator code is, running a simulator in the cloud will in most cases incur more costs than just running a replication server (which is comparatively very lean).

Server Authority

Having one or several simulators taking care of the important world simulation tasks (like AI, player character state, score, health, etc.) is always a good idea for competitive PvP games.

Running a simulator in the cloud next to the replicator (the ping between them being negligible) will also result in lower latency.

The player character can also be simulated on the server, with the client locally predicting its state based on inputs. You can read more about how to achieve that in the section .

Remote Communication

Cloud Deploy Video Tutorial

Now that we have tested our project locally, it's time to upload it to the cloud and share it with our friends and colleagues. To be able to do that, we need to create a free account with coherence.

Sign up or log in

Create an account or log into an existing one.

Create an organization

Create an organization.

Create project

Under the organization, create a new project.

Get portal token

Copy the token to your clipboard.

Copy Portal token into Unity

Open Unity and navigate to the Project Settings. Open the coherence tab.

Paste the token into the Portal Token section.

Fetch the Runtime key

Once you have pasted the portal token successfully, you need to fetch the runtime token as well.

Now we can finally deploy our schema and replication server into the cloud.

Upload schemas

In the Project Settings tab for coherence, click on Upload Schemas.

The status should change from "Unknown" to "In Sync".

Your project schema is now deployed with the correct version of the replication server already running in the cloud.

Run project

You can now build the project again and send the build to your friends for testing.

You will be able to play over the internet without worrying about firewalls and local network connections.

Persistent vs. session-based entities

When we connect to a game world with a game client, the traditional approach is that all entities originating on our client are session-based. This means that when the client disconnects, they will disappear from the network world for all players.

A persistent object, however, will remain on the replication server even when the client or simulator that created or last simulated it, is gone.

This allows us to create a living world where player actions leave lasting effects.

In a virtual world, examples of persistent objects are:

• A door anyone can open, close or lock

• User-generated or user-configured objects left in the world to be found by others

• Game progress objects (e.g. in PvE games)

• Voice or video messages left by users

• NPC's wandering around the world using an AI logic

• Player characters on "auto pilot" that continue affecting the world when the player is offline

• And many, many more

A persistent object with no simulator is called an orphan. Orphans can be configured to be auto-adopted by clients or simulators on a FCFS basis.

Persistence in memory

All persistent objects remain in the world for the entire lifetime of the replication server. But what happens when the replication server is restarted or goes offline?

Persistence Client

Persistence Client is a special utility that runs alongside the replication server and records the state of the world and saves it to physical storage. If the replication server goes offline, the Persistence Client will backup the entire state of the world.

Extrapolation or "dead reckoning" uses historical data to predict the future state of a component. The actual network data that arrives later can be used to interpolate or snap the predicted values to the correct ones.

This document explains how to set up an ever increasing counter that all clients have access to. This could be used to make sure that everyone can generate unique identifiers, with no chance of ever getting a duplicate.

By being persistent, the counter will also keep its value even if all clients log off, as long as the replication server is running.

The Counter

First, create a script called Counter.cs and add the following code to it:

using UnityEngine;
using Coherence.Toolkit;

public class Counter : MonoBehaviour
{
    public int counter = 0;

    public void NextNumber(CoherenceSync requester)
    {
        requester.SendCommand("NumberRequester.GotNumber", counter);
        counter++;
    }
}

Next, add this script to a prefab with CoherenceSync on it, and select the counterand the method NextNumber for syncing in the bindings window. To make the counter behave like we want, mark the prefab as "Persistent" and give it a unique persistence ID, e.g. "THE_COUNTER". Also change the adoption behaviour to "Auto Adopt":

Finally, make sure that a single instance of this prefab is placed in the scene.

NumberRequester

Now, create a script called NumberRequester.cs. This will be an example MonoBehaviour that requests a unique number by sending the command GetNumber to the Counter prefab. As a single argument to this command, the NumberRequester will send an entity reference to itself. This makes it possible for the Counter to send back a response command (GotNumber) with the number that was generated. In this simple example we just log the number to the console.

using UnityEngine;
using Coherence.Toolkit;

public class NumberRequester : MonoBehaviour
{
    CoherenceSync sync;

    private void Awake()
    {
        sync = GetComponent<CoherenceSync>();
    }

    void Update()
    {
        if(sync.isSimulated && Input.GetKeyDown(KeyCode.Return))
        {
            var counter = FindObjectOfType<Counter>();
            var counterSync = counter.GetComponent<CoherenceSync>();
            
            counterSync.SendCommand("Counter.NextNumber", sync);
        }
    }

    public void GotNumber(int number)
    {
        Debug.Log($"Got number: {number}");
    }
}

To make this script work, add it to a prefab that has the CoherenceSync script and mark the GotNumber for syncing in the bindings window.

What are Input Queues?

Input queues enable a simulator to take control of the simulation of another client's objects based on the client's inputs.

When To Use Input Queues?

• In situations where you want a centralized simulation of all inputs. Many game genres use input queues and centralized simulation to guarantee the fairness of actions or the stability of physics simulations.

• In situations where clients have low processing power. If the clients don't have sufficient processing power to simulate the world it makes sense to use input queue and just display the replicated results on the clients.

• In situations where determinism is important. RTS and fighting games will use input queues and rollback to process input events in a shared (not centralized), and deterministic, way so that all clients simulate the same conditions and produce the same results.

Setup With CoherenceSync and CoherenceInput

Setting up an object to simulate via input queues using CoherenceSync is done in three steps:

1. Preparing the CoherenceSync component on the object prefab

The Simulation Type of the CoherenceSync component is set to Simulation Server With Client Input

Setting the simulation type to this mode instructs the client to automatically give authority over this object to the simulator in charge of simulating all inputs on all objects.

2. Declaring Inputs for the simulated object

Each simulated CoherenceSync component is able to define their own, unique, set of inputs for simulating that object. An input can be one of:

• Button. A button input is tracked with just a binary on/off state.

• Button Range. A button range input is tracked with a float value from 0 - 1.

• Axis. An axis input is tracked as two floats from 0 - 1 in both the X and Y axis.

To declare the inputs used by the CoherenceSync component, the CoherenceInput component is added to the object. The input is named and the fields are defined.

In this example, the input block is named "Player Movement" and the inputs are WASD and "mouse" for the XY mouse position.

3. Bake the CoherenceSync object

In order for the inputs to be simulated on CoherenceSync objects, they must be optimized through baking.

When a simulator is running it will find objects that are set up using CoherenceInput components and will automatically assume authority and perform simulations. In the case of a setup with multiple simulators, it is important that only one is designated as the processor of these objects. So, for all other simulators the InputServerSystem must be disabled.

using Coherence.Generated.Internal;
using Unity.Entities;

public void DisableInputServerSystem()
{
    var iss = World.DefaultGameObjectInjectionWorld.GetExistingSystem<InputServerSystem>();
    iss.Enabled = false;
}

Using CoherenceInput

Both the client and simulator need to access the inputs of the CoherenceInput of the replicated object. The client uses the Set* methods and the simulator uses the Get* methods to access the state of the inputs of the object. In all of these methods, the name parameter is the same as the Name field in the CoherenceInput component.

Client-Side Set* Methods

• public void SetButtonState(string name, bool value)

• public void SetButtonRangeState(string name, float value)

• public void SetAxisState(string name, Vector2 value)

Simulator-Side Get* Methods

• public bool GetButtonState(string name)

• public float GetButtonRangeState(string name)

• public Vector2 GetAxisState(string name)

For example, the mouse click position can be passed from the client to the simulator via the "mouse" field in the setup example.

using Coherence.Toolkit;
using UnityEngine;

public void SendMousePosition()
{
    var coherenceInput = GetComponent<CoherenceInput>();
    var mousePos = Input.mousePosition;
    coherenceInput.SetAxisState("mouse", new Vector2(mousePos.x, mousePos.y));
}

The simulator can access the state of the input to perform simulations on the object which are then reflected back to the client as any replicated object is.

using Coherence.Toolkit;
using UnityEngine;

public void ProcessMousePosition()
{
    var coherenceInput = GetComponent<CoherenceInput>();
    var mousePos = coherenceInput.GetAxisState("mouse");
    
    //Move object
}

Client-Side Prediction

Generally, using server-side simulation with simulators makes the time from the client providing input to the time the object is updated with that input significantly longer than just client-side simulation because of the time required for the input to be sent to the simulator, processed, and then the updates to the object returned across the network. This can cause visual lag. Using input queues allows the client to perform prediction of the simulation to provide a smooth playing experience.

If the client simulates the inputs on the object as well as applying them to the CoherenceInput component and then blends the authoritative results from the simulator with the locally simulated results, then smoother and more responsive simulation is achieved.

Overview

Commands are network messages sent from one entity to another entity in the networked world. Commands bind to public methods accessible on the GameObject that CoherenceSync sits on.

Design Phase

In the design phase, you can expose public methods the same way you select fields for synchronization: by using the Select Bindings interface on your CoherenceSync object.

Selected public methods will be exposed as network commands in the baking process.

The resulting schema section will look something like this:

command FemZombie_Character_SendDamage
  damageValue Int
  staminaBlockCost Float
  staminaRecoveryDelay Float
  ignoreDefense Bool
  hitReaction Bool
  hitPosition Vector3
  sourceConnection Int
  isPlayer Bool

Sending a Command on a Networked Object

To send a command, we call the SendCommand method on the target CoherenceSync object. We must supply as many parameters as are defined in the target method and the schema.

var target = enemy.GetComponent<CoherenceSync>();
                    
target.SendCommand("Character.SendDamage", damageValue, 
                staminaBlockCost, staminaRecoveryDelay,
                ignoreDefense, hitReaction, hitPosition, 
                ConnectionId, isPlayer);

Sending a Command on All Instances of a Networked Object

Sometimes you want to inform not only the entity that has authority, but all the networked instances across all clients. To do that, use the alternative method overload and set it's boolean value to true:

SendCommand(string commandName, bool broadcast, params object[] args)

This is useful when you want every client that networks that entity to execute the same logic. Similar to how RPCs work on other networking solutions.

Receiving a Command

We don't have to do anything special to receive the command. The system will simply call the corresponding method on the target network entity.

If the target is a locally simulated entity, SendCommand will recognize that and not send a network command, but instead simply call the method directly.

Sending a Command to multiple entities

Sometimes you want to inform a bunch of different entities about a change. For example, a explosion impact on a few players. To do so, we have to go through the instances we want to notify, and send commands to each of them.

public void MulticastCommand()
{
    var self = GetComponent<CoherenceSync>();
    var listeners = CoherenceSync.instances.Values;
    
    foreach (var listener in listeners)
    {
        if (!listener || listener == self)
        {
            continue;
        }

        listener.SendCommand("MyScript.ReceiveCommand");
    }
}

// bind to this method via the Bindings window
public void ReceiveCommand()
{
    Debug.Log("Received!");
}

In this example, a command will get sent to every network entity known to this client. To make it only affect entities within a certain criteria, you need to filter to which CoherenceSync you send the command to on your own.

Supported types in Commands

When a prefab is using reflection there are some restrictions for what types can be sent in a single command:

• 4 integers

• 4 floats

• 4 bools

• 4 entity references

• 1 string

If you ever need to send commands containing any other type (like a vector) or a higher quantity (like two strings) you must mark the prefab to use baked code. This will generate a custom command that can handle all the supported primitive types of the coherence SDK.

CoherenceSync configuration

The CoherenceSync editor interface allows us to define the Lifetime of a networked object. The following options are available:

• Session Based. No persistence. The entity will disappear when the client or simulator disconnects.

• Persistent. The entity will remain on the server until a simulating client deletes it.

• Persistent Expire. A persistent object that will be automatically deleted from backing storage after X seconds. These object will continue to exist as long as the replication server is active.

Persistence UUID

Persistent objects need to be identified so that the system can know how to treat duplicate persistent objects.

Setting the Auto Generate Persistence UUID flag means that each instance of this persistent object prefab is assigned a unique identifier so that each instance is considered unique.

Manually assigning a UUID means that each instance of this persistent object prefab is considered the same object regardless of where on the network it is instantiated. So, for example, if two clients instantiate the same prefab object with the same persistence UUID then only one is considered official and the other is replaced by the replication server.

Deleting a persistent object

A persistent object can be deleted only by the client or simulator that has authority over it. For indirect remote deletion, see the section about network commands.

Deleting a persistent object is done the same as with any network object - by destroying its GameObject.

Destroy(coherenceSync.gameObject);

Overview

The state of network entities that are currently not simulated locally (either because they are being simulated on another game client or on a simulator) cannot be affected directly.

Network commands and events can help us affect state indirectly, but for anything more involved, an authority transfer might be necessary.

Types of Authority Transfer

In the design phase, CoherenceSync objects can be configured to handle authority transfer in different ways:

• Request. Authority transfer may be requested, but it may be rejected by the receiving party (i.e. when Approve requests is false).

• Steal. Authority will always be given to the requesting party on a FCFS ("first come first serve") basis.

• Not transferable. Authority cannot be transferred.

Requesting Authority in Code

Requesting authority is very straight-forward.

var coherenceSync = target.GetComponent<CoherenceSync>();
coherenceSync.RequestAuthority();

As the transfer is asynchronous, we have to subscribe to one or more Unity Events in CoherenceSync to learn the result.

The request will first go to the replication server and be passed onto the receiving simulator or game client, so it may take a few frames to get a response.

// There Unity Events in CoherenceSync help us understand 
// what happened with authority requests and act accordingly.

public UnityEvent OnAuthorityTransferRejected;

// TRUE is authority is transfered being gained, FALSE if lost
public UnityEvent<bool> OnBeforeAuthorityTransfer;

// TRUE is authority is transfered being gained, FALSE if lost
public UnityEvent<bool> OnAfterAuthorityTransfer;

Unity Animator's parameters are bindable out of the box, with the exception of triggers.

Triggers

Triggers can be invoked over the network using commands and events. Here's an example where we inform networked clients that we have played a jump animation:

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

public class JumpController : MonoBehaviour
{
    static List<CoherenceSync> instances = new List<CoherenceSync>();

    CoherenceSync coherenceSync;
    Animator animator;

    void Awake()
    {
        coherenceSync = GetComponent<CoherenceSync>();
        animator = GetComponent<Animator>();
    }

    void OnEnable()
    {
        instances.Add(coherenceSync);
    }

    void OnDisable()
    {
        instances.Remove(coherenceSync);
    }

    void Update()
    {
        if (!coherenceSync.isSimulated)
        {
            return;
        }

        if (Input.GetKeyDown(KeyCode.Space))
        {
            MakePlayerJump();
        }
    }

    void MakePlayerJump()
    {
        animator.SetTrigger("Jump");
        // TODO move your character up
        NotifyJumpOverNetwork(coherenceSync);
    }

    // bind to this method via the Bindings window
    public void PlayJumpAnimation(CoherenceSync target)
    {
        var animator = target.GetComponent<Animator>();
        animator.SetTrigger("Jump");
    }

    void NotifyJumpOverNetwork(CoherenceSync whoJumped)
    {
        foreach (var s in instances)
        {
            if (!s || s == whoJumped)
            {
                continue;
            }

            s.SendCommand("JumpController.PlayJumpAnimation", whoJumped);
        }
    }
}

Now, bind to PlayJumpAnimator.

Why does world size matter?

Positions and livequeries in the world are compressed, and the compression is defined by maximum scale and bit count. Larger scale at the same bit count means lower precision, and vice-versa.

Defining world size

A default maximum world size of 2400 means that only values from [-2400, 2400] will be supported for all spatial axes.

If our game scenes are larger than 2400 x 2 (4800) units across, we can increase this value in the Settings window or in the schema as illustrated below.

Don't forget to extend the LiveQuery scale to match the world position scale.

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 defined the area of interested 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.

Bandwidth is limited

No matter how fast the internet becomes, conserving bandwidth will always be important. Some game clients might be on poor mobile networks with low upload and download speeds, or have high ping to the replication server and/or other clients, etc.

Additionally, sending more data than is required consumes more memory and unnecessarily burdens the CPU and potentially GPU, which could add to performance issues, and even to quicker battery drainage.

Optimization techniques

In order to optimize the data we are sending over the network, we can employ various techniques built into the core of coherence.

• Delta-compression (automatic). When possible, only send differences in data, not the entire state every frame.

• Compression and quantization (automatic and configurable). Various data types can be compressed to consume less bandwidth that they naturally would.

• Simulation frequency (configurable). Most entities do not need to be simulated at 60+ frames per second.

• Levels of detail (configurable). Entities need to consume less and less bandwidth the farther away they move from the observer.

• Area of interest. Only replicate what we can see.

If we don't do any special configuration, entity data is captured at the highest possible frequency and sent to the replication server. This often generates more data than is needed to efficiently replicate the entity's state across the network.

Global simulator frequency

On a simulator, we can limit the framerate globally using Unity's built-in static variable targetFrameRate.

Per-component frequency limitation

Components can have their own maximum simulation framerates. These can be defined at runtime by adding a Set[ComponentName]Frequency component to the entity.

Overview

Depending on the settings in our project, data may not always arrive at a smooth 60 frames per second through the network. This is completely okay, but in order to make state changes (e.g. movement, rotation) appear smooth on the client, we use interpolation.

Interpolation is a type of estimation, a method of constructing new data points within the range of a discrete set of known data points.

The way interpolation works in coherence is that we wait for three data points and then start smoothing the subsequent values according to the interpolation parameters defined in the schema (or default parameters, if no overrides are present).

Overriding interpolation settings

To override interpolation settings, create a new schema asset via Assets/Create/coherence/Schema and mark it as an active schema in the settings window.

There, add an interpolation definition:

This new interpolation definition MyInterpolation isn't used yet. We need to tell coherence which component is going to use it. We can associate it to WorldPosition and WorldOrientation:

There are a few fields you can tune to get the most out of interpolation:

• overshootPercentage

  • How far into dead reckoning we can venture when the time fraction exceeds 100%

• overshootRetraction

  • How fast to pull back to 100% if we overshoot the allowed dead reckoning maximum in seconds

• manualLatency

  • Seconds to stay behind the sample data

• autoLatencyFactor

  • targetInterpolation = autoLatencyFactor * packetDeltaTime . -1 disables auto latency

• elasticity

  • Seconds to remain behind the current interpolation point, applied to smoothdamp function or slerp

• maxDistance

  • maximum distance between data points before the component "teleports" to the next value without smoothing.

  • allowed values: positive real numbers

• curveType

  • the type of interpolation used

  • allowed values: "CatmullRom", "Linear"

Interpolation can be overridden globally, per component and per LOD level. Here is a sample schema that defines a named interpolation style OverrideTranslation and uses it for all WorldPosition components.

Here's another example that overrides interpolation for WorldPosition and WorldOrientation:

We need one last piece to tie everything together. We need a way to let our bindings to use this interpolation override. To do so, we can create a custom binding provider that extends how the transform component is bound. Create a file named CustomTransformBindingProvider.cs in an Editor folder (e.g. Assets/Editor), with these contents:

This will use OverrideTranslation interpolation component for WorldPosition, and OverrideRotation for WorldOrientation. You can use any name for these as long as it matches the names you defined in your schema. If you don't want to override one of these, just comment out the assignment you don't need.

After you compile this script, a popup will appear letting you know that your CoherenceSync assets have been updated to point to these new components you defined.

From here on, any additional change to interpolation you want to make, you can adjust the values in the schema and bake again.

Motivation

coherence can support large game worlds with many objects. Since the amount of data that can be transmitted over the network is limited, it's very important to only send the most important things.

You already know a very efficient tool for enabling this – the . It ensures that a client is only sent data when an object in its vicinity has been updated.

Often though, there is a possibility for an even more nuanced and optimized approach. It is based on the fact that we might not need to send as much data for an entity that is far away, compared to a close one. A similar technique is often used in 3D-programming to show a simpler model when something is far away, and a more detailed when close-up.

This idea works really well for networking too. For example, when another player is close to you it's important to know exactly what animation it is playing, what it's carrying around, etc. When the same player is far off in the horizon, it might suffice to only know it's position and orientation, since nothing else will be discernible anyways.

To use this technique we must learn about something called archetypes.

Archetypes

An archetype is a component that can be added to any prefab with the CoherenceSync component. It contains a list of the various levels of detail (LODs) that this particular prefab can have.

There must always exist a LOD 0, this is the default level and it always has all components enabled (it can have per-field overrides though, see below.)

There can be any number of subsequent LODs (e.g. LOD 1, LOD 2, etc.) and each one must have a distance threshold higher than the previous one. The coherence SDK will try to use the LOD with the highest number, but that is still within the distance threshold.

One each LOD, there are two options for optimizing data being transferred:

1. Components can be turned off, meaning you won't receive any updates from it.

2. It's fields can be configured to use fewer bits, usually leading to less fine-grained information. The idea is that this won't be noticeable at the distance of the LOD.

Scale, bits and range

coherence allows us to define the scale of numeric fields and how many bits we want to allocate to them.

Here are some terms we will be using:

• Scale. The minimum/maximum value of the field before it overflows. A scale of 2400 means the number can run from -2400 to 2400.

• Bits. The number of bits (octets) user for the field. When used for vectors, the number defined the number of bits used for each component (x, y and z). A vector3 set to 24 bits will consume 3 * 24 = 72 bits.

• Range. For integer values, we define a minimum and maximum possible value (e.g. Health can lie between 0 and 100).

coherence allows us to define these values for specific components and fields. Furthermore, we can define levels of detail so that precision and therefore bandwidth consumption falls with the distance of the object to the point of observation.

Defining levels of detail

On each LOD you can configure the individual fields of any component to use less data. You can only decrease the fidelity, so a field can't use more data on a lower (more far away) LOD. The Archetype editor interface will help you to follow these rules.

In order to define levels of detail, we have to add a CoherenceArchetype component to a prefab with CoherenceSync defined field bindings.

Clicking on Edit LODs opens the Archetype Editor.

We can override the base component settings even without defining further levels of detail.

Clicking on Add new Level Of Detail will add a new LOD. We can now define the distance at which the LOD starts. This is the minimum distance between the entity and the center of the LiveQuery at which the new level of detail becomes active (i.e. the replicator will start sending data as defined here at this distance).

You can also disable components at later LOD levels if they are not needed. In the example above, you can see that the entire Animator component is disabled beyond the distance of 100 units. At 100 units (a.k.a. meters), we usually do not see animation details, so it does not make sense to replicate this data.

The Data Cost Overview shows us that this takes the original 416 bits down to just 81 bits at LOD level 2.

Field overrides per type

The primitive types that coherence supports can be configured in different ways:

Float, Vector2 & Vector3

These three types can all be configured in the same way:

1. By setting the scale, which affects the maximum and minimum value that the data type can take on. For example, a scale of 100 means that a float ranges from -100 to 100.

2. By setting the precision, which defines the greatest deviation allowed for the data type. For example, a precision of 0.5 means that a float of value 10.0 can be transmitted as anything from 9.5 to 10.5 over the network.

Based on the scale and the desired precision, a bit count will be calculated. The default precision and scale (which happens to be 2400) gives a bit count of 24. This means that for a Vector3 a total of 72 bits will be used, 24 x 3.

Integers

Integers can be configured to any span (that fits within a 32-bit int) by setting its minimum and maximum value.

For example, the member variable age in a game about ancient trolls might use a minimum of 100 and a maximum of 2000. Based on the size of the range (1900 in this case) a bit-count will be calculated for you.

Quaternions

Right now quaternions (used for rotations) do not support field overrides, but this will be fixed in the near future.

Other types

All other types (strings, booleans, entity references) have no settings that can be overridden, so your only option for optimizing those are to turn them off completely at lower LODs.

LODs in the schema

When we bake, information from the CoherenceArchetype component gets written into our schema. Below, you can see the setup presented earlier reflected in the resulting schema file.

Caveats

The most unintuitive thing about archetypes and LOD-ing is that it doesn't affect the sending of data. This means that a "fat" object with tons of fields will still tax the network and the replication server if it is constantly updated, even if it uses a very optimized Archetype.

Also, it's important to realize that the exact LOD used on an entity varies for each other client, depending on the position of their query (or the closest one, if several are used.)

Query

Objects with the ConnectedEntity component on them are treated in a special way by the query system. If the entity they are connected to is present in a query, then they are also included automatically. They are also excluded/removed automatically when the entity they are connected to goes out of the query.

Usage

You need to add the ConnectedEntity component to entity. The entity will disappear from all queries that don't have the entity this is connected to. The entity has to be converted to its SerializeEntityID before it can be used in the ConnectedEntity component. This can be done using the CoherenceMonoBridge.UnityObjectToEntityId static function.

var entity = coherenceSync.LinkedEntity;

if(entity != Entity.Null)
{
    var serializeId = CoherenceMonoBridge.UnityObjectToEntityId(other)
    EntityManager.AddComponentData(entity, 
        new ConnectedEntity 
        { 
            Value = serializeId
        }
    );
}     

Sometimes you want to synchronize entities that are connected to other entities. These relationships can be references between entities, but they can also involve direct parent-child relationship between game objects, or more nuanced use cases.

Here's a guide for what technique to use, depending on the situation:

• If you have an entity that needs to keep a nullable reference to another entity, use a normal Entity reference. This includes any existing MonoBehaviour that has GameObject or Transform fields that you want to synchronize over the network.

• If knowing about an entity implies that you should also know about some other (connected) entity, you might need to use the ConnectEntity component.

• If the entities are placed in a hierarchy, use the techniques for parent-child relationships.

An entity with the ConnectedEntity component does not cause an entity to attach itself to the connected entity. It is on the game developer to detect entities with ConnectedEntity components and attach to them to their game specific parents.

Example

A ball that is supposed to be attached to the hand bone of a networked entity. In this case, the ball would show up only once the entity its connected to show up. To attach the ball to the hand, the game developer can write the following code snippet -

var entity = coherenceSync.LinkedEntity;
if (entity != Entity.Null && EntityManager.HasComponent<ConnectedEntity>(entity))
{
    var connected = EntityManager.GetComponent<ConnectedEntity>(entity);
    var parent = CoherenceMonoBridge.EntityIdToTransform(connected.Value);
    var hand = parent.Find("RHand")
    gameObject.SetParent(hand);
}

What is a simulator?

A simulation server or simulator is a version of the game client without the graphics ("headless client") optimized and configured to perform server-side simulation of the game world. When we say something is simulated on the server, we mean it is simulated on one or several simulators.

Why do we need a simulator?

A simulator can have various uses, including:

• Server-side simulation of game logic that cannot be tampered with

• Offloading processing from game clients

• Splitting up a large game world with many entities between them

Here are some examples of things a simulator could be taking care of:

• Running all the important game logic

• Running NPC AI

• Simulating the player character (by receiving only inputs from the clients through input queues)

How many simulators can we have per project?

We can have as many simulators as we like. They will connect to the replication server like any other game client.

Am I a simulator?

Ask Coherence.SimulatorUtility.IsSimulator.

using Coherence;

if (SimulatorUtility.IsSimulator)
{
    // I'm a simulator!
}

There are a few ways you can tell coherence if the instance should behave as a simulator:

• Specifying a ConnectionType when connecting via Coherence.Network.Connect.

• COHERENCE_SIMULATOR preprocessor define.

• --coherence-simulation-server command-line argument.

• Toggling on Simulator in the sample connection dialog.

Connect and ConnectionType

The Connect method on Coherence.Network accepts a ConnectionType parameter.

using Network = Coherence.Network;
using ConnectionType = Replication.Client.Unity.Ecs.ConnectionType;

public class ConnectAsSimulator : MonoBehaviour
{
    void Start()
    {
        if (Network.Connect("127.0.0.1:32001", ConnectionType.Simulator))
        {
            // Connection successful
        }
        else 
        {
            // Connection failed
        }
    }
}

COHERENCE_SIMULATOR

#if COHERENCE_SIMULATOR

// simulator-specific code

#endif

Whenever the project compiles with the COHERENCE_SIMULATOR preprocessor define, coherence understands that the game will act as a simulator.

Command-line argument

Launching the game with --coherence-simulation-server will let coherence know that the loaded instance must act as a simulator.

Server-side simulation

You can define who simulates the object in the CoherenceSync inspector.

Auto-reconnect

The sample UI provided includes auto-reconnect behaviour out of the box for simulators. The root GameObject has an AutoReconnect component attached to it.

If you need a different solution, take a look at its implementation use plug your own.

Entity references let you set up references between entities and have those be synchronized, just like other value types (like integers, vectors, etc.)

To use Entity references, simply select any fields of type GameObject, Transform, or CoherenceSync for syncing in the Bindings window:

The synchronization works both when using reflection and in baked sync scripts.

Entity references can also be used as arguments in Commands.

Limitations

It's important to know about the situations when an entity reference might become null, even though it seems like it should have a value:

• A client might not have the referenced entity in its live query. A local reference can only be valid if there's an actual entity instance to reference. If this becomes a problem, consider switching to using the ConnectedEntity component which ensures that another entity becomes part of the query.

• The owner of the entity reference might sync the reference to the Replication Server before syncing the referenced entity. This will lead to the Replication Server storing a null reference. If possible, try setting the entity references during gameplay when the referenced entities have already existed for a while.

In any case, it's important to use a defensive coding style when working with entity references. Make sure that your code can handle missing entities and nulls in a graceful way.

coherence allows us to use multiple simulators to split up a large game world with many entities between them. This is called spatial load balancing. Please refer to the section about simulators for more information.

Physics

This scene will show you how to use coherence to sync GameObject transforms and Physics objects across the network.

In this example, each client will have its own player character to move. Left-clicking on the map will make the entity move to that location. Right-clicking will spawn local physics based objects that all player characters can interact with. Each client will only have control over its local entity.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail in Exploring the Network Playground.

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

Coherence Connection Events handles overall Scene connectivity. Additionally, it removes all Entities with coherenceSync from the Scene to demo disconnection/reconnection via the Interface without refreshing the Scene.

In This Scene...

Coherence Entity Character (always change the prefab, not the instance) is located in the Resources folder. The UnityEngine.Transform and position are ticked to sync. All other settings (persistence and authority) use the default settings. This entity will be session based, no authority handover and no adoption will take place, when a client leaves.

The On Network Instantiation event is used to change the colour of the mesh.

The Physics Entity Spawner is a simple script to instantiate a Coherence Entity Physics Prefab with a coherenceSync component that replicates the transform and position. The component also changes the material based on if it is locally simulated or synced over the network.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

Build a simulator to be uploaded to the cloud

A simulator build is a built Unity Player for the Linux 64-bit platform that you can upload to coherence straight from Unity Editor.

On Unity's menu bar, navigate to coherence -> Simulator -> Build Wizard.

From within the Build Wizard you can build and upload simulators.

The Info tab provides information and requirements to build simulators properly.

The Build tab creates valid simulator builds from Build Configuration Assets.

Creating a Build Configuration Asset

You can create them via Assets -> Create -> coherence -> Simulator Build Configuration.

A newly created build configuration looks like this:

There are several settings you might want to change.

• Specify the scenes you want to get in the build via the Scene List component.

• Specify a Company Name and a Version from the General Settings component (optional).

• Additionally, you can add our OptimizeForSize component (find it using Add Component). Specify which optimizations you want to use to reduce the final build size from the Optimize For Size component (optional).

Reducing simulator build size (experimental ⚠️)

You can add an OptimizeForSize component to your build configuration via the Add Component in the build configuration inspector. It looks like this:

Select the desired optimizations depending on your needs.

Upload your simulator

Once you have created a valid simulator build, you can upload it to coherence.

If you built your simulator using the Build tab, you should have a valid path to your simulator build set already. If you haven't or want to use a different path, use the Browse button.

Network Playground Project

The Network Playground is a starter project for you to dive into. It contains the latest SDK, all the required preview packages and a bunch of extra resources for you to learn how to make multiplayer games with coherence.

Step 1: Download the Network Playground Unity Project

You will need Unity Version 2020.1.9f1 or later.

Download the Network Playground Project here

Network Playground Scenes

Each Scene in this Network Playground Project shows you something new:

• Scene 1. Synchronizing Transforms

• Scene 2. Physics

• Scene 3. Persistence

• Scene 4. Synchronizing Animations and Custom Variables

• Scene 5. AI Navigation

• Scene 6. Network Commands

• Scene 7. Network Events

Transforms

Welcome to the first scene of the coherence Network Playground. This scene will show you how easy it is to set up networking in your Unity project and sync GameObject transforms across the network.

In this example, each client will have a player character to move by clicking on the map to make the entity move to that location. Each client will only have control of its local entity.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs.

Core Scene Setup and Coherence Setup are present in all (Network Playground) Scenes and described in detail in Exploring the Network Playground.

Coherence Entity Character is the Prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement through the Input Manager in the Core Scene Setup prefab.

In This Scene...

Coherence Entity Character (always change the prefab, not the instance) is located in the Resources folder. The UnityEngine.Transform and position are ticked to sync. All other settings (persistence and authority) use the default settings. This entity will be session based, no authority handover and no adoption will take place, when a client leaves.

The On Network Instantiation event is used to change the color of the mesh and recalculate the RigidBody collisions. That's it.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

The Network Playground project is a series of scenes with different features of coherence for you to pick through and learn.

They will teach you the fundamentals that should set you on your way to creating a multiplayer game.

Scenes

Each Scene in this Network Playground Project shows you something new:

• Scene 1. Synchronizing Transforms

• Scene 2. Physics

• Scene 3. Persistence

• Scene 4. Synchronizing Animations and Custom Variables

• Scene 5. AI Navigation

• Scene 6. Network Commands

• Scene 7. Network Events

Each scene comes with a few helpful core components.

Core Scene SetUp

This Prefab stores all the generic things that make up these simple Scenes.

• Main Camera

• PostFX Volume

• Directional Light

• Environment (Ground, Walls etc)

• Navigation Interface

  • To move between the Scenes without having to enter and exit playmode, useful when testing the standalone build.

• Input Manager

  • Input Manager that uses Raycasting to send a message to the GameObject (with a collider) that it hit.

Coherence Setup

This Prefab includes all of the things that make coherence work.

• Interface

  • Canvas UI that handles Connection/Disconnection dialog and what address to connect.

• Event System

  • Event system to interact with any UI in the scene.

• Coherence Live Query

  • Game Object/Component with a query radius that coherence uses to ask the server "What is happening in the query radius?" so it does not query unnecessarily big areas of large worlds. You can find more information here.

• Coherence Mono Bridge

  • GameObject/Component to transform the Mono based coherenceSync component to archetypes so all data can be processed as ECS code.

coherenceSync (on coherence Entity Prefab)

We use this component on anything that we require to be networked, whether this is a playable character, NPC (non playing character), an object (ball, weapon, banana, car, plant etc) or any Game/Input Managers that require to sync data between Clients/Simulators/Servers.

It scans the inspector for attached components and allows us to sync those component values (as long as they are public) and communicate them to other clients. It also allows us to set individual Prefabs persistent, authoritative and network connect/disconnect settings. There's much more information on the coherenceSync Fundamentals page

Physics & Persistence

This scene will show you how easy it is to set up Networking in your Unity project and sync GameObject transforms and Physics objects across the network whilst keeping them persistent. As long as the server is running you can disconnect and re-connect, your world will persist.

In this example each client will have it's own player character to move, we will click on the map to make the entity move to that location, simple click to move functionality and right click to spawn local physics based objects that all other player characters can interact with. Each client will only have control of its local entity. You can disconnect and re-connect and the persistent entities will all remain.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail in Exploring the Network Playground.

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

Coherence Connection Events handles overall Scene connectivity. Additionally, it removes all Entities with coherenceSync from the Scene to demo disconnection/reconnection via the Interface without refreshing the Scene.

In This Scene...

The Physics Entity Spawner component is a simple script to instantiate a Coherence Entity Physics Persistent prefab with a coherenceSync component that replicates the transform and position. The component also changes the material based on if it is locally simulated or synced over the network.

Coherence Entity Physics Persistent has Entity Lifetime Type set to Persistent. This means it will remain in the world as long as the replication server is running, even if all clients disconnect. It also has Authority Transfer Style set to Stealing which means the entity can be "stolen" and simulated on a client requesting authority.

The Auto Generate Persistance UUID should be checked so that a unique identification string will be used to identify instances of this entity as unique. When the entity is spawned with this checked, it will generate its own UUID.

This is done via the Input Manager in the Core Scene Setup prefab. When the object is left-clicked, it sends the message "Adopt" to the GameObject on the specific Layer Mask "Physics Entities". The component called Coherence Handler on Coherence Entity Physics Persistent handles the Adopt call and requests the authority change via the coherenceSync component.

Coherence Handler is a basic layer for handling Commands and Events, both sending and receiving. You can create your own or reuse and extend this for your project.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

Animation & Variables

This scene will show you how easy it is to set up Networking in your Unity project and sync GameObject transforms, animations via the Animator parameters and customer variables.

In this example, each client will have its own player character to move, the beloved Unity RobotKyle asset. Type your name into the connect dialog box and connect. You can move around with WASD. When another player connects, their name is carried across and their transform and animation state is replicated.

General Set Up

In the Hierarchy of the scene you can see the two core prefabs Core Scene Setup and Coherence Setup. Both are present in all scenes and described in detail in Exploring the Network Playground.

In This Scene...

Coherence Kyle is taken from the Unity asset "Robot Kyle", with added components Rigidbody, Character Controller, and Animator with the two animation states - Idle and Walk. The animation states are controlled by a speed parameter from the Agent script. The scene also contains a Name Badge script which gets the Connect Dialog GameObject from the Core Scene Setup and sets the color depending if it's local or networked.

Attached to Coherence Kyle is a coherenceSync component which replicates the parametersTransform; position and rotation, Animator; Speed[float] and NameBadge; Name [string]. The authority and persistence settings are set to their default values and the On Network Instantiation event is used to change the color of the networked entities.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

You can read more about synchronizing animations on the Animations section.

AI Navigation, Session Based NPC's

This scene will show you how easy it is to set up Networking in your Unity project and sync non player characters that move around the world via Unity's Navmesh system.

In this example each client can spawn as many navigation agents as they wish, and these navigation agents will move intermittently to different locations on the grid. All navigation agents will be replicated across clients with a specific colors signifying if they are local or networked.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Coherence Connection Events handles overall Scene connectivity. Additionally, it removes all Entities with coherenceSync from the Scene to demo disconnection/reconnection via the Interface without refreshing the Scene.

In This Scene...

Spawner is a simple script to instantiate a Coherence Entity Nav Agent prefab with a coherenceSync component that replicates the transform and position. The component also changes the material based on if it is locally simulated or synced over the network.

Coherence Entity Nav Agent has a Nav Mesh Agent component controlled via the Navigation Agent script which every few seconds sets a new destination on the grid. It's not required to sync anything other than the Transform; position, rotation parameter as the Nav Mesh Agent settings only need to simulate locally.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

Sending Network Commands

This scene will show you how easy it is to set up Networking in your Unity project and send Network Commands to other clients. Network Commands is like sending a direct message to another player, without anyone else knowing.

In this example each client has one character they can control with click to move input. They can right-click on another Entity to send a command and that Entity will instantiate an Exclamation mark above their head.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail in Exploring the Network Playground.

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

In This Scene...

Coherence Entity can send commands to other entities through the Coherence Handler component. In the coherenceSync component, small "lightning bolt" icons are displayed next to the tick boxes for the syncable properties. These icons signify that they are public methods rather than singular variables and that these methods can be called through the Coherence Handler Event System, either to send or receive commands.

In the game view in Play mode, Commands can be sent to other entities via the right click button. An exclamation mark asset should pop up above the right-clicked entity, but only for the sending and the receiving client. No other clients will be made aware of this.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

Motivation

coherence provides a powerful matchmaking API with various different setups (multiple teams, team sizes, etc.).

Configuration

Before using the matchmaking service you have to configure it on the developer portal. Currently there are two things to setup: the timeout and the teams.

The timeout is in seconds. There can be any number of teams and any number of players per team.

For example, a chess game would need only one team with two players, while in a socker game you'd need two teams with eleven players per team.

Using the matchmaking

Motivation

coherence provides an API for creating player game accounts that uniquely identify players across multiple devices. An account is required in order to use the rest of the online services, like the key-value store and matchmaking.

Account Types

There are two types of accounts that are currently supported - guest accounts and user accounts.

Guest Accounts

Guest accounts provide an easy way to start using the coherence online services without providing any user interface for user names or password. Everything is controlled with the , and is completely transparent to the player.

The session data for the account is stored locally on the device so it is important to know that uninstalling the game will also wipe out all the data and the account will be no longer accessible even if the player installs the game again.

User Accounts

User accounts require explicit authorization by the player. Currently, only user name and password are supported as means for authentication. The user interface for entering the credentials must be provided by the game. Check the how to use this feature.

In the future, there will be support for many more authentication mechanisms like Steam, Google Play Games, Sign in with Apple, etc.

Using game accounts

Please refer to the .

Sending Network Events

This scene will show you how easy it is to set up Networking in your Unity project and send Network Events to other clients. Network Commands is like sending a direct message to another player, without anyone else knowing. Network Events is like shouting out loud for anyone in the area to hear you.

In this example each client has one character they can control with click to move input. They can right-click anywhere on the grid and all entities will instantiate an exclamation mark above their head.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

In This Scene...

Network Events are still in development but this example shows a workaround using Commands. When an event is sent to an entity, Coherence Handler finds all instances of coherenceSync and sends the event command to all these entities.

In the coherenceSync component, small "lightning bolt" icons are shown next to the tick boxes for the syncable properties. These icons signify that they are public methods rather than singular variables and that these methods can be called through the Coherence Handler Event System, either to send or receive commands.

In the game view in Play mode, Commands can be sent to other entities via the right click button anywhere on the grid and an exclamation mark asset should pop up above all clients entities.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> Coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

Motivation

coherence provides an API and a database for storing key-value pairs from within game sessions.

Description

The key/value store provides a simple way to store and retrieve data for the currently logged in player. For example, you could store player's score, email address, or any other data.

It is important to mention that this feature requires a game account.

Limitations

The keys must be alphanumerical strings, underscore or dash. Currently, only strings are accepted as values. If you need to store numbers or complex types like arrays, you have to convert them to strings.

The total amount of storred data (keys + values) cannot exceed 256 KB per player (TBD).

There is no limit how often the data is stored or retrieved.

Using key-value store

Please refer to the Cloud API: Key-value store.

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.

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.

OnBeforeAuthorityTransfer and OnAfterAuthorityTransfer

If you want to run some custom code when passing ownership, you can add your own event callbacks in the CoherenceSync component. The OnBeforeAuthorityTransfer event is invoked just before the transfer happens. The OnAfterAuthorityTransfer event is invoked just after the transfer happens. Both events supply a boolean parameter. If set to true, it means you are getting ownership, and if false it means you are losing ownership. In other words, if a game object is transferred from Client A to Client B, the events will be invoked in this order:

1. ClientA: OnBeforeAuthorityTransfer(false); 2. ClientA: OnAfterAuthorityTransfer(false); 3. ClientB: OnBeforeAuthorityTransfer(true); 4. ClientB: OnAfterAuthorityTransfer(true);

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.

Events

Refer to the events section.

Refer to the Level of detail section for more information.

The coherence User Interface is a prefab that you can add to your scene that handles Connection, IP, Port and Disconnection from your server. It is made up of a Unity UI Canvas and various buttons and images.

The main functionality is located on the "Connect Dialog" GameObject with the script Connect Dialog

Overview

The coherence Cloud API allows us to access online services like game accounts, key-value store, matchmaking, and others. It also allows you to get the addresses (IP and port number) of the servers the players can connect to.

The Cloud API requires you to use tokens connected to your coherence project.

List of endpoints

• Server discovery

• Game account

• Key-value store

• Matchmaking

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 defined the area of interested in a particular part of the world. It 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.

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.

Portal Token

The token you get when creating a project on the .

You paste it in the Project Settings.

Runtime Key

Once you have pasted the portal token successfully, you need to fetch the runtime key as well.

Here is a sample script showing how you can use the server discovery API to get the servers associated with your runtime key.