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

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

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

A MonoBridge 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.

Persistent Entity limits

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.

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

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

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

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

This component is added by CoherenceSync on .

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.

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 = FindObjectsOfType<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.

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. You can select which of the attached components you would like to sync across the network as well as individual public properties.

Synced variables and commands

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

Persistence and authority

Ownership transfer

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

Entity lifetime

When a player disconnects, all the GameObjects created by that player are usually destroyed. If you want any GameObjects to stay in the Game World after the owner disconnects, you need to set Entity lifetime type of that GameObject to Persistent.

• Session Based - will be removed when the Client disconnects. GameObjects will stay on the scene of the Client who is an Authority owner for session-based objects until the scene reloads.

Uniqueness

• Allow Duplicates - no restrictions on which objects can be instantiated over the network.

• No Duplicates - ensure objects are not duplicated by marking them with a UUID.

  • You can set the UUID manually

  • If you leave the field blank a GUID will be assigned at runtime (This is rarely what you want)

  • Use the CoherenceUUID component helper to generate GUIDs for you at editor time. CoherenceUUID is an design time only tool for assigning unique UUIDs to prefab instances.

Uniqueness examples

Manager: If your game has a prefab, of which there can only be 1 in-game instance at any time (Such as a Game Controller), assign a UUID manually on the prefab asset.

Interactable objects: If you have several instances of a given prefab, but each instance must be unique (Such as doors, elevators, pickups etc) you should add the CoherenceUUID script and set it to Auto-generate in scene. This means that i.e. a door will only spawn once, but still replicate its state across the network.

Entity simulation type

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

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

Authority transfer style

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

• Stealing - Allows the GameObject to be transferred to another Client.

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

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, enable Auto-adopt orphan.

Transfer request

Once you have set the transfer style to Stealing, any Client can request ownership by calling the RequestAuthority() method on the CoherenceSync component of that GameObject:

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

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

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

Connection status

You can set up Custom Events for handling user connection and disconnection. Manual Destroy is useful for session based objects that you want to keep "semi-persistent" which would be removed when all the Clients disconnect.

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<NameOfThePrefab>. This component will be instantiated at runtime, and will take care of networked serialization and deserialization, instead of the built-in reflection-based one.

Commands

Overview

Objects with the CoherenceSync component can be connected to other objects with CoherenceSync components to form a parent-child relationship. For example, an object can be linked to a hand, a hand to an arm, and the arm to a spine.

Usage

Creating an Entity hierarchy is very simple. All you need to do is add a GameObject with a CoherenceSynccomponent as a direct child of another GameObject with a CoherenceSynccomponent. You can add and remove parent-child relationships at runtime (even from the editor).

Destruction or disconnection of the parent object will also destroy and remove all children of this object. Those objects' state needs to be treated on the Client side to be reinstantiated on the next connection.

Hierarchies with intermediary transforms

Sometimes, it is not practical to add CoherenceSyncobjects to all the links in the chain. For example, if a weapon is parented to a hand controlled by an Animator, we do not need to synchronize the entire skeleton over the network. In that case, see .

Level of detail considerations

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

Handling parent destruction

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

When the Preserve Children option is enabled, destroying the parent entity will result in children getting unparented instead of being destroyed together with the parent. Those children will now reside at the root of the scene hierarchy.

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.

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

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

To do so, open the Prefab in Prefab Mode by clicking the Open Prefab option in the inspector. This will allow you to select 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.

Sometimes you want to synchronize data outside of the current GameObject.

Out of the box, coherence offers you coherence offers you several options to synchronize data from your CoherenceSync objects' hierarchy:

• : when you need to network data directly from other GameObjects.

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

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

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

Script execution order

The following coherence components use a non-standard script execution order:

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

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

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

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

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

Sync Attribute

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

[Sync]
public int health;

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

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

Command Attribute

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

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

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

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

• bool

• int

• uint

• byte

• char

• short

• ushort

• float

• string

• Vector2

• Vector3

• Quaternion

• GameObject

• Transform

• RectTransform

• CoherenceSync

• SerializeEntityID

