This page lists changes in coherence 1.0.0 version which might affect existing projects when upgrading from a 0.10.x version to 1.0.0.

Baked code and Prefabs with missing scripts

Version 1.0.0 includes breaking changes to the baked scripts, which means your current ones will cause compilation errors. It is recommended to delete your current baked scripts under Assets/coherence/baked before performing a coherence Unity SDK update.

CoherenceMonoBridge has been renamed to CoherenceBridge

There have been a number of updates to the old CoherenceMonoBridge, which have resulted in a rebranding of the component to CoherenceBridge.

The script asset GUID and the public API of the component remain unchanged, so asset references to CoherenceMonoBridge components should remain intact.

CoherenceSyncConfigRegistry and removal of PrefabMapper

In coherence 1.0.0, we have revamped our asset management systems to make them more scalable and customizable, both in Editor and in runtime. Read more about the new implementations and the possibilities in the Asset Management article.

Upon upgrading the SDK, a new CoherenceSyncConfigRegistry asset will be automatically created in Assets/coherence/CoherenceSyncConfigRegistry.asset and populated with sub-assets for each of your Prefabs that have a CoherenceSync component attached.

If the automatic migration completed successfully, you can browse all your networked Prefabs in the new CoherenceSync Objects window found under the coherence menu item:

If something has gone wrong during the automatic migration, you can restart the process by deleting the current CoherenceSyncConfigRegistry asset, and selecting the Reimport coherence Assets option under the coherence menu item. This will automatically create a config entry for each of your CoherenceSync Prefabs:

Changes to CoherenceSync lifetime in runtime

In previous versions of coherence, Prefabs with the CoherenceSync component would be automatically synced over the network in the Start method, and they would stop being synced only when destroyed. This prevented us from supporting things like object pooling and reusing the same CoherenceSync instance to represent different network entities across its lifetime.

As a result, CoherenceSync instances are now automatically synced and unsynced with the network in the OnEnable and OnDisable methods of the MonoBehaviour. This means you can disable the GameObject instance in the hierarchy and it will stop being synced, you can also keep the local visual representation by only disabling the CoherenceSync component.

You can learn more about the CoherenceSync lifetime cycle in the Order Of Execution page.

Play API deprecation

The Play API was the public API we offered to connect with your coherence Cloud project in runtime. It has been deprecated in favor of a new non-static API called CloudService, with separation of a ReplicationServerRoomsService so you can talk to self-hosted Room Replication Servers with a lot more customization and without having to use the coherence Cloud.

The Play API includes the following classes:

• PlayResolver

• PlayClient

• Play

• WorldsResolverClient

• RoomsResolverClient

If you were using PlayResolver static calls, you can now access CloudService instance from CoherenceBridge instead, and you will be able to use the CloudService.Worlds or CloudService.Rooms instances to fetch Worlds or to create, delete or fetch available Rooms respectively.

CloudService offers callback-based methods and an async variant for all of the available requests.

You can learn more about the Cloud Service API under the Unity Cloud Service section.

"No Domain Reload" Unity Editor option is now supported

No Domain Reload is a Unity Editor option that allows users to enter Play mode very fast without having to recompile all your code. This wasn't properly supported in earlier versions of coherence, but now it is!

You can find this option under Edit > Project Settings > Editor > Enter Play Mode Settings.

CoherenceSync.OnNetworkedInstantiation and OnBeforeNetworkedInstantiation events behaviour change

In previous releases of coherence, this event would be fired strictly for CoherenceSync prefab instances created by coherence, which means it would be fired for instances you didn't have authority over.

In 1.0, this event will be fired for every instance of CoherenceSync that starts being synchronized over the network.

If you wish to hook behaviour to non-authority instances, please use the OnStateRemote event instead, which is fired when a CoherenceSync instance is non-authoritative.

Changes to the Client Connections system

In 1.0, there has been two major changes to Client Connection instances.

• Client Connection instances now live in the DontDestroyOnLoad scene. Since now we support Scene Transitioning, and Client Connections instances are managed by coherence, they need to survive the destruction of the Scene they were in.

• References to the Client Connection Prefab in the CoherenceBridge Component have been changed from hard referencing a Unity Prefab, to referencing a CoherenceSyncConfig asset. If you were using a Unity Prefab reference, it still exists serialized but is deprecated. If you wish to stop using the Unity Prefab reference, please delete the CoherenceBridge Component and add it again.

• using Coherence.Entity; -> using Coherence.Entities;

If your project is using the Source Generator baking strategy

It is recommended to switch to Assets strategy before upgrading. If you upgrade while using the Source Generator, you might see an error popup, guiding you to switch back to Assets. After the upgrade and a clean Bake, you can switch back to Source Generators baking strategy.

Notable API changes include:

• Coherence.Network is removed now. OnConnected and OnDisconnected events are moved to IClient and have changed a signature:

    private void OnEnable()
    {
        if (!BridgeStore.TryGetBridge(gameObject.scene, out CoherenceBridge Bridge))
            return; 
        
        client = Bridge.Client;
        client.OnConnected += OnConnect;
        client.OnDisconnected += OnDisconnect;
    }

    private void OnDisable()
    {
        client.OnConnected -= OnConnect;
        client.OnDisconnected -= OnDisconnect;
    }

    private void OnConnect(ushort u)
    {
        onConnect.Invoke();
    }

    private void OnDisconnect(ConnectionCloseReason reason)
    {
        onDisconnect.Invoke();
    }

• BridgeStore.GetBridge is now obsolete, and will be replaced with BridgeStore.TryGetBridge.

BridgeStore.TryGetBridge(gameObject.scene, out Bridge);

• CoherenceSync.isSimulated is now obsolete, and will be replaced with CoherenceSync.HasStateAuthority.

• CoherenceSync.RequestAuthority is now obsolete, and will be replaced with CoherenceSync.RequestAuthority(AuthorityType).

CLI Tools

The CLI tools have been updated, especially the ones that handle Simulators. To learn more about this, see CLI utilities.

Major changes for CoherenceSyncConfigRegistry

There has been a major refactor on how we deal with the registry.

First off, we're deprecating the registry holding configs as sub-assets. This has been the default up to 1.1, but on 1.2, it has been changed to store the configs in the Assets/coherence/CoherenceSyncConfigs folder.

For 1.2, we have avoided manual migration of existing subassets. You can trigger this operation from the registry inspector (Assets/coherence/CoherenceSyncRegistry). We don't automate this operation, since the extraction changes the asset GUIDs of the configs, which could lead to missing references. This is specially true if your project is referencing the configs directly, instead of going through the registry. Keep this in mind when you decide to extract existing subassets.

Compilation Errors

Client Hosting

In this update, bundling the Replication Server has been revamped to work with Streaming Assets. On the Settings window, instead of different toggles per platform, there's now one unified toggle:

If you wish to get started and install the coherence Unity SDK, please refer to the page.

Upgrading to a new version

Open Unity Package Manager under Window > Package Manager and check the Packages - coherence section. It will state the currently installed version and if there are any recommended updates available:

Upgrade Guides

For example, if your project is on 0.7 and would like to upgrade to 1.0, upgrade from 0.7 to 0.8, then from 0.8 to 0.9, and so on. Always back up your project before upgrading, to avoid any risk of losing your data.

Versions prior to 0.9 are considered legacy. We don't provide a detailed upgrade guide for those versions.

Defines a network entity and what data to sync from the GameObject. Anything that needs to be synchronized over the network can use a CoherenceSync component. You can select data from your GameObject hierarchy that you'd like to sync across the network.

Queries an area of interest, so that you can read/write across the network on the desired location. In our Starter Project, the LiveQuery position is static with an extent large enough to cover the entire playable level. If the World was very large and potentially set over multiple Simulators, the LiveQuery could be attached to the playable character or camera.

Handles the connection between the coherence transport layer and the Unity scene.

Enables a Simulator to take control of the state authority of a Client's CoherenceSync, while retaining input authority.

This component is added by CoherenceSync on .

The Bridge establishes a connection between your scene and the coherence . It makes sure all networked entities stay in sync.

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

At runtime, you can inspect which Entites the Bridge is currently tracking.

A Bridge is associated with the scene it's instantiated on, and keeps track of Entities that are part of that scene. This also allows for multiple connections at the same time coming from the game or within the Unity Editor.

Unity Events

The CoherenceBridge offers a couple of Unity Events in its inspector where you can hook your custom game logic:

OnLiveQuerySynced

This event is invoked when the Replication Server state has been fully synchronized, it is fired after OnConnected.

