Overview

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

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

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

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

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

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

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

Network engine

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

Authority models

The network engine supports multiple authority models:

• Client authority

• Server authority

• Server authority with client prediction

• Authority handover (request, steal)

• Distributed authority (multiple simulators with seamless transition)

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

Persistence

coherence supports persistence out of the box.

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

Engine support

Rooms

Rooms are best for session-based gameplay where the match between players takes place in a short-lived environment.

Use case

A good example is a first person shooter multiplayer match. The match takes place between two teams in a single game session, and players enter through a lobby and matchmaking. When the match is concluded, the multiplayer environment the match took place in is closed and players return to a lobby.

This is one example of how Rooms can be used, but it is by no means the only use case. The important distinction between Rooms and Worlds (see below) is that Rooms are relatively short-lived and are meant to be created and closed by the Game Client through the coherence SDK.

See Rooms API.

Worlds

Worlds, as opposed to Rooms, are long-lived and permanent multiplayer environments provided by coherence. Using the Developer Portal, your project will easily define and manage your World configurations.

See Manage Worlds.

Use case

A good example of a World is a permanent environment for an Massively Multiplayer Game (MMO). Regardless of the number of players connected, the environment is always available, and players can connect and disconnect at will.

Entities can be permanently saved in the World so that even if there are no active connections, they still persist when players do connect.

See Worlds API.

Rooms and Worlds work together

Your project does not have to choose one-or-the-other. A project in coherence can contain both World and Rooms.

Use case

A good example of this scenario is again, our MMO. Although players connect to a permanent and persistent World, they may enter a dungeon instance with other players. These dungeon instances can be Rooms.

The primary difference in the configuration and usage of Room and Worlds is that Worlds are managed in the Developer Portal, whereas Rooms are created and managed through the SDK.

coherence allows you to upload and share the builds of your games to your team, friends or adoring fans via an easy access play link.

Right now we support desktop (PC, Mac, Linux) and also WebGL, where you can host and instantly play your multiplayer game and share it around the world.

Build the game

Build your game to a local folder on your desktop as you would normally.

In the coherence menu in Unity select Share > Build Upload.

Upload to coherence

In this window you can select which platform the build is for. You also need to browse to the local path folder.

Click Upload or Begin Upload and coherence will confirm that it's okay to compress and upload the build to the Portal dashboard.

Share your build

Now that build has been updated (signified by the green tick), you can share it by enabling and sharing the public URL. Anyone with this link can access the build.

WebGL

If you uploaded a WebGL build, the public link allows for instant play.

Game engine support

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

Unity requirements

• Unity 2020.3.36f1 or later.

• A Windows, Linux or macOS system.

Setup video tutorial

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

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

1. Add MonoBridge

coherence > Scene Setup > Create MonoBridge

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

2. Add LiveQuery - hierarchy

coherence > Scene Setup > Create LiveQuery

3. Add the sample UI

coherence > Scene Setup > Add Sample UI

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

Using the coherence Hub window

Using the coherence Hub window gives you an overview of everything related to networking in your project. The Overview tab will show you the current status and which actions you need to perform for everything to work.

coherence > coherence Hub

Automatic issue solving

