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.

Unity Requirements

• Unity 2020.1.9f1 or later.

• A Windows, Linux or Mac system.

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.

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.

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

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

Build the game

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

In the coherence menu in Unity select "Share -> Build Upload"

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

Now we can finally deploy our schema and replication server into the cloud.

Upload schemas

In the Project Settings tab for coherence, click on Upload.

The status should change from "Unknown" to "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

When you run the project now, you will notice that the Connect Dialog now contains additional address(-es). The Connect Dialog uses the to fetch all the addresses available for your project. This depends on the project configuration (e.g. the regions that you have selected for your project).

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.

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

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

Running a Replication Server Locally

You can run a local replication server from the coherence menu by clicking:

coherence -> Server -> Run Local Server.

Setup Video Tutorial

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

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

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

coherence is currently in private preview. Some stability and performance issues may still be present and being ironed out. Additionally, more features are planned for the public release later this year.

Current features

Install Video Tutorial

Unity Package Manager

Networked entities can be simulated either on a game client ("client authority") or a simulation server ("server authority).

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 replications server and replication server to client 2).

Extrapolation or "dead reckoning" uses historical data to predict the future state of a component. The actual network data that arrives later can be used to interpolate or snap the predicted values to the correct ones.

Sometimes you want to synchronize entities that are connected to other entities. These relationships can be references between entities, but they can also involve direct parent-child relationship between game objects, or more nuanced use cases.

Here's a guide for what technique to use, depending on the situation:

• If you have an entity that needs to keep a nullable reference to another entity, use a normal Entity reference. This includes any existing MonoBehaviour that has GameObject or Transform fields that you want to synchronize over the network.

• If the entities are placed in a hierarchy, use the techniques for parent-child relationships.

coherence Network Playground Unity Project Zip

coherence Network Playground (Unity Version 2020.3.13f1 or later)

Refer to the Level of detail section for more information.

Baking Video Tutorial

Overview

Out of the box, coherence will use C# Reflection to sync all the data at runtime. This is a great way to get started but it is very costly performance-wise.

For optimal runtime performance, we need to create a schema and perform code generation specific to our project. Learn more about this in the section.

coherence offers an automatic way of doing that called baking.

Bake schemas

Click on coherence -> Schema and Baking -> Bake Schemas.

This will go through all CoherenceSync components in the project and generate a schema file based on the selected variables, commands and other settings. It will also take into account any CoherenceArchetype components.

For every prefab with a CoherenceSync object, the baking process will generate a bespoke C# file in the coherence/baked folder in the project.

Adding that file to the prefab will make that prefab use bespoke generated code instead of C# reflection.

Activate baked schema on prefab

Once the Schema has been baked, you will be able to switch to baked mode in the CoherenceSync inspector.

The name of the baked script will be CoherenceSync[prefabName].

Modifying bound data, safe mode and the watchdog

When you bind to your script's fields and bake, coherence generates specific code that accesses your code directly, without using reflection. This means, whenever you change your scripts, you might break compilation.

For example, if you have a Health.cs script which exposes a public float health; field, and you mark health as a binding in the Bindings window, the baked script will access your component via type name, and your field via field name.

Your baked script might now reference your component:

This means that if you decide to change your component name (Health) or your any of your bound field names (health), Unity script recompilation will fail. In this example, we will be deprecating health and adding health2 in its place.

Our watchdog is able to understand when this happens, and offer you a solution right away.

It will suggest you to bake in safe mode, and then diagnose the state of your prefabs. After a few seconds of script recompilation, you'll be presented with the diagnosis window.

In this window, you can easily spot bindings in your prefabs that are no longer valid. In our example, health is no longer valid since we've moved it elsewhere (or deleted it).

Click on the hand pointing button to open the bindings window, and take a look at your script:

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

CoherenceSync configuration

The CoherenceSync editor interface allows us to define the Lifetime of a networked object. The following options are available:

• Session Based. No persistence. The entity will disappear when the client or simulator disconnects.

• Persistent. The entity will remain on the server until a simulating client deletes it.

Persistence UUID

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

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

Deleting a persistent object

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

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

Bandwidth is limited

No matter how fast the internet becomes, conserving bandwidth will always be important. Some game clients might be on poor mobile networks with low upload and download speeds, or have high ping to the replication server and/or other clients, etc.

Additionally, sending more data than is required consumes more memory and unnecessarily burdens the CPU and potentially GPU, which could add to performance issues, and even to quicker battery drainage.

Optimization techniques

In order to optimize the data we are sending over the network, we can employ various techniques built into the core of coherence.

• Delta-compression (automatic). When possible, only send differences in data, not the entire state every frame.

• Compression and quantization (automatic and configurable). Various data types can be compressed to consume less bandwidth that they naturally would.

• Simulation frequency (configurable). Most entities do not need to be simulated at 60+ frames per second.

Why does world size matter?

Positions and livequeries in the world are compressed, and the compression is defined by maximum scale and bit count. Larger scale at the same bit count means lower precision, and vice-versa.

Defining world size

A default maximum world size of 2400 means that only values from [-2400, 2400] will be supported for all spatial axes.

