CoherenceSync

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.

CoherenceLiveQuery

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.

CoherenceBridge

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

CoherenceInput

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 server-authoritative setups.

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.

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.

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.

Ensure hierarchies are synced

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 child 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 syncing positions of objects that never or rarely move, because the position is not synced 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.

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

This page describes the order of various coherence events and scripts in relation to Unity's main loop.

Script execution order

Check out ScriptExecutionOrder.

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 Unity manual article 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.

Overview

Supporting Unity physics in a network environment requires managing the state of rigid bodies on replicated Prefabs. Generally, if a Prefab using CoherenceSync has a Rigidbody or Rigidbody2D component, the replicated instances of the Prefab should have the body set to kinematic so that they do not simulate in the physics step on non-authoritative clients. There is a convenient configuration for this in the CoherenceSync configuration components tab.

For most purposes, this is all that is required to have physically simulated entities correctly replicated on Clients. However, only the transform of the rigid body is actually replicated. For additional physical state replication a more advanced setup is required.

Advanced Rigid Body support

The CoherenceSync component supports three modes for replication of Unity rigid bodies:

• Direct - the default mode used for basic replication of the transform of the Unity GameObject with a rigid body component. When a rigid body is detected, the position and rotation of the GameObject are provided by and assigned to the rigid body's position and rotation directly and Unity updates the GameObject transform after the physics step.

• Interpolated - similar to Direct mode, except the update to the rigid body position and rotation are applied using MovePosition and MoveRotation which allows the Unity physics system to calculate rigid body state such as linear and angular velocity on Clients with replicated Entities.

• Manual - disables automatic update of position and rotation of CoherenceSync Prefabs with rigid bodies and enables the use of callbacks, allowing custom implementation of how position and rotation updates are applied. The callbacks are OnRigidbody2DPositionUpdate, OnRigidbody3DPositionUpdate, OnRigidbody2DRotationUpdate, and OnRigidbody3DRotationUpdate.

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

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

using Coherence.Toolkit;
using UnityEngine;

public class CoherenceSyncConfigExample : MonoBehaviour
{
    public CoherenceSyncConfig prefabSyncConfig;
    public CoherenceBridge bridge;
    
    private CoherenceSync instance1;
    private CoherenceSync instance2;
    
    void Start()
    {
        // Load the prefab and instantiate it in the current scene
        instance1 = prefabSyncConfig.GetInstance();
        // Load the prefab and instantiate it in the specific networked scene for the given CoherenceBridge
        instance2 = prefabSyncConfig.GetInstance(bridge, Vector3.zero, Quaternion.identity);
    }
    
    private void OnDestroy()
    {
        // Instances have to be destroyed via the ReleaseInstance method, so that its destruction is handle by the 
        // internal INetworkObjectInstantiator
        prefabSyncConfig.ReleaseInstance(instance1);
        prefabSyncConfig.ReleaseInstance(instance2);
    }
}

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

using System;
using Coherence.Toolkit;
using UnityEngine;

public class InstantiatorViaCoherenceSyncComponent : MonoBehaviour
{
    // Serialized prefab reference
    public CoherenceSync prefab;
    public CoherenceBridge bridge;

    private CoherenceSync instance1;
    private CoherenceSync instance2;

    void Start()
    {
        // Instantiate it in the current scene
        instance1 = prefab.GetInstance();
        // Instantiate it in the specific networked scene for the given CoherenceBridge
        instance2 = prefab.GetInstance(bridge, Vector3.zero, Quaternion.identity);
    }

    private void OnDestroy()
    {
        // Instances have to be destroyed via the ReleaseInstance method, so that its destruction is handle by the 
        // internal INetworkObjectInstantiator
        instance1.ReleaseInstance();
        instance2.ReleaseInstance();
    }
}

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 Prefab setup page to learn how to configure your Prefab to network state changes.

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 Client ID as one of the parameters. Then, on the receiving end, compare that value with a list of connected Clients.

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.

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.

After your changes to GameObject, don't forget to Bake again to rebuild the netcode for the entity.

The CoherenceSyncConfigRegistry is a ScriptableObject that will hold a list of references to your existing CoherenceSyncConfig objects.

CoherenceSyncConfig is a separate ScriptableObject that holds the configuration for each of your networked objects.

Since the Registry needs to keep a list of references, in coherence we offer three different ways you can handle your CoherenceSyncConfigRegistry asset:

• Sub Assets: The CoherenceSyncConfig assets will be saved as sub-assets of the CoherenceSyncConfigRegistry asset.

• Standalone Assets: The CoherenceSyncConfig assets will be saved separately in the Assets/coherence/baked folder, the CoherenceSyncConfigRegistry will simply keep a list of references to them.

• Dynamic Standalone Assets: The CoherenceSyncConfig assets will be saved separately in the Assets/coherence/baked folder. The CoherenceSyncConfigRegistry will not be saved to disk but it will be generated on-demand in memory.

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:

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

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

At edit time:

• Nesting connected Prefabs assets: 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.

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 deeply nest CoherenceSyncs.

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 Level of detail 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.

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:

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.

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

This option is only available if you have the Addressables Unity Package installed.

This loader will be used if your prefab is marked as an Addressable asset, and it will be soft referenced using Addressables AssetReference class.

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.

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:

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:

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:

• 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:

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.

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

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:

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.

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!

Value sync callbacks are currently only supported for value types. That means the following types are not supported: byte[], CoherenceSync, GameObject, Transform and RectTransform.

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.

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:

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

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.

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

Command Attribute

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

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

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

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.

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

When an Entity is created, the creator is assigned authority over the Entity. Authority can be then transferred at a later point between Clients – or even between Clients and Simulators, or between Simulators. Regardless, only one Client or Simulator can be the authority over the Entity at any given time.

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.

In addition to key gameplay objects, the player character can also be simulated on the Server, with the Client locally predicting its state based on inputs. You can read more about how to achieve that in the section about CoherenceInput and Server-authoritative setup.

Remote Communication

Even if an entity is not currently being simulated locally (the client does not have authority), we can still affect its state by sending a network command or even requesting a transfer of authority.

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

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 LODs 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 settings.

Bake modes

coherence offers two mechanisms to generate baked scripts: through Assets or through a Source Generator. By default, coherence baked using Assets, but you can change this setting anytime in the coherence Settings window.

1. Assets

When you bake using Assets, the generated code will output to Asset/coherence/baked. This is a simple solution, allowing for an easy inspection and debugging of the generated files, but it comes with a few drawbacks:

• You should version the baked files, which can clutter your VCS workflow.

• Since baked scripts access your code, changing your code will get you into compilation errors.

2. Source Generator

When you bake using the Source Generator, the generated code is fed directly to the compilation pipeline, not generating the files in the Assets folder. In this process, coherence can analyze your code syntactically and semantically. This means it can detect cases where changes in your code can affect the baked files, anticipating compiler errors and avoiding them altogether. This mode comes with a few drawbacks too:

• File Assets/coherence/Footprint.cs is created/updated every bake operation, to trigger a recompile on your code. This file (and its .meta) can be ignored in your VCS.

• A bake operation is performed on every recompile. For most projects this is not noticeable. But if your project is heavy or your computer is slow, this can take additional time on top of the normal recompilation time.

• Since baked files are not versioned and have to be generated, the protocol code generator (executable bundled with the SDK package) needs to keep its execute permissions and should have write permission on <project>/Library/coherence. This is usually not a problem, except in continuous integration scenarios, where there might be strict rules on files having the execute permission.

• Harder to debug. Since files are not in Assets anymore, you can't click on them and have proper code completion. The last generation made through the Source Generator is available in Library/coherence/LastBake.

As you can see, there are pros and cons to each mechanism, so we recommend you try both and check what works best for your workflow.

Modifying bound data, 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:

var healthComponent = GetComponent<Health>();
...
var healthField = healthComponent.health;

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.

//public float health;
public float health2;

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:

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.

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 CoherenceBridge 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