If we have identified any issues in your project, the Overview tab provides a one-click solution to solving it. In the example below, simply click the error icon (that's the red icon with an exclamation mark in it) and coherence will solve the issue for you.

Current features

General

• Custom UDP transport layer using bit streams with reliability

• WebRTC support for WebGL builds

• Smooth state replication

• Server-side, Client-side, distributed authority

• Connected entity support

• Fast authority transfer

• Remote messaging (RPC)

• Persistence

• Verified support for Windows, macOS, Linux, Android, iOS and WebGL

• Support for Rooms and Worlds

SDK

• Unity SDK with an intuitive no-code layer

• Per-field adjustable interpolation and extrapolation

• Input queues

• Easy deployment into the cloud

• SDK source included, no 3rd-party libraries

• Multi-room Simulators

• Multiple code generation strategies (Assets/Baking, automated with C# Source Generators)

• Multiple object spawning strategies (Resources, Prefab Mapper, Addressables)

Optimization and performance

• Per-field compression and quantization

• Per-field sampling frequency adjustable at runtime

• Unlimited per-field levels of detail

• Areas of interest

• Accurate SimulationFrame tracking

Online

• Developer portal with server and service configurator

• Automatic server scaling

• Multiple regions (US East, EU Central)

• Player accounts

• Key-value store

• Matchmaking

Coming soon

General

• Float64 support

• Permissions and roles system for clients and simulators

• World origin shifting

SDK

• Input queue UX improvements

• More logging and diagnostics tools

• Built-in network condition simulation

Online

• Additional server regions

• Support for multiple Simulators and Replicators in a single project

• Dashboard with usage statistics

• Paid plans with more CCU and credits

Mid-term roadmap

• Network profiler

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

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

• MTU detection

• Packet replay

• Ability to deploy multiple Simulation Servers per environment

• Player analytics

• Developer portal graphs and analytics

• Simulator authentication

• Bare-metal and cloud support

• Misprediction detection support

• SDK library that can be used in C++ and other languages

• More starter/sample projects and helper scripts

• Ability to embed WebGL games in web portals

• Global KV-Store

• Complex data types/entities in the KV store

• More GGPO support for specific game genres

• Misprediction detection support

Roadmap

• Unreal Engine SDK

• JavaScript SDK

• TCP fallback support

• Advanced matchmaking

• Multiple Replication Servers per game world

• Customer-specific serialization

• User-space load-balancing (SDK framework)

• Game world map with admin interface

• Advanced anti-cheat functionality

• Advanced transaction logs (audit trail)

• Schema versioning (hot updates)

• Console-specific updates

• Player analytics

Basic terms

Replication Server ("Replicator")

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

Game Client

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

Simulation Server ("Simulator")

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

Schema

A text file defining the structure of the world from the network's point of view. The schema is shared between the Replicators, Simulators and Game Clients. The world is generally divided in components and archetypes.

**** Code generation

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

State replication

The process of making sure the state of the world is eventually the same on the Replicator, Simulators and Game Clients, depending on their areas of interest.

State Replication

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

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

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

Fast authority transfer and remote commands allow different authority models, including Client authority, Server authority, distributed authority and combinations like Client prediction with input queues.

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

Installation - video tutorial

Unity Package Manager

1. Add a scoped registry

First, open Edit > Project Settings.

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

• Name: coherence

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

• Scope(s): io.coherence.sdk

• Enable Preview / Pre-release Packages: checked

• Show Dependencies: checked

Click Save/Apply.

2. Find and install the coherence package

Now open the Window > Package Manager.

Click Packages and My Registries.

Under coherence, click Install.

Alternative method: edit manifest.json manually

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

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

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

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

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

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

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

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

Get started

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

Update an existing project

If you are an existing user and looking to update, check out the latest . And maybe the as well!

Tutorial project

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

Existing or new Unity project

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

Join the community

Join our community Discord for community chatter and support.

• Join our official Developer

• Contact us at

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

1. Add CoherenceSync to your GameObject

For a Unity GameObject to be networked through coherence, it needs to have a CoherenceSync component attached. Currently, only Prefabs are supported. If your GameObject is not a Prefab, CoherenceSync can assist you.

First, create a new GameObject. In this example, we're going to create a Cube.

Next, let's add the CoherenceSync component to this Cube.

The CoherenceSync inspector now tells us that we need to make a Prefab out of this GameObject for it to work. We get to choose where to create it.

In this example, I'll be creating it on Assets / Resources by clicking Convert to Prefab in Resources.

1.1 (Optional) Using Prefab Variants

One way to configure your Prefab, instead of just adding CoherenceSync into it, is to fork a Prefab variant and add the component there.

In our Cube example, instead of adding CoherenceSync to Cube, you can create a Cube (Networked) and add CoherenceSync to it:

This way, you can retain the original Prefab untouched.

Another way to use Prefab variants to our advantage is to have a base Prefab using CoherenceSync, and create Prefab variants off that one with customizations. For example, Enemy (base Prefab) and Enemy 1, Enemy 2, Enemy 3... (variant Prefabs, using different models, animations, materials, etc.). In this setup, all of the enemies will share the networking settings stored in CoherenceSync, so you don't have to manually update every one of them.

2. Configure CoherenceSync

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

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

3. (Optional) Prefabs outside of the Resources folders

In order for coherence to know which Prefab to instantiate through the network, they must be located in Resources folders or added to the Prefab Mapper. The Prefab Mapper is simply a ScriptableObject that holds Prefabs we want to sync.

When a CoherenceSync Prefab outside the Resources folder is not present in the Prefab Mapper, the Add to Prefab Mapper button appears.

3.1. Addressables

If you are using the Addressables Package (1.15.0 or newer), the Prefab Mapper also supports that. The Prefab Mapper has a list for direct references and a list for addressables referenced using AddressableAssets.AssetReference. The directly referenced assets will be loaded at game start, while the addressables will be asynchronously loaded when needed.

Remember, in order for coherence to load assets as addressables, you need to follow Unity's default workflow for using Addressables which entails building the Addressables Group Bundles whenever the Prefab changes.

3.2. Prefab Mapper utilities

When adding a new Prefab to the mapper, it will automatically make sure to add it to the correct list (addressable or not), but if the Prefab already exists in the mapper and you have changed how it is loaded, simply press the Validate Mapping Lists button.

If you have a number of valid Prefabs that have not yet been added to the Prefab Mapper you can press the Add all CoherenceSync prefabs button.

If you have empty entries in the Prefab Mapper you can remove them by pressing Remove empty entries. This is optional.

4. Select variables to replicate

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

Under Configure, click Variables.

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

Close the Configuration dialog.

5. Add an input script

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

Click on Assets > Create > C# Script.

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

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

6. Disable input on replicated object

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

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

Under Configure, click Components.

Here you will see a list of Component Actions that you can apply to non-authoritative GameObjects that have been spawned by the network.

Selecting Disable for your Move script will make sure the Component is disabled for network instances of your Prefab.

7. Implementing your own Component Actions

By extending the ComponentAction abstract class, you can implement your own Component Actions.

Your custom Component Action must implement the following methods:

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

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

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

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

8. Additional CoherenceSync settings

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

There are also some Events that are triggered at different times.

• On Before Networked Instantiation (before the GameObject is instantiated)

• On Networked Instantiation (when the GameObject is instantiated)

• On Networked Destruction (when the GameObject is destroyed)

• On Authority Gained (when authority over the GameObject is transferred to the local client)

• On Authority Lost (when authority over the GameObject is transferred to another client)

• On After Authority Transfer Rejected (when GameObject's Authority transfer was requested and denied).

• On Input Simulator Connected (when client with simulator is ready for Server-side with Client Input)

• On Input Owner Assigned (when InputOwner was changed is ready)

Using the Coherence Hub

If you prefer, you can let the Coherence Hub guide you through your Prefab setup process. Simply select a Prefab, open the Synced Object tab in Coherence Hub and follow the instructions.

Extras

9. Constraints

There are some constraints when setting up a Prefab with CoherenceSync, hereafter referred to as Sync Prefab.

1. A Sync Prefab has one, and only one CoherenceSync component in its hierarchy

2. The CoherenceSync component must be at the Sync Prefab root

3. A Sync Prefab cannot contain instances of other Sync Prefabs

4. A hierarchy in a scene can contain multiple Sync Prefabs. However, such a hierarchy cannot be saved as a Sync Prefab as that would break rule 1-3.

9.1. Examples of valid setup

9.2. Examples of disallowed setup

Cloud deployment - video tutorial

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

Sign up or log in

Create an account or log into an existing one.

Login through Unity

Open Unity

Open Unity and open the Coherence Hub window. Then open the Portal tab.

Login to Portal

After pressing Login you will be taken to the login page. Simply login as usual, and return to Unity.

Select Organization and Project

You are now logged into the Portal through Unity. Select the correct Organization and Project, and you are ready to start creating.

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.

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

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

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 IntelliSense. 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 to 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 Use Baked Script in the CoherenceSync inspector.

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.

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

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

Running a Replication Server locally

You can run a local Replication Server from the coherence menu:

This will open a new terminal window with the Replication Server and a World created in it.

Building through Coherence Hub

As with most features found in the menu, you can find local replication server functionality in the Coherence Hub as well. Open the Servers tab and run a Room or a World Replication Server.

Build and Connect

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

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

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

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

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

Connect across the local network

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

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

Check out the highlighted features for 0.9 release in our .

v0.9.2

This is a maintenance patch that includes the following items:

Fixes

• Spawning of session-based unique Entities that had a UUID in the Prefab and in an instance saved in the Scene.

• OnInputSimulatorConnected is now raised for Simulator or Client-As-Host only if they have both input and state authority.

• Selecting Prefab variants no longer updates the internal Archetype name (hence, no unintended schema changes).

• Configure window: Animator parameters are no longer added if they already exist.

• coherence now warns you when there are internal inconsistencies within the CoherenceSync Archetype data.

• coherence Hub: disabled interactions with coherence Cloud when logged out.

Changes

• The Welcome window is presented when the package is upgraded.

v0.9.1

This is a small patch that includes the following items:

New features and functionality

• Exposed OnConnectionError event in CoherenceMonoBridge.

Fixes

• Automatic passing of room secret when using PlayResolver.GetRoomEndpointData.

v0.9

New features and functionality

• coherence Hub window: a singular tool combining all the functionality you need to work with coherence.

• Per-binding sampling rate configurable from Optimize window.

• Additional delay parameters added to InterpolationSettings.

• Replication Server can now send the Client commands to change the connection's send frequency of packets.

• New floating point compression methods.

• Quaternion and Color compression control.

• New CoherenceMonoBridge.OnLiveQuerySynced event for notifying when the initial query finishes syncing.

• New CoherenceMonoBridge.ClientConnections.OnSynced event for notifying when connections finish syncing.

• Threaded keep-alive packets to keep connection alive even when the main thread is stalled.

• Allow manual sending of changes on a CoherenceSync object.

• SimulatorBuildPipeline public API: a static API to build Simulators, with headless support out of the box.

• Unity 2021: Headless Unity Players are now built with the Dedicated Server modules.

• Added option to copy the run local simulator build terminal command to the clipboard.

• Queries can be added to any synced GameObject.

• Queries are applied to the input authority. This enables server-authoritative games to restrict Client visibility by placing a query on the player Prefab.

• Client can connect as a Simulator.

• Client can connect as a host for server-simulated inputs (Experimental).

• Local Replication Server can now set both send and receive frequencies.

• Added options in settings to auto-bake and upload schemas.

• Added support for Addressables.

• Log to file in Library/coherence.

• Icons showing input authority in editor hierarchy.

Changes

• Entity changes are now based on the simulation frames from their origin.

• ServerUpdateFrequency is now SendFrequency.

• By default, new fields marked for syncing do not use compression.

• Commands do not use any compression for simple types.

• CoherenceMonoBridge.ClientConnections.OnDestroyed is now called for the local connection.

• Baking timeout increased to 2 minutes.

• Baking is now cancellable.

• CoherenceSync.HasPhysics is now obsolete.

• CoherenceSync's Rigidbody position and rotation is now updated only in the FixedUpdate. In all other cases the Transform.position/rotation will be updated directly.

• Predicted toggle is available for Prefabs with no CoherenceInput, but prompts a warning in this case.

• Exposed IsInterpolationNone on InterpolationSettings so runtime can check if a binding will interpolate.

• The auto-fill functionality from the Endpoint data to run a local Simulator went from being automatic to working manually through a button in the UI.

• CoherenceInput fields now only transmit changed field state instead of entire component to save bandwidth.

• Authority requests and transfers use ClientID instead of ConnectionID.

• Requesting authority over orphaned entities now works only via CoherenceSync.Adopt() call.

• Improved layout of settings.

• Button in Prefab Mapper now automatically places Prefabs in the correct list (Addressable/non-addressable)

Fixes

• Baking timing out with high number of synced components.

• CoherenceLiveQuery and CoherenceTagQuery handling on disable and after disconnect.

• Sending commands from the onConnected callback.

• OnValueSynced callbacks working for all value types.

• Byte array sync bugfix.

• Sampling and send rates now account for time drift across update calls.

• Error when trying to dispose non-activated InterpolationSettings.

• Unsigned long handling in reflection mode.

• Creating connection objects with Global Query turned off.

• "WebSocket: already connected" error when changing scenes.

• Bug where reconnecting would cause incoming commands to duplicate.

• OnEntityUpdated exception caused by samples with frames out-of-order.

• WebGL connection timeout issues.

• Double query creation in some circumstances.

• AutoSimulatorConnection fixed and made the default way to reconnect Simulators. Two obsolete scripts removed.

• OnValueSynced event will raise after smaller deltas.

• If baked script is missing, fallback to generic pool will map bindings.

• OnValueSynced on components shared by multiple Prefabs.

• Deleting and recreating unique Entities in the same frame no longer results in broken state.

• Pending Entity changes that are not sent in a given packet have their priority increased so that they don't starve out.

• Prevent sending component remove updates until the Client knows the Replication Server acknowledged the original create.

• Checking for a received packet before deciding we haven't received one and disconnecting. Fixes issue when the main thread stalls before we read packets, causing a timeout disconnect.

• Authority change handling for unique Entities.

• CoherenceSync spawn issues in bad connection conditions.

• Include the instantiating bridge as the fist resolver when resolving bridges in a CoherenceSync object.

• Building Simulators: fixed issue where you had to click the Build button twice, in order for the build to trigger.

• CustomBinding now respects setToLastSamples parameter during Reset.

• InputAuthority is displayed correctly in the CoherenceSync inspector.

• SmoothTime is now 0 when using InterpolationSettings.None.

• Default Interpolator now implements latest sample instead of nearest neighbor to lower latency.

• Interpolation Type set to None now doesn't throw exceptions.

• Prefabs set to load using Resources will no longer be overridden to use PrefabMapper.

• Prefab instance name no longer breaks LOD's.

Deprecations

• 'AuthorityMode' has been deprecated in favour of 'AuthorityType'.

• 'IClient.OnAuthorityTransferRequest' has been deprecated in favour of 'IClient.OnAuthorityRequested'.

• 'IClient.OnAuthorityTransferRejected' has been deprecated in favour of 'IClient.OnAuthorityRequestRejected'.

• 'IClient.OnAuthorityChanged' has been deprecated in favour of 'IClient.OnAuthorityChange'.

• 'IClient.EntityIsOwned' has been deprecated in favour of 'IClient.HasAuthorityOverEntity'.

• 'IClient.SendAuthorityTransferRequest' has been deprecated in favour of 'IClient.SendAuthorityRequest'.

• 'IClient.AuthorizeAuthorityTransfer' has been deprecated in favour of 'IClient.SendAuthorityTransfer'.

• 'SpawnInfo.isLocal' has been deprecated in favour of 'SpawnInfo.authorityType'.

• 'CoherenceInput.SetInputOwner' has been deprecated in favour of 'CoherenceSync.TransferAuthority'.

• 'CoherenceSync.isSimulated' has been deprecated in favour of 'CoherenceSync.HasStateAuthority'.

• 'CoherenceSync.OnAuthorityRequestedByConnection' has been deprecated in favour of 'CoherenceSync.OnAuthorityRequested'.

• 'CoherenceSync.OnAuthorityGained' has been deprecated in favour of 'CoherenceSync.OnStateAuthorityGained'.

• 'CoherenceSync.OnAuthorityLost' has been deprecated in favour of 'CoherenceSync.OnStateAuthorityLost'.

• 'CoherenceSync.OnAuthorityTransferRejected' has been deprecated in favour of 'CoherenceSync.OnAuthorityRequestRejected'.

• 'CoherenceSync.OnInputOwnerAssigned' has been deprecated in favour of 'CoherenceSync.OnInputAuthorityGained' and 'CoherenceSync.OnInputAuthorityGained'.

• 'CoherenceSync.RequestAuthority' has been deprecated in favour of 'CoherenceSync.RequestAuthority(AuthorityType)'.

• 'MonoBridgeStore.GetBridge' has been deprecated in favour of 'MonoBridgeStore.TryGetBridge'.

Removals

• Manual and auto-latency removed. Latency is now fixed to the binding's sample rate.

• "World size" setting.

• Manual disabling of updates to rotation and position of the CoherenceSync object.

• Removed CoherenceMonoBridge.OnConnectionCreated that was deprecated in v0.8.

• Removed CoherenceMonoBridge.OnConnectionDestroyed that was deprecated in v0.8.

• Removed CoherenceMonoBridge.ClientConnectionCount that was deprecated in v0.8.

• Removed CoherenceMonoBridge.GetMyConnection that was deprecated in v0.8.

• Removed CoherenceMonoBridge.GetClientConnection that was deprecated in v0.8.

• Removed CoherenceMonoBridge.GetAllClientConnections that was deprecated in v0.8.

• Removed CoherenceMonoBridge.GetOtherConnections that was deprecated in v0.8.

• Removed CoherenceMonoBridge.SendClientMessage that was deprecated in v0.8.

• Removed dependency to the experimental package Platforms. As a result, your existing BuildConfiguration assets will have its defining script missing. To recreate the Simulator build configuration with the new pipeline, you can do it from the Simulators Module in coherence Hub.

• Removed dependencies to the following packages: Collections, Properties, Test Framework, Jobs, Burst.

• No longer show byte arrays, bools or strings as interpolable types in the Configure window.

Known Issues

Older Versions of Unity Editor not Building WebGL on Latest Mac OS and Ubuntu 22

Unity does not build WebGL because Python 2 is missing on latest Mac OS and Ubuntu 22. This is fixed for Unity Editor version 2020.3.40f1 and onwards.

Persistence

There's a known bug preventing the removal of session-based objects from the scene after the Client disconnects. We're working on it.

Level of Detail

• LOD levels are not properly updated when queries move or resize.

CoherenceMonoBridge: ClientCore

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 transferred 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 input queues.

Remote Communication

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

Can't build on platforms that Unity Hub reports as installed

On macOS, some versions of the Unity Hub don't install platform modules properly. This issue is fixed on version Unity Hub version 3.3.0. If you want to use a prior version, install one module at a time.

BuildConfiguration assets missing defining script

SDK 0.9 release removed dependency to the experimental package Platforms. As a result, your existing BuildConfiguration assets will have its defining script missing. To recreate the Simulator build configuration with the new pipeline, you can do it from the Simulators Module in coherence Hub.

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.

It is often useful to know when a synced property 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 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.

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 GGPO (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 floating point 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:

using Coherence.Toolkit;
using UnityEngine;

[RequireComponent(typeof(CoherenceSync))]
[RequireComponent(typeof(CoherenceInput))]
public class Player : MonoBehaviour
{
    // Movement speed in units/sec
    public float Speed = 5f;
    
    private CoherenceInput input;

    private void Awake()
    {
        input = GetComponent<CoherenceInput>();
    }

    // Retrieves the "movement" input state for a given frame
    public Vector2 GetMovement(long frame)
    {
        return input.GetAxisState("Mov", frame);
    }

    // Sets the "movement" state for the current frame
    public void SetMovement()
    {
        Vector2 movement = new Vector2(Input.GetAxis("Horizontal"), Input.GetAxis("Vertical")).normalized;
        input.SetAxisState("Mov", movement);
    }
}

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

• Unlike in the Server authoritative setup our simulation uses client-to-client communication, meaning each Client is responsible for its Entity and sending inputs to other Clients. To ensure such behavior set the CoherenceSync > Simulation and Interpolation > Simulation Type to Client Side
• In the deterministic simulation, it is our code that is responsible for producing deterministic output on all Clients. This means that the automatic transform position syncing is no longer desirable. To turn it off, toggle the Predicted button in the CoherenceSync Bindings window (see the chapter on client-side prediction in Server authoritative setup).
• 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
• Make sure to use the baked mode (CoherenceInput > Use Baked Script) - inputs do not work in the reflection mode

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:

using UnityEngine;t

public struct SimulationState
{
    public Vector3[] PlayerPositions;
}

Simulation implementation

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

using Coherence.Toolkit;
using UnityEngine;

public class Simulation : CoherenceInputSimulation<SimulationState>
{
    protected override void SetInputs(CoherenceClientConnection client)
    {
        var player = client.GameObject.GetComponent<Player>();
        player.SetMovement();
    }

    protected override void Simulate(long simulationFrame)
    {
        foreach (CoherenceClientConnection client in AllClients)
        {
            var player = client.GameObject.GetComponent<Player>();
            var movement = (Vector3)player.GetMovement(simulationFrame);
            player.transform.position += movement * player.Speed * FixedTimeStep;
        }
    }

    protected override void Rollback(long toFrame, SimulationState state)
    {
        for (var i = 0; i < AllClients.Count; i++)
        {
            Transform playerTransform = AllClients[i].GameObject.transform;
            playerTransform.position = state.PlayerPositions[i];
        }
    }

    protected override SimulationState CreateState()
    {
        var simulationState = new SimulationState { PlayerPositions = new Vector3[AllClients.Count] };
        for (var i = 0; i < AllClients.Count; i++)
        {
            Transform playerTransform = AllClients[i].GameObject.transform;
            simulationState.PlayerPositions[i] = playerTransform.position;
        }

        return simulationState;
    }

    protected override void OnClientJoined(CoherenceClientConnection client)
    {
        SimulationEnabled = AllClients.Count >= 2;
        if (SimulationEnabled)
        {
            // Lets us rejoin the same simulation without restarting the app.
            StateStore.Clear();
        }
    }

    protected override void OnClientLeft(CoherenceClientConnection client)
    {
        SimulationEnabled = AllClients.Count >= 2;
    }
}

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

using Coherence.Toolkit;
using UnityEngine;

[RequireComponent(typeof(CoherenceSync))]
[RequireComponent(typeof(CoherenceInput))]
public class Player: MonoBehaviour
{
    private FixedUpdateInput fixedUpdateInput;
    private CoherenceInput input;

    private void Awake()
    {
        var coherenceSync = GetComponent<CoherenceSync>();
        fixedUpdateInput = coherenceSync.MonoBridge.FixedUpdateInput;
        input = coherenceSync.Input;
    }

    // Retrieves the "jump" input state for a given frame
    public bool GetJump(long frame)
    {
        return input.GetButtonState("Jump", frame);
    }

    // Sets the "jump" state for the current frame
    public void SetJump()
    {
        bool hasJumped = fixedUpdateInput.GetKey(KeyCode.Space);
        input.SetButtonState("Jump", hasJumped);
    }
}

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:

using Coherence.Toolkit;

public class Simulation : CoherenceInputSimulation<SimulationState>
{
    // ... stubbed example simulation implementation ...
    protected override void SetInputs(CoherenceClientConnection client) { /* ... */ }
    protected override void Simulate(long simulationFrame) { /* ... */ }
    protected override void Rollback(long toFrame, SimulationState state) { /* ... */ }
    protected override SimulationState CreateState() { /* ... */ return default; }

    protected override void OnPauseChange(bool isPaused)
    {
        PauseScreen.SetActive(isPaused);
    }
}

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:

using Coherence.Toolkit;

public class Simulation : CoherenceInputSimulation<SimulationState>
{
    // ... stubbed example simulation implementation ...
    protected override void Simulate(long simulationFrame) { /* ... */ }
    protected override void Rollback(long toFrame, SimulationState state) { /* ... */ }
    protected override SimulationState CreateState() { /* ... */ return default; }

    protected override void SetInputs(CoherenceClientConnection client)
    {
        Debugger.AddEvent("myCustomEvent", new
        {
            Data = "my custom data",
            UnityFrameCount = Time.frameCount
        });
        // ... movement code ...
    }
}

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:

using Coherence.Toolkit;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;
using UnityEngine;

public struct SimulationState : IHashable
{
    [JsonProperty(ItemConverterType = typeof(UnityVector3Converter))]
    public Vector3[] PlayerPositions { get; set; }

    public Hash128 ComputeHash() { return Hash128.Compute(PlayerPositions); }
}

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:

"32625635555": {
    "Frame": 32625635555,
    "AckFrame": 32625635556,
    "ReceiveFrame": 32625635556,
    "AckedAt": 32625635555,
    "MispredictionFrame": -1,
    "Hash": "3fa00ad32cee971e43ee4a3206dc79f0",
    "Time": "15:48:36.977",
    "InitialState": {
      "PlayerPositions": [
        "0.2494998,3.992,0",
        "0.2494998,-2.086163E-07,0",
        "-2.086163E-07,0.7484999,0",
        "0.4989998,3.992,0"
      ]
    },
    "InitialInputs": {
      "153470363": "Mov:float2(-0.998f, 0f)",
      "322232370": "Mov: float2(0.998f, 0f)",
    },
    "InputBufferStates": {
      "153470363": {
        "LastFrame": 32625635557,
        "LastSentFrame": 32625635557,
        "LastReceivedFrame": -1,
        "LastAcknowledgedFrame": -1,
        "MispredictionFrame": null,
        "QueueCount": 0,
        "ShouldPause": false
      },
      "322232370": {
        "LastFrame": 32625635556,
        "LastSentFrame": -1,
        "LastReceivedFrame": 32625635556,
        "LastAcknowledgedFrame": 32625635556,
        "MispredictionFrame": null,
        "QueueCount": 0,
        "ShouldPause": false
      }
    },
    "Events": [
      {
        "Event": "InputSent",
        "Time": "15:48:36.977",
        "Data": {
          "ClientId": 153470363,
          "SentFrame": 32625635558,
          "Input": "Mov:float2(0f, -0.998f)"
        }
      },
      {
        "Event": "InputReceived",
        "Time": "15:48:36.978",
        "Data": {
          "ClientId": 322232370,
          "RecvFrame": 32625635557,
          "Input": "Mov: float2(0.998f, 0f)"
        }
      }
    ]
  },

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:

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

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

Overview

Authority over state changes to an Entity is transferrable, so it is possible to move the authority over the 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.

• Not transferable. Authority cannot be transferred.

When using Request, an optional callback OnAuthorityRequestedByConnection 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>();
coherenceSync.RequestAuthority(AuthorityType.Full);

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

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

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

These events are also exposed to the Unity inspector in the Events on authority transfer section of the CoherenceSync behaviour.

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

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

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.

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

Client fixed simulation frame

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

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

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

Now we can finally deploy our schema and Replication Server into the cloud.

Upload schemas

In the coherence Hub window, select the coherence Cloud tab, and click on Upload to coherence Cloud in the Schemas section.

The status in the Schemas section should now be In Sync.

Your project schema is now deployed with the correct version of the Replication Server already running in the cloud. You will be able to see this in your cloud dashboard status.

Run project

The Connect Dialog uses the runtime key to fetch all the regions available for your project. This depends on the project configuration (e.g. the regions that you have selected for your project in the Portal).

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

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

Overview

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

Design phase

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

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

The button on the right of the method lets you choose the routing mode. Commands with aSend to Authority Only mode can be sent only to the authority of the target Entity, while ones with the Send to All Instances can be broadcasted to all clients that have a copy of this Entity. 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 type argument (within the <and>) must be the type of the receiving MonoBehaviour. This ensures that the correct method gets called if the receiving GameObject has components that implement methods that share the same name.

• The first argument is the name of the method on the MonoBehaviour 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.

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

Receiving a command

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

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

Sending a command to multiple Entities

Sometimes you want to inform a bunch of different Entities about a change. For example, 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 network Entity under the authority of this Client. To make it only affect Entities 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.

Supported types in commands

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.

Overview

The Client connection system lets you uniquely identify users connected to the same session, find any user by their ID, spawn objects whenever a new user joins the session, and send messages between those users.

To achieve this a special connection entity is automatically created by the Replication Server for each connected Client, including a Simulator. Those Entities are subject to a different rule set than standard Entities. Connection entities:

• Can't be created or destroyed by the Client - they are always Replication Server-driven

• Are global - they are replicated across Clients regardless of the in-simulation distance or LiveQuery 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 connection 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 (think World Of Warcraft). If this is your use case, make sure Client connections are turned off by default.

To enable Client connections, check that Global Query in the MonoBridge is turned on (it should be by default):

Connection management

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

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

public class ExampleGameManager : MonoBehaviour
{
    public CoherenceMonoBridge MonoBridge;

    void Start()
    {
        // Raised whenever a new connection is made (including the local one).
        MonoBridge.ClientConnections.OnCreated += connection =>
        {
            Debug.Log($"Connection #{connection.ClientId} " +
                      $"of type {connection.Type} created.");
        };

        // Raised whenever a connection is destroyed.
        MonoBridge.ClientConnections.OnDestroyed += connection =>
        {
            Debug.Log($"Connection #{connection.ClientId} " +
                      $"of type {connection.Type} destroyed.");
        };

        // Raised when all initial connections have been synced.
        MonoBridge.ClientConnections.OnSynced += connectionManager =>
        {
            Debug.Log($"ClientConnections are now ready to be used.");
        };
    }
    
    void Update()
    {
        // IMPORTANT: All of the connection retrieving calls may return null 
        // if the connection system was not turned on, not initialized yet,
        // or simply if the connection was not found.
        
        // Specifies how many clients are in this session (room or world).
        int clientCount = MonoBridge.ClientConnections.ClientConnectionCount;
        
        // Returns connection objects for all connections in this session.
        IEnumerable<CoherenceClientConnection> allConnections
            = MonoBridge.ClientConnections.GetAll();

        // Returns all connections except for the local one.
        IEnumerable<CoherenceClientConnection> otherConnections
            = MonoBridge.ClientConnections.GetOther();

        // Returns connection object of the local user.
        CoherenceClientConnection myConnection
            = MonoBridge.ClientConnections.GetMine();

        // Returns connection object of the simulator (if one is connected).
        CoherenceClientConnection simulatorConnection
            = MonoBridge.ClientConnections.GetSimulator();

        // Retrieves a connection by its ClientID.
        CoherenceClientConnection selectedConnection
            = MonoBridge.ClientConnections.Get(myConnection.ClientId);

        // Retrieves a connection by its EntityID (warning: requires
        // connection prefab with a CoherenceSync attached).
        if (myConnection.Sync != null)
        {
            selectedConnection
                = MonoBridge.ClientConnections.Get(myConnection.Sync.EntityID);
        }

        // Specifies if this is a client or a simulator connection.
        ConnectionType connectionType = selectedConnection.Type;

        // Specifies if this is a local connection (belonging to the
        // local user).
        bool isMine = selectedConnection.IsMyConnection;

        // Returns a GameObject associated with this connection.
        // Applicable only if connection prefabs are used.
        GameObject connectionGameObject = selectedConnection.GameObject;
    }
}

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.

Connection objects

Each Client connection can have a GameObject with 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 client connection prefab

This step is described in detail in the Prefab setup section. In short, a Prefab with a CoherenceSync and a custom component (PlayerConnection in this example) must be created and placed in a Resources folder:

2. Link a connection Prefab to the MonoBridge

For the system to know which object to create for every new Client connection, we have to link our Prefab to the MonoBridge. Simply drag the prefab to the Client field in the MonoBridge 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:

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

public class ExampleGameManager : MonoBehaviour
{
    public CoherenceMonoBridge MonoBridge;
    public CoherenceSync CustomConnectionPrefab;

    void Start()
    {
        MonoBridge = FindObjectOfType<CoherenceMonoBridge>();
        MonoBridge.ClientConnections.ProvidePrefab += (clientId, connectionType) =>
        {
            return CustomConnectionPrefab;
        };
    }
}

Client messages

Client messages are commands sent between the Client connection objects. Implementing Client messages is as simple as adding a new method to the component used by our connection Prefab and binding it in the configuration:

public class PlayerConnection : MonoBehaviour
{
    // My chat command
    public void OnChatMessage(string message)
    {
        Debug.Log($"Received chat message: {message}");
    }
}

Don't forget to bind the new command:

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

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

public class PlayerConnection : MonoBehaviour
{
    void Start()
    {
        var monoBridge = FindObjectOfType<CoherenceMonoBridge>();
        CoherenceClientConnection myConnection = monoBridge.ClientConnections.GetMine();

        myConnection.SendClientMessage<PlayerConnection>(nameof(OnChatMessage),
            MessageTarget.Other, "Hello!");
    }

    // My chat command
    public void OnChatMessage(string message)
    {
        Debug.Log($"Received chat message: {message}");
    }
}