If our game scenes are larger than 2400 x 2 (4800) units across, we can increase this value in the Settings window or in the schema as illustrated below.

Don't forget to extend the LiveQuery scale to match the world position scale.

Persistence in memory

All persistent objects remain in the world for the entire lifetime of the replication server. But what happens when the replication server is restarted or goes offline?

Persistence Client

Persistence Client is a special utility that runs alongside the replication server and records the state of the world and saves it to physical storage. If the replication server goes offline, the Persistence Client will backup the entire state of the world.

General Set up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail on page.

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

In This Scene...

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

The MonoBridge is a system that makes sure every GameObject is linked to its networked representation. It essentially interfaces between the GameObject world and the DOTS/ECS-based coherence SDK code running "under the hood".

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.

Overview

The state of network entities that are currently not simulated locally (either because they are being simulated on another game client or on a simulator) cannot be affected directly.

Network can help us affect state indirectly, but for anything more involved, an authority transfer might be necessary.

Persistent vs. session-based entities

When we connect to a game world with a game client, the traditional approach is that all entities originating on our client are session-based. This means that when the client disconnects, they will disappear from the network world for all players.

A persistent object, however, will remain on the replication server even when the client or simulator that created or last simulated it, is gone.

This allows us to create a living world where player actions leave lasting effects.

In a virtual world, examples of persistent objects are:

If we don't do any special configuration, entity data is captured at the highest possible frequency and sent to the replication server. This often generates more data than is needed to efficiently replicate the entity's state across the network.

Global simulator frequency

On a simulator, we can limit the framerate globally using Unity's built-in static variable targetFrameRate.

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 around to look in a dark cave.

What is the Developer Portal?

The developer portal is an online dashboard where the cloud services behind your coherence-based game can be managed. It can be found at or from the Developer Portal link above.

The developer portal includes:

Animation & Variables

This scene will show you how easy it is to set up Networking in your Unity project and sync GameObject transforms, animations via the Animator parameters and customer variables.

In this example, each client will have its own player character to move, the beloved Unity RobotKyle asset. Type your name into the connect dialog box and connect. You can move around with WASD. When another player connects, their name is carried across and their transform and animation state is replicated.

Network Playground Project

Overview

The coherence Cloud API allows us to access online services like game accounts, key-value store, matchmaking, and others. It also allows you to get the addresses (IP and port number) of the servers the players can connect to.

The Cloud API requires you to use.

Here is a sample script showing how you can use the server discovery API to get the servers associated with your runtime key.

Besides the core replicator and simulator, coherence offers additional services to enhance your game's experience and we are constantly working on more.

Currently available services are:

Motivation

coherence provides an API for creating player game accounts that uniquely identify players across multiple devices. An account is required in order to use the rest of the online services, like the key-value store and matchmaking.

After creating an Organization and Project, (see ), your Developer Portal home page will be the Dashboard.

Here you can find:

• Your Portal token

• The status of your replication, simulation, and persistence resources

Transforms

Welcome to the first scene of the coherence Network Playground. This scene will show you how easy it is to set up networking in your Unity project and sync GameObject transforms across the network.

In this example, each client will have a player character to move by clicking on the map to make the entity move to that location. Each client will only have control of its local entity.

Sending Network Commands

This scene will show you how easy it is to set up Networking in your Unity project and send Network Commands to other clients. Network Commands is like sending a direct message to another player, without anyone else knowing.

In this example each client has one character they can control with click to move input. They can right-click on another Entity to send a command and that Entity will instantiate an Exclamation mark above their head.

Motivation

coherence provides a powerful matchmaking API with various different setups (multiple teams, team sizes, etc.).

Configuration

Overview

Objects with the CoherenceSync component can be connected to other CoherenceSync components with 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.

Currently, resource usage resides on the Dashboard. A dedicated Resource Usage to help understand your costs and usage is coming soon.

• Replicator - the CPU/Memory and Bandwidth usage of your replication servers per region

For anyone building WebGL in Linux: you need to install these packages: sudo apt install clang libtinfo5 python python-setuptools

For running a WebGL build locally, please refer to the .

Archetype

Group of Components that define a type. Makes use of LODs.

Client

Allows a User to interact with the World. Connects to Replication Server.

Client connection​

An object representing a client connected to the Replication Server. Required for the client messages.

Client message​

A message sent to a client connection.

Command

Allows for sending an instruction to an Entity that may be running on a different machine.

Component

Part of ECS. Describes a characteristic or aspect of an Entity.

ECS

Stands for Entity Component System. An entity system where entities are made of components.

Entity

An instance of an Archetype. Part of ECS.

Live Query

Allows the Client to specify a subset of the World to receive updates from. Acts as a filter to exclude updates on less relevant entities that could otherwise result in undesired latency.

LOD

A partial representation of an Archetype. Allows for specifying priorities of components within an Archetype.

Protocol Code Generator

Generates the client schema source file (e.g. schema.cs) that automatically handles serialization/deserialization of an ECS world and commands.

Replication Server

Replicates the state of the world to the connected Clients and Simulators.

Simulator

Responsible for simulating a subset of the game world. Connects to Replication Server through which the state gets replicated to Clients.

