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

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

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

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

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

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

What is coherence made of?

Replication Server ("Replicator")

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

Game Client

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

Simulation Server ("Simulator")

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

Schema

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

Code generation

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

State replication

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

State Replication

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

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

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

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

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

1.1.4

Published 26.03.2024

Fixed

• Commands routing pop-up doesn't block information with scrollbars on a few specific scaling settings anymore.

• CoherenceRelayManager no longer causes a stack overflow in rare circumstances if there are errors in the underlying UDP transport.

1.1.3

Published 08.02.2024

Fixed

• Labels no longer overflow when UI Scaling is set above 100% (on Windows: Edit > Preferences... > UI Scaling).

Changed

• Creating a Command on the Configure Window now defaults to "Send to Everyone, including yourself".

1.1.2

Published 23.01.2024

Added

• Sample Scenes were added and are now accessible from the package samples section and coherence's Explore Samples menu.

Fixed

• Source Generator no longer skips baked scripts that don't compile.

• CoherenceNode: no longer teleports to origin when reparenting.

1.1.1

Published 12.12.2023

Added

• coherence > Local Replication Server > Backup World Data toggle.

Changed

• Hub: Persistence renamed to Backup World Data, and disabled by default for local replication servers.

Fixed

• Version label in the Hub now copies correct OS information to the clipboard.

• CoherenceSync's Configure window no longer shows the Animator Controller on variables that have the same name as animation parameters.

• No longer send invalid updates when gaining authority.

1.1

Published 28.11.2023

Added

• CoherenceSync: added support for nested Prefabs and hierarchies via PrefabSyncGroup component.

• Sample: matchmaking with manual authentication.

• CoherenceBridge: added ability to disconnect from within the inspector.

• CoherenceSync: added support for byte, sbyte, short, ushort and char.

Changed

• CoherenceNode: improved stability.

• CoherenceSync: reworked Play Mode panel on the inspector.

• CoherenceSync: we now allow sending commands while disconnected (method gets called locally).

• CoherenceSync: Configure window shows variables and methods tagged with [Sync] and [Command].

• CoherenceScene: editor scene visibility settings split for Clients and Simulators.

• Reworked interpolation. Removed overshoot settings.

• Reworked code generation. Now, it's implemented on the Unity/C#-side.

• Updated JWT implementation, which is no longer provided as a pre-build DLL. This also prevents dependency conflicts.

• HTTP request timeout changed from 1 second to 10 seconds.

• Multi-Room Simulators Wizard: reworked, simplified layout.

Fixed

• Game Object getting deselected after adding CoherenceSync.

• Reduced the amount of GC allocs made for better performance.

• Release WebSocket when leaving Play Mode.

• Instantiated InterpolationSettings never getting destroyed.

• Time scale related issues, including jitter and low-FPS scenarios.

• Restrict and warn about the 31 components per entity limitation.

• Resolve inheritance when sending commands.

• Client Connection Prefab instances initialization issue when using the CreateScene API.

• Issue where mixing Transform and RectTransform networked variables could break.

• Console error after baking when Upload Schema on Baking Complete was on.

• Profiler: count messages received.

• Sample: wasn't refreshing Worlds properly in some scenarios.

• CoherenceSync: deleting a Component or a GameObject on the hierarchy spammed errors on the console.

• Uploading WebGL builds now shows the correct information on the progress bar.

• Console errors after deleting a Prefab, when the Coherence Objects Window has been opened and closed.

Removed

• Unity 2020 support. (Minimum supported version is now Unity 2021.3 LTS)

1.0.5

Published 06.10.2023

Added

• Extrapolation: Max Overshoot Allowed range increased to [0, 20].

• Extrapolation: Expose stale factor (defaults to 2).

Changed

• Highly reduced GC allocs made while serializing.

Fixed

• WebSocket request timings.

• OnValueSynced not triggering when the update packet came with a parenting change.

• Shifting the floating origin now correctly shifts rigidbodies in the same frame without kicking in the physics interpolation.

1.0.4

Published 05.09.2023

Added

• Descriptor Providers: two new properties were added to Bindings, called OverrideGetter and OverrideSetter. Setting this to true will allow you to write custom code blocks in your getters and setters, as opposed to being limited to "UnityComponent.{myCustomCode}".

• CoherenceBridge API: TranslateFloatingOrigin(Vector3d) overload.

Fixed:

• Floating Origin: fixed entities jittering on remote clients when Floating Origin is changed.

1.0.3

Published 11.08.2023

Added

1.0.2

Published 10.08.2023

Fixed

• CoherenceNode: Reset on OnDisable.

• Reset entity reference when destroying the entity.

• Force re-cache SchemaID after writing Gathered.schema to disk.

1.0.1

Published 25.07.2023

Fixed

• Commands: fixed trying to send a command from an inherited class that is bound in the parent class.

• Bindings: fixed rare cases where RectTransform bindings would be reported as missing.

• Client Connection Prefabs: fixed Client Connection instances duplication when changing Physics scene.

• Coherence Profiler: fixed count of messages received.

• ReplicationServerRoomsService: fixed RemoveRoom methods.

• Optimize window rendering issue where rows would disappear.

1.0

Published 04.07.2023

Still, nothing beats Release Notes for a quick and comprehensive review of the changes, so go ahead!

New features and functionality

• Lobby Rooms

• Unity multi-scene support

• TCP Fallback

• Client-hosting

• Profiler: a coherence Profiler module for basic networking information.

• Added support for object pooling and a default pooling implementation.

• Protocol: added support for ordered components so parenting component changes always arrive with related position changes.

• CloudService: non-static public API to communicate with your coherence Cloud project.

• Samples: Explore Samples window.

• Samples: New Connection Dialog Samples for Rooms and Worlds.

• Enter Play Mode Options (No Domain Reload) is now fully supported.

• CoherenceSyncConfigRegistry: Added new ScriptableObject to soft reference CoherenceSync assets in runtime and serialize how they are loaded and instantiated.

• INetworkObjectProvider: Added runtime interface to be able to customize how CoherenceSync assets are loaded, with three default implementations (Resources, Direct Reference and Addressables)

• INetworkObjectInstantiator: Added runtime interface to be able to customize how CoherenceSync prefabs are instantiated, with three default implementations (Default, Pooling and DestroyCoherenceSync)

• CoherenceSyncConfigUtils: Editor public API to be able to add, delete and browse CoherenceSync assets, aswell as start or stop syncing variables via scripting.

• CoherenceSync Objects Editor Window: New Editor window to be able to browse CoherenceSync assets, found under coherence => CoherenceSync Objects menu item.

• UniquenessManager: Encapsulated uniqueness logic under CoherenceBridge.UniquenessManager, where you will be able to register unique IDs at runtime.

• AuthorityManager: Encapsulated authority transfer logic under CoherenceBridge.AuthorityManager, where you will be able to send authority transfer requests without accessing the CoherenceSync directly.

• ReplicationServerRoomsService: non-static public API to be able to create, delete and fetch rooms from self-hosted Replication Servers.

• CoherenceSync: Rigidbody Update Mode.

• CoherenceSync: Advanced Uniqueness Options.

• CoherenceSync: CoherenceBridge resolver API.

• Coherence.Editor.UploadBuildToCoherence API.

Changed

• CoherenceSync: CoherenceSync instances are now automatically synced and unsynced with the network in the OnEnable/OnDisable methods, instead of Start/OnDestroy.

• CoherenceSync: CoherenceSync instances can now be disabled and reused for different network entities, which allows for object pooling to happen.

• CoherenceSync Baked Scripts: Baked scripts for CoherenceSync prefabs are no longer MonoBehaviours.

• Uniqueness: Improved handling unique IDs for Unique CoherenceSyncs when creating serialized scene Prefab instances.

• Updated JWT to 10.0.2.

• Reworked AutoSimulatorConnection component.

Fixed

• ParrelSync/symlink support: avoid read exceptions on Gathered.schema.

• CoherenceSync: Initialization of disabled objects.

• CoherenceSync: adding the component to a Prefab no longer deselects it.

• Source Generator: avoid running on IDEs, to avoid IO-related exceptions.

• Simulator Slug not being encoded correctly.

• CoherenceNode: race condition when setting parent.

Removed

• PrefabMapper has been removed in favor of CoherenceSyncConfigRegistry.

• NetworkTime.Time

Deprecated

• PlayResolver API: Play, PlayClient and PlayResolver have been deprecated in favor of CloudService API.

• Sample UI: the old Sample UI that depended on the PlayResolver API has been deprecated in favor of the new Unity Package Samples.

• CoherenceUUID: This Component is no longer needed and it has been deprecated, the functionality has been baked into the Editor and now works automatically. Prefabs that use this Component can stop using it.

• CoherenceMonoBridgeSender: This Component is no longer needed and it no longer has any functionality, it can be safely removed.

• Client Connection Prefab References: References to the Prefabs in CoherenceBridge have been deprecated. Please use CoherenceSyncConfig references instead.

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.

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

• Floating Origin for extremely large virtual Worlds

• TCP Fallback

• Support for Client hosting through Steam Datagram Relay

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)

• Extendable object spawning strategies (Resources, Direct References, Addressables) or implement your own

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

• Network profiler

Online

• Brand new developer portal for management and usage statistics

• Automatic server deployment and scaling

• Multiple regions in the US, Europe and Asia

• Player accounts with a persistent key/value store

• Matchmaking and lobby rooms

Coming soon

General

• Float64 support

• Permissions and roles system for clients and simulators

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

Mid-term roadmap

• 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

• 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

Multi-Room Simulators throw errors in 1.1.0 - 1.1.4 versions of coherence

A fix for this is expected to arrive in version 1.1.5 of coherence very soon. Until that materializes, feel free to check out our on this topic that includes a workaround.

Byte arrays don't sync when changing values by index

When binding a byte[] field, the field will not be synced when changed by someField[x] = y. The only way to actually update the field, is through someField = new byte[]... which assigns a new reference.

Warning messages when running GGPO network rollback

We have identified a misprediction bug in coherence 1.1.3 and earlier versions that causes a failed rollback right after a new Client joins a session, throwing relevant error messages. However if the Client manages to connect, this won't affect the rest of the simulation. The fix should ship in the next release.

Warnings about missing hashes

If you're getting errors such as the ones below, the issue is that your Prefab has multiple AnimationControllers, but coherence only supports a single AnimationController.

Parameter 'Hash 1963678224' does not exist.

CoherenceSync: We can't find any binding for component 'GenericFieldQuaternion0' when receiving a component update.

Importing a Sample shows missing scripts and/or errors on save

If you see missing scripts on freshly imported samples, like this:

Or see an error on saving a prefab from the sample:

Delete the sample itself (mind any modifications you might have done), close Unity and delete the Library folder. Note that by doing so you're forcing a reimport of all your assets, which might take time depending on your project size.

Changing parent teleports the Entity to world zero for a frame

When using CoherenceNode on your CoherenceSync, if CoherenceNode's networked variables have interpolation applied, you'll experience this issue. Turn off interpolation for such variables.

CoherenceSync Prefab instances on the scene not appearing when using "No Duplicates" uniqueness setting

This can happen if coherence fails to set a Unique ID on your scene instances. Check the CoherenceSync inspector on Prefab instances. Look for Prefab Instance Unique ID. Click the button to generate an ID. Do this for every Prefab instance that is missing its ID.

Alternatively, you can set a Manual Unique ID of your own on the Prefab itself or per-Prefab instance on your scene.

Types missing the ExtensionOfNativeClass attribute

Reimport assets via menu item Assets / Reimport All.

Scripts losing references to Prefabs, Fix Serialized Data button appears

The Optimize window stops rendering components

I can't see Rooms or Worlds

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

Prefab Variants use 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. You can prune within the Configure window.

Binding is interpolated into correct position after instantiating

The current recommended workaround is to make sure that the Prefab has initial values set before instantiation. Or in the case of position and rotation, those could be directly supplied to Instantiate() instead of setting them later in the frame.

Source Generator Baking Strategy and CI setups

The source generator relies on an auto-generated configuration file to inject the baked code into Unity's Assembly-CSharp.dll. Such file will not be available on a fresh, non-cached project (i.e., no Library), such as a Continuous Integration setup.

The SDK doesn't offer yet an API to initialize the source generator from code.

If you experience issues, switch to Assets strategy in your CI setup. You can keep using the source generator to develop locally, since either baking strategy can be used interchangeably, and the generated code is the same.

Clicking on a Prefab instance logs "CoherenceSyncEditor: Upgraded legacy archetype name on the CoherenceSync Prefab instance"

If you see this message, the CoherenceSync Prefab instance has been modified to point to the correct archetype name. If that's the case, select every CoherenceSync Prefab instance on your scene(s) to make sure this fixup happens. Even if you don't see the message, you're good to go. Make sure you save your project (Ctrl+S) to apply the changes (if any) to disk.

InvalidOperationException: Insecure connection not allowed