• byte[]

• long

• ulong

• Int64

• UInt64

• Color

• double

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

Usage

Let's start with a simple example:

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

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

    public Text HealthLabel;

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

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

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

Limitations

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

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

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.

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 little extra work.

An example of such a hierarchy would be a synced Player Prefab with a hierarchical bone structure, where you want to place an item (e.g. a flashlight) in the hand:

Player > Shoulder > Arm > Hand

A Prefab can only have a single CoherenceSync script on it (and only on its root node), so you can't add an additional one to the hand. Instead, you need to add the CoherenceNode component to another Prefab so that it can be parented. Please note that this parenting relationship can only be set up in the scene or at runtime; you can't store it in the parent Prefab since that would break the rule of only one CoherenceSync per Prefab.

To prepare the child Prefab that you want to place in the hierarchy, add the CoherenceNode component to it (it also has to have a CoherenceSync). In the example above, that would be the flashlight you want your player to be able to pick up. You don't need to make any changes to the Player Prefab, just make sure it has a CoherenceSync script in the root.

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

To recap, for CoherenceNode to work you need two things:

1. One or more Prefabs with CoherenceSync that have some kind of hierarchy of child transforms (the child transforms can't have CoherenceSyncs on them).

2. Another Prefab with CoherenceSync and CoherenceNode. Instances of this Prefab can now be parented to any transform of the Prefabs with just CoherenceSync (in step 1).

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.

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

Triggers

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

using UnityEngine;
using Coherence;
using Coherence.Toolkit;

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

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

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

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

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

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

Now, bind to the PlayJumpAnimator.

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.

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

coherence ships with a Sample UI that can be used to kickstart your project.

One implementation that we often see pretty early on prototypes, is the ability to show a name to identify players within a game session. So we've created a component to help achieve that: CoherencePlayerName.

If you want to network the Player Name set on the Sample UI, add a CoherencePlayerName component to your CoherenceSync:

Networked entities can be simulated either on a Game Client ("Client authority") or a Simulation Server ("Server authority"). Authority defines which Client or Simulation Server is allowed to make changes to an Entity. An Entity is any networked GameObject.

When an Entity is created, the creator is assigned authority over the Entity and that authority can be between Clients and Simulators, but only one Client or Simulator can be the authority over the Entity at at 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.

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

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

Remote Communication

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.

Learn more about this in the section.

coherence calls this mechanism baking.

Baking

Click on coherence / Bake.

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

Baking Settings

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

Bake mode: 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.

Bake mode: 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.

Using the Baked Script in your Prefab

Once the baked scripts have been generated, you can make use of it by ticking the checkbox Baked in the CoherenceSync inspector. This is on by default.

Modifying bound data, safe mode and the watchdog

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

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

Like so:

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

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

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

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

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

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

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

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

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

Destroy(coherenceSync.gameObject);

Persistent objects are stored

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

Persistent object limits

Overview

Authority over state changes to an Entity is transferrable, so it is possible to move the authority over simulation of an Entity between Clients and Simulation Servers. This is useful for things such as balancing the simulation load, or 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.

The request will first go to the Replication Server and be passed onto the receiving Simulator or Game Client, so it may take a few frames to get a response.

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

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

Overview

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

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

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

Configuring interpolation settings

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

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

Interpolation types

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

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

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

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

Latency

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

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

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

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

Other Settings

There are a few settings you can tweak:

• Smoothing

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

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

• Latency

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

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

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

• Overshooting

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

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

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

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

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

Custom interpolators

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

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

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

using Coherence.Interpolation;
using UnityEngine;

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

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

The NumberOfSamplesToStayBehind property controls the internal latency.

Extrapolation

Extrapolation uses historical data to predict the future state of a binding. By predicting the state of other players before their network data actually arrives, network lag can be reduced or removed entirely. This will cause mispredictions that need to be corrected when the incoming network data does not match the predicted state.

Motivation

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

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

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

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

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

Levels of Detail

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

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

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

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

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

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

Bits and range

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

Here are some terms we will be using:

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

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

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

Defining levels of detail

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

In order to define levels of detail, we have to click the Optimize button on a Prefab's CoherenceSync component with defined field bindings.

That opens the Optimization window. We can override the base component settings even without defining further levels of detail.

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

You can also disable components at later LOD levels if they are not needed. In the example above, you can see that in LOD2 the entire Transform and Animator components are disabled beyond the distance of 20 units. At 100 units (a.k.a. meters), we usually do not see animation details, so we can save a lot of bandwidth and processing power by not replicating this data.

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

Field overrides per type

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

Float, Vector2 & Vector3

These three types can all be configured in the same way, using different compression types:

None

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

Truncated

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

Fixed point

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

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

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

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

Integers

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

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

Quaternions & Colors

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

Other types

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

Using LODs with connected entities

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

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

LODs in the schema

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

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

Caveats

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

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

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.

The simulation frame represents an internal clock that every Client syncs with a . 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:

Server simulation frame

The latest simulation frame received from the Replication Server. Accessible via CoherenceMonoBridge.NetworkTime.ServerSimulationFrame.

Client simulation frame

Local Client simulation frame that progresses with local time. Accessible via CoherenceMonoBridge.NetworkTime.ClientSimulationFrame.

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.

Client fixed simulation frame

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

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

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.

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

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

Connect to a Replication Server hosted in the coherence Cloud

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.

The coherence Settings window is located in coherence / Settings.

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 headless mode (Unity 2020) or 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.

Connecting Simulators to the Internet is a paid-only feature. If you are currently on a Free Tier Subscription and need your Simulators to connect to external services, please upgrade your Subscription.

Before deploying a Simulation Server, testing and debugging locally can significantly improve development and iteration times. There are a few ways of accomplishing this.

Running the Editor as a Simulator

Using the Unity Editor as a Simulator allows us to easily debug the Simulator. This way we can see logs, examine the state of scenes and GameObjects and test fixes very rapidly.

To run the Editor as a Simulator, run the Editor from the command line with the proper parameters:

• --coherence-simulation-server: used to specify that the program should run as a coherence Simulator.

• --coherence-simulator-type: tells the Simulator what kind of connection to make with the Replication Server, can be Rooms or World.

• --coherence-region: tells the Simulator which region the Replication Server is running in: EU, US or local.

• --coherence-ip: tells the Simulator which IP it should connect to. Using 127.0.0.1 will connect the Simulator to a local server, if one is running.

• --coherence-port: specifies the port the Simulator will use.

• --coherence-world-id: specifies the World ID to connect to, used only when set to Worlds.

• --coherence-room-id: specifies the Room ID to connect to, used only when set to Rooms.

• --coherence-unique-room-id: specifies the unique Room ID to connect to, used only when set to Rooms.

• --coherence-auth-token: specifies your local dev authentication token, that you get from pressing the coherence Hub > Simulators > Run local simulator build > Fetch Last Endpoint button. This will change in the near future and will no longer be a required parameter.

For example:

<Editor path> -projectPath <project path>
--coherence-simulation-server 
--coherence-simulator-type rooms
--coherence-region local
--coherence-ip 127.0.0.1 
--coherence-port 32001 
--coherence-room-id [room-id]
--coherence-unique-room-id [room-uid]
--coherence-auth-token [auth-token-string]

If you're not sure which values should be used, adding a COHERENCE_LOG_DEBUG define symbol will let you see detailed logs. Among them are logs that describe which IP, port and such the Client is connecting to. This can be done in the Player settings: Project Settings > Player > Other Settings > Script Compilation > Scripting Define Symbols.

Running a Simulator build locally from the command line

Another option is making a Simulator build and running it locally. This option emulates more closely what will happen when the Simulator is running after being uploaded.

You can run a Simulator executable build in the same way you run the Editor.

"simulator build path"
--coherence-simulation-server 
--coherence-ip 127.0.0.1 
--coherence-port 32001 
--coherence-world-id 0 
--coherence-room-id [room-id]
--coherence-unique-room-id [room-uid]

This allows you to test a Simulator build before it is uploaded or if you are having trouble debugging it.

Running a Simulator build locally from the Unity Editor

You can also run existing Simulator build from coherence Hub > Simulators > Run local simulator build.

Use the Fetch Last Endpoint button to autofill the required fields.

Connecting a Simulator to a Room

When using a Rooms-based setup, you first have to create a Room in the local Replication Server (e.g. by using the connect dialog in the Client).

The local Replication Server will print out the Room ID and unique Room ID that you can use when connecting the Simulator.

Am I a Simulator ?

Ask Coherence.SimulatorUtility.IsSimulator.

using Coherence;
using UnityEngine;

public class SimualatorClass : MonoBehaviour
{
    public void Awake()
    {
        if (SimulatorUtility.IsSimulator)
        {
            // I'm a simulator!
        }
    }
}

There are two ways you can tell coherence if the game build should behave as a Simulator:

• COHERENCE_SIMULATOR preprocessor define.

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

Connect and ConnectionType

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

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

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

        var monoBridge = FindObjectOfType<CoherenceMonoBridge>();
        monoBridge.Connect(endpoint, ConnectionType.Simulator);
    }
}