Unreal Engine support is planned for a future release of coherence.

Check back here for more news or contact [email protected] for more information or collaboration options.

You can also join our Discord to get in touch with the team directly.

Physics & Persistence

This scene will show you how easy it is to set up Networking in your Unity project and sync GameObject transforms and Physics objects across the network whilst keeping them persistent. As long as the server is running you can disconnect and re-connect, your world will persist.

In this example each client will have it's own player character to move, we will click on the map to make the entity move to that location, simple click to move functionality and right click to spawn local physics based objects that all other player characters can interact with. Each client will only have control of its local entity. You can disconnect and re-connect and the persistent entities will all remain.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail on page.

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

Coherence Connection Events handles overall Scene connectivity. Additionally, it removes all Entities with coherenceSync from the Scene to demo disconnection/reconnection via the Interface without refreshing the Scene.

In This Scene...

The Physics Entity Spawner component is a simple script to instantiate a Coherence Entity Physics Persistent prefab with a coherenceSync component that replicates the transform and position. The component also changes the material based on if it is locally simulated or synced over the network.

Coherence Entity Physics Persistent has Entity Lifetime Type set to Persistent. This means it will remain in the world as long as the replication server is running, even if all clients disconnect. It also has Authority Transfer Style set to Stealing which means the entity can be "stolen" and simulated on a client requesting authority.

The Auto Generate Persistance UUID should be checked so that a unique identification string will be used to identify instances of this entity as unique. When the entity is spawned with this checked, it will generate its own UUID.

This is done via the Input Manager in the Core Scene Setup prefab. When the object is left-clicked, it sends the message "Adopt" to the GameObject on the specific Layer Mask "Physics Entities". The component called Coherence Handler on Coherence Entity Physics Persistent handles the Adopt call and requests the authority change via the coherenceSync component.

Coherence Handler is a basic layer for handling Commands and Events, both sending and receiving. You can create your own or reuse and extend this for your project.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

Physics

This scene will show you how to use coherence to sync GameObject transforms and Physics objects across the network.

In this example, each client will have its own player character to move. Left-clicking on the map will make the entity move to that location. Right-clicking will spawn local physics based objects that all player characters can interact with. Each client will only have control over its local entity.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail on page.

Coherence Entity is the prefab that will change per Scene with different functionality. It has a standard CharacterControllerand Rigidbody as well as an Agent script which will handle movement functionality through the Input Manager in the Core Scene Setup prefab.

Coherence Connection Events handles overall Scene connectivity. Additionally, it removes all Entities with coherenceSync from the Scene to demo disconnection/reconnection via the Interface without refreshing the Scene.

In This Scene...

Coherence Entity Character (always change the prefab, not the instance) is located in the Resources folder. The UnityEngine.Transform and position are ticked to sync. All other settings (persistence and authority) use the default settings. This entity will be session based, no authority handover and no adoption will take place, when a client leaves.

The On Network Instantiation event is used to change the colour of the mesh.

The Physics Entity Spawner is a simple script to instantiate a Coherence Entity Physics Prefab with a coherenceSync component that replicates the transform and position. The component also changes the material based on if it is locally simulated or synced over the network.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

AI Navigation, Session Based NPC's

This scene will show you how easy it is to set up Networking in your Unity project and sync non player characters that move around the world via Unity's Navmesh system.

In this example each client can spawn as many navigation agents as they wish, and these navigation agents will move intermittently to different locations on the grid. All navigation agents will be replicated across clients with a specific colors signifying if they are local or networked.

General Set Up

In the Hierarchy of the Scene you can see three core Prefabs:

Core Scene Setup and Coherence Setup are present in all scenes and described in detail on page.

Coherence Connection Events handles overall Scene connectivity. Additionally, it removes all Entities with coherenceSync from the Scene to demo disconnection/reconnection via the Interface without refreshing the Scene.

In This Scene...

Spawner is a simple script to instantiate a Coherence Entity Nav Agent prefab with a coherenceSync component that replicates the transform and position. The component also changes the material based on if it is locally simulated or synced over the network.

Coherence Entity Nav Agent has a Nav Mesh Agent component controlled via the Navigation Agent script which every few seconds sets a new destination on the grid. It's not required to sync anything other than the Transform; position, rotation parameter as the Nav Mesh Agent settings only need to simulate locally.

Build and Try

You can build this Scene via the Build Settings. Run the local Replication Server through the Window -> coherence -> Settings window and see how it works. You can try running multiple clients rather than just two and see replicating for each.

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 around to look in a dark cave.

Adding a LiveQuery to the scene

A LiveQuery is a cube that defines the area of interest in a particular part of the world. It is defined by its position and its radius (half the side of the cube). There can be multiple LiveQueries in a single scene.

Moving a LiveQuery

A classic approach is to put a LiveQuery on the camera and set the radius to correspond to the far clipping plane or visibility distance.

Moving the GameObject containing the LiveQuery will also notify the replication server that the query for that particular game client has moved.

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 Bindings window:

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

Entity references can also be used as arguments in Commands.

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:

• A client might not have the referenced entity in its live query. A local reference can only be valid if there's an actual entity instance to reference.

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

