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 and key-value stores.

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") - experimental

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

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

• 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

Baking fails under Ubuntu 22.04

Ubuntu 22.04 suffers from a GLIBC version mismatch, resulting in coherence baking failure. The current solution is to downgrade by one version of Ubuntu.

Sample UI behaves/looks odd after upgrading

Revert all your Prefab Instance Overrides

I can't see other players' rooms

Check that all your clients are using the same Schema ID.

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.

Multi-scene setup

When networked Entities are added by loading a scene additively, mind that the CoherenceMonoBridge must be set to a singleton mode. In case of a non-singleton MonoBridge the Entity will search for a MonoBridge instance within its scene, and if none is found it will be created in that scene. This applies to both CoherenceSync and LiveQuery objects.

For a complete control over CoherenceMonoBridge resolving you can use either CoherenceSync.MonoBridgeResolve instance event or MonoBridgeStore.MonoBridgeResolve global event. A CoherenceMonoBridge instance provided by the MonoBridgeResolve event takes precedence over the scene and singleton ones.

Showing incorrect SDK version

Sometimes the package cache gets stalled and after updating the coherence package you might find Unity still uses the old package version. Try Reimport all or closing the project, deleting the Library folder, and reopening the project again. It will clean and update packages cache, and use the version of coherence stated in manifest.json.

Type '...' already defines member called '...' with the same parameters

Currently, coherence doesn't support networking prefabs with the same name. Doing so can yield duplicated definition errors. Best course of action is to rename your prefabs so they have different names.

We will support networking prefabs with the same name in the future.

Prefab Variants using excessive memory

When working with Prefab Variants, Unity leaks managed references (fields marked with [SerializeReference]). This can make your prefab grow big and use more memory than necessary. Until Unity fixes this issue, we provide you with the ability to prune the leaked references. Pruning is only available for Unity 2021.2+.

Building for WebGL

Unity does not build WebGL because Python 2 is missing on latest macOS and Ubuntu 22. This is fixed on Unity 2020.3.40f1 and onwards.

Dots (.) are not supported as part of WebGL build names.

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.

KeyNotFoundException

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.

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

0.10.15

Published 02.06.2023

This is a maintenance release.

Fixed

• Child entities of duplicate unique entities are no longer destroyed.

Removed

• TCP fallback removed until it receives a rework in the next major version.

0.10.14

Published 27.04.2023

This is a maintenance release.

Fixed

• Permissions issue while executing baking or a Replication Server on macOS.

0.10.13

Published 26.04.2023

This is a feature release!

Added

• Added Floating Origin support. It's now possible to move the whole world underneath an entity and position game objects precisely even in very large virtual worlds. For more information, see the Floating Origin article.

0.10.12

Published 24.04.2023

This is a maintenance release.

Fixes

• Compilation on Unity 2022.2+ works now.

• Reverted a warning on the CoherenceSync inspector where the object is not in the Prefab Mapper.

0.10.11

Published 11.04.2023

This is a maintenance release.

New Features and Functionality

• Added a warning about Prefabs not being addded to the Prefab Mapper when baking from the CoherenceSync inspector.

Changes

• Log settings are now stored in Library/coherence/logSettings.json.

• Improved coherence Hub performance.

Fixes

• BakeUtil.Bake method return value.

• LogSettings saved on fresh imports.

• Multi-Room Simulators no longer attempt to serve more than one HTTP server.

0.10.10

Published 28.03.2023

The main benefits of this release involve schema. Gathered.schema is now stored in the project and as such, became fully versionable. This and some other choice improvements below have dramatically improved SchemaID stability.

New Features and Functionality

• BakeUtil.OnBakeStarted and BakeUtil.OnBakeEnded events.

• Multi-Room Simulators: reconnection timeout.

Changes

• CoherenceNode: fixed order of execution. Now, updates are applied before parenting is resolved.

• Gathered.schema moved to Assets/coherence/Gathered.schema (from Library/coherence/Gathered.schema).

• Can no longer disable Toolkit/Reflection/Generic Schema on Settings. It's required now.

• RuntimeSettings' SchemaID property now warns about outdated schemas.

• Optimize window: added statement that it is an experimental feature for now.

Fixes

• Sample UI hanging when there's no connection.

• Reduced allocations made by the SDK.

• Auto-update RuntimeSettings after bake.

• Entering Play Mode is now faster on big projects.

• CoherenceInput: now works with Prefabs containing spaces in their name.

• Faster synchronization of Transform's position.

• Connection: packets filtered by roomID to prevent cross-room data contamination.

Removals

• Users no longer receive a prompt to bake before entering Play Mode.

• Bake Window button removed from the Optimize window UI.

v0.10.9

Fixes

• macOS builds uploaded to coherence Cloud now keep the Application Bundle (.app) structure intact.

• When a simulator fails to build, the scripting define symbol COHERENCE_SIMULATOR is properly removed.

• Faster assembly reloads, since coherence no longer tries to load your project Prefabs (was done to inform about possible issues or misconfigurations).

• WebGL won't crash when failing to create a WebSocket.

Discuss on Community

v0.10.8

New features and functionality

• TCP fallback when UDP connections fail or are blocked. Useful in heavily firewalled/restricted environments.

• CoherenceSync: ability to trigger authority transfers from within the inspector while in Play Mode.

• CoherenceSync: when adding CoherenceSync to a Prefab Instance, it's possible to apply CoherenceSync to the original Prefab instead of creating a new one.

Changes

• Sample UI: layout.

• Sample UI: watermark shows current Room/World ID, region and schema ID.

Fixes

• Replication issues when commands or inputs are being sent right after instantiation.

• CoherenceSync: moving to Assets/Resources won't fail if the folder doesn't exist yet, and it's possible to issue from within a Prefab Stage.

• CoherenceSync: adding a CoherenceSync inside a Prefab Stage resolves 'Load via' properly now.

• Sample UI: highly reduced GC allocations in watermark.

• Sample UI: refreshing was performed multiple times. Now, it also takes less time to get the state updated.

v0.10.7

New features and functionality

• New PlayResolver.RemoveRoom API.

• Sample UI: detect available local Replication Server.

• CoherencePlayerName component to ease networking the player name set on the Sample UI.

Changes

• Bake automatically defaults to false.

• Sample UI: improved layout and better state management.

• CoherenceSync: tooltips have been rewritten and improved.

• PlayResolver.FetchWorlds takes optional region and simulator slug as arguments.

• Connection Dialog defaults to rooms.

• Baking automatically on building a Unity Player no longer updates Prefabs.

Fixes

• Texture-loading related issues (Editor).

• Packets received from incorrect endpoints are ignored.

• Build uploading on macOS.

• Hub: improvements to the Overview section.

• Hub: Multi-Room Simulators Wizard no longer reopens.

• coherence now waits for the AssetDatabase to be ready before performing changes to Prefabs.

• CoherenceSync: No Duplicates resolves uniqueness properly now.

• Uploading schemas from CI using COHERENCE_PORTAL_TOKEN.

• CoherenceSync: with rigidbody, parented under an object without CoherenceSync, now correctly syncs its position.

v0.10

The first thing you'll notice is that our Documentation has gotten a thorough overhaul to its structure. We hope you find the new layout of topics more usable and logical.

New features and functionality

• Play.IsLoggedIn to wait before interacting further with the Play API.

• Authority-side sample interpolation that removes jitter for bindings that are sampled at high frequencies.

• CoherenceSync: now fully configurable in Prefab variants. Prefab overrides can be visualized both in the CoherenceSync inspector and the Configure window.

• PlayResolver: Option to create or join existing room with matching tags.

• DescriptorProvider custom data object added for extended binding support.

• Play.IsLoggedIn now waits before interacting further with the Play API.

• Authority-side sample interpolation that removes jitter for bindings that are sampled at high frequencies.

• CoherenceSync: a new 'Preserve Children' option to prevent connected entities (CoherenceSyncs in hierarchy) from being destroyed if the parent entity is destroyed.

• CoherenceSync: [Sync] and [Command] attributes now allow you to specify the old name of the member to migrate it in place (example: [Sync("myOldVar")] public float myVar;).

• CoherenceMonoBridge: onLiveQuerySynced exposed in the inspector (OnLiveQuerySynced deprecated).

• Build sharing: improved build path validation.

• Baking: now informs users about the current limitation of 32 schema components.

• Source Generator: improved reports so that it's clear when there's a failure.

• PlayResolver: Option to create or join existing room with matching tags.

• DescriptorProvider custom data object for extended binding support.

Changes

• CoherenceSync: polymorphic bindings using serialized references. Upgrading from older coherence versions requires migration (done automatically, can trigger manually via menu item 'coherence > Reimport coherence Assets').

• CoherenceSync: configurable rigidbody component action. You can decide when isKinematic should be (un)set.

• CoherenceSync: authority transfer UI label changed from 'No' to 'Disabled'.

• CoherenceHub: last tab opened is now persistent when closing and opening the window again.

Fixes

• Networked Prefabs are now instantiated with their original rotation if the rotation is not synced.

• Truncated floating point precision in the 'Optimize' window.

• Losing latest changes when transferring authority.

• Overshooting and overflowing of integers while interpolating.

• WebGL Client automatically disconnecting after Replication Server shutdown.

• Recycling of EntityIDs caused by a double delete of an ID when an Entity is destroyed because of a parent moving out of the query.

• Negative latency calculations during CPU spikes.

• Fixed ConnectionSettings.PingOnConnect causing a timeout when connecting.

• Editor getting stuck in an infinite loop when trying to import packages that reference missing types.

• CoherenceNode script is now executed before CoherenceSync to mitigate parenting validation warnings.

• Entities that exceed the Room's max Entity count are destroyed and a warning is logged.

• Cloning GameObject instances with baked bindings using Instantiate would result in binding errors due to missing GUIDs (globally unique identifiers).

• Warnings spammed when exiting Play Mode in Unity Editor.

• Baking: process running longer than expected.

• Baking: gather bindings from inactive GameObjects in hierarchy.

• Baking: fixed NullReferenceException by skipping missing scripts.

• Hub: don't show synchronous fetch organization progress bar.

• Hub: improved scene setup instructions.

• Hub: improved Multi-Room Simulators setup.

• More coherence components implement a custom editor now, showing the logo and a brief description.

• Source Generator: allow on 2020.3.

• Source Generator: first time import failing due to directories not yet existing.

• CoherenceSync: binding the same method as a command multiple times in the same Prefab is now supported.

• CoherenceSync: fixed issue with parenting and interpolation which would result in a few frames of the connected Entity being in the wrong place.

• CoherenceSync: use the method SendCommandToChildren to send a command to every bound component in the hierarchy.

• CoherenceSync: new overload for the SendCommand method that accepts an Action, you can use it to send a command to a specific Component instance, if a method is bound to more than one component in the hierarchy.

• CoherenceSync: disabled prediction controls on reflection (non-baked) mode.

• CoherenceSync: set default interpolation.

• CoherenceSync: fixed error on cancelling interpolation asset creation.

• CoherenceSync: opening the inspector should not load additional assets (noticeable speedups on bigger projects).

• CoherenceSync: binding to generic members is no longer allowed.

• CoherenceSync: collapsed 'Custom Events' section by default.

• CoherenceSync: 'Steal' authority transfer type on persistent Entities is no longer forced.

• CoherenceNode: executed before CoherenceSync to mitigate parenting validation warnings.

• Sample UI: don't auto-generate EventSystem, but inform when it's missing.

• Sample UI: fixed default room name.

• Sample UI: fixed Refresh button throttling (too many requests).

• PlayClient: fixed missing Client version header.

• Analytics: Exception thrown due to threading error.

• PlayResolver: Cached rooms not filtered by tags.

Removals

• CoherenceMonoBridge: OnShutdown event.

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 0.10.15

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.

Use Lens search in docs for AI-powered answers

When you use our search bar, you can now switch from Search to Lens. Simply tell Lens what you want, or ask it a question. It’ll use AI to scan coherence documentation and give you a simple, semantic answer — with clickable references if you want to dive deeper.

Update an existing project

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

Tutorial project

First Steps is a collection of articles and 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 Discord channel.

• Contact us at devrel@coherence.io

Using the same scene as in the previous lesson, let's see how to easily sync animation over the network.

Key controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

Topics covered

Animation | Bindings

In this scene...

We haven't mentioned it before, but the player Prefab does a lot more than just syncing its position and rotation.

If you perform the actions mentioned in the controls, you will notice that animation is also replicated across Clients. This is done via synced Animator parameters (and Network Commands, but we cover these in the next lesson).

Very much like in the example about position and rotation, just sending these across the network allows us to synchronize of the state of animation, making it look like network-instantiated Prefabs on other Clients (the other players) are performing actions.

How it's set up

Open the player Prefab located in the Characters/Player __ folder. Browse the Hierarchy until you find the sub-object called PlayerModel. You will notice it has an Animator component. Select this object and open the Animator window.

As you can imagine, animation is controlled by a few parameters of different types (int, bool, float).

Make sure to keep the GameObject with the Animator component selected, and open the coherence Configure window:

You will see that a group of animation parameters are being synced. It's that simple: just checking them will start sending the values across, once the game starts.

There is only one piece missing: animation triggers. They are not a variable holding a value that changes over time, but rather an action that happens instantaneously, so we will see how to sync them in the next lesson using Network Commands.

The First Steps project is a series of small sample scenes, each one demonstrating one or more features of coherence.

If you're a first time user, we suggest to go through the scenes in the established order. They will guide you through some key coherence and networking concepts.

Remember that playing the scenes on your own only shows part of the picture. To fully experience the networked aspects, you have to play them in the Editor plus one or more built instances, and even better - with other people.

Download the Unity project

The Unity project can be downloaded on its Github repo.

Try a pre-made build

To quickly try a pre-built version of the game, head to this link and either play the WebGL build directly in the browser, or download one of the available desktop versions.

Share the link with friends and colleagues, and have them join you!

Make your own build

Once you open the project in the Unity Editor, you can build scenes via File > Build Settings, as per usual.

To be able to connect, you need to also run a local Replication Server, that can be started via coherence > Local Server > Run Local Worlds Server.

You can try running multiple Clients rather than just two, and see how replication works for each of them. You can also have one Client just be the Unity Editor. This allows you to inspect GameObjects while the game runs.

You can also upload a build to the cloud and share a link with friends. To do that, follow these steps to host builds on the coherence Cloud.

This scene demonstrates the simplest networking scenario possible with coherence. Characters sync their position and rotation, which immediately creates a feeling of presence. Someone else is connected!

Key controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

Topics covered

CoherenceSync | Bindings | Component behaviours | Authority

In this scene...

Upon connecting, the PlayerHandler script (attached to the PlayerHandler GameObject) creates a new instance of the character Prefab, located in the Prefabs/Characters folder. When disconnecting, the same script destroys the instance created.

coherence takes care of keeping all Game Clients in sync regarding network entities. When another Client connects, a new instance of your game character is instantiated in their scene, and a copy of their character is instantiated into yours. This is called network instantiation.

Now you can move and jump around, and you will see other characters move too.

How it's set up

You can see what is synced over the network by selecting the Prefab asset, and opening coherence's Configuration window (either by clicking on the Configure button on the CoherenceSync component, or by going to coherence > GameObject setup > Configure).

When this window opens on the first tab you will notice that, at the very top, Transform.position and Transform.rotation are checked.

This is the data being transferred over the network. Each Client sends position and rotation of the character they have authority over to every other connected Client, every time there is a change to it that is significant enough. We call these bindings.

Each connected Client receives these values and applies them to the Transform component of their own instance of the remote player character.

To ensure that Clients don't modify properties of entities they don't have authority on, some components are either disabled or changed on instances that are non-authoritative. If you open the third tab of the Configuration window, you will see that 3 components are modified:

In particular:

• The PlayerInput and KinematicMove scripts are disabled.

• The Rigidbody component is made kinematic.

Understanding authority

One important concept to get familiar with is the fact that every networked entity exists as a GameObject on every Client currently connected. However, only one of them has what we call authority over the network entity, and can control its synced variables.

For instance, if we play this scene with two Clients, each one will have 2 instances in their respective worlds:

This is something to keep in mind as you decide which components have to keep running or be disabled on remote instances, in order to not have the same code running unnecessarily on various Clients. This could create a conflict or put the two GameObjects in a very different state, generating unwanted results.

In the Unity Editor, the name of a GameObject and the icon next to it informs you about its current authority state (see image).

If you want to see which entities are currently local and which ones are remote, we included a debug visualisation in this project. Hit the Tab key (or click the Joystick) to switch to a view that shows authority. You can keep playing the game while in this view, and see how things change.

Using the same scene as in the , we now take a look at another way to make Clients communicate: Network Commands. Network Commands are like sending direct messages to objects, instead of syncing the value of a variable.

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

• Q or D-pad up: Wave

Topics covered

|

In this scene...

Building on top of previous examples, let's now focus on two key player actions. Press Space to jump, or Q to wave. For both of these actions to play their animation, we need to send a command over the network to call Animator.SetTrigger() on the other Client.

How it's set up

Like before, select the player Prefab located in the Characters/Player __ folder, and browse the Hierarchy until you find the sub-object called PlayerModel.

Open the coherence Configure window on the Methods tab:

You can see how the method Animator.SetTrigger(string) has been marked as a Network Command. Once this is done, it is possible to invoke it over the network.

You can find the code doing so in the Hail class (located in /Scripts/PlayerActions/Hail.cs):

With this simple line of code, we're asking to:

• Send a command to an object of class Animator.

• Invoke a method called Animator.SetTrigger.

• Do so only for network entities other than the one with authority (MessageTarget.Other).

• Pass the string "Hail" as the first parameter (which is the name of the animation trigger parameter).

Game characters and other networked entities are often made of very deep hierarchies of nested GameObjects, needing to sync specific properties along these chains. In addition, a common use case is to parent a networked object to the tip of a chain of GameObjects.

Let's see how to handle these cases.

Controls

• A/D or Left/right joypad triggers: Rotate crane base

• W/S or Left joystick up/down: Raise/lower crane head

• Q/E or Left joystick left/right: Move crane head forward/back

• P/Space/Enter or Joypad button left: Pickup and release crate

Topics covered

| |

In this scene...

This scene features a robotic arm that can be controlled by one player at a time. In the scene, a small crate can be picked up and released.

The first player to connect takes control of the arm, and other players can request it via a UI button.

How it's set up

To demonstrate complex hierarchies we choose to sync the movement of a robot arm, made of several GameObjects. In addition to syncing several positions and rotations, we also sync animation variables and other script parameters, present on child objects.

To sync the whole arm we use a coherence feature called deep bindings, that is bindings that are located not on the root object, but deeper in the transform hierarchy.

Select the RobotArm __ Prefab asset located in /Prefabs, and open it for editing. You will immediately notice a host of little coherence icons to the right of several GameObjects in the Hierarchy window:

These icons are telling us that these GameObjects have one or more binding currently configured (a variable, a method, or a component action).

Now open the coherence Configuration window, and click through those objects to discover what's being synced:

In addition to position and rotation, we also choose to sync the animation parameter ClawsOpen, and enable Animator.SetTrigger() as a Network Command. Finally we disable the Robot Arm script when losing authority (to disallow input).

This is the base of the robot arm, for which we only sync rotation:

We don't sync the rotation of every object in the chain, since the arm is equipped with an IK solver, which allows us to just sync the target (Two-Bone IK_target) and work out the rotation of the limb (robotarm_bottomarm and robotarm_toparm) on each Client:

By syncing all of these properties, we can have the robotic arm move in sync on all Clients, simply by translating the tip of the IK, and rotating the base of the crane. All of the bindings in this hierarchy are synced through the Coherence Sync component present on the Prefab's root object RobotArm.

As you can see, using deep bindings doesn't require any special setup: they are enabled in exactly the same way as a binding, Network Command or Component action on the root object.

Parenting the crate with CoherenceNode