In the CoherenceBridge inspector you will find all the options related to handling Scene transitions. First thing to know is that Client Connections must be enabled for this feature to work.

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:

private IEnumerator LoadNextScene()
{
    CoherenceSync[] bringAlong = new CoherenceSync[] { sword, torch, rope };
    yield return CoherenceSceneManager.LoadScene(bridge, ++sceneIndex, bringAlong);
}

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:

using UnityEngine;
using UnityEngine.SceneManagement;
using Coherence.Toolkit;

public class Example : MonoBehaviour
{
    public CoherenceBridge bridge;
    public CoherenceLiveQuery query;

    void Awake()
    {
        // Move the bridge to DontDestroyOnLoad but still
        // instantiate into the active scene
        var scene = bridge.gameObject.scene;
        DontDestroyOnLoad(bridge);
        bridge.InstantiationScene = scene;

        // Make the query find the bridge
        query.BridgeResolve += _ => bridge;

        // Make new CoherenceSync:s find the bridge
        CoherenceSync.BridgeResolve += _ => bridge;

        // Get notified if the scene is changed
        SceneManager.sceneLoaded += OnSceneLoaded;
    }

    void OnSceneLoaded(Scene scene, LoadSceneMode mode)
    {
        // Moves the client connection to another scene on the server
        bridge.SceneManager.SetClientScene(scene.buildIndex);

        // Instantiate remote entities into the new scene instead
        bridge.InstantiationScene = scene;
    }
}

Motivation

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

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

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

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

To use this technique we must learn about something called .

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.

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

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.

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:

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.

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.

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.

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.

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.

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.

Uniqueness and UUID

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

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

The CoherenceUUID behaviour is used to uniquely identify a Prefab.

It has several functions: you can generate a new ID for your object, and you can set auto-generate UUID on the scene to true, so each time the object will receive a new ID.

Deleting a persistent object

Deleting a persistent object is done the same as with any network object - by destroying its 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

coherence uses the concept of ownership to determine who is responsible for simulating each Entity. By default, each Client that connects to the Replication Server owns and simulates the Entities they create. There are a lot of situations where this setup is not adequate. For example:

• The number of Entities could be too large to be simulated by the players on their own, especially if there are few players and the World is very large.

• The game might have an advanced AI that requires a lot of coordination, which makes it hard to split up the work between Clients.

• It is often desirable to have an authoritative object that ensures a single source of truth for certain data. State replication and "eventual correctness" doesn't give us these guarantees.

• Perhaps the game should run a persistent simulation, even while no one is playing.

With coherence, all of these situations can be solved using dedicated Simulators. They behave very much like normal Clients, except they run on their own with no player involved. Usually, they also have special code that only they run (and not the clients). It is up to the game developer to create and run these programs somewhere in the cloud, based on the demands of their particular game.

Creating a Simulator

If you have determined that you need one or more Simulator for your game, there are multiple ways you can go about implementing these. You could create a separate Unity project and write the specific code for the Simulator there (while making sure you use the same schema as your original project).

An easier way is to use your existing Unity project and modify it in a way so that it can be started either as a normal Client, or as a Simulator. This will ensure that you maximize code sharing between Clients and Servers - they both do simulation of Entities in the same Game World after all.

To force a build to start as a Simulator, you can use the following command line argument:

$ ./Game --coherence-simulation-server

Simulators in coherence Cloud

The Simulator is started with the following parameters in coherence Cloud:

--coherence-region             // region where the simulator is started
--coherence-world-id           // unique world id (in world mode)
--coherence-http-server-port   // REST access for starting / stopping rooms
--coherence-auth-token         // token to authorize access
--coherence-simulation-server  // identify as simulation server
--coherence-simulator-type     // Room or World

// the following should be used also when starting a local simulation server to 
// successfully connect to the local replication server

--coherence-ip                 // address of the replication server (eg 127.0.0.1)
--coherence-port               // port of the replication server
--coherence-room-id            // room id when connecting to a room
--coherence-unique-room-id     // unique room id to connect to in room mode
--coherence-room-tags          // tags used when creating the room
--coherence-room-kv            // key values supplied when creating the room

SimulatorUtility

The SDK provides a static helper class to access all the above parameters in the C# code called SimulatorUtility.

static class SimulatorUtility
{
    public enum Type
    {
        Undefined = 0,
        World = 1,
        Rooms = 2
    }
    
    public static Type SimulatorType;         // Type of simulator: Room / World.
    public string Region;                     // Region where simulator was spawned.
    public string Ip;                         // Ip of the replication server.
    public int Port;                          // UDP port of the replication server.
    public int RoomId;                        // RoomId for current session. 
    public ulong UniqueRoomId;                // Unique RoomId.
    public ulong WorldId;                     // World Id (in worlds mode).
    public int HttpServerPort;                // Port used for REST commands.
    public string AuthToken;                  // Auth token used for authentication.
    public List<string> RoomTags;             // Tags for the room. 
    public Dictionary<string,string> RoomKV;  // Key Values for the room.
    public bool IsInvokedAsSimulator;         // Whether the instance was invoked as a simulator.
    public bool IsInvokedInCommandLine;       // Whether the instance was invoked on the commandline.
    public bool IsSimulator;                  // Identify whether simulator.  
}

Building simulators

To build Simulators, it's best to use the Linux Dedicated Server Build Target.

This is great for Simulators since we're not interested in rendering any graphics on these outside of local development. You will also get a leaner executable that is smaller and faster to be published in coherence Cloud.

When a room has only Simulators (no Clients) it shuts down automatically after a short period of time.

Build and deploy

Refer to the Simulator: Build and deploy section.

The simulation frame represents an internal clock that every Client syncs with a Replication Server. This clock runs at a 60Hz frequency which means that the resolution of a single simulation frame is ~16ms.

There are 3 different simulation frame types used within the coherence:

Simulation Frame

Accessible via CoherenceBridge.NetworkTime.

void Start()
{
    if (!CoherenceBridgeStore.TryGetBridge(gameObject.scene, out var bridge))
    {
        Debug.LogWarning("Couldn't find CoherenceBridge in the scene.");
        return;
    }
    
    var networkTime = bridge.NetworkTime;

    var serverFrame = networkTime.ServerSimulationFrame.Frame;
    Debug.Log("Server Simulation Frame: " + serverFrame);
    
    var clientFrame = networkTime.ClientSimulationFrame.Frame;
    Debug.Log("Client Simulation Frame: " + clientFrame);
}

Every Client tries to match the Client simulation frame with the Server simulation frame by continuously monitoring the distance between the two and adjusting the NetworkTime.NetworkTimeScale based on the distance, ping, delta time, and several other factors starting from the first simulation frame captured when the client first connects in NetworkTime.ConnectionSimulationFrame

In perfect conditions, all Clients connected to a single session should have exactly the same ClientSimulationFrame value at any point in the real-world time.

The Client simulation frame is used to timestamp any outgoing Entity changes to achieve a consistent view of the World for all players. The receiving side uses it for interpolation of the synced values.

Client fixed simulation frame

Local simulation frame that progresses in user-controlled fixed steps. Accessible via CoherenceBridge.ClientFixedSimulationFrame.

By default, the fixed step value is set to the Time.fixedDeltaTime.

Just like the basic Client simulation frame, it uses the NetworkTime.NetworkTimeScale to correct the drift. The fixed simulation frame is used as a base for the fixed-step, network-driven simulation loop that is run via CoherenceBridge.OnFixedNetworkUpdate. This loop is used internally to power the CoherenceInput and the GGPO code.

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.

The coherence Settings window is located in coherence > Settings.

The Replication Server replicates the state of the world to all connected Clients and Simulators.

To understand what is happening in the Game World, and to be able to contribute your simulated values, you need to connect to a Replication Server. The Replication Server acts as a central place where data is received from and distributed to interested Clients.

You can connect to a Replication Server in the coherence Cloud, but we recommend that you first start one locally on your computer. coherence is designed so you can easily develop everything locally first, before deploying to the Cloud.

Replication Servers replicate data defined in schema files. The schema's inspector provides all the tools needed to start a Replication Server.

1. Run the Replication Server by clicking the Run button or copy the run command to the clipboard via clicking the copy run-command icon located to the right of it.

2. A terminal/command line will pop up, running your Server locally.

3. The port the Replication Server will use. Rooms: 42001 Worlds: 32001

4. The web port used for webGL connections. Rooms: 42001 Worlds: 32002

5. The Replication Server send frequency. Default: 20 packets / s

6. The Replication Server receive frequency. Default: 60 packets / s

Replication Server send and receive frequencies

The Replication Server supports different packet frequencies for sending and receiving data.

The send frequency is the frequency that the Replication Server uses to send packets to a given Client. Each Client can be sent packets at different times, but the packet receive frequency for any Client will not exceed the Replication Server's send frequency.

The receive frequency is the maximum frequency at which the Replication Server expects to receive packets from any Client, before throttling. If a Client sends packets to the Replication Server at a higher than expected frequency, that Client will receive a command to slow down sending. If the Client doesn't respect the command to throttle packet sending then the Client is disconnected after a time. All extra packets received by the Replication Server, after a threshold based on the receive frequency, are dropped and not processed. This is to prevent malicious Clients from flooding the Replication Server. The Unity SDK handles throttling automatically.

It is possible for the Replication Server to temporarily request Clients to reduce their packet send rates if the processing load of the Replication Server is too high. This is automatic and send rates from the affected Clients are commanded to resume once the load is reduced.

Adjusting send and receive frequencies

Low and consistent send rates from the Replication Server allow for optimal bandwidth use and still support a smooth stream of updates to Clients. Try different rates during local replication tests to see what works well for your game.

For a locally hosted Replication Server, you can edit the send and receive frequencies by using the CLI arguments --send-frequency and --recv-frequency. Or by changing it in the coherence Settings -> Local Replication Server -> Send Frequency / Recv Frequency.

On the dashboard, the packet frequencies for sending and receiving data can be adjusted per project too. It is part of the Advanced Config section of Worlds create/edit and Rooms pages of the dashboard.

Connecting to a Replication Server

When the Replication Server is running, you connect to it using the Connect method.

Connect to a local Replication Server

using Coherence;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class ConnectToLocal : MonoBehaviour
{
    void Start()
    {
        var Bridge = FindAnyObjectByType<CoherenceBridge>();
        
        var endpoint = new EndpointData
        {
            region = EndpointData.LocalRegion,
            host = "127.0.0.1",
            port = 32001,
            schemaId = RuntimeSettings.instance.SchemaID,
        };

        Bridge.Connect(endpoint);
    }
}

After trying to connect you might be interested in knowing whether the connection succeeded. The Connect call will run asynchronously and take around 100 ms to finish, or longer if you connect to a remote Server.

Respond to connection events

using Coherence;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class ConnectToLocal : MonoBehaviour
{
    private CoherenceBridge Bridge;

    void Start()
    {
        Bridge = FindAnyObjectByType<CoherenceBridge>();
        Bridge.onConnected.AddListener(HandleConnected);
        Bridge.onDisconnected.AddListener(HandleDisconnected);
        Bridge.onLiveQuerySynced.AddListener(HandleLiveQuerySynced);

        var endpoint = new EndpointData
        {
            region = EndpointData.LocalRegion,
            host = "127.0.0.1",
            port = 32001,
            schemaId = RuntimeSettings.instance.SchemaID,
        };

        Bridge.Connect(endpoint);
    }

    private void HandleConnected(CoherenceBridge _) { /* ... */ }

    private void HandleLiveQuerySynced(CoherenceBridge _) { /* ... */ }

    private void HandleDisconnected(CoherenceBridge _, ConnectionCloseReason reason) { /* ... */ }

    private void OnDestroy()
    {
        Bridge.onConnected.RemoveListener(HandleConnected);
        Bridge.onDisconnected.RemoveListener(HandleDisconnected);
        Bridge.onLiveQuerySynced.RemoveListener(HandleLiveQuerySynced);
    }
}