Choosing Regions

Click one or more regions you would like to run your replication and simulation services in, and click 'Save Regions'.

Size your Replicator

Click a replicator size best suited for the needs of your game and click the 'Save Sizing' button.

Enable and Size the Simulator

To enable the simulator, ensure that the 'Enabled' check box is checked. Choose a simulator size based on the needs of your game.

The coherence Sample UI prefab that comes bundled with the coherence SDK contains some basic UI controls that allows you to easily connect to and disconnect from servers.

The connect dialog lists all available servers for your game. If the list is empty, please make sure you have setup your game on the coherence portal and deployed a replication server. Also make sure you have selected the correct region from the Region dropdown menu.

The connect dialog comes in two flavors, one is for Rooms and the other is for Worlds. The Connect Dialog Rooms is enabled by default. If your project is configured for Worlds, you'll need to select the coherence Sample UI in the Hierarchy window and activate the Connect Dialog Worlds.

Connect Dialog Rooms allows you to create or join rooms on the selected region.

Connect Dialog Worlds allows you to join worlds on the selected region, but you can only create new worlds from the coherence portal.

Coherence.Play.DB

This class provides the methods to set, get and unset key-value pairs. This is executed within the context of the currently logged in player.

public static class KvStore
{
    // Sets a value
    // key: lowercase letters, numbers, underscore, dash
    // val: any string (null is not allowed)
    public static void Set(string key, string val)
    
    // Gets a value
    // key: lowercase letters, numbers, underscore, dash
    public static string Get(string key)
    
    // Unsets a value, removing it from the store
    // key: lowercase letters, numbers, underscore, dash
    public static void Unset(string key)
}

Example

Limitations

Size: there are no limits to the number of stored key/values as long as the total size is less than 256kb.

Requests: Set/Get/Unset can be called unlimited amount of times but the execution may be throttled.

Portal Token

The token you get when creating a project on the developer portal.

You paste it in the Project Settings.

Runtime Key

Once you have pasted the portal token successfully, you need to fetch the runtime key as well.

You can fetch the by clicking on the down-arrow button on the right side of the input field.

coherence allows us to use multiple simulators to split up a large game world with many entities between them. This is called spatial load balancing. Please refer to the section about simulators for more information.

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

1. Create a prefab and move it to Resources

Add an asset and create a prefab of it. Make sure the prefab is in a Resources folder in your Unity project.

Here is an example:

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

Build and Run Server

The coherence Settings window is located in Project Settings -> coherence and lets you launch a local replication server, upload your server to the cloud via the access token and bakes your Schemas for more optimized data transfer of Networked GameObjects.

Enable CoherenceSync support

Uncheck Enable CoherenceSync support

Many of the primitive data types in coherence supports configuration to make it possible to optimize the data being sent over the network. These settings can be made individually for each field of a component and will then be used throughout your code base.

Syntax

The field settings uses the meta data syntax in the schema, which looks like this:

The meta data always goes at the end of the line and can be set on both definitions and the fields within a definition, like this:

In this example, an ECS component named Health would be created, but instead of using the default 24 bits when sending its value, it would just use 8. Any updates to it would also be deprioritized compared to other components, so it could potentially be sent a bit late if bandwidth is scarse.

What is a simulator?

A simulation server or simulator is 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.

SDK Overview

The coherence SDK is a set of prefabs & scripts to help you create multiplayer games super fast.

It makes it easy for anyone to create a multiplayer game by having flexible, intuitive and powerful visual components.

Here are the main building blocks of the SDK.

The schema has two uses in your project:

1. As a basis for code generation, creating various structs and methods that can be used in your project to communicate with the replication server.

2. As a description for the Replication Server, telling it how the data in your project looks like – to receive, store, and send this data to its clients.

When using MonoBehaviours and CoherenceSync you often don't need to interact with the schema directly.

If you're writing your game using ECS/DOTS you will have to create and modify it yourself. Here's an example of a small schema:

Motivation

coherence provides an API and a database for storing key-value pairs from within game sessions.

Description

Coherence.Play.Matchmaking

The matchmaking module has only one method.

// Invoked on success/failure
public delegate void OnMatch(Result result, MatchResponse match);

// The data for every player returned by the matchmaking request
public struct PlayerPayload
{
    public string user_id;
    public string team;
    public int score;
    public string payload;
}

// The response of the matchmaking request
public class MatchResponse
{
    public string match_id;
    public PlayerPayload[] players;
    public string error;
}

public static class Matchmaker
{
    // Sends matchmaking request.
    // region:  matchmaking region, e.g. eu, us, ...
    // team:    team name
    // payload: custom string that will be send to all other players
    public static void Match(string region, string team, string payload, OnMatch callback)
    
    // Sends a matchmaking request
    // region:  matchmaking region, e.g. eu, us, ...
    // team:    team name
    // payload: custom string that will be send to all other players
    // tags:    custom tags to segment the player pool, e.g. "level1", "qa", etc
    // friends: group the player with his friends. If any of the friends doesn't show up the request will fail
    public static void Match(string region, string team, string payload, string[] tags, string[] friends, OnMatch callback)
}

Example

This document explains how to set up an ever increasing counter that all clients have access to. This could be used to make sure that everyone can generate unique identifiers, with no chance of ever getting a duplicate.

By being persistent, the counter will also keep its value even if all clients log off, as long as the replication server is running.

The Counter

First, create a script called Counter.cs and add the following code to it:

using UnityEngine;
using Coherence.Toolkit;

public class Counter : MonoBehaviour
{
    public int counter = 0;

    public void NextNumber(CoherenceSync requester)
    {
        requester.SendCommand<NumberRequester>(
            nameof(NumberRequester.GotNumber), 
            MessageTarget.AuthorityOnly,
            counter);
        counter++;
    }
}

Next, add this script to a prefab with CoherenceSync on it, and select the counterand the method NextNumber for syncing in the bindings window. To make the counter behave like we want, mark the prefab as "Persistent" and give it a unique persistence ID, e.g. "THE_COUNTER". Also change the adoption behaviour to "Auto Adopt":

Finally, make sure that a single instance of this prefab is placed in the scene.

NumberRequester

Now, create a script called NumberRequester.cs. This will be an example MonoBehaviour that requests a unique number by sending the command GetNumber to the Counter prefab. As a single argument to this command, the NumberRequester will send an entity reference to itself. This makes it possible for the Counter to send back a response command (GotNumber) with the number that was generated. In this simple example we just log the number to the console.

To make this script work, add it to a prefab that has the CoherenceSync script and mark the GotNumber for syncing in the bindings window.

Am I a simulator?

Ask Coherence.SimulatorUtility.IsSimulator.

There are a few ways you can tell coherence if the instance should behave as a simulator:

• Specifying a ConnectionType when connecting via Coherence.Network.Connect.

• COHERENCE_SIMULATOR preprocessor define.

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

• Toggling on Simulator in the sample connection dialog.

Connect and ConnectionType

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

COHERENCE_SIMULATOR

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

Command-line argument

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

Server-side simulation

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

Auto-reconnect

The provided includes auto-reconnect behaviour out of the box for simulators. The root GameObject has an AutoReconnect component attached to it.

If you need a different solution, take a look at its implementation use plug your own.

The Network Playground project is a series of scenes with different features of coherence for you to pick through and learn.

They will teach you the fundamentals that should set you on your way to creating a multiplayer game.

Scenes

Each Scene in this Network Playground Project shows you something new:

• Scene 1. Synchronizing Transforms

• Scene 2. Physics

• Scene 3. Persistence

• Scene 4. Synchronizing Animations and Custom Variables

• Scene 5. AI Navigation

• Scene 6. Network Commands

• Scene 7. Network Teams

Each scene comes with a few helpful core components.

Core Scene setup

This Prefab stores all the generic things that make up these simple Scenes.

• Main Camera

• Global Volume

• Directional Light

• Environment (Ground, Walls etc)

coherence Setup

This Prefab includes all of the things that make coherence work.

• Interface

  • Canvas UI that handles Connection/Disconnection dialog and what address to connect.

• Event System

coherenceSync (on coherence Entity Prefab)

We use this component on anything that we require to be networked, whether this is a playable character, NPC (non playing character), an object (ball, weapon, banana, car, plant etc) or any Game/Input Managers that require to sync data between Clients/Simulators/Servers.

It scans the inspector for attached components and allows us to sync those component values (as long as they are public) and communicate them to other clients. It also allows us to set individual Prefabs persistent, authoritative and network connect/disconnect settings. There's much more information on the page.

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

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

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

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

1. Run the Replication Server by clicking the run button.

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

3. The port the Replication Server will use. Default: 32001.

4. The Replication Server frequency. Default: 60.

To connect with multiple clients locally, publish a build for your platform (File > Build and Run, details in ). Run the Replication Server and launch the build any number of times. You can also enter Play Mode in the Unity Editor.

Connecting to a Replication Server

When the replication server is running, you connect to it using the Connect command from one of your component systems.

Connect to a Replication Server

After trying to connect you might be interested in knowing whether the connection succeeded. The Connect call will run asynchronously and take around 100 ms to finish, or longer if you connect to a remote server. One way is to poll the once each tick until we know that it has succeeded. It is also possible to listen for a [network event]().

Check if we are connected

Make sure that your system is actually run, for example by adding the [AlwaysUpdateSystem] attribute to your system class. By default, Unity ECS will not run your system if it doesn't process any Entities.

Basics

Level of Detail (or LOD-ing, for short) is a technique to optimize the amount of data being sent from the replication server to each client. Often a client doesn't need to get as much information about an entity if it's far away. The way this is achieved when working with coherence is by using archetypes.

Archetypes let you group components together and create distinct "levels of detail". Each such level must have a distance threshold, and a list of components that should be present at that distance. Optionally it can also contain per-field overrides that make the primitive data types in the components take up less space (at the cost of less precision.)

To define an archetype, use the archetype keyword in your schema, then list the LODs in ascending order. Notice that LOD 0 does not need a distance, since it always starts at 0. Here's an example of a simple archetype:

In this example, any Enemy entity that is 200 or more units away from the live query of a particular client will only get updates for the WorldPosition. Any client with a distance of 10 – 200 will get WorldPosition and WorldOrientation, and anything closer than that will get the full entity.

Given one or more archetype definitions in your schema, you will have access to a few different data types and methods in your project (these will be generated when you run the Protocol Code Generator.)

• ArchetypeComponent – this component has a field index that keeps track of which one of the archetypes in your schema that is being used. If you add the ArchetypeComponent yourself you have to use the static constants in the Coherence.Generated.Archetype to set the index. These all have the name "archetype name" + "Index", e.g. EnemyIndex in the example above.

• An individual "tag" component (with no fields) called "archetype name" + "Archetype", e.g. EnemyArchetype in the example above. This component can be used to create optimized ForEach queries for a specific archetype.

Field Overrides

If a component isn't present at a certain LOD, no updates will be sent for that component. This is a great optimization, but sometimes a little too extreme. We might actually need the information, but be OK with a slightly less fine-grained version of it.

To achieve this, you can use the same field settings that are available when defining components, but use them as overrides on specific LOD's instead.

Here's an example of the syntax to use:

Notice that the settings are exactly the same as when defining components. To override a field, you must know its name (value in this case.) Any field that is not overridden will use the settings of the LOD above, or the original component if at LOD 0.

Priority

Each component in an archetype can also override the default priority for that component. Just add the priority meta data after the component, like this:

To read more about priority, see the page about .

General Updates

• After an sdk upgrade a bake process will be initiated automatically by the sdk to make sure the baked scripts are up to date.

• If you run into any compilation or runtime errors in coherence code after the update these steps might help resolve the issue:

1) Go to coherence -> Schema and Baking -> Bake schemas (Safe Mode)

This will generate baked skeleton scripts which will compile but not work at runtime.

2) Go to coherence -> Schema and Baking -> Bake schemas

To fully generate the baked code (This can also be done via any of the other baking options).

3) This process should handle old bindings which are different on the updated version. If the errors persist check the bindings window for the relevant prefab to make sure they are set up properly then perform steps 1 and 2 again.

SDK Upgrade 0.4.x -> 0.5.0

• Notable api changes you should be aware of:

commands are now called like so:

sync.SendCommand<ComponentType>("CommandMethodName", MessageTarget.All);

For example:

• Notice the MessageTarget parameter and generic type argument which might be missing in the version you were using before.

Method parameters should be added after the MessageTarget parameter.

• Notice the MessageTarget must be set for command methods in the Bindings window as well. If this is not set up in accordance with the way the method is called at runtime the command will not go through and a warning will be given about improper routing.

coherence uses the concept of ownership to determine who is responsible for simulating each entity in the game world. By default, each client that connects to the server owns and simulates the entities they create. There are a lot of situations where this setup is not adequate. For example:

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

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

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

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

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

Creating a simulation server

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

An easier way is to use your existing Unity project and modify it in a way so that it can be started either as a normal game client, or as a simulation server. This will ensure that you maximize code sharing between clients and servers -- they both do simulation of entities in the same game world after all.

To determine whether to start a build as client or simulation server, you can use command line arguments:

Reading command line arguments

To pass the command line argument, start the application like this:

When building stand-alone builds, Unity also has an option for . This is great for simulation servers since we're not interested in rendering any graphics on these anyway, and you can use it from code. By using headless mode we get a leaner executable that is easier to deploy in the cloud.

To build server build change your build target to be Linux and tick Server build.

Build and deploy

Refer to the .

Overview

Commands are network messages sent from one entity to another entity in the networked world. Commands bind to public methods accessible on the GameObject that CoherenceSync sits on.

Design Phase

In the design phase, you can expose public methods the same way you select fields for synchronization: by using the Select Bindings interface on your CoherenceSync object.

Selected public methods will be exposed as network commands in the .

The button on the right of the method lets you choose the routing mode. Commands with aSend to authority mode can be sent only to the authority of the target entity, while ones with the Send to all instances can be broadcasted to all clients that have a copy of this entity. The routing is enforced by the Replication Server as a security measure so the outdated or malicious clients don't break the game.

The resulting schema section will look something like this:

where routing metadata can have the following values:

• "All" - (Send to all instances equivalent)

• "AuthorityOnly" - (Send to authority equivalent)

Sending a Command on a Networked Object

To send a command, we call the SendCommand method on the target CoherenceSync object. It takes a number of arguments:

• The type argument (within the <and>) must be the type of the recieving MonoBehaviour. This ensures that the correct method gets called if the receiving GameObject has components that implement methods which share the same name.

• The first argument is the name of the method on the MonoBehaviour that we want to call. It is good practice to use the C# expression when referring to the method name, since it prevents accidentally misspelling it, or forgetting to update the string if the method changes name.

• The second argument is an enum that specifies the

Here's an example of how to send a command:

Receiving a Command

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

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

Sending a Command to multiple entities

Sometimes you want to inform a bunch of different entities about a change. For example, a 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.

In this example, a will get sent to every network entity known to this client. To make it only affect entities within a certain criteria, you need to filter to which CoherenceSync you send the command to on your own.

Supported types in Commands

When a prefab is using reflection there are some restrictions for what types can be sent in a single command:

• 4 integers

• 4 floats

• 4 bools

• 4 entity references

If you ever need to send commands containing any other type (like a vector) or a higher quantity (like two strings) you must mark the prefab to use . This will generate a custom command that can handle all the supported of the coherence SDK.

Primitive Types

These are the primitive types supported in a coherence schema:

Int

Uses a default range of -9999 to 9999.

Float

Uses a default scale of +/- 2400, which is encoded using 24 bits.

Bool

Encoded using a single bit.

Vector2

Encoded using two floats.

Vector3

Encoded using three floats.

Quaternion

String64

The size of a string depends on its length. Try to keep the length of your strings as short as possible, or they won't fit inside a network package.

Bytes4096

An array of bytes with an upper limit of 4094 bytes (2 bytes reserverd for length).

Entity

The Entity type is used to keep references to other Entities. Technically the reference is stored as a local index that has to be resolved to an actual Entity before usage. Also, since a client might not know about the referenced Entity (due to it being outside of its live query) an Entity reference might be impossible to resolve in some circumstances. Your client code will have to take this into account and be programmed in a defensive way that handles missing Entities gracefully.

Field Settings

Several of the primitive types can be configured to take up less space when sent over the network, see .

Components

The most common definition in schemas is components, which correspond to ECS components in DOTS/ECS and to MonoBehaviours in regular Unity code.

The definition takes a name of the component, and on the following lines an indented list of member variables, each one followed by their primitive type (see above.) The indentation has to be exactly 2 spaces. Here's how it might look:

After code generation, this will give access to a component with the name Portal that has the members locked, connectedTo, and size.

Optionally, each member/type pair can have additional meta data listed on the same line, using the following syntax:

This is how it might look in an actual example:

Built-in components

There are some components that are built into the Protocol Code Generator and that you will always have access to.

Archetypes

Archetypes are used to optimize the sending of data from the server to each client, lowering the precision or even turning off whole components based on the distance from the live query to a particular Entity. Read more about how to define them in the schema on the page .

Commands

Commands are defined very similarly to components, but they use the command keyword instead.

Here's a simple example Command:

Routing defines to whom the command can be sent. Currently two values are supported:

• AuthorityOnly - command will be received only by the owner of the target entity

• All - command will be received by every client that has a copy of this entity

When using reflection, there are limitations to what types are supported in commands. See the section for more information.

Build a simulator to be uploaded to the cloud

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

On Unity's menu bar, navigate to coherence -> Simulator -> Build Wizard.

From within the Build Wizard you can build and upload simulators.

The Info tab provides information and requirements to build simulators properly.

The Build tab creates valid simulator builds from Build Configuration Assets.

Creating a Build Configuration Asset

You can create them via Assets -> Create -> coherence -> Simulator Build Configuration.

A newly created build configuration looks like this:

There are several settings you might want to change.

• Specify the scenes you want to get in the build via the Scene List component.

• Specify a Company Name and a Version from the General Settings component (optional).

• Additionally, you can add our OptimizeForSize component (find it using Add Component). Specify which optimizations you want to use to reduce the final build size from the Optimize For Size component (optional).

Reducing simulator build size (experimental ⚠️)

You can add an OptimizeForSize component to your build configuration via the Add Component in the build configuration inspector. It looks like this:

Select the desired optimizations depending on your needs.

Upload your simulator

Once you have created a valid simulator build, you can upload it to coherence.

If you built your simulator using the Build tab, you should have a valid path to your simulator build set already. If you haven't or want to use a different path, use the Browse button.

You'll see in the developer dashboard when your simulator is ready and running.

Initialization

To initialize the Cloud API you need to provide a Runtime Key that can be obtained from the settings.

Callbacks

Guest Account

The easiest way to get started is by using a guest account. The only thing that is needed is to call LoginAsGuest. This will create a random username / password combination and will authenticate the player with the coherence Cloud.

Once logged in, the credentials are securely persisted so if the game is restarted the player will be able to log in automatically.

If the game is uninstalled then the account credentials will be lost and a new guest account will be created next time the game is installed.

User Account

Another alternative is to login with a username and a password. You have to provide the user interface.

Example

This example initializes the Cloud API, checks for an existing session and, if no session was found or if it expired, logs in the player as guest.

CoherenceSync is a component that should be attached to every networked Game Object. 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 game object, you automatically become the owner of that game object. 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 Type

When a player disconnects, all the game objects created by that player are usually destroyed. If you want any game objects to stay in the game world after the owner disconnects, you need to set Entity lifetime type of that game object to Persistent.

• Session Based - Will be removed when the client disconnects

• Persistence - Entities with this option will persist as long as the server is running. Auto Generate Persistance UUID should be checked so that a unique identification string will be used to regenerate the object when you reconnect to the server. When the entity is spawned with this checked it will generate its own UUID.

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

Authority Transfer Style

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

• Stealing - Allows the game object to be transferred to another client.

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

Orphaned Entities

By making the game object persistent, you ensure that it remains in the game world even after its owner disconnects. But once the game object 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 game object.

In order to make the orphaned game object interactive again, another client needs to take ownership of it. To do this, you need to set When orphaned to Auto Adopt.

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 game object:

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

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

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

Connection Status

When this object is synchronized over the network lets you set if you instantiate the specific prefab or an alternative one by giving its name path (Make sure it's in the Resources folder). Very useful if you are setting up a local player (with controls, camera etc) and a variant without those components.

Event system for handling user connection and disconnection. Destroy Component Only is really useful for session based objects that you want to keep "semi persistent" which would be removed when all the clients disconnect.

Bake/Optimize Script

When CoherenceSync variables/components are turned into ECS to send over the network, C# reflection 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 into a Schema.

The schema is a text 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 Inspector of that Game Object called NameOfGameObject_Sync.

OnNetworkedInstantiation and OnNetworkedDestruction

OnNetworkedInstantiation is called when the network entity is instantiated by coherence. This is the best moment to make sure you prepare the GameObject the way you need. For example, disabling colliders or swapping materials.

OnNetworkedDestruction is called when the network entity is going to be destroyed by coherence. The boolean parameter it takes reports if the destruction behavior is set to just destroy CoherenceSync rather than the Game Object.

Commands

Refer to the section.

What are Input Queues?

Input queues enable a simulator to take control of the simulation of another client's objects based on the client's inputs.

When To Use Input Queues?

Overview

Client messages are a form of commands that are used for client-to-client communication rather than client-to-entity. To achieve this type of communication a special connection entity is automatically created by the replication server for each connected client. Those entities are subject to a different rule set than standard entities. Connection entities:

• Can't be created or destroyed by the client - they are always replication server-driven

• Are global - they are replicated across clients regardless of the in-simulation distance or radius

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

• Global chat

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

• Server announcements

• Server-wide leaderboard

Enabling client messages

The globality of client messages doesn't fit all game types - for example, it rarely makes sense to keep every client informed about the presence of all players on the server in an MMORPG (think World Of Warcraft). Due to this reason, client messages are turned off by default. To enable client messages:

1. Turn on the global query in the (the Global Query On toggle)

Global query enables querying for entities containing a global component, including a connection entity.

2. Create a class that inherits from the CoherenceClientConnection class

Under the hood, client messages are nothing but sent between the connection entities. Each such entity is represented on the client side by an instance of a CoherenceClientConnection class. Implementing client messages is as simple as adding a new command to our custom connection class:

Next, we have to create a binding:​

3. Create a client connection prefab

This step is described in detail in the . In short, a prefab with CoherenceSync and our PlayerConnection must be created and placed in the Resources directory:​

4. Link the connection prefab to the MonoBridge

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

Connection management

Once we have everything set up, whenever a new client joins an instance of the connection prefab will be created. The instantiated object resembles a client connection and will be kept alive for as long as that client remains connected to the replication server.

To get notified about the creation and destruction of connections we can use the following events:

To get local connection or connection of any client by the ID use the following MonoBridge methods:

The CoherenceClientConnection class exposes the following properties:

Sending client messages

Client messages are sent using the SendClientMessage method of the CoherencePlayerConnection class:

The first message will be delivered only to the player that owns the created connection. The other message will be delivered to all instances of this connection, that is, every player (including the sender) that knows about this connection will receive this message.

If the connection ID of the message recipient is known we can use the MonoBridge to send a client message:

Overview

Depending on the settings in our project, data may not always arrive at a smooth 60 frames per second through the network. This is completely okay, but in order to make state changes (e.g. movement, rotation) appear smooth on the client, we use interpolation.

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

The way interpolation works in coherence is that we wait for three data points and then start smoothing the subsequent values according to the interpolation parameters defined in the schema (or default parameters, if no overrides are present).

Overriding interpolation settings

To override interpolation settings, create a new schema asset via Assets/Create/coherence/Schema. Once created, mark it as an active schema in the settings window.

In this new schema, add an interpolation definition:

This interpolation definition MyInterpolation isn't used yet. We need to tell coherence which component is going to use it. We can associate it to WorldPosition and WorldOrientation:

There are a few fields you can tune to get the most out of interpolation:

• overshootPercentage

  • How far into dead reckoning we can venture when the time fraction exceeds 100%

• overshootRetraction

Interpolation can be overridden globally, per component and per LOD level. Here is a sample schema that defines a named interpolation style OverrideTranslation and uses it for all WorldPosition components.

Here's another example that overrides interpolation for WorldPosition and WorldOrientation:

We need one last piece to tie everything together. We need a way to let our bindings to use this interpolation override. To do so, we can create a custom binding provider that extends how the transform component is bound. Create a file named CustomTransformBindingProvider.cs in an Editor folder (e.g. Assets/Editor), with these contents:

This will use OverrideTranslation interpolation component for WorldPosition, and OverrideRotation for WorldOrientation. You can use any name for these as long as it matches the names you defined in your schema. If you don't want to override one of these, just comment out the assignment you don't need.

After you compile this script, a popup will appear letting you know that your CoherenceSync assets have been updated to point to these new components you defined.

From here on, any additional change to interpolation you want to make, you can adjust the values in the schema and bake again.

Motivation

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

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

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

Some extra scripts that are part of the Network Playground that may be useful