The Path property displays the location in the hierarchy where this object will be inserted. It gets automatically updated by coherence every time the object is parented. Each number represents a child in the root object (and it's 0-based).

Once we have this component set up, parenting the object only requires calling Transform.SetParent() like any usual parenting operation, and setting its Rigidbody component to be kinematic.

When we do this, coherence takes care of propagating the parenting to other Clients, so that the crate becomes a child GameObject on every connected Client.

This code is in the RobotArmHand class, a component attached to the tip of our hierarchy chain: GrabPoint. In OnTriggerEnter we detect when the crate is in range, storing a reference to it in a variable of type Transform named grabbableObject.

This reference is set to sync:

When the player presses the key P (or the Left Gamepad face button), the referenced crate is parented to the GrabPoint GameObject.

Even if the Robot Arm Hand script is disabled on non-authoritative Clients, by referencing the grabbed crate in the grabbableObject variable and syncing it over the network, even if a Client disconnects, other Clients will already have the correct reference to the crate network entity.

This allows us to gracefully handle a case where, for instance, a Client picks up the crate and disconnects. Because both the crate and the robot arm have Auto-adopt Orphan set to "on", authority is passed onto another Client and they immediately have all the data needed to keep handling the crate.

Transferring authority

To move authority between Clients, we can use the UI in the bottom left corner. The button is connected to the Robot Arm Authority script on the ArmAuthoritySwapper GameObject. This script takes care of the authority transfer and what happens as a result, including setting the crate to be kinematic or not.

Is Kinematic is set as follows:

The code is in the RobotArmAuthority class. To detect whether it's currently being held, it's as simple as checking whether its Transform.parent is null:

Remember you can use Tab/click the Gamepad stick to use the authority visualization mode. Try requesting authority from another Client while in this mode.

Every now and then it makes sense to parent network entities to each other, for instance when creating vehicles or an elevator. In this sample scene we'll see what are the implications of that, and how coherence uses this to optimize network traffic.

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

Topics covered

Moving platforms | | Parenting at runtime |

In this scene...

This wintery setting contains 2 moving platforms running along splines. Players can jump on them and they will receive the platform's movement and rotation, while still being able to move relative to the platform itself.

How it's set up

This scene doesn't require anything special in terms of network setup to work.

Direct parenting of network entities in coherence happens exactly like usual, with a simple transform.SetParent(), or even just dragging one GameObject onto another in the Unity Editor's Hierarchy window. The player's Move script is set to recognize the moving platforms when it lands on them, and it just parents itself to it.

As for the platforms, they are just moving themselves as kinematic rigid bodies, following the path of their spline (see the FloatingPlatform script). Their position and rotation is synced on the network, and the first Client to connect assumes authority over them.

Effects of parenting entities

Once directly parented, coherence automatically switches to sync the child's position and rotation as local, rather than in world space. This means that when child entities don't move within their parent, no data about them is being sent across the network.

Imagine for instance a situation where 3 players are riding one of the platforms and not moving, only the coordinates of the platform are being synced every frame.

Limitations of simple parenting

You might have noticed we always mentioned "direct" parenting. One limitation of this simple setup is that the parented network entity has to be a first-level child of the parent one. This doesn't exclude that the parent can have other child GameObjects (and other networked entities!), but networked entities have to be a direct child.

A hierarchy could look like this:

• Platform

  • Player

    • Character graphics

    • Bones

    • ...

  • Platform's graphics

  • ...

(In bold is the root of each Prefab, which has a CoherenceSync component)

You can even parent multiple network entities to each other. For example, a networked character holding a networked crate, riding a networked elevator, on a networked spaceship. In that case:

• Spaceship

  • Elevator1

    • Elevator graphics

  • Elevator2

    • Player

      • Crate

      • Character graphics

    • Elevator graphics

  • Spaceship graphics

  • ...

In this sample we look at how to network simple physics simulated directly on the Clients, and the implications of this setup.

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

• E or Joypad button left: Pick up / throw objects

Topics covered

Physics | | Uniqueness |

In this scene...

In this scene we have mostly static scenery, and a few crates that the players can pick up and throw around. Who runs the physics simulation here? You could say that everyone runs their part. Let's take a closer look into the setup.

How it's set up

Select one of the crates in the scene. You can see that they have normal Box Collider and Rigidbody components. Up until a player is connected, they are being simulated locally. In fact if you press Play, they will fall down and settle.

The crates also have a CoherenceSync component. The first player to connect gets authority over them, and keeps running their simulation without interruption. That Client now syncs 2 values over the network: Transform.position and Transform.rotation.

On other Clients however (the ones that connect after the first), these crates will become remote. The configured component action makes their Rigidbody kinematic, so that now their movement is controlled by the remote authority (i.e. the first Client).

Authority switch

At this point, the first Client to connect is simulating all the crates. However, interacting with physical objects that are simulated by another Client is quite unpleasant due to the lag. To make it better, other Clients steal authority over crates, whenever they either:

• Touch/collide with a crate directly

• Pick a crate up

In code, this authority switch is a trivial operation, done in a single line. You can find the code in the NetworkGrabbable class:

As you can see, it's good practice to ask first if the requesting script already has authority over an object, to avoid wasted work.

Once the request succeeds, the instance of the crate on the requesting Client becomes authoritative, and the Client starts simulating its physics. On the other Client (the previous owner), the object becomes remote (and its Rigidbody kinematic), and is now just receiving position and rotation over the network.

So who is running the physics, after all? We can now say that it's everyone at the same time, as the roles change all the time.

As we mentioned in the intro - in a simple game where precise physics are non-crucial this might be enough, and it will definitely keep the costs of running the game down, since no Simulation Server has to run in order to make the game playable.

About uniqueness and persistence

There is one important thing to note in this setup. Since the objects are already in the scene at the start, by default every time a Client connects it would try to sync those instances to the network. This is very similar to what we have seen with character instantiation so far: each Clients brings their own copy.

However, in this case this would effectively duplicate the crates, once online. One extra copy for each connected player! We don't want that.

For this reason, the CoherenceSync is configured so that these crates are Persistent and have No Duplicates. This is generally the correct way of configuring networked Prefab instances that have been manually placed in the scene.

With these parameters in mind, the way the crates behave is as follows:

• At the start, none of the entities exist on the Replication Server (yet).

• The first Client connects. They sync the crates onto the network. Being unique, the Replication Server takes note of their Universally Unique ID (UUID).

• Another Client connects. They try to bring the same crates onto the network, but because they are set to be No Duplicates and coherence finds there is already a network entity with the same UUID, it destroys the instance in the scene and network-instantiates a new instance, which is now non-authoritative.

• If the first Client disconnects, the crates are not destroyed because their Lifetime is set to Persistent. They briefly become orphaned (no one has authority on them) but immediately the authority is passed to the second Client due to the option Auto-adopt Orphan being on.

• If everyone disconnects, the crates persist on the Replication Server as network entities that are orphaned. They keep whatever position/rotation they had, since nobody is simulating them anymore.

At this point, nobody is connected. The Replication Server is not doing any work.

• When a new Client reconnects and tries to bring the crates online, a duplication is detected: the Prefab instance in the scene and the network instance on the Replication Server have the same UUID. Due to Uniqueness set to No Duplicates, their local instances are destroyed and re-instantiated as network copies. They are orphaned, but thanks to Auto-adopt Orphan, the Client immediately assumes authority on them.

• They will also most probably see the crates snap to the last seen position/translation that was stored on the Replication Server, which is synced just before they assume full control over the crates. At this point, they start simulating their physics locally.

We have seen a lot of examples with objects belonging to a Client, and when that Client disconnects, they disappear with them. We call these session-based entities.

But coherence also has a built-in system to make objects survive the disconnection of a Client, and be ready to be adopted by another Client or a Simulator. We call these objects persistent. Persistent objects stay on the Replication Server even if no Client is connected, creating the feeling that the game world is alive beyond an individual player session.

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• P or Right shoulder button: Plant a flower (hold to preview placement)

Topics covered

| |

In this scene...

Players can plant flowers in this little valley. Each flower has 3 phases: starts as a bud, blooms into a full flower, and then withers after some time.

Creating a flower generates a new, persistent network entity. Even if the Client disconnects, the flower will persist on the server. When they reconnect, they will see the flower at their correct stage of growth (this is a little trick ).

Planting too many flowers starts erasing older flowers. A button in the UI allows clearing all flowers (belonging to any player) at any time.

How it's set up

When using the plant action, any connected player instantiates a copy of the Flower Prefab (located in the /Prefabs/Nature folder).

By selecting the Prefab asset, we can see its CoherenceSync component is set up like this:

In particular, the Lifetime __ is set to Persistent. This means that when the Client who plants a flower disconnects, the network entity won't be automatically destroyed. Auto-adopt Orphan __ set to on makes it so the next player who sees the flower instantly adopts it, and keeps simulating its growth.

Opening coherence's Configuration window, you will see that we sync position, rotation, and a variable called timePlanted:

Once a flower has spawned, all of its logic runs locally (no coherence involved). An internal timer calculates what phase it should be in by looking at the timePlanted property and doing the math, and playing the appropriate animations and particles as a result.

Simulating lifetime without a Simulator

To achieve this, the flowers of this scene store the Flower.timePlanted value on the Replication Server. A Replication Server with no connected Clients is dormant, and has a very low cost to run. So the flowers are not actually simulating, they are just waiting.

When a new Client comes online and this value is synced to them, they immediately fast-forward the phase of the flower to the correct value, and then they start simulating locally as normal.

This gives the players the perception that things are still running even when they are not connected.

Destroying other Client's flowers

Every Client can, at any time, remove all flowers from the scene by clicking a button in the UI.

It's important to remember that you shouldn't call Destroy() on a network entity on which the Client doesn't have authority on. To achieve this, we first request authority on remote flowers and listen for a reply. Once obtained it, we destroy them.

Check the code at the end of the Flower script:

This section introduces you to coherence features and terminology by using well-known genres and game types as examples. Each example will come with a list of considerations and how we propose to use coherence to achieve a similar result. As you well know, game creation is a complex process, so the list is far from exhaustive, but aims to highlight pitfalls, suggest solutions and generally just provide you with a starting point when trying to create a multiplayer game with coherence in the context of a game type you are working on.

Racing games involve multiple vehicles racing a number of laps. They can be realistic or arcade-y, but the end goal is always the same: crossing the finish line first.

Synchronicity is important

In multiplayer racing games it is vital to have as precise information about the position of other clients as possible. The server and the players both need to know details like if its possible to overtake in a curve, if players bumped into each other, and even more importantly - who crossed the finish line first. We need to have server authority, but each Client also needs reliable predictions about where the other players are.

Fighting games come in many shapes and forms. Usually they involve 2 or more players fighting each other. The players can kick, punch, block, grab and trigger intricate combos for extra damage. Often this type of game relies on quick reactions to the opponent's movement.

Deterministic simulation

For a fighting game, we need a reliable game state regardless of user ping. It needs to be deterministic. For example, if two players press the kick button a few milliseconds apart, the Simulator needs to be able to figure out which player is the one doing the kicking, and which is the one getting kicked. Our solution is called input queues and the setup is described in great detail here. The key idea is that only the input is being processed by the Client, and the Simulator is responsible for deciding the outcome. The Simulator stores a queue of inputs, which is then used to decide on the correct order of actions.

Deep bindings

If you want to synchronize more than just the root of the Game Object, e.g. if you want to have precise replication of ragdoll on all Clients, you need to create bindings to more that just the root transform. We support deep bindings which allow you to select any object in the hierarchy and synchronize whatever is needed.

First-Person Shooters (FPS) are games where multiple players join opposing teams and shoot each other. You will often win by either eliminating the opposite team, exploding a bomb, or running out the timer.

Communication

Good communication between players is often essential in winning. Serious players will have voice communication, but its also good to have in-game comms to easily communicate tactics. In coherence there is the concept of Client Connections which you can use to easily send messages between players. It can also be used to communicate game state changes e.g., "The bomb has been planted".

Doors

When building your level there may be certain objects that should be duplicated across Clients. You want to have a duplicate of each player on every Client, but for something like doors which can be opened or closed, you only want one "shared" door across all Clients. For this to happen you need to understand Uniqueness and Lifetime. Using those concepts, you can make sure that a given objects is persistent on the scene, and that only one exists.

Bomb

Similar to doors, the bomb is also unique. The difference is that the bomb is spawned and only 1 bomb can exist in the game at any time. Doors are also unique, but multiple instances of a door asset can exist, just not at the same place. To understand more, read about Setting up a global counter. This is the same principle of having a Prefab that is uniquely identified.

Cheating

Online competitive multiplayer games are tricky to get exactly right, and there is no "right" solution. It's a constant tradeoff between cheat protection, latency, client prediction, etc. You need to do further research to decide on the solution that best suits you. One thing you definitely need to learn about is client vs server authority.

For turn-based games, the requirements for networking can be quite different from other, more fast-paced games. You are only interested in changes to the game state, and don't really need more granularity than that. Let's take chess as an example.

Player character representation

You don't really need a player character so in order to process input you don't really need a CoherenceSync object. You could use a Client Connection Prefab if you want to have an easy way to implement chat.

Client-side simulation

You might want to have a Simulator to process everything if you want cheat protection, but for a game such as this it could also be viable to simply opt for client-side simulation and then have one of the Clients have authority over the game controller. That is the default setting when adding a CoherenceSync Component. Each client can then talk to the game controller using Commands.

Setup video tutorial

The topics of this page are covered in the first minute of this video:

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

Creates a LiveQuery which queries the area around the local player to get the required information from the Replication Server. You can surround your entire scene in one query or can attach it to an object such as the player or a camera.

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 blue link next to the warning messages and coherence will redirect you to the correct place to learn more about how to fix the issue.

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

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

Running a Replication Server locally

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

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

The coherence Sample UI is a Prefab that you can add to your scene. It handles interaction with coherence services, is made up of a Unity UI Canvas and includes everything needed to handle connection to coherence.

The UI component on the root of the Prefab allows us to switch between using Rooms or Worlds. Each of these methods has a dedicated dialog for connection.

The Auto Simulator Connection component is used by Simulator builds to connect to the relevant Replication Server.

The Rooms Connect Dialog has a few components that facilitate the usage of Rooms.

At the top of the dialog we have an input field for the player's name.

Next is a dropdown for region selection. This dropdown is populated when regions are fetched. The default selection is the first available region.

Beneath these elements is a Rooms list of available Rooms in the selected region.

After selecting a Room from the list the Join button can be used to join that Room.

The New Room tab will take us to the Room creation screen.

This screen contains controls for setting a Room's name and maximum player capacity. Pressing the Create button will create a Room with the specified parameters and immediately add it to the Room List in the previous tab. Create and Join will create the room, and join immediately

The Worlds Connect Dialog is much simpler. It simply holds a dropdown for region selection, an input field for the players name, and a Connect button.

Requirements

Game engine support

coherence currently supports Unity. For custom engine integration, please contact our developer relations team. For updates regarding Unreal Engine support, please check the Unreal Engine support page.

For custom engine integration, please contact our developer relations team.

Unity requirements

• Unity 2020 LTS or 2021 LTS (2020.3.36f1 or later).

• A Windows, Linux or macOS system.

Video Tutorial

Unity Package Manager

1. Add the Scoped Registry

First, open Unity's Project Settings.

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

• Name: coherence

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

• Scope(s): io.coherence.sdk

• Enable Preview / Pre-release Packages: yes

2. Install coherence

Now open the Window / Package Manager.

Select My Registries in the Packages dropdown.

Under coherence, click Install.

Alternative method: edit manifest.json manually

Refer to Unity's instructions on modifying your project manifest.

Edit <project-path>/Packages/manifest.json.

Add an entry for the coherence sdk on the dependencies object, and for the scoped registry in the scopedRegistries array:

{
  "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 ***/
  
}

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

In most MMOs you control a character, interact with other players and group up with other players to clear dungeons. Here's a few networking considerations for anyone creating something similar.

Persistence

In a MMO the world needs to be persistent. Any given user can join and leave a world at any given time and we want their changes to be persistent. Which NPCs was killed, which treasures were looted, which items are available on the action house, etc. In order to achieve this, you need to run a in the which will make sure the world state is saved even if no players are logged in.

Optimization by range

Given that there can be a large amount of players distributed over a very large area, we don't really care about the ones in all the different areas. By not sending information about players far from the player itself, we can significantly limit the amount of data sent over the network. When using coherence you can use the to set a bounding box in which we replicate data from networked entities - anything outside of it is ignored.

Optmizations using LOD

Even within a there might be further room to optimize. When having a large amount of networked entities, you might want to prioritize those that are closer. Our solution to this is called . Using this you are able to control values such compression, value range and sample rate in order to hit the optimization sweet spot.

Simulators

To make sure that all users experience an identical game world at any given time, we need a Simulator to be responsible for taking decisions for the AI, triggering events, etc. In coherence we support launching your game with any number of taking responsibility for the various parts of your game.

Instance dungeons

A common part of all MMO's are instanced areas where a smaller group of players enters together and completes a set of tasks. It does not make much sense to run these instances as a part of the World Replication Server. The idea is that it can be possible to spin up a separate server for each group who enters such an instance. In coherence we offer this through the . This allows you to have a shared world, as well as any number of instances for a specific area for a subset of players.

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

Video tutorial

Setting up basic syncing is explained in this video, from 1:03 and onwards:

Alternatively, you can follow the text guide below.

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.

When the Prefab variant inherits the network settings from the Prefab parent, you can configure your Prefab variant with overrides in the Configuration window. When a synced variable, method or component action is present in the variant and not in the parent, it will be bolded and it will have the blue prefix beside it, just like any other override in Unity.

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

When developing multiplayer experiences you will need to run multiple instances of your game in order to test properly. You also need to make sure these instances can be restarted quickly, so you can iterate quickly.

coherence does not have a built-in solution for multiclient testing, but there are several options available to you, each with their own benefits and drawbacks.

ParrelSync

ParrelSync is an open-source project which allows you to have multiple Editors open which share Assets and ProjectSettings using Symbolic links.

Benefits

• Short iteration times.

• Easily debuggable instances.

Drawbacks

• Requires you to have multiple Editors open.

Caveats

• All instances of the game must have identical schemas, which are NOT shared using ParrelSync. That means you need to bake on all open Editors. Setting Auto Bake on Enter Play Mode to true in coherence Settings will alleviate this issue.

• EditorPrefs are not consistently shared between Editors.

Best practice

• First, install the ParrelSync package as described in the .

• Open ParrelSync -> Clones Manager. Create a new clone, and open it.

• Continue development in the original Editor.

• When you need to test, do the following for all open Editors: Bake, press play. Alternatively you can set Auto Bake on Enter Play Mode to true.

Building an executable

The easiest method is to simply create a new build each time you want to test anything. You can launch any number of instances of that build, and have an instance running in the Editor as well.

Benefits

• Easy to distribute amongst team members.

• Well-understood workflow.

Drawbacks

• Long iteration time as you need to continuously make builds.

• Harder to debug the executables.

Caveats

• All instances of the game must have identical schemas, so remember to bake before building the executable.

Multiplayer Play Mode

Unity has an experimental package called Multiplayer Play Mode (MPPM) available for 2023.1. As this is currently experimental, we do not officially recommend it - but it does show some promise and should be mentioned. This package allows a single Editor to run several instances of a game.

Benefits

• Short iteration times.

• No issues with schema incompatibility.

Drawbacks

• Experimental.

Now we can finally deploy our schema and Replication Server on coherence Cloud.

Video tutorial

The topics on this page start from around 1:03 in the video below:

Alternatively, you have the steps detailed in the text below.

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

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.

Upload to coherence

In the coherence Hub window, select the coherence Cloud tab. You can upload your build from the Share Build section of the tab, select the platform (macOS, Linux, Window or WebGL are supported) and click on the Begin Upload button.

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.

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 coherence Cloud 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.

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 .

LiveQuery

The way you get information about the World is through LiveQueries. We set criteria for what part of the World we are interested in at each given moment. That way, the Replicator won’t send information about everything that is going on in the Game World everywhere, at all times.

Instead, we will just get information about what’s within a certain area, kind of like moving a torch to look around in a dark cave.

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

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

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

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

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:

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

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

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

• bool

• int

• uint

• byte

• char

• short

• ushort

• float

• string

• Vector2

• Vector3

• Quaternion

• GameObject

• Transform

• RectTransform

• CoherenceSync

• SerializeEntityID

• byte[]

• long

• ulong

• Int64

• UInt64

• Color

• double

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

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.

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

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

Refer to the Commands section.

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

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

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.

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

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

Handling parent destruction

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

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.

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.

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.

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

Triggers

Now, bind to the PlayJumpAnimator.

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:

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

Sync Attribute

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

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

Command Attribute

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

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

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.

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

Usage

Let's start with a simple example:

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

Limitations

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

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

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

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

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

Limitations

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

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

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.

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.

Requesting authority in code

Requesting authority is very straight-forward.

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.

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