For example, if you connect to a ongoing game that has five players connected, when this event is fired all the entities and information of all the other players will already be synchronized and available to be polled.

OnConnected

This event is invoked the moment you stablish a connection with the Replication Server, but before any synchronization has happened.

Following the previous example, if you connect to an ongoing game that has five players connected, when this event is fired, you won't have any entities or information available about those five players.

OnDisconnected

This event is invoked when you disconnect from a Replication Server. In the parameters of the event you will be given a ConnectionCloseReason value that will explain why the disconnection happened.

OnConnectionError

This event is invoked when you attempt to connect to a Replication Server, but the connection fails, you will be returned a ConnectionException with information about the error.

Client Connections

The Client Connections system allows you to keep track of how many users are connected and uniquely identify them, as well as easily send server-wide messages.

Connecting to Worlds/Rooms from coherence Cloud

Persistent Entity limits

In addition to the LiveQuery, coherence also supports filtering objects by tag. This is useful when you have some special objects that should always be visible regardless of World position.

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 to look around in a dark cave.

CoherenceSync is a component that should be attached to every networked GameObject. 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.

Once a CoherenceSync is added to a Prefab, you can select which individual public properties you would like to sync across the network, expose methods as Network Commands, and configure other network-related properties.

Synced variables

To start syncing variables, open the Configure window that you can access from the CoherenceSync's Inspector.

Any components attached to the GameObject with CoherenceSync that have public variables will be shown here and can be synced across the network.

To start syncing a property, just use the checkbox. Optionally, choose how it is interpolated on the right.

Network Commands

Network Commands are public methods that can be invoked remotely. In other networking frameworks they are often referred to as RPCs (Remote Procedure Calls).

To mark a method as a Command, you can do it from the Configure window in the same way described above when syncing properties by going to the second tab labelled "Commands".

For more info, refer to the page about messaging with Commands.

Component Actions

When an entity is instantiated in the network, other Clients will see it but they won't have authority on it. It is then important to ensure that some components behave differently when an entity is non-authoritative.

To quickly achieve this, you can leverage Component Actions, which are located in the Components tab of the Configure window:

Other properties

Authority Transfer

When you create a networked GameObject, you automatically become the owner of that GameObject. That means only you are allowed to update its values, or destroy it. But sometimes it is necessary to pass ownership from one Client to another. For example, you could snatch the football in a soccer game or throw a mind control spell in a strategy game. In these cases, you will need to transfer ownership over these Entities from one Client to another.

When an authority transfer request is performed, an Entity can be set up to respond in different ways to account for different gameplay cases:

• Not Transferable - Authority requests will always fail. This is a typical choice for player characters.

• Steal - Authority requests always succeed.

• Request - This option is intended for conditional transfers. The owner of an Entity can reply to an authority request by either accepting or denying it.

  • Approve Requests - The requests will succeed even if no event listener is present.

Transfer requests API

Any Client or Simulator can request ownership by invoking the RequestAuthority() method on the CoherenceSync component of a Network Entity:

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

A request will be sent to the Entity's current owner. They will then accept or deny the request, and complete the transfer. If the transfer succeeds, the previous owner is no longer allowed to update or destroy the Entity.

Lifetime

When a Client disconnects, all the Network Entities created by that Client are usually destroyed. If you want any Entity to stay after the owner disconnects, you need to set Entity lifetime type of that Prefab to Persistent.

• Session Based - the Entity will be removed on all other Clients, when the owner Client disconnects.

• Persistence - Entities with this option will persist as long as the Replication Server is running. For more details, see Configuring persistence.

Orphaned Entities

By making the GameObject persistent, you ensure that it remains in the game world even after its owner disconnects. But once the GameObject 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 GameObject.

In order to make the orphaned GameObject interactive again, another Client needs to take ownership of it. To do this, one can use APIs (specifically, Adopt()) or – more conveniently – enable Auto-adopt orphan on the Prefab.

Uniqueness

• Allow Duplicates - multiple copies of this object can be instantiated over the network. This is typical for bullets, spell effects, RTS units, and similar repeated Entities.

• No Duplicates - ensures objects are not duplicated by assigning them a Unique ID.

  • Manual Unique ID - You can set the Unique ID manually in the Prefab, only one Prefab instance will be allowed at runtime, any other instance created with the same UUID will be destroyed.

  • Prefab Instance Unique ID - When creating a Prefab instance in the Scene at Editor time, a special Prefab Instance Unique ID is assigned, if the manual UUID is blank, the UUID assigned at runtime will be the Prefab Instance ID.

Manual ID vs. Prefab Instance ID

To understand the difference between these two IDs, consider the following use cases:

Manager: If your game has a Prefab of which there can only be 1 in-game instance at any time (such as a Game Manager), assign an ID manually on the Prefab asset.

Multiple interactable scene objects: If you have several instances of a given Prefab, but each instance must be unique (such as doors, elevators, pickups, traps, etc.), each instance created in Editor time will have a auto-generated Prefab Instance Unique ID. This will ensure that when 2 players come online, they only bring one copy of any given door/trap/pickup, but each of them still replicates its state across the network to all Clients currently in the same scene.

Simulate In

Defines which type of network node (Client or Simulator) can have authority over this Entity.

• Client Side - The Entity is by default owned by the Client that spawns it. It can be also owned by a Simulator.

• Server Side - The Entity can't be owned by a normal Client, but only by a "server" (in coherence called Simulator).

• Server Side with Client Input - This automatically adds a CoherenceInput component. Ownership is split: a Simulator holds State Authority, while a Client has Input Authority. See Server Authoritative setup for more info.

CoherenceSync Events

You can hook into the events fired by the CoherenceSync to conveniently structure gameplay in response to key moment of the component's lifecycle. Events are initially hidden, but you can reveal them using the button at the bottom of the Inspector called "Subscribe to...".

Once revealed, you can use them just like regular UnityEvents:

You can also subscribe to these events in code.

Baked script

When CoherenceSync variables/components are sent over the network, by default, Reflection Mode 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, creating a compatible schema and then generating code for it.

The schema is a 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 baked folder called CoherenceSync<AssetIdOfThePrefab>. This class will be instantiated at runtime, and will take care of networked serialization and deserialization, instead of the built-in reflection-based one.

You can find more information on the page about Baking.

The CoherenceSync component will help you prepare an object for network synchronization. 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, including third-party Asset Store packages that you may have downloaded.

Refer to the page to learn how to configure your Prefab to network state changes.

Instead of hard referencing Prefabs in your scripts to instantiate them, you can reference a CoherenceSyncConfig and instantiate your local Prefab instances through our API. This will utilize the internal INetworkObjectProvider and INetworkObjectInstantiator interfaces to load and instantiate the Prefab in a given networked scene (a scene with a CoherenceBridge component in it).

You can also hard reference the Prefab in your script, and use our extensions to instantiate the Prefab easily using the internal INetworkObjectInstantiator interface implementation. The main difference is that the previous approach doesn't need a Prefab hard reference, and you won't have to change the code if the way that the Prefab is loaded into memory changes (for example, if you go from Resources to load it via Addressables).

This page describes the order of various coherence events and scripts in relation to .

Script execution order

Check out .

Additionally, take a look at your project's Script Execution Order settings by opening Edit > Project Settings and selecting the Script Execution Order category. See this for more details.

CoherenceSync instance lifecycle

When a Prefab instance with CoherenceSync is created at runtime, it will be fully synchronized with the network in the OnEnable method of CoherenceSync. This means that you can expect your custom Components to have fully resolved synchronized values and authority state in your Awake method. It occurs in the following order:

CoherenceSync

1. Awake() is called

   1. Internal initialization.

2. OnEnable() is called

   1. Synchronize with a new or existing Network Entity.

   2. OnBeforeNetworkedInstantiation event is invoked.

   3. Initial component updates are applied (for entities you have no authority over).

   4. OnNetworkedInstantiation event is invoked.

   5. OnStateAuthority or OnStateRemote (for authority or non-authority instances respectively) event is invoked.

User-defined Components

1. Awake() is called

   1. At this point, if you get the CoherenceSync component, you can expect networked variables and authority state to be fully resolved.

In this page we will learn about how coherence handles loading CoherenceSync Prefabs into memory and instantiating them when a new remote entity appears in the network. You will also learn how you can hook your own asset loading and instantiation systems seamlessly.

CoherenceSyncConfigRegistry asset

Whenever you start synchronizing one of your prefabs, either by adding the CoherenceSync component manually or clicking the Sync with coherence toggle in the prefab inspector, coherence will automatically create a CoherenceSyncConfig object that will be added to the CoherenceSyncConfigRegistry asset found in the Assets/coherence folder.

This CoherenceSyncConfig object allows us to do the following:

• Hard reference the prefab in Editor, this means that whenever we have to do postprocessing in synced prefabs, we don't have to do a lookup or load them from Resources.

• Serialize the method of loading and instantiating this prefab in runtime.

• Soft reference the prefab in Runtime with a GUID, this means we can access the loading and instantiating implementations without having to load the prefab itself into memory.

All your CoherenceSync prefabs will have a related CoherenceSyncConfig object, you can inspect all your prefabs in the CoherenceSync Objects window, found under the coherence => CoherenceSync Objects menu item:

You can also manually inspect your CoherenceSyncConfig objects by selecting the CoherenceSyncConfigRegistry asset in Assets/coherence/CoherenceSyncConfigRegistry.asset:

You can also find your related CoherenceSyncConfig in the inspector of the CoherenceSync component, you can directly edit your Config from here:

CoherenceSyncConfig Load via option

This option allows you to specify how this prefab will be loaded into memory in runtime, we support three default implementations, or you can create your own. The three default implementations are Resources, Direct Reference or Addressables, these three will be automatically managed by coherence and you won't have to worry much about them.

Resources

Resources loader will be used if your prefab is inside a Resources folder, if you wish to use any other type of loading method, you will be prompted to move the prefab outside of the Resources folder.

Direct Reference

This loader will be used if your prefab is outside of a Resources folder, and the prefab is not marked as Addressable. This means that we will need to hard reference your prefab in the CoherenceSyncConfig, which means it will always be loaded into memory from the moment you start your game.

Addressables

Creating your own asset loader

You can implement the INetworkObjectProvider interface to create your custom implementations that will be used by coherence when we need to load the prefab into memory.

Custom implementations can be Serializable and have your own custom serialized data.

Implementations of this interface will be automatically selectable via the Load via option in the CoherenceSyncObject asset.

CoherenceSyncConfig Instantiate via option

This option allows you to specify how this prefab will be instantiated in runtime, we support three default implementations, or you can create your own. The three default implementations are Default, Pooling or DestroyCoherenceSync.

Default Instantiator

This instantiator will create a new instance of your prefab, and when the related network entity is destroyed, this prefab instance will also be destroyed.

Pool Instantiator

This instantiator supports object pooling, instead of always creating and destroying instances, the pool instantiator will attempt to reuse existing instances. It has two options:

• Max Size: maximum size of the pool for this prefab, instances that exceed the limit of the pool will be destroyed when returned.

• Initial Size: coherence will create this amount of instances on app startup.

DestroyCoherenceSync Instantiator

This instantiator will create a new instance for your prefab, but instead of completely destroying the object when the related network entity is destroyed, it will destroy or disable the CoherenceSync component instead.

Creating your own instantiator

You can implement the INetworkObjectInstantiator interface to create your custom implementations that will be used by coherence when we need to instantiate a pefab in the scene.

Custom implementations can be Serializable and have your own custom serialized data.

Implementations of this interface will be automatically selectable via the Instantiate via option in the CoherenceSyncObject asset.

coherence can sync the following types out of the box:

• bool

• int

• uint

• byte

• char

• short

• ushort

• float

• string

• Vector2

• Vector3

• Quaternion

• GameObject

• Transform

• RectTransform

• CoherenceSync

• SerializeEntityID

• byte[]

• long

• ulong

• Int64

• UInt64

• Color

• double

Overview

Commands are network messages sent from one CoherenceSync to another CoherenceSync. Functionally equivalent to RPCs, commands bind to public methods accessible on the GameObject hierarchy that CoherenceSync sits on.

Design phase

In the design phase, you can expose public methods the same way you select fields for synchronization: through the Configure window on your CoherenceSync component.

By clicking on the method, you bind to it, defining a command. The grid icon on its right lets you configure the routing mode. Commands with a Send to Authority Only mode can be sent only to the authority of the target CoherenceSync, while ones with the Send to All Instances can be broadcasted to all clients that see it. The routing is enforced by the Replication Server as a security measure, so that outdated or malicious clients don't break the game.

Sending a command on a networked object

To send a command, we call the SendCommand method on the target CoherenceSync object. It takes a number of arguments:

• The generic type parameter must be the type of the receiving Component. This ensures that the correct method gets called if the receiving GameObject has components that implement methods that share the same name. Example: sync.SendCommand<Transform>(...)

• The first argument is the name of the method on the component that we want to call. It is good practice to use the C# nameof expression when referring to the method name, since it prevents accidentally misspelling it, or forgetting to update the string if the method changes name.

• Alternatively, if you want to know which Client sent the command, you can add CoherenceSync sender as the first argument of the command, and the correct value will be automatically filled in by the SDK.

• The second argument is an enum that specifies the MessageTarget of the command. The possible values are:

  • MessageTarget.All – sends the command to each Client that has an instance of this Entity.

  • MessageTarget.AuthorityOnly – send the command only to the Client that has authority over the Entity.

  • MessageTarget.Other - sends the command to every Entity other than the one SendCommand is called on.

• The rest of the arguments (if any) vary depending on the command itself. We must supply as many parameters as are defined in the target method and the schema.

Here's an example of how to send a command:

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

Sending a command to a specific MonoBehaviour instance

If you have the same command bound more than once in the same Prefab hierarchy, you can target a specific MonoBehaviour when sending a message, you can do so via the SendCommand(Action action) method in CoherenceSync.

Additionally, if you want to target every bound MonoBehaviour, you can do so via the SendCommandToChildren method in CoherenceSync.

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.

Identifying which Client sent a command

While commands by default carry no information on who sent them in order to optimise traffic, you can create commands that include a ClientID as one of the parameters. Then, on the receiving end, compare that value with a list of connected Clients.

[Sync] private uint StateAuthority;
(...)
sync.OnStateAuthority.AddListener(() => StateAuthority = (uint)sync.CoherenceBridge.ClientID);

You can create your own implementation for these IDs or, more simply, use coherence's built-in Client Connections feature.

Sending a command to multiple CoherenceSyncs

Sometimes you want to inform a bunch of different CoherenceSyncs about a change. For example, an 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.

using Coherence;
using Coherence.Toolkit;
using UnityEngine;

public class MyCommands : MonoBehaviour
{
    public void MulticastCommand()
    {
        var self = GetComponent<CoherenceSync>();
        var listeners = FindObjectsByType<CoherenceSync>(); 
        
        foreach (var listener in listeners)
        {
            if (!listener || listener == self)
            {
                continue;
            }
            
            listener.SendCommand<MyCommands>(nameof(ReceiveCommand), MessageTarget.AuthorityOnly);
        }
    }

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

In this example, a command will get sent to each CoherenceSync under the state authority of this Client. To make it only affect CoherenceSyncs within certain criteria, you need to filter to which CoherenceSync you send the command to, on your own.

Sending null values in command arguments

Some of the primitive types supported are nullable values, this includes:

• Byte[]

• string

• Entity references: CoherenceSync, Transform, and GameObject

In order to send one of these values as a null (or default) we need to use special syntax to ensure the right method signature is resolved.

using Coherence;
using Coherence.Toolkit;
using UnityEngine;
using System;

public class MyCommand : MonoBehaviour
{
    private CoherenceSync sync;

    public void MyNullableCommand(string someString, Byte[] someArray)
    {
        if (!string.IsNullOrEmpty(someString)) //Could be null or string.Empty
        {
            // Do something with the string
        }

        if (someArray != null && someArray.Length > 0) //Could be null or Byte[0]
        {
            // Do something with the array
        }
    }

    public void SendNullableCommand()
    {
        sync.SendCommand<MyCommand>(nameof(MyNullableCommand),
            MessageTarget.All,
            (typeof(string), (string)null),
            (typeof(Byte[]), (Byte[])null));
    }
}

Null-value arguments need to be passed as a ValueTuple<Type, object> so that their type can be correctly resolved. In the example above sending a null value for a string is written as: (typeof(string), (string)null)

and the null Byte[] argument is written as: (typeof(Byte[]), (Byte[])null)

Mis-ordered arguments, type mis-match, or unresolvable types will result in errors logged and the command not being sent.

Limitations

When a Prefab is not using a baked script there are some restrictions for what types can be sent in a single command:

• 4 entity references

• maximum of 511 bytes total of data in other arguments

• a single Byte[] argument can be no longer than 509 bytes because of overhead

Some network primitive types send extra data when serialized (like Byte arrays and string types) so gauging how many bits a command will use is difficult. If a single command is bigger than the supported packet size, it won't work even with baked code. For a good and performant game experience, always try to keep the total command argument sizes low.

When a Client receives a command targeted at AuthorityOnly but it has already transferred an authority of that entity, the command is simply discarded.

While the basic case of direct parent-child relationships between CoherenceSync entities is handled automatically by coherence, more complex hierarchies (with multiple levels) need a specific component.

Implementation

To prepare the child Prefab that you want to parent at runtime, add the CoherenceNode component to it (in addition to its CoherenceSync). In the example above, that would be the flashlight you want your player to be able to pick up. No additional changes are required.

This setup allows you to place instances of the flashlight Prefab anywhere in the hierarchy of the Player (you could even move it from one hand to the other, and it would work).

You don't need to input any value in the fields of the CoherenceNode. They are used at runtime, by coherence, automatically.

To recap, for deep-nesting network entities to work, you need two things:

1. The parent: a Prefab with CoherenceSync that has some hierarchy of child transforms (these child transforms are not networked entities themselves).

2. The child: another connected Prefab with CoherenceSync and CoherenceNode.

Ensuring hierarchies are in sync

One important constraint for using CoherenceNode is that the hierarchies have to be identical on all Clients.

Position and rotation

Similarly to the above, intermediate children objects need to have the same position and rotation on all Clients. If not, that would lead to desync because the parented entity doesn't track the position of its parent object(s).

If you plan to move these intermediate children, then we suggest to sync the position and/or rotation of those objects as part of the containing Prefab.

Keep in mind that there is no penalty for synching positions of objects that never or rarely move, because the position is not synched every frame if it hasn't changed.

Inner workings

CoherenceNode works using two public fields which are automatically set to sync using the [Sync] attribute.

[Sync] public string path;
[Sync] public int pathDirtyCounter;

The path variable describes where in the parent's hierarchy the child object should be located. It is a string consisting of comma-separated indexes. Every one of these indexes designates a specific child index in the hierarchy. The child object which has the CoherenceNode component will be placed in the resulting place in the hierarchy.

The pathDirtyCounter variable is a helper variable used to keep track of the applied hierarchy changes. In case the object's position in the parent's hierarchy changes, this variable will be used to help settle and properly sync those changes.

Objects with the CoherenceSync component can be connected at runtime to other objects with a CoherenceSync component to form a direct parent-child relationship.

For example, an item of cargo can be parented to a vehicle, so that they move together when the vehicle is in motion.

Keep in mind that on this page we deal with direct parenting of two CoherenceSync GameObjects. If it's not practical to parent a network entity directly to the root of another, see instead how to .

Implementation

Parenting network entities directly doesn't require any extra work. Any parenting code (i.e. Unity's own transform.SetParent() will work out of the box, without any need for additional action.

You can add and remove parent-child relationships at runtime – even from the Unity editor, by drag-and-drop.

Effect on coherence LODs

If the child object is using LODs, it will base its distance calculations on the world position of its parent. For more info, see the documentation.

Handling parent destruction

When the parent CoherenceSync is destroyed, by default its CoherenceSync children get destroyed together with it. This can be changed via the Preserve Children option on the parent, under Advanced Settings:

When Preserve Children is enabled, if the authority destroys or disables the parent entity, child entities get unparented instead of being destroyed together with the parent. Those children will now reside at the root of the Scene hierarchy.

Out of the box, coherence offers several options to handle parenting of networked entities. While some workflows are automatic, others require a specific component to be added.

Generally there is a distinction if the parenting happens at runtime vs. edit time, and whether the two entities are direct parent-child, or have a complex hierarchy. See below for each case.

At runtime:

• : when you create a parent-child relationship of CoherenceSync objects at runtime.

• : when you create a complex parent-child relationship of CoherenceSync objects at runtime.

At edit time:

• : the developer prepares several connected Prefabs and nests them one to another before entering Play Mode. This covers both Prefabs in the scene and in the assets.

If a synced Prefab has a hierarchy, you can synchronize variables, methods and component actions for any of the child GameObjects within its hierarchy.

When the Configure window is open it will show the variables, methods and component actions available for synchronization for your currently selected GameObject.

First, make sure to be editing the Prefab in Prefab Mode:

Once in Prefab Mode and with the Configure window open, shift the selection to any of the GameObjects that belong to the hierarchy.

The Configure window will be updated automatically, showing you everything that is available to be synchronized on the child GameObject:

That's it!

Syncing properties, methods and component actions on child GameObjects doesn't require any different flow than what you usually do for the root object. They all get collected and networked as part of one single network entity.

coherence supports all Prefab-related Unity workflows, and nesting is one of them. It can make a lot of sense to prepare multiple networked Prefabs, parent them to each other, and either place them in the scene, or save them as a complex Prefab, ready to be instantiated. This page covers these cases.

Nested Prefabs for instantiation

When preparing a networked Prefab that contains another networked Prefab, one extra component is needed to allow coherence to sync the whole hierarchy: PrefabSyncGroup.

For instance, let's suppose we have a vehicle in an RTS that can carry cargo, and it comes with cargo pre-loaded when it's instantiated:

In this example Spacetruck is a synced Prefab, with 4 instances of the synced Prefab Cargo nested within. To make this work, we add a PrefabSyncedGroup to the root:

The component keeps track of child Prefabs that are also synced Prefabs. Now, whenever Spacetruck is instantiated, PrefabSyncGroup makes sure to take 4 instances of Cargo and link the Prefab instances to the correct network entities.

So to recap:

• The outermost Prefab needs CoherenceSync and PrefabSyncGroup.

• The child Prefabs need CoherenceSync and, optionally, CoherenceNode.

Nested Prefabs pre-placed in a Unity scene

When dealing with synced Prefabs that are hand-placed in the scene before connecting, such as level design elements like interactive doors, you need to ensure that they are seen as "unique". This is also covered in the Uniqueness page, but it's worth talking about it in the context of nested synced Prefabs.

When preparing such a Prefab, you need to set the Uniqueness property to No Duplicates. This ensures that, once multiple Clients connect and open the same scene, the synced Prefabs contained within are not spawned on the network multiple times.

Let's suppose we have a networked Prefab that represents a structure in an RTS (a LandingPad) that can be pre-placed in the scene. This structure also contains a networked vehicle Prefab (a Lander). This Prefab is synced as an independent network entity because at runtime it can detach, change ownership, be destroyed, etc.

To achieve this, all we need to do is ensure that both Prefabs are set to be unique. When we drag-and-drop the LandingPad Prefab into the scene, coherence automatically assigns a randomly-generated Prefab Instance Unique ID as an override. This number identifies these particular instances of these two Prefabs in the scene.

With this setting, we don't need to do anything else for these compound Prefabs to work.

To recap:

• The outermost Prefab needs its Uniqueness set to No Duplicates. Optionally, you can add PrefabSyncGroup to enable runtime-instantiation.

• Any child Prefab also needs its Uniqueness set to No Duplicates. It also needs a CoherenceNode if it's parented deep in the hierarchy.

Unique IDs on already-placed Prefabs

An important thing to keep in mind when working with compound Prefabs in the scene: when you add a new nested synced Prefab to an existing one that has already been placed in the scene a few times, the Prefab Instance Unique ID for these instances will initially be the same.

For this reason, once you play the game, you might see all children disappear (except one). That is normal: coherence thinks that all these network entities are the same, because they have the same uniqueness ID.

You need to ensure that these new children have an overriden and unique ID on each instance in the scene. To do so, click on the button next to the Prefab Instance Unique ID for each child that needs it:

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

Multiple AnimatorControllers

While coherence doesn't officially support working with multiple AnimatorControllers, there's a way to work around it. As long as the parameters you want to network are shared among the AnimatorControllers you want to use, they will get networked. Parameters need to have the same type and name. Using the example above, any AnimatorController featuring a Boolean Walk parameter is compatible, and can be switched.

Triggers

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

using UnityEngine;
using Coherence;
using Coherence.Toolkit;

public class JumpController : MonoBehaviour
{
    CoherenceSync coherenceSync;
    Animator animator;

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

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

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

    void MakePlayerJump()
    {
        coherenceSync.SendCommand<JumpController>(nameof(PlayJumpAnimation), MessageTarget.All, coherenceSync);
    }

    // bind to this method via the Bindings window
    public void PlayJumpAnimation(CoherenceSync jumpSync)
    {
        animator.SetTrigger("Jump");
    }
}

Now, bind the PlayJumpAnimator method as a command.

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 Configuration 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 LiveQuery. 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 CoherenceNode component or Parent-Child relationships of prefabs, which ensures that that Entity stays 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.

• Cyclic references are undefined behavior for now. Therefore multiple entities created on the same Client that reference each other might never get synced properly. This is also holds true for references that exist through intermediate entities (A has reference to B has reference to C has reference A - cyclic).

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.

Even though coherence provides Component Actions out of the box for various component, you can implement your own Component Actions in order to give designers on the team full authoring power on network entities, directly from within the Configure window UI.

Creating a new one is simply done by extending the ComponentAction abstract class:

Your custom Component Action must implement the following methods:

• OnAuthority This method will be called when the object is spawned and you have authority over it.

• OnRemote This method will be called when a remote object is spawned and you do not have authority over it.

It will also require the ComponentAction class attribute, specifying the type of Component that you want the Action to work with, and the display name.

For example, here is the implementation of the Component Action that we use to disable Components on remote objects:

It is often useful to know when a synchronized variable has changed its value. It can be easily achieved using the OnValueSyncedAttribute. This attribute lets you define a method that will be called each time a value of a synced member (field or property) changes in the non-simulated version of an entity.

Usage

Let's start with a simple example:

using Coherence.Toolkit;
using UnityEngine;
using UnityEngine.UI;

public class Player : MonoBehaviour
{
    [OnValueSynced(nameof(UpdateHealthLabel))]
    public float Health;

    public Text HealthLabel;

    public void UpdateHealthLabel(float oldHealth, float newHealth)
    {
        HealthLabel.text = newHealth.ToString();
        Debug.Log($"Player HP changed by: {newHealth - oldHealth}");
    }
}

Whenever the value of the Health field gets updated (synced with its simulated version) the UpdateHealthLabel will be called automatically, changing the health label text and printing a log with a health difference.

This comes in handy in projects that use authoritative Simulators. The Client code can easily react to changes in the Player entity state introduced by the Simulator, updating the visual representation (which the Simulator doesn't need).

Limitations

The OnValueSynced feature can be used only on members of user-defined types, that is, there's no way to be notified about a change in the value of a Unity type member, like transform.position. This might however change in the future, so stay tuned!

Aside from configuring your CoherenceSync bindings from within the Configure window, it's possible to use the [Sync] and [Command] C# attributes directly on your scripts. Your prefabs will get updated to require such bindings.

Sync Attribute

Mark public fields and properties to be synchronized over the network.

[Sync]
public int health;

It's possible to migrate the variable automatically, if you decide to change its definition:

[Sync("health")]
public float hp;

Command Attribute

Mark public methods to be invoked over the network. Method return type must be void.

[Command]
public void Heal(int amount)
{
    ...
}

It's possible to migrate the command automatically, if you decide to change the method signature:

[Command("Heal", typeof(int))]
public void IncreaseHp(float hp)
{
    ...
}

The Configure window lists all variables and methods that can be synced for the selected Prefab. Each selected element in the list is stored in the Prefab as a Binding with an associated Descriptor, which holds information about how to access that data.

By default, coherence uses reflection to gather public fields, properties and methods from each of the Prefab's components. You can specify exactly what to list in the Configure window for a given component by implementing a custom DescriptorProvider. This allows you to sync custom component data over the network.

Take this player inventory for example:

using UnityEngine;

public class Inventory : MonoBehaviour
{
    [System.Serializable]
    public class Item
    {
        public int id;
        public string name;
        public int durability;
    }

    public Item[] items = new Item[]
    {
        new Item {id = 0, name = "Shield", durability = 80},
        new Item {id = 1, name = "Stick", durability = 50},
        new Item {id = 2, name = "Stone", durability = 100},
    };

    public Item GetItem(int id)
    {
        foreach (var item in items)
        {
            if (item.id == id)
            {
                return item;
            }
        }

        return default;
    }
}

Since the inventory items are not immediately accessible as fields or properties, they are not listed in the Configure window. In order to expose the inventory items so they can be synced across the network, we need to implement a custom DescriptorProvider.

Creating a custom DescriptorProvider

The main job of the DescriptorProvider is to provide the list of Descriptors that you want to show up in the Configure window. You can instantiate new Descriptors using this constructor:

public Descriptor(string name, Type ownerType, Type bindingType, bool required=false)

• name: identifying name for this Descriptor.

• ownerType: type of the MonoBehaviour that this Descriptor is for.

• bindingType: type of the ValueBinding class that will be instantiated and serialized in CoherenceSync, when selecting this Descriptor in the Configure window.

• required: if true, every network Prefab that uses a MonoBehaviour of ownerType will always have this Binding active.

Here is an example InventoryDescriptorProvider that returns a Descriptor for each of the inventory items:

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

[DescriptorProvider(typeof(Inventory))]
public class InventoryDescriptorProvider : DescriptorProvider
{
    public override List<Descriptor> Fetch()
    {
        // Call base.Fetch to include public fields, properties and methods
        var descriptors = base.Fetch();

        var inventory = Component as Inventory;

        foreach (var item in inventory.items)
        {
            var inventoryDescriptor = new Descriptor(name: item.name, ownerType: typeof(Inventory), bindingType: typeof(InventoryBinding));
            inventoryDescriptor.CustomData = item.id;
            descriptors.Add(inventoryDescriptor);
        }

        return descriptors;
    }
}

To specify how to read and write data to the Inventory component, we also need a custom binding implementation.

Creating a custom Binding

A Descriptor must specify through the bindingType which type of ValueBinding it is going to instantiate when synced in a CoherenceSync. In our example, we need an InventoryBinding to specify how to set and get the values from the Inventory. To sync the durability property of the inventory item, we should extend the IntBinding class which provides functionality for syncing int values.

using Coherence.Toolkit.Bindings;
using Coherence.Toolkit.Bindings.ValueBindings;
using UnityEngine;

public class InventoryBinding : IntBinding
{
    public override string BakedSyncScriptGetter => "GetItem(ItemId).durability";
    public override string BakedSyncScriptSetter => "GetItem(ItemId).durability = @";

    // Required constructor signatures
    public InventoryBinding(Descriptor descriptor, Component unityComponent) : base(descriptor, unityComponent) { }
    public InventoryBinding() { }

    public int ItemId => (int)descriptor.CustomData;

    public override int Value
    {
        get => ((Inventory) unityComponent).GetItem(ItemId).durability;
        set => ((Inventory) unityComponent).GetItem(ItemId).durability = value;
    }
}

We are now ready to sync the inventory items on the Prefabs.

Overview

Out of the box, coherence can use C# reflection to sync data at runtime. This is a great way to get started but is very costly performance-wise and has a number of limitations on what features can be used through this system.

For optimal runtime performance and a complete feature set, we need to create a schema and perform code generation specific to our project. coherence calls this mechanism Baking.

How to Bake

Click on the coherence > Bake menu item.

This will go through all indexed CoherenceSync GameObjects (Resources folders and Prefab Mapper) in the project and generate a schema file based on the selected variables, commands and other settings. It will also take into account any that have been added.

For every Prefab with a CoherenceSync component attached, the baking process will generate a C# baked script specifically tuned for it.

Baking settings

Check .

When baking, the generated code will output to Asset/coherence/baked.

• You can version the baked files or ignore them, your call.

  • If you work on a larger game or team, where you use continuous integration, chances are you are better off including the baked files on your VCS.

• Since baked scripts access your code, changing networked variables or commands with coherence will get you into compilation errors.

Modifying networked variables or commands - The Watchdog

When you configure your Prefab to network variables, and then bake, coherence generates baked scripts that access your code directly, without using reflection. This means that whenever you change your code, you might break compilation by accident.

For example, if you have a Health.cs script which exposes a public float health; field, and you toggle health in the Configure window and bake, the generated baked script will access your component via its type, and your field via field name.

Like so:

If you decide you want to change your component name (Health) or any of your bound fields (health), Unity script recompilation can fail. In this example, we will be removing health and adding health2 in its place.

When baking via assets, the watchdog is able to catch compilation problems related with this, and offer you a solution right away.

It will suggest that you delete the baked folder, and then diagnose the state of your Prefabs. After a few seconds of script recompilation, you will be presented with the Diagnosis window.

In this window, you can easily spot variables in your Prefabs that can't be resolved properly. In our example, health is no longer valid since we've moved it elsewhere (or deleted it).

From here, you can access the Configure window, where you can spot the problem.

Now, we can manually rebind our data: unbind health and bind health2. Once we do, we can now safely bake again.

Switching a Prefab to reflection mode

Once the baked code has been generated, Prefabs will automatically make use of it. If you want to switch a particular Prefab to reflection code, you can do so in the Inspector of its CoherenceSync, by unchecking the Baked checkbox:

Networked entities can be simulated either on a Game Client ("Client authority") or a Simulator ("Server authority"). Authority defines which Client or Simulator is allowed to make changes to the synced properties of an Entity, and in general defines who "runs the gameplay code" for that Entity. An Entity is any networked GameObject.

To learn more about authority, check out this short video:

Authority owners

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 and commands is the combined ping (Client 1 to Replication 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. In this scenario, the Simulator has authority over key game elements, like a "game manager", a score-keeping object, and so on.

Running a Simulator in the cloud next to the Replication Server (with the ping between them being negligible) will also result in lower latency.

Remote Communication

Scenes or levels are a common feature of Unity games. They can be loaded from Unity scenes, custom level formats, or even be procedurally generated. In networked games, players should not be able to see entities that are in other scenes. To address this, coherence's scene feature gives you a simple way of controlling what scene you're acting in.

Each Coherence scene is represented by an integer index. You can map this index to your scenes or levels in any way you find appropriate. Projects that don't use scenes will implicitly put all their entities into scene 0.

Keeping a Connection alive between Scene changes

Since the connection to the Replication Server is done through the component, it means that if you switch Scenes, the current CoherenceBridge that holds the connection to the Replication Server will be destroyed.

In order to keep a CoherenceBridge with its connection alive between Scene changes, you will have to set it as Main Bridge in the Component inspector:

Automating Scene transitions

These are the options related to Scene transitions:

• Main Bridge: This CoherenceBridge instance will be saved as DontDestroyOnLoad and its connection to the Replication Server will be kept alive between Scene changes. All other CoherenceBridge components that are instantiated from this point forward will update the target Scene of the Main Bridge, and destroy themselves afterwards.

• Use Build Index as Scene Id: Every Scene needs a unique identifier over the network. This option will automate the creation of this ID by using the Scene Build Index (from the Build Settings window).

• Scene Identifier: If the previous option is unchecked, then you will be able to manually set a Scene Identifier of your own (restricted to unsigned integers).

Authority

A client connection and all the entities it has authority over are always kept in the same coherence scene. Clients cannot have authority over entities in other scenes. This implies two things:

1. When a client changes scene, it will bring along any entities it has authority over.

2. If an entity changes ownership via authority transfer, it will be moved to the new owner's scene.

Orphans

An entity that does not have an owner is an orphan. Orphaned entities will stay in the scene where their previous owner left them.

Implicit destruction of entities when loading Unity scenes

Note that Unity will destroy all game objects not marked as DontDestroyOnLoad whenever a new Unity scene is loaded (non-additively). If the client has authority over any of those entities at that point, coherence will replicate that destruction to all other clients. If that is undesirable and you need to leave entities behind, make sure that authority has been lost or transferred before loading the new Unity scene. You can of course also mark them as DontDestroyOnLoad, which will bring them along to then new scene.

Since this process involves a bit of logic that has to be executed over several frames, coherence provides a LoadScene helper method (co-routine) on CoherenceSceneManager. Here's an example of how to use it:

Limitations

It is not possible to move entities to other scenes without the client connection also moving there. Additionally, you can't currently query for entities in other scenes.

Both of these limitations are planned to be addressed in future versions of coherence.

Custom setup

If your project isn't a good fit for the automatic scene transitioning support described above, it is possible to use a more manual approach. There are a few important things to take care of in such a setup:

If you ever load another Unity scene, the CoherenceBridge that connects to the server needs to be kept alive, or else the client will be disconnected. A straightforward way of doing this is to call Unity's DontDestroyOnLoad method on it. This creates two problems when replicating entities from other Clients:

1. The bridge instantiates remote entities into the scene where it is currently located. To override this behaviour, set the InstantiationScene property on your CoherenceBridge to the desired scene.

2. Any new CoherenceSync instances will look for the bridge in the same scene that they are located. If the bridge is moved to the DontDestroyOnLoad scene, this lookup will fail. You can use the static CoherenceSync.BridgeResolve event to solve this problem (see the code sample in the next section). Alternatively, if you have a reference to a Scene, you can register the appropriate bridge for entities in that scene with CoherenceBridgeStore.RegisterBridge before it is loaded.

Additionally, coherence queries (e.g. CoherenceLiveQuery) also look for their bridge in their own scene, so you might have to set its bridgeResolve event too.

Code sample

Here's a complete code sample of how to use all the above things together:

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.

Lifetime 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.

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);

Persistent objects are stored

All persistent objects remain in the World for the entire lifetime of the Replication Server and, periodically, the Replication Server records the state of the World and saves it to physical storage. If the Replication Server is restarted, then the saved persistent objects are reloaded when the Replication Server resumes.

Persistent object limits

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;
using Coherence.Toolkit;

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

    public void NextNumber(CoherenceSync requester)
    {
        requester.SendCommand<NumberRequester>(
            nameof(NumberRequester.GotNumber),
            MessageTarget.AuthorityOnly,
            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;
using Coherence.Toolkit;

public class NumberRequester : MonoBehaviour
{
    CoherenceSync sync;

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

    void Update()
    {
        if (sync.HasStateAuthority && Input.GetKeyDown(KeyCode.Return))
        {
            var counter = FindAnyObjectByType<Counter>();
            var counterSync = counter.GetComponent<CoherenceSync>();

            counterSync.SendCommand<Counter>(
                nameof(Counter.NextNumber),
                MessageTarget.AuthorityOnly,
                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.

Overview

Authority over an Entity is transferrable, so it is possible to move the authority between different Clients or even to a Simulator. This is useful for things such as balancing the simulation load, or for exchanging items. It is possible for an Entity to have no Client or Simulator as the authority - these Entities are considered orphaned and are not simulated.

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 current authority.

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

• Disabled. Authority cannot be transferred.

When using Request, an optional callback OnAuthorityRequested can be set on the CoherenceSync behaviour. If the callback is set, then the results of the callback will override the Approve Requests setting in the behaviour.

The request can be approved or rejected in the callback.

// connectionID is the network connection ID of the requesting client.
// sync is the CoherenceSync behaviour of the object the other client is
// requesting authority over.
public bool OnRequest(ushort connectionID, CoherenceSync sync)
{
    return (sync == theRightSync && connectionID == goodConnectionID);
}

Requesting authority in code

Requesting authority is very straight-forward.

var coherenceSync = target.GetComponent<CoherenceSync>();
bool requestSuccess = coherenceSync.RequestAuthority(AuthorityType.Full);

RequestAuthority returns false if the request was not sent. This can be because of the following reasons:

1. The sync is not ready yet.

2. The entity is not allowed to be transferred becauseauthorityTransferType is set to NonTransferable.

3. There is already a request underway.

4. The entity is orphaned, in which case you must call Adopt instead to request authority.

The request itself might fail depending on the response of the current authority.

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

Also because of their asynchronous nature, clients can receive commands for entities that they have already transferred. Such commands are dropped.

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

// called when the CoherenceSync entity becomes the simulation authority
public UnityEvent OnStateAuthority;

// called when the CoherenceSync entity loses simulatino authority
public UnityEvent OnStateRemote;

// called when a request to assume authority over the CoherenceSync entity
// is rejected
public UnityEvent OnAuthorityRequestRejected;

These events are also exposed in the Custom Events section of the CoherenceSync inspector.

What is CoherenceInput?

CoherenceInput is a component that enables a Simulator to take control of the simulation of another Client's objects based on the Client's inputs.

When to use CoherenceInput?

• In situations where you want a centralized simulation of all inputs. Many game genres use client inputs 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 send inputs and just display the replicated results on the Clients.

• In situations where determinism is important. RTS and fighting games will use CoherenceInput 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 for server-side simulation using CoherenceInput and 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 Server Side With Client Input

Setting the simulation type to this mode instructs the Client to automatically transfer State Authority for this object to the Simulator that is in charge of simulating inputs on all objects.

2. Declaring Inputs for the simulated object

Each simulated CoherenceSync component is able to define its 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 to 1.

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

• String. A string value representing custom input state. (max length of 63 characters)

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.

Using CoherenceInput

When a Simulator is running it will find objects that are set up using CoherenceInput components and will automatically assume authority and perform simulations. 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.

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

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 just as any replicated object is.

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

Input Authority

Each object only accepts inputs from one specific Client, called the object's Input Authority.

When a Client spawns an object it automatically becomes the Input Authority for that object. The object's creator will retain control over the object even after state authority has been transferred to the Simulator.

If an object is spawned directly by the Simulator, you will need to assign the Input Authority manually. Use the TransferAuthority method on the CoherenceSync component to assign or re-assign a Client that will take control of the object:

public void AssignNewInputAuthority(CoherenceClientConnection newInputOwner)
{
    var coherenceSync = GetComponent<CoherenceSync>();
    coherenceSync.TransferAuthority(newInputOwner.ClientId, AuthorityType.Input);
}

The ClientId used to specify Input Authority can currently only be accessed from the ClientConnection class. For detailed information about setting up the ClientConnection Prefab, see the Client connections page.

In order to get notified when the Simulator (or host) takes state authority of the input you can use the OnInputSimulatorConnected event from the CoherenceSync component.

The OnInputSimulatorConnected event can also be raised on the Simulator or host if they have both input and state authority over an entity. This allows the session host to use inputs just like any other client but might be undesirable if input entities are created on the host and then have their input authority transferred to the clients.

To solve this you can check the CoherenceSync.IsSimulatorOrHost flag in the callback:

coherenceSync.OnInputSimulatorConnected.AddListener(() =>
{
    if (coherenceSync.Bridge.IsSimulatorOrHost)
    {
        // Ignore for Simulators and hosts.
        return;
    }

    // Insert your game logic here
    Debug.Log("Input ready for use!");
});

Server-authoritative network visibility

The CoherenceLiveQuery component can be used to limit the visible portion of the Game World that a player is allowed to see. The Replication Server filters out networked objects that are outside the range of the LiveQuery so that players can't cheat by inspecting the incoming network traffic.

When a query component is placed on a Game Object that is set to Server Side With Client Inputs the query visibility will be applied to the Game Object's Input Authority (i.e., the player) while the component remains in control of the State Authority (i.e. the Simulator). This prevents players from viewing other parts of the map by simply manipulating the radius or position of the query component.

Client-side prediction

Using Server-side simulation takes a significantly longer period of time from the Client providing input until the game state is updated, compared to just using Client-side simulation. That's 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 round-trip time results in an input lag that can make controls feel awkward and slow to respond.

If you want to use a Server-authoritative setup without sacrificing input responsiveness, you need to use Client-side prediction. With Client-side prediction enabled, incoming network data is ignored for one or more bindings, allowing the Client to predict those values locally. Usually, position and rotation are predicted for the local player, but you can toggle Client-side prediction for any binding in the Configuration window.

By processing inputs both on the Client and on the Server, the Client can make a prediction of where the player is heading without having to wait for the authoritative Server response. This provides immediate input feedback and a more responsive playing experience.

Note that inputs should not be processed for Clients that neither have State Authority nor Input Authority. That's because we can only predict the local player; remote players and other networked objects are synced just as normal.

public void Update()
{
    if (coherenceSync.HasStateAuthority || coherenceSync.HasInputAuthority)
    {
        ProcessMousePosition();
    }

    if (coherenceSync.HasInputAuthority)
    {
        SendMousePosition();
    }
}

Misprediction and Server Reconciliation

With Client-side prediction enabled, the predicted Client state will sometimes diverge from the Server state. This is called misprediction. When misprediction occurs, you will need to adjust the Client state to match the Server state in one way or another. This is called Server Reconciliation.

There are many possible approaches to Server Reconciliation and coherence doesn't favor one over another. The simplest method is to snap the Client state to the Server state once a misprediction is detected. Another method is to continuously blend from Client state to Server state.

Misprediction detection and reconciliation can be implemented in a binding's OnNetworkSampleReceived event callback. This event is called every time new network data arrives, so we can test the incoming data to see if it matches with our local Client state.

private void Awake()
{
    var positionBinding = GetComponent<CoherenceSync>().Bindings.FirstOrDefault(c => c.Name == "position");
    positionBinding.OnNetworkSampleReceived += DetectMisprediction;
}

private void DetectMisprediction(object sampleData, long simulationFrame)
{
    const float MispredictionThreshold = 3;

    var networkPosition = (Vector3)sampleData;
    var distance = (networkPosition - transform.position).magnitude;

    if (distance > MispredictionThreshold)
    {
        transform.position = networkPosition;
    }
}

The misprediction threshold is a measure of how far the prediction is allowed to drift from the Server state. Its value will depend on how fast your player is moving and how much divergence is acceptable in your particular game.

Remember that incoming sample data is delayed by the round-trip time to the Server, so it will trail the currently predicted state by at least a few frames, depending on network latency. The simulationFrame parameter tells you the exact frame at which the sample was produced on the authoritative Server.

Client as a host

A client-hosted session is an alternative way to use CoherenceInput in Server Side With Client Input mode that doesn't require a Simulator.

A Client that created a Room can join as a Host of this Room. Just like a Simulator, the Host will take over the State Authority of the CoherenceInput objects while leaving the Input Authority in the hands of the Client that created those objects.

The difference between a Host and a Simulator is that the Host is still a standard client connection, which means it counts towards the Room's client limit and will show up as a client connection in the connection list.

Usage

To connect as a Host all we have to do is call CoherenceBridge.ConnectAsHost:

public CoherenceBridge bridge;

public async Task CreateRoomAndJoinAsHost(string region)
{
    CloudService cloudService = bridge.CloudService;
    
    // Wait for connection to be established with the coherence Cloud, authenticated as a Guest User.
    await cloudService.WaitForCloudServiceReadyAsync(1000);

    var roomServiceForRegion = cloudService.Rooms.GetRoomServiceForRegion(region);
    
    RoomData roomData = await roomServiceForRegion.CreateRoomAsync(RoomCreationOptions.Default);
    (EndpointData roomEndpoint, bool isEndpointValid, string validationErrorMessage) = RoomData.GetRoomEndpointData(roomData);

    if (!isEndpointValid)
    {
        throw new Exception($"Invalid room endpoint: {validationErrorMessage}");
    }

    bridge.onConnected.AddListener(OnConnected);
    bridge.ConnectAsHost(roomEndpoint);
}

public void OnConnected(CoherenceBridge bridge)
{
    Debug.Log($"Connected! IsHost: {bridge.IsSimulatorOrHost}");
}

Bandwidth is limited

No matter how fast the internet becomes, conserving bandwidth will always be important. Some Game Clients might be on poor quality 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.

Overview

An integration with the Unity Profiler provides basic statistics on networking events and bandwidth.

Usage

To view the module, open the Unity Profiler by selecting Window > Analysis > Profiler. Open the Profiler Modules dropdown menu in the top left, and select the coherence module.

To hide unneeded graph lines, select the colored square next to the item you do not wish to see.

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

Application.targetFrameRate = 10;

Per-binding sampling frequency

Replication frequency can be configured for each binding individually in the Prefab Optimize window. The Sample Rate controls how many times per second values are sampled and synced over the network.

High sample rates increase replication accuracy and reduce latency, but consume more bandwidth. The upper limit at which samples can be quantized is 60hz, so sample rates beyond that are generally not recommended. It is not possible to change sampling frequency at runtime.

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 to look around 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 extent (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 extent 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.

Adding a TagQuery

In addition to the LiveQuery, coherence also supports filtering objects by tag. This is useful when you have some special objects that should always be visible regardless of World position.

To create a TagQuery, right click a GameObject in the scene and select coherence > TagQuery from the context menu.

All networked GameObjects with matching tags will now be visible to the Client. The coherence tag can be any string and can be configured separately from the Unity tag in the Advanced Settings section of the CoherenceSync component.

Tags and TagQueries can be updated at any time while the application is running, either from the Unity inspector or setting CoherenceSync.coherenceTag and CoherenceTagQuery.coherenceTag with code.

Currently, only a single tag per GameObject and TagQuery is supported. To include objects with different tags, you can create multiple TagQuery objects for each tag.

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 LiveQuery. 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.

Levels of Detail

Any Prefab with the CoherenceSync component can be optimized to use a various levels of details (LODs).

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.

On 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 them.

2. Its 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.

Bits and range

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

Here are some terms we will be using:

• Bits. The number of bits (octets) used 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 and fixed-point floats, 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 click the Optimize button on a Prefab's CoherenceSync component with defined field bindings.

That opens the Optimization window. 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 in LOD2 the entire Transform and Animator components are disabled beyond the distance of 20 units. At 100 units (a.k.a. meters), we usually do not see animation details, so we can save a lot of bandwidth and processing power by not replicating this data.

The Data Cost Overview shows us that this takes the original 913 bits down to just 372 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, using different compression types:

None

No compression will be used, a full 32-bit float will be transmitted every time.

Truncated

Allows for specifying the number of bits for compression. Less bits means lower bandwidth usage but at the cost of precision loss. The minimum number of bits is 10. Using 22 bits will result in around half of the precision of the full float, while 16 will result in the quarter of the precision.

Fixed point

Allows for specifying the range of values used together with either number of bits or a desired precision.

• Range affects the maximum and minimum value that the data type can take on. For example, a range of 100 to 200 means only values within that range can be sent - any value outside of this range will be clamped to the nearest correct value.

• Precision defines the greatest deviation allowed for the data type. For example, a precision of 0.1 means that a float of value 10.0 can be transmitted as anything from 9.9 to 10.1 over the network. The minimum allowed precision is 0.1, while the maximum precision depends on the range. Changing precision automatically recalculates the number of bits required for given range.

• Bits dictate how many bits to use when calculating the precision for a given range. When set manually, it will trigger recalculation of the precision for a given range. Mind that the number of bits can be rounded down if the calculated precision uses less, e.g. for a range of [0, 1] setting the number of bits to 6 will result in precision of 0.1 and a final bit count of 4, since 4 bits suffice to represent this range with a calculated precision.

Integers

Integers can be configured to any span (that fits within a 32-bit integer) 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 & Colors

Quaternions and Colors can be configured using the number of bits per component. Quaternions require sending 3 components while Colors require 4 components.

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.

Using LODs with connected entities

If a LODed game object is parented to another synced object, the child will base its LOD level on the World position of its parent. This means that the (local) position of the LODed child does not have any effect on its LOD, until it is unparented.

Also – to save bandwidth, detection of LOD changes on the client only happens when the entity sends a component update. This means that a child object might appear to be using a nonsensical LOD until it changes in some way, for example by modifying its position.

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.

archetype FemZombie
  lod 0
    WorldPosition 
      value [compression "FixedPoint", range-min "-2400", range-max "2400", bits "19", precision "0.01"]
    WorldOrientation 
      value [bits "24"]
    FemZombie_UnityEngine_Animator 
      InputHorizontal [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      InputVertical [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      InputMagnitude [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      TurnOnSpotDirection [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      ActionState [bits "15", range-min "0", range-max "10"]
  lod 1 [distance "50"]
    WorldPosition 
      value [compression "FixedPoint", range-min "-2400", range-max "2400", bits "16", precision "0.1"]
    WorldOrientation 
      value [bits "20"]
    FemZombie_UnityEngine_Animator 
      InputHorizontal [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      InputVertical [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      InputMagnitude [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      TurnOnSpotDirection [compression "FixedPoint", range-min "-1", range-max "1", bits "15", precision "0.0001"]
      ActionState [bits "15", range-min "0", range-max "10"]
      IdleRandom [bits "15", range-min "-9999", range-max "-9999"]
      RandomAttack [bits "15", range-min "-9999", range-max "-9999"]
      AttackID [bits "15", range-min "-9999", range-max "-9999"]
      DefenseID [bits "15", range-min "-9999", range-max "-9999"]
      RecoilID [bits "15", range-min "-9999", range-max "-9999"]
      ReactionID [bits "15", range-min "-9999", range-max "-9999"]
      HitDirection [bits "15", range-min "-9999", range-max "-9999"]
  lod 2 [distance "100"]
    WorldPosition 
      value [compression "FixedPoint", range-min "-2400", range-max "2400", bits "16", precision "0.1"]
    WorldOrientation 
      value [bits "16"]

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.)

Overview

For an object to appear to move smoothly on the screen, it must be rendered at a high rate, usually 60 frames per second or more. However, depending on the settings in your project, and the conditions of your internet connection, data may not always arrive at a smooth 60 frames per second across the network. This is completely okay, but in order to make state changes 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.

When you select a variable to replicate in the Configure window, it is automatically assigned a default interpolation setting. The default settings are usually good to get started, but you can modify or create your own interpolation settings that better fit your specific needs.

Configuring interpolation settings

In the Configure window, each binding displays its interpolation settings next to it.

Built-in interpolation settings for position and rotation are provided out-of-the-box, but you are free to create your own and use them instead.

Interpolation types

Linear interpolation blends values by moving along straight lines from sample to sample. This makes the networked object move in a zig-zag pattern, but this is usually not noticeable when sampled at a sufficient rate and with some additional smoothing applied (see section Other settings > Smoothing below).

Spline interpolation blends between samples using the Catmull-Rom spline method which gives a smoother movement than linear interpolation without any sharp corners, at the cost of increased latency (see: Latency below). Spline interpolation requires at least 4 samples to produce good results.

If interpolation type is set to None, the value will simply snap to the most recent sample without any blending. This is recommended for binding types that have no obvious blending methods, e.g., string, byte array and object references.

You could also implement your own interpolation type (see: Custom Interpolators below).

Latency

Interpolation will add some additional latency to synced bindings. That's because incoming network samples must first be put in a buffer that is then used to calculate the interpolated value.

The amount of latency depends on the binding's sample rate and interpolation type. The lower the sample rate, the higher the latency.

Linear Interpolation requires a headroom of one sample while Spline Interpolation requires two samples. If interpolation type is set to None, there is no additional latency added, and samples will be rendered as soon as they arrive over the network.

Since a Prefab can define separate interpolation types and sample rates for its different bindings, it is possible that not all bindings share the same latency. If, for example, position and rotation are interpolated with different latency, the position and rotation of a vehicle might not match on the remote object.

Other Settings

There are a few settings you can tweak:

• Smoothing

  • Smooth Time: additional smoothing can be applied (using SmoothDamp) to clear out any jerky movement after regular interpolation has been performed.

  • Max Smoothing Speed: the maximum speed at which the value can change, unless teleporting.

• Latency

  • Network Latency Factor: fudge factor applied to the network latency. A factor of 1 means adapting to network latency with no margin, so the incoming sample must arrive at its exact predicted time to prevent the buffer from becoming stale. In general, a factor of 1.1 is recommended to prevent network fluctuations from causing dead reckoning due to latency peaks.

  • Network Latency Cooldown: when network latency decreases, wait this amount of time (in seconds) before recalculating network latency. This prevents network fluctuations from causing dead reckoning due to latency valleys.

  • Additional Latency: increases latency by a fixed amount (in seconds) to add an additional margin for the sample buffer.

• Overshooting

  • Max: how far into the dead reckoning to venture when the time fraction exceeds 100%, as a percentage of the sample rate.

  • Retraction: how fast to pull back to 100% when overshooting the allowed dead reckoning maximum (in seconds)

• Teleport Distance: if two consecutive samples are further apart than this, the value will teleport or snap to the new sample immediately without interpolating or smoothing in between.

• Stale Factor: defines when to insert a virtual sample in case of a longer time gap between the samples. High stale factor puts the virtual sample close to first sample leading to a smooth transition between two distant samples. This is suitable for parameters that do not change rapidly - the position of a big ship for example. Low stale factor places the virtual sample near the second sample resulting in initial lack of change in value during interpolation followed by a quick transition to the second sample. This is best suited for parameters that can change rapidly, e.g. position of a player.

Interpolation works both in Baked and Reflection modes. You can change these settings at runtime via the Configure window (editor) or by accessing the binding and changing the interpolation settings yourself:

if (coherenceSync.TryGetBinding(typeof(Transform), "position", out Binding binding))
{
    // change your interpolation settings at runtime
    binding.interpolationSettings = someSettings;
}

Custom interpolators

The Linear and Spline interpolators that are provided by coherence are sufficient for most common use cases, but you can also implement your own interpolation algorithm by sub-classing Interpolator.

You can choose to override one or more of the base methods depending on which type or types of values you want to support. The method signatures usually take two adjacent samples and a fractional value (from 0 to 1) to blend between them. There are also method signatures that provide four samples, which is useful for the Catmull-Rom spline interpolation.

Here's an example of a custom interpolator that makes the remote object appear at an offset distance from the object's actual position.

using Coherence.Interpolation;
using UnityEngine;

public class InterpolatorWithOffset : Interpolator
{
    public Vector3 offset;
    public override float NumberOfSamplesToStayBehind => 1;

    public override Vector3 InterpolateVector3(Vector3 value1, Vector3 value2, float t)
    {
        var interpolatedValue = Vector3.Lerp(value1, value2, t);
        return interpolatedValue + offset;
    }
}