COHERENCE_SIMULATOR

#if COHERENCE_SIMULATOR

// simulator-specific code

#endif

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

Command-line argument

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

Server-side simulation

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

Auto-reconnect

The sample UI provided includes auto-reconnect behaviour out of the box for Room- and World-based simulators. The root GameObject has AutoReconnect components attached to it.

Simulators per room can be enabled in the dashboard for the project. The Simulator used is matched according to the Simulator slug in the RuntimeSettings scriptable object file. This is set automatically when you upload a Simulator.

For each new Room, a Simulator will be created with the command line parameters described in the Simulators section. The Simulator is shutdown automatically when the Room is closed.

When using the Simulators tab in the coherence Hub, you can specify a Simulator slug. This is simply a unique identifier for a Simulator. This value is automatically saved in RuntimeSettings when an upload is complete, and Room creation requests will use this value to identify which Simulator should be started alongside your room.

The Simulator slug can be any string value, but we recommend using something descriptive. If the same slug is used between two uploads, the later upload will overwrite the previous Simulator.

A list of uploaded Simulators and their corresponding slugs can be found in the Developer Portal:

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 the 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 a 2D axis for movement and a jump button.

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

Client-Side Set* Methods

• public void SetButtonState(string name, bool value)

• public void SetButtonRangeState(string name, float value)

• public void SetAxisState(string name, Vector2 value)

• public void SetStringState(string name, string value)

Simulator-Side Get* Methods

• public bool GetButtonState(string name)

• public float GetButtonRangeState(string name)

• public Vector2 GetAxisState(string name)

• public string GetStringState(string name)

For example, if the jump button is pressed, this can be passed from Client to Simulator via the "Jump" input. Similarly, horizontal and vertical movement is passed via the "Move" input.

The Simulator can access the state of the input to perform simulations on the object which are then reflected back to the Client, just like any replicated object.

using Coherence.Toolkit;
using UnityEngine;

public class Player : MonoBehaviour
{
    public CoherenceSync coherenceSync;

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

    void Update()
    {
        // This code will run on the client 
        if (coherenceSync.HasInputAuthority)
        {
            SendInputs();
        }
        
        // This code will run on the simulator
        if (coherenceSyncnc.HasStateAuthority)
        {
            ProcessInputs();
        }
    }

    void SendInputs()
    {
        var jump = Input.GetButton("Jump");
        coherenceSync.Input.SetButton("Jump", jump);
        
        var moveX = Input.GetAxis("Horizontal");
        var moveY = Input.GetAxis("Vertical");
        var move = new Vector2(moveX, moveY);
        coherenceSync.Input.SetAxis2D("Move", move);
    }

    void ProcessInputs()
    {
        var jump = coherenceSync.Input.GetButton("Jump");
        /* Apply jumping logic here */
        
        var move = coherenceSync.Input.GetAxis2D("Move");
        /* Apply movement logic here */
    }
}

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)
{
    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.MonoBridge.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 visibility query 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.

void Update()
{
    // This code will run on the client 
    if (coherenceSync.HasInputAuthority)
    {
        SendInputs();
    }

    // This code will run on the simulator and local client
    if (coherenceSync.HasStateAuthority || coherenceSync.HasInputAuthority)
    {
        ProcessInputs();
    }
}

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 CoherenceMonoBridge.ConnectAsHost:

public async Task CreateRoomAndJoinAsHost(string region)
{
    RoomData roomData = await PlayResolver.CreateRoom(region);
    (EndpointData roomEndpoint, bool isEndpointValid) = PlayResolver.GetRoomEndpointData(roomData);

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

    CoherenceMonoBridge monoBridge = GetComponent<CoherenceMonoBridge>();
    monoBridge.onConnected.AddListener(OnConnected);
    monoBridge.ConnectAsHost(roomEndpoint);
}

public void OnConnected(CoherenceMonoBridge monoBridge)
{
    Debug.Log($"Connected! Is Host: {monoBridge.IsSimulatorOrHost}");
}

World Simulators are started and shut down with the World. They can be enabled and assigned in the Worlds section of the Developer Portal.

World simulation servers are started with the command line parameters described in the section.

Overview

coherence Input Queues are backed by a rolling buffer of inputs transmitted between the Clients. This buffer can be used to build a fully deterministic simulation with a client side-prediction, rollback, and input delay. This game networking model is often called the (Good Game Peace Out).

Input delay allows for a smooth, synchronized netplay with almost no negative effect on the user experience. The way it works is input is scheduled to be processed X frames in the future. Consider a fighting game scenario with two players. At frame 10 Player A presses a kick button that is scheduled to be executed at frame 13. This input is immediately sent to Player B. With a decent internet connection, there's a very good chance that Player B will receive that input even before his frame 13. Thanks to this, the simulation is always in sync and can progress steadily.

Prediction is used to run the simulation forward even in the absence of inputs from other players. Consider the scenario from the previous paragraph - what if Player B doesn't receive the input on time? The answer is very simple - we just assume that the input state hasn't changed and progress with the simulation. As it turns out this assumption is valid most of the time.

Rollback is used to correct the simulation when our predictions turn out wrong. The game keeps historical states of the game for past frames. When an input is received for a past simulation frame the system checks whether it matches the input prediction made at that frame. If it does we don't have to do anything (the simulation is correct up to that point). If it doesn't match, however, we need to restore the simulation state to the last known valid state (last frame which was processed with non-predicted inputs). After restoring the state we re-simulate all frames up to the current one, using the fresh inputs.

Determinism

In a deterministic simulation, given the same set of inputs and a state we are guaranteed to receive the same output. In other words, the simulation is always predictable. Deterministic simulation is a key part of the GGPO model, as well as a lockstep model because it lets us run exactly the same simulation on multiple Clients without a need for synchronizing big and complex states.

Implementing a deterministic simulation is a non-trivial task. Even the smallest divergence in simulation can lead to a completely different game outcome. This is usually called a desync. Here's a list of common determinism pitfalls that have to be avoided:

• Using Update to run the simulation (every player might run at a different frame rate)

• Using coroutines, asynchronous code, or system time in a way that affects the simulation (anything time-sensitive is almost guaranteed to be non-deterministic)

• Using Unity physics (it is non-deterministic)

• Using random numbers generator without prior seed synchronization

• Non-symmetrical processing (e.g. processing players by their spawn order which might be different for everyone)

• Relying on numbers across different platforms, compilations or processor types

Quickstart guide

We'll create a simple, deterministic simulation using provided utility components.

Our simulation will synchronize the movement of multiple Clients, using the rollback and prediction in order to cover for the latency.

Player implementation

Start by creating a Player component and a Prefab for it. We'll use the client connection system to make our Player represent a session participant and automatically spawn the selected Prefab for each player that connects to the Server. The Player will also be responsible for handling inputs using the CoherenceInput component.

Our Player code looks as follows:

The GetMovement and SetMovement will be called by our "central" simulation code. Now that we have our Player defined let's prepare a Prefab for it. Create a GameObject and attach the Player component to it, using the CoherenceSync inspector create a Prefab. The inspector view for our Prefab should look as follows:

A couple of things to note:

• A Mov axis has been added to the CoherenceInput which will let us sync the movement input state

• In order for inputs to be processed in a deterministic way, we need to use the fixed simulation frames. Tick the CoherenceInput > Use Fixed Simulation Frames checkbox\

Since our player is the base of the Client connection we must set it as the connection Prefab in the CoherenceMonoBridge and enable the global query:

State implementation

Before we move on to the simulation, we need to define our simulation state which is a key part of the rollback system. The simulation state should contain all the information required to "rewind" the simulation in time. For example, in a fighting game that would be the position of all players, their health, and perhaps a combo gauge level. In a shooting game, this could be player positions, their health, ammo, and map objective progression.

In the example we're building, player position is the only state. We need to store it for every player:

Simulation implementation

Simulation code is where all the logic should happen, including applying inputs and moving our Players:

• SetInputs is called by the system when it's time for our local Player to update its input state using the CoherenceInput

• Simulate is called when it's time to simulate a given frame. It is also called during frame re-simulation after misprediction - don't worry though, the complex part is handled by the CoherenceInputSimulation internals - all you need to do in this method is apply inputs from the CoherenceInput to run the simulation

• Rollback is where we need to set the simulation state back to how it was at a given frame. The state is already provided in the state parameter, we just need to apply it

• CreateState is where we create a snapshot of our simulation so it can be used later in case of rollback

• OnClientJoined and OnClientLeft are optional callbacks. We use them here to start and stop the simulation depending on the number of clients

As a final step, attach the Simulation script to the MonoBridge object on scene and link the MonoBridge back to the Simulation:

That's it! Once you build a client executable you can verify that the simulation works by connecting two Clients to the Replication Server. Move one of the Clients using arrow keys while observing the movement being synced on the other one.

Input in fixed network update

Due to the FixedNetworkUpdate running at different (usually lower) rate than Unity's Update loop, polling inputs using the functions like Input.GetKeyDown is susceptible to a input loss, i.e. keys that were pressed during the Update loop might not show up as pressed in the FixedNetworkUpdate.

To illustrate why this happens consider the following scenario: given that Update is running five times for each network FixedNetworkUpdate, if we polled inputs from the FixedNetworkUpdate there's a chance that an input was fully processed within the five Updates in-between FixedNetworkUpdates, i.e. a key was "down" on the first Update, "pressed" on the second, and "up" on a third one.

To prevent this issue from occurring you can use the FixedUpdateInput class:

The FixedUpdateInput works by sampling inputs at Update and prolonging their lifetime to the network FixedNetworkUpdate so they can be processed correctly there. For our last example that would mean "down" & "pressed" registered in the first FixedNetworkUpdate after the initial five updates, followed by an "up" state in the subsequent FixedNetworkUpdate.

Pause handling

There's a limit to how many frames can be predicted by the Clients. This limit is controlled by the CoherenceInput.InputBufferSize. When Clients try to predict too many frames into the future (more frames than the size of the buffer) the simulation will issue a pause. This pause affects only the local Client. As soon as the Client receives enough inputs to run another frame the simulation will resume.

To get notified about the pause use the OnPauseChange(bool isPaused) method from the CoherenceInputSimulation:

This can be used for example to display a pause screen that informs the player about a bad internet connection.

Debugging

The CoherenceInputSimulation has a built-in debugging utility that collects various information about the input simulation on each frame. This data can prove extremely helpful in finding a simulation desync point.

Setup

Since debugging might induce a non-negligible overhead it is turned off by default. To turn it on, add a COHERENCE_INPUT_DEBUG scripting define:

From that point, all the debugging information will be gathered. The debug data is dumped to a JSON file as soon as the Client disconnects. The file can be located under a root directory of the executable (in case of Unity Editor the project root directory) under the following name: inputDbg_<ClientId>.json, where <ClientId> is the CoherenceClientConnection.ClientId of the local client.

Data handling behavior can be overridden by setting the CoherenceInputDebugger.OnDump delegate, where the string parameter is a JSON dump of the data.

The debugger is available as a property in the simulation base class: CoherenceInputSimulation.Debugger. Most of the debugging data is recorded automatically, however, the user is free to append any arbitrary information to a frame debug data, as long as it is JSON serializable. This is done by using the CoherenceInputDebugger.AddEvent method:

Since the simulation can span an indefinite amount of frames it might be wise to limit the number of debug frames kept by the debugging tool (it's unlimited by default). To do this use the CoherenceInputDebugger.FramesToKeep property. For example, setting it to 1000 will instruct the debugger to keep only the latest 1000 frames worth of debugging information in the memory.

Serialization

Since the debugging tool uses JSON as a serialization format, any data that is part of the debug dump must be JSON-serializable. An example of this is the simulation state. The simulation state from the quickstart example is not JSON serializable by default, due to Unity's Vector3 that doesn't serialize well out of the box. To fix this we need to give JSON serializer a hint:

With the JsonProperty attribute, we can control how a given field/property/class will be serialized. In this case, we've instructed the JSON serializer to use the custom UnityVector3Converter for serializing the vectors.

Comparing debug data

To find a problem in the simulation, we can compare the debug dumps from multiple clients. The easiest way to find a divergence point is to search for a frame where the hash differs for one or more of the clients. From there, one can inspect the inputs and simulation states from previous frames to find the source of the problem.

Here's the debug data dump example for one frame:

Explanation of the fields:

• Frame - frame of this debug data

• AckFrame - the common acknowledged frame, i.e. the lowest frame for which inputs from all clients have been received and are known to be valid (not mispredicted)

• ReceiveFrame - the common received frame, i.e. the lowest frame for which inputs from all clients have been received

• AckedAt - a frame at which this frame has been acknowledged, i.e. set as known to be valid (not mispredicted)

• MispredictionFrame - a frame that is known to be mispredicted, or -1 if there's no misprediction

• Hash - hash of the simulation state. Available only if the simulation state implements the IHashable interface

• Initial state - the original simulation state at this frame, i.e. a one before rollback and resimulation

• Initial inputs - original inputs at this frame, i.e. ones that were used for the first simulation of this frame

• Updated state - the state of the simulation after rollback and resimulation. Available only in case of rollback and resimulation

• Updated inputs - inputs after being corrected (post misprediction). Available only in case of rollback and resimulation

• Input buffer states - dump of the input buffer states for each client. For details on the fields see the InputBuffer code documentation

• Events - all debug events registered in this frame

Configuration

Input buffer

There are two main variables which affect the behaviour of the InputBuffer:

• Initial buffer size - the size of the buffer determines how far into the future the input system is allowed to predict. The bigger the size, the more frames can be predicted without running into a pause. Note that the further we predict, the more unexpected the rollback can be for the player. The InitialBufferSize value can be set directly in code however it must be done before the Awake of the baked component, which might require a script execution order configuration.

• Initial buffer delay - dictates how many frames must pass before applying an input. In other words, it defines how "laggy" the input is. The higher the value, the less likely Clients are going to run into prediction (because a "future" input is sent to other Clients), but the more unresponsive the game might feel. This value can be changed freely at runtime, even during a simulation (it is however not recommended due to inconsistent input feeling).

The other two options are:

• Disconnect on time reset - if set to "true" the input system will automatically issue a disconnect on an attempt to resync time with the Server. This happens when the Client's connection was so unstable that frame-wise it drifted too far away from the Server. In order to recover from that situation, the Client performs an immediate "jump" to what it thinks is the actual server frame. There's no easy way to recover from such a "jump" in the deterministic simulation code, so the advised action is to simply disconnect.

• Use fixed simulation frames - if set to "true" the input system will use the IClient.ClientFixedSimulationFrame frame for simulation - otherwise the IClient.ClientSimulationFrame is used. Setting this to "true" is recommended for a deterministic simulation.

Fixed frame rate

The fixed network update rate is based on the Fixed Timestep configured through the Unity project settings:

To know the exact fixed frame number that is executing at any given moment use the IClient.ClientFixedSimulationFrame or CoherenceInputSimulation.CurrentSimulationFrame property.

Build a Simulator to be uploaded to the cloud

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

Open Coherence Hub and select the Simulators tab.

From here you can build and upload Simulators.

Configuring your Simulator build

You can change your Simulator build options by editing the SimulatorBuildOptions object, or in the coherence Hub Simulators tab.

There are several settings you might want to change.

• Specify the scenes you want to get in the build via the Scenes To Build field.

• For a local build, you can choose to enable/disable the Headless Mode by ticking the checkbox. For a cloud build, Headless Mode is always enabled by default.

Create and upload the build

Press the coherence Hub > Simulators > Build And Upload Headless Linux Client button.

When the build is finished, it will be uploaded to your currently selected organization and project in the Developer Portal.

Connecting your Simulator to a Room or World

You'll see in the developer dashboard when your Simulator is ready to be associated with a Room or World.

Reducing Simulator build size (experimental ⚠️)

You can set the values for the Build Size Optimizations in the drop-down list of the build configuration inspector. It looks like this:

Select the desired optimizations depending on your needs.

coherence allows us to use multiple Simulators to split up a large game world with many entities between them. This is called spatial load balancing.

Overview

Client Connections are CoherenceSyncs that the CoherenceMonoBridge can handle for you and let you uniquely identify users connected, find them by their ID, spawn CoherenceSyncs whenever a new user joins the session, and send commands between those users.

When using Client Connections, CoherenceMonoBridge will spawn a CoherenceSync for each connection (Client or Simulator). Those CoherenceSyncs are subject to a different ruleset than standard CoherenceSyncs:

• They can't be created or destroyed by the Client - they are always driven by CoherenceMonoBridge.

• They are global - they are replicated across Clients regardless of the extent.

Client Connections shine whenever there's a need to communicate something to all the connected players. Usage examples:

• Global chat

• Game state changes: game started, game ended, map changed

• Server announcements

• Server-wide leaderboard

• Server-wide events

Enabling Client Connections

The global nature of Client Connections doesn't fit all game types - for example, it rarely makes sense to keep every Client informed about the presence of all players on the server in an MMORPG. If this is your use case, don't set Client Connections on your CoherenceMonoBridge.

To enable Client Connections, turn Global Query on in your (it should be by default):

Connection Management

Most of the Client Connection functionality is accessible through the CoherenceMonoBridge.ClientConnections object:

Each connection is represented by a plain C# CoherenceClientConnection object. It contains all the important information about a connection - its ClientID, Type, whether it IsMyConnection, and a reference to the GameObject and Coherence Sync associated with it.

ClientConnection Objects

Each Client Connection can have a CoherenceSync automatically being spawned and associated with it. Those objects, like any other objects with CoherenceSync, can be used for syncing properties or sending messages, with a little twist - they are global and thus not limited by the LiveQuery extent. That makes them perfect candidates for operations like:

• Syncing global information - name, stats, tags, etc.

• Sending global messages - chat, server interaction

To enable connection objects:

1. Create a ClientConnection Prefab

2. Link a ClientConnection Prefab to the CoherenceMonoBridge

For the system to know which object to create for every new Client connection, we have to link our Prefab to the CoherenceMonoBridge. Simply drag the prefab to the Client field in the inspector:

From now on every new connection will be assigned an instance of this Prefab, which can be accessed through the CoherenceClientConnection.GameObject property.

Prefab selection

Note that there's a separate field for the Simulator Connection Prefab. It can be used to spawn a completely different object for the Simulator connection that may contain Simulator-specific commands and replicated properties. If the field is left empty, no object will be created for the Simulator connection.

The Prefab selection process can be also controlled from code using the CoherenceMonoBridge.ClientConnections.ProvidePrefab callback:

Client Messages

Don't forget to bind to the new method to define a command:

Client Messages can be sent using the CoherenceClientConnection.SendClientMessage method:

If the ClientID of the message recipient is known we can use the CoherenceMonoBridge.ClientConnections directly to send a client message: