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

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

Fundamentals of networking

This article will try to explain a handful of fundamental concepts that all are central to how networked games work. It does not contain any code examples and tries to not delve into minor details. Instead, its goal is to prepare someone new to the field for thinking about networking from a high-level perspective; what problems can arise and how they are commonly solved. The information in here is very useful for understanding the coherence SDK, but it should also be general enough to be applicable to any other similar networking library.

Synchronizing state

When a game runs on your local computer, it contains a lot of data which is used to model the game. This includes things like animation state, the position and orientation of various game objects, AI calculations, physical forces, among with any gameplay-specific variables. Colloquially we refer to all of this data as state. Efficiently updating state is a hard problem, even for a game that is only running locally.

To create the illusion that you're playing together in the same game world, a networked multiplayer game has to transmit enough of its state to the other players. Since computer networks have limited bandwidth it is absolutely necessary to restrict the amount of data being sent.

Generally speaking, there are two main ways to synchronize state; we can either send inputs, or the updated data itself. It is also possible to mix these approaches in various ways. We will now discuss each of the options briefly.

1. Sending inputs

It is usually possible to enumerate a number of predefined inputs that the players of the game are allowed to perform (e.g. "jump", "run", "activate"). When an input is applied to the local game state, we can also make sure it is simultaneously sent to every other player in the session. If we make sure that each player starts the game in exactly the same state, and make sure that everyone applies exactly the same inputs as everyone else, the game state will appear in sync for each player. For certain types of games, this can save a lot of data from having to be transferred.

A good example might be an RTS game with hundreds of units, where it might be enough to send the coordinates of mouse clicks instead of the location of each unit. This of course requires completely deterministic game logic, which is a challenge in itself.

Another problem is that if there's even the slightest mismatch in inputs, the local game states of the players will begin to diverge. To learn more about this approach (and how to work around some of the problems) see our documentation on GGPO.

It is noteworthy that sending inputs doesn't necessarily require a server; thus it is a great model to be used in a peer-to-peer setting.

2. Sending updates

A second approach is to send the updated data itself. This can often be more costly in terms if data transfer (a single player action can change a lot of local data, which in turn has to be transmitted to the other players). It leads to some nice benefits though; most importantly that game states are allowed to diverge slightly, as long as they have a chance to catch up.

This concept is usually referred to as eventual consistency. Not having a single "initial state" also makes it easier to support features like letting players join late, or backing up the state of the game world.

Since it's the clients that run the simulation locally and then send the updated game state to the server, this setup can be referred to as client-authoritative.

3. Inputs + updates

A third option is a combination of the two solutions above, where clients send inputs but receive updated world data. This requires a central Simulator that is be able to run the game logic. The Simulator is a program trusted by the game developer and it knows how the inputs sent by the players are supposed to affect the game state.

This is a server-authoritative setup; players won't be in charge of the simulation and can't affect the game state directly. This has multiple implications, for example it shifts some of the burden of computation from user devices onto the server. To read more about this approach, see Server-authoritative setup.

It is also worth noting that you can combine client-authoritative simulation with inputs in interesting and useful ways. For example, it is possible to let players simulate some less-critical parts of the game state locally, while still sending inputs for their characters to a central server to be processed.

Common optimizations

As stated before, a game contains a lot of data and it is not feasible to send all of it over the network in a real-time fashion. While using inputs is often the most lightweight choice in terms of data usage, it is common to have to send updates to the game state - both from the client to the server, and vice versa. In both those cases we have to use some optimizations. Here are the most important ones.

By keeping track of what the other players know about the state of your game, it is often possible to avoid a lot of data transfer. For example, a player might drop some game object on the ground and send the new location of it to each other participant. Unless that object moves, it is unnecessary to keep sending the same position over and over. This simple idea is used pervasively in coherence (and other similar networking solutions) to great effect.

It's important to acknowledge that a game sometimes generates many changes in a short timeframe. In such a situation, it is useful to prioritize changes based on how important they are for the particular game in question, while also factoring in how long it has been on hold. This means that an "old" change that doesn't get sent will build up importance and relative priority compared to other changes, eventually getting sent.

Finally, a major way of limiting data usage is to filter out uninteresting information and only send the most important parts based on the needs of each participant, also known as Area of Interest. Most commonly this takes the form of a position-based query. The query will make sure that a specific player only gets updates from objects in its vicinity. Anything far away will simply be ignored, and no data has to be sent. It is also possible to send some (but less detailed) data depending on distance. To learn more about these techniques, take a look at the coherence documentation for Queries and Level of Detail.

The role of a central server

A game can have many users, and to facilitate the optimizations mentioned in the previous section it is necessary to track what each participant knows about the game state (and what they are interested in knowing). Instead of putting this burden on each game client, which entails an additional performance cost and can be hard to coordinate, it is better to make this part of a central server. For coherence, this is named the Replication Server.

In the case of using an input-based setup, there also has to be a central arbiter in charge of handling the received inputs, applying them to the game state, and sending the new game state to each client. In a coherence setup, the simulation of the game (which requires game-specific knowledge) is handled by a Simulator which communicates with the Replication Server.

This modular approach where various tasks are performed by different programs, potentially on different machines or from different physical locations, can help with the scaling of a game if it has many users.

Authority

Most people who play computer games versus other people online want it to be fair, with equal conditions for each player.

If your game is client-authoritative, with clients sending updates of the game state to the server, we can't verify the validity of such an update and it becomes a problem. It would be quite feasible for a savvy player to modify their game and remove certain limitations put there by the game developer.

As an example, a game client could send an update that sets the health of each enemy to 0. To prevent such blatant cheating, it is useful to introduce the concept of authority (also often called "ownership"). This means that the Replication Server keeps track of which client has the rights to update each entity in the game. If an unauthorized update is sent to the server, it is rejected and will not get sent to any other participant.

For an input-based game, the cheating problem is slightly different. Since inputs will have to be applied in the right situation to have any effect, it is much harder to simply set the game state to illegal values. The role of authority in this case is to make sure that no player sends inputs for a game object they shouldn't be able to control.

In many cases it is useful to allow for the transfer of authority. For example, there could be a magical potion that you can drink from in the game. If a player has authority over the potion, she can move it around and drink from it, or refill it. If she then gives the potion to another player, they would get authority over it and the original player would no longer be able to update it.

For certain game objects where we don't trust the players with updating them (or don't want potentially expensive logic to run on their devices) it is also possible to have dedicated machines that have authority over those objects and update them (see Simulators).

Error correction

There are multiple ways of sending data over a network. These are called protocols. When speed is not the single most important factor, TCP is often used. It has mechanisms for checking that the correct information was sent and it will try to resend the information if it was lost along the way to it recipient.

This design does not work well for fast-paced games, since their simulations run at many frames per second. By the time a lost network message has been resent and finally made it to its final address, the information in it will have a high chance of already being outdated.

So instead of TCP, games often use UDP. This protocol is unreliable by design, but coherence adds a reliability layer on top of it. If turns out that an update didn't make it to its recipient, that update will be re-sent, but only after checking if any more recent changes to its data exist. This way, it is more likely that each player gets a consistent and up-to-date view of the shared game state.

Time and latency

Sending data from one computer to another takes time, and there's no way around that. As a programmer of a networked game, it is important to embrace this fact and recognize that it changes how you must think about your game logic. When programming a single-player game (especially if it only runs on a single processor thread) we can assume that any change to the game state is immediate. In a networked game, this is not true.

This means that each player of a networked game is playing in their own "parallel universe", which affect each other at a distance. Updates to data that you don't have authority over will appear in an irregular and unpredictable way. Because of this it is beneficial to use a defensive coding style that tries to correct for out-of-order updates, and other unexpected circumstances.

One example of such a coding technique (which is already built into coherence) is interpolation. It uses a selection of algorithms to predict what a value will be, based on previous values. This "smooths out" the values over time, which often looks better than using the raw versions. The best example of this is probably interpolation of position - if an object is moving in a straight line at a certain speed and then the update with its new position is somehow lost, it is better to assume that the object will keep moving instead of stopping it.

Conclusions

If the concepts in this article were new to you, we hope that you now feel more confident thinking about the challenges of networked game. While networking surely can be tricky at times, it's also immensely cool and fun when it works - hopefully coherence will make you reach that point in no time! Our docs contain lots of information on how to proceed from here. Perhaps you should start by following a tutorial?

Types missing the ExtensionOfNativeClass attribute

Reimport assets via menu item Assets / Reimport All.

Scripts losing references to Prefabs, Fix Serialized Data button appears

There is a bug in some early versions of Unity 2022 LTS that causes Prefabs to be corrupted on reimport, leading to all sorts of issues like scripts losing references, or the CoherenceSync component showing a button to "Fix Serialized Data" (which cures the problem, but only temporarily).

The real solution is to upgrade to a newer version of Unity 2022. Unity claims they fixed the bug in version 2022.3.5f1 (note the specific patch number, .5).

The Optimize window stops rendering components

The current workaround to avoid this issue is to open your CoherenceSync prefabs in prefab mode.

I can't see Rooms or Worlds

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

Prefab Variants using excessive memory

When working with Prefab Variants, Unity leaks managed references (fields marked with [SerializeReference]). This can make your prefab grow big and use more memory than necessary. Until Unity fixes this issue, we provide you with the ability to prune the leaked references. You can prune within the Configure window.

Binding is interpolated into correct position after instantiating

If you are instantiating a Prefab from a coherence event (such as a Command, OnValueSynced, OnStateAuthority, OnLiveQuerySynced...) and then changing its bindings in the same frame, the remote Clients will not instantly get updated values. Instead, if the binding has interpolation enabled, the value of the binding will be interpolated from the original value (from the instantiation step) to the updated value (from the change later in the frame).

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.

InvalidOperationException: Insecure connection not allowed

Make sure you allow HTTP connections in Editor to avoid InvalidOperationException: Insecure connection not allowed errors. Find out how to enable HTTP connections in Unity's InsecureHttpOption article.

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

Key controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

Topics covered

Animation | Bindings

In this scene

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

When you move around, you will notice that animation is also replicated across Clients. This is done via synced Animator parameters (and Network Commands, but we cover these in the next lesson).

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

How it's set up

Open the player Prefab located in the /Prefabs/Characters folder. Browse its Hierarchy until you find the child GameObject called Workman. You will notice it has an Animator component.

Select this GameObject and open the Animator window.

As is usually the case, animation is controlled by a few Animator parameters of different types (int, bool, float).

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

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

There is only one piece missing: animation Triggers. We use one to trigger the transition to the Jump state.

Since Triggers are not a variable holding a value that changes over time, but rather an action that happens instantaneously, we will see how to sync them in the next lesson using Network Commands.

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

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

• Q or D-pad up: Wave

Topics covered

|

In this scene

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

How it's set up

Like before, select the player Prefab located in the /Prefabs/Characters folder, and browse its Hierarchy until you find the child GameObject called Workman.

Open the coherence Configure window on the Methods tab:

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

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

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

• Find a recipient to the command that is of the class Animator.

• Invoke a method called Animator.SetTrigger.

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

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

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

Key controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

Topics covered

| Bindings | Component behaviours |

In this scene

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

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

coherence takes care of keeping all Game Clients in sync regarding network entities. When another Client connects, a new instance of your game character is instantiated in their scene, and an instance of their character is instantiated into yours. We refer to this as network instantiation.

How it's set up

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

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

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

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

To ensure that Clients don't modify the properties of entities they don't have authority over, some components are either disabled or behave differently on the character instances that are non-authoritative.

coherence offers a rapid way to make this happen. If you open the Components tab of the Configuration window, you will see that 3 components are configured to do something special:

In particular:

• The PlayerInput and KinematicMove scripts get disabled.

• The Rigidbody component is made kinematic.

Understanding authority

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

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

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

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

Getting updates about every entity in the whole scene is unfeasible for big-world games, like MMOs. For this, coherence has a flexible system for creating areas of interest, and getting updates only about the entities that each Client cares about, using a tool called Live Query.

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

Topics covered

|

In this scene

This scene contains two cubes that represent areas of interest. Every connected Client can only see other players if they are standing in one of these cubes.

How it's set up

Select one of the two GameObjects named LiveQuery. You will see they have a Coherence Live Query component:

This component defines an area of interest, in this case a 10x10x10 cube (5 is the Radius). This is telling the Replication Server that this Clients is only interested in network entities that are physically present within this volume.

If a Client has to know about the whole world, it's just enough to set the Live Query Radius to 0, to make it capture all updates.

In addition, Live Queries can be moved in space. They can be parented to the camera, to the player, or to other moving elements that denote an area of interest - depending on the type of game.

It is also possible, like in this scene, to have more than one Live Query. They will act as additive, requesting updates from entities that are within at least one of the volumes.

Notice that at least one Live Query is needed: a Client with no Live Query in the scene will receive no updates at all.

Not just visibility

Try moving in and out of volumes. You will notice that network-instantiation takes care of destroying the GameObject representing a remote entity that exits a Live Query, and reinstantiates it when it enters one again.

Also, notice that the player belonging to the local Client doesn't disappear. coherence will stop sending updates about this instance to other Clients, but the instance is not destroyed locally, as long as the Client retains authority on it.

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

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

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

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

Topics covered

| |

In this scene

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

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

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

How it's set up

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

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

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

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

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

Simulating lifetime without a Simulator

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

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

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

Destroying other Clients' flowers

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

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

Check the code at the end of the Flower script:

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

Let's see how to handle these cases.

Controls

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

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

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

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

Topics covered

| |

In this scene

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

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

How it's set up

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

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

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

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

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

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

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

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

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

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

Parenting the crate with CoherenceNode

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

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

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

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

This reference is set to sync:

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

Even if the Robot Arm Hand script is disabled on non-authoritative Clients, it references the correct grabbed crate in the grabbableObject variable due to it being synced over the network. So when its authority disconnects, other Clients will already have the correct reference to the crate network entity.

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

Transferring authority

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

Is Kinematic is set as follows:

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

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

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

Once you have learned the basics using the First Steps tutorial project, Campfire is the natural follow-up to get acquainted with more advanced and practical topics.

As with First Steps, you can download the whole Campfire Unity project and explore it at your own pace. Instead of being a series of independent scenes, Campfire is one big scene that presents multiple concepts working together at the same time. We recommend using the pages on this section as guidance on the individual topics, starting with getting acquainted with the game structure.

Download the Unity project

The Unity project can be downloaded from its Github repo. The Readme will tell you the minimum Unity version to use.

Try a pre-made build

To quickly try out the game, we shared a WebGL build on the coherence Cloud. You can play it directly in the browser, or download one of the available desktop versions. Share the link with friends and colleagues, and try it together!

Play as a Client

To play as a regular Client, make sure that the GameObject called Simulator is disabled in the scene Main:

Without it, the game will behave as a pure Client and spawn a player character on connection.

Making a Client build

If you want to make a game build, simply having that object off will produce a Client build. You can run many Client builds to experience multiplayer gameplay.

Play as the Simulator

In this project, there is an NPC that is supposed to be controlled by the Simulator (the Keeper Robot). Though this is intended to be a server-side behavior, you can actually make it run locally and play as a player at the same time without modifications to the code.

First, enable the Simulator GameObject in the scene.

Now press Play and connect.

The robot will start acting, exactly like it would do if it were running on a Simulator (minus, of course, the network delay). This allows you to see what would be happening on the server, with the full debugging power of the Unity Editor.

You can even use this Editor instance running alongside one or more Client builds.

Building the Simulator

To create a Simulator build, you have two ways to go about it, as usual:

• building a Simulator to launch locally on your machine

• building one to upload on the coherence Cloud

In both cases, make sure that the Simulator GameObject is enabled in the scene.

Don't change the Keeper Robot's Simulate In property like described in the previous section, since to run this behavior on the Simulator we want it to stay Server Side.

For more information, refer to the Simulators: Build and Deploy page.

Topics covered

Object lifecycle | | Runtime Unique IDs

In many cases, creating and destroying GameObjects like usual will be enough. Just call Instantiate() or Destroy(), and coherence takes care of instantiating and destroying the appropriate Prefab instance on each connected Client.

However, there are moments when it makes sense to customize how exactly coherence does this. To take full control over the lifetime of the object, or to attach custom behavior to these events.

coherence provides by default (and we use one too), but for ultimate control we also have the ability to create new, completely custom ones.

Our use case

The campsite in this demo has a few pre-placed unique objects in the scene, that can be picked up, moved, and burned on the campfire.

Until the comes in and recreates them, they will not be replaced.

When we burn them, we could in theory just destroy the instance. However the burn code is deeply nested in the Burnable.cs class which is used not only by these unique objects, but also by the pooled and non-unique wood logs.

In this method we do this:

However, by default unique network entities also get disabled, not destroyed. This doesn't work for our special objects!

We could potentially add an if statement in the GetBurned() above, detect if the object being destroyed is a log or not, and act differently based on that. Or subclass the Burnable and implement overrides for GetBurned...

... or we can just create a custom instantiator, and take full control of the object's lifecycle. Let's see the code.

The custom instantiator

Creating a custom instantiator is trivial. We just need a class to implement the interface INetworkObjectInstantiator, like so:

The key parts of this script being that on network entity creation a simple Object.Instantiate() is performed, and on release Object.Destroy(). The other methods (omitted here) are actually empty.

We also want to prepend the class with the DisplayName attribute so it shows up in the dropdown when we configure a CoherenceSync. Now the UniqueBurnableObjects instantiator appears alongside the others in the Instantiate via dropdown:

That's it, the instantiator is ready to use.

When we call ReleaseInstance() now, it will act differently depending on which instantiator the Prefab is configured to use: the wood logs get disabled, but the unique campfire objects get destroyed.

This was a very simple use case for customization, but it illustrates how easy it can be to get in control of the lifetime of Prefab instances associated to network entities.

Object anchors

One interesting thing we do with anchors is that they are themselves unique objects, but because they are spawned at runtime, they need to get their unique ID dynamically at runtime.

The code is in the PersistentObject class:

We take the ManualUniqueId from the object spawning it (i.e., "Boombox"), and we combine with the string "-anchor" to create a new unique ID, "Boombox-anchor". We register this ID to the UniquenessManager of the CoherenceBridge to inform it that the next spawned network entity will have that ID. And then we simply call Instantiate().

Because they are set to be Persistent, even though a player has burned something and disconnected, the anchors stay on the Replication Server. When a Simulator connects it will find these placeholders and, thanks to the synced properties, will know exactly what to recreate and where to put it.

The check code is in KeeperRobot.cs, under CheckAnchors() and ActOnAnchor().

First, each anchor's isObjectPresent property is used for a quick scan. This property is synced.

If the object is still present, the robot needs to get a reference to it. It calls GetLinkedObject() on the anchor, which does this:

Once again using the UUID of the object this anchor is a placeholder for (holdingForUUID) as a key, we can now ask the UniquenessManager to retrieve an object that has that UUID.

With a reference to this, the robot can now put it back into place using the anchor's position and rotation as a reference.

And if the object has been destroyed (isObjectPresent is false), the robot proceeds to recreate it.

After that, like we saw before, the robot registers the newly recreated object with the UniquenessManager so that it has the same UUID that it had before being burned.

The object is reinstated, and to a new Client connecting, it will look exactly the same as if it never got removed.

Topics covered

| |

Network entities need to be created and removed all the time. This can be due to entities getting in and out of a LiveQuery, or simply because gameplay requires so. If that is the case, we can leverage coherence's object pooling system in order to avoid costly calls to Instantiate and Destroy, which are famously expensive operations in Unity.

Our use case

In this project we use pooling for one very clear use case: the tree logs that get spawned when chopping down a tree.

This was a natural choice as players will be chopping trees all the time, but we can also assume that they will burn the logs on the fire almost as often. So by pre-allocating a pool of around 10 logs, we should be covered in most cases.

Prefab setup

To set up the log to behave like this, all we did was to set that option on the log's own CoherenceSync inspector.

A pool configured like this means that coherence will pre-spawn 10 instances of the Prefab at the beginning of the game.

However if we were to need more, we could request more instances and they would be created and added to the pool. The game can even go above 20. If that were to happen, any instance released beyond 20 wouldn't just be returned to the pool, but would be destroyed.

In other words, 10 and 20 represent the lower and upper limit for the amount of memory we are reserving for the logs alone in our game. We are considering anything above 20 as a temporary exception.

When we press Play, coherence instantiates these 10 logs, deactivate them, and put the pool in the DontDestroyOnLoad scene:

Because they are inactive, their CoherenceSync components are not syncing any value.

Spawning a new log

To spawn a new log we only need to call one line of code. However, we don't provide a reference to a regular Prefab like we would with Instantiate. We instead leverage the CoherenceSyncConfig object that represents the log.

This CoherenceSyncConfig contains all the info that coherence needs to handle this particular Prefab over the network. If we inspect it, we will notice that it contains in fact how the object is loaded (Load via) and how it's instantiated (Instantiate via).

You can notice how this is the same info we saw while configuring the CoherenceSync before.

Now that we have a reference to it, we can spawn the log with one line of code. In the ChoppableTree script, we do something like:

This line looks remarkably similar to Unity's own Instantiate in its syntax. The difference is that it gives us back a reference to the CoherenceSync attached to the log instance that will be enabled. From this, we can do all sorts of setup operations by just fetching other components with GetComponent, to prepare the instance.

Burning a log

When we are done with it (in this case, when it's thrown into the campfire), we can dispose of it:

(this line is in the Burnable.cs class, inside the GetBurned() method)

The instance is then automatically returned into the pool, and disabled.

Cleaning up

When taking an instance out of the pool or when returning it, coherence doesn't automatically do any particular clean up to its state.

As such, when we reuse a pool instance, it is good practice to think of what values should be reset that might have been messed up by previous usage. We should think about what happens during gameplay, and use OnEnable / OnDisable as needed to ensure that disabled instances are put in a state that makes them ready to be used again.

For this project, since an object can be burned while being carried, we do some cleaning in the OnDisable of the Grabbable.cs class to prepare the wood logs for another round, like so:

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

Controls

• WASD or Left stick: Move character

• Hold Shift or Shoulder button left: Run

• Spacebar or Joypad button down: Jump

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

Topics covered

Physics | | Uniqueness |

In this scene

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

Let's take a closer look at the setup.

How it's set up

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

The crates also have a CoherenceSync component. The first player to connect gets authority over them, and keeps running their simulation without interruption.

That Client now syncs 5 values over the network, including the most important ones that will drive the crate's motion: Transform.position and Transform.rotation.

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

Authority switch

At this point, the first Client to connect is simulating all the crates. However, if we were to leave things like this, interacting with physical objects that are simulated by another Client would be quite unpleasant due to the lag.

To make it better, other Clients steal authority over crates, whenever they either:

• Touch/collide with a crate directly

• Pick a crate up

In code, this authority switch is a trivial operation, done in a single line. You can find the code in the Grabbable class. Essentially, it boils down to this:

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

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

When they want authority, Clients have to request it and most importantly, wait for an answer.

We implemented this request / answer mechanism to avoid problems of concurrency, where two players are requesting authority on a crate at the same time, and end up with a broken state because the game code assumes that they both got it.

In conclusion

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

About uniqueness and persistence

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

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

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

In addition to a unique identifier (the Manual Unique ID), coherence will auto-assign an additional identifier (the Prefab Instance Unique ID) whenever the crate is instantiated in the scene at edit time.

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

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

• Client A connects. They sync the crates onto the network. Being unique, the Replication Server takes note of their ID.

• Client B connects. They try to bring the same crates onto the network, but because it is set to be No Duplicates and coherence finds there is already a network entity with the same ID, it doesn't create a new network entity but recognises that crate as the one on the server, and just makes it non-authoritative for Client B.

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

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

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

• When a new Client reconnects and tries to bring the crates online again, the same thing happens again: the crates in the scene are associated with the orphaned entities and are adopted by the new client, who assumes authority on them.

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

• At this point, they start simulating their physics locally, like normal.

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

Communication

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

Doors

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

Bomb

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

Cheating

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

Topics covered

Network Commands | Seamless authority transfer | Optional server-side logic

It's often the case that in addition to objects being fully owned by players, like their characters, there is often the need to have objects that exist only in one copy in the world and that need to store a complex state that needs to be reflected in the same way on each Client. And the state might not be a simple int or bool that can be just automatically synced over the network whenever it changes, but something more complex that requires to be elaborated.

This is often the case for more invisible objects like a leaderboard, a spawn point, a score counter or a match timer; but can also be the case for objects that have graphics.

Our use case

An example of such an object, that also happens to be very central to this demo, is the campfire. As the players pick up objects and throw them on the fire, the campfire needs to perform a calculation based on a timer and the type of the object burned to decide which fire effect to play.

Timing is key here! If two players throw in two objects, one right after the other, they activate a special effect that makes the campfire burn bigger and brighter. But the two objects need to get on the fire within 2.5 seconds from each other (it's the teamEffortLength variable in the Campfire.cs script).

Because this calculation depends on the timer value that is managed by the Authority, we can't just independently calculate a result on each Client, as they would almost certainly end up with different results. We need to inform the Authority that the action is taking place, let it figure out the final state, and only then propagate the resulting state and actions to all Clients.

This is in a way similar to what happens with the trees. The event flow is very similar:

(1) Action happens on a Client -> (2) Authority campfire is notified, processes result -> (3) Authority campfire sends result to all others -> (4) Non-authority campfire objects execute local effects

We do have an extra challenge here though. Ultimately we want the Authority to inform everyone to play specific visual and sound effects depending on the object burned. But we can't send Network Commands with a reference to audio assets or particle systems. So we need to change this information to something we can send, and then on the receiving end, "unpack it" and transform it into the info we actually need (i.e., which sound).

The code

If you look into the Campfire.cs script, you will find this sequence of actions as exemplified by the flow below:

(1) The player throws an object on the fire. BurnObjectLocal() is invoked by the Burnable that collided with the Campfire. The script checks if Authority is already on this Client:

public void BurnObjectLocal(CoherenceSync syncToBurn)
{
    //...
    if (_sync.HasStateAuthority)
        BurnObject(syncToBurn.CoherenceSyncConfig.ID);
    else
        _sync.SendCommand<Campfire>(nameof(BurnObject), MessageTarget.AuthorityOnly, syncToBurn.CoherenceSyncConfig.ID);
}

The method invoked in both cases is BurnObject(), but it's invoked differently depending on whether it is local (direct invocation) or remote (using SendCommand via the CoherenceSync).

We use the ID of the CoherenceSyncConfig of the object that burned as a parameter. The ID is a string, so it's something we can send over the network.

(2) The logic for which fire effect to play is then calculated in BurnObject().

The campfire uses the CoherenceSyncConfig ID as a key to look into the CoherenceSyncConfigRegistry, and find the right object archetype to play the right effect.

[Command(defaultRouting = MessageTarget.AuthorityOnly)]
public void BurnObject(string syncConfigID)
{
    if (RetrieveBurnableInConfigRegistry(syncConfigID, out Burnable burnable))
    {
        // Did two objects get burned at the same time? Calculate big fire time
        // IsBigFireOn = ...

        ChangeFireState(IsBigFireOn ? burnable.bigFireEffectType : burnable.fireEffectType, syncConfigID);
    }
}

(3) ChangeFireState() is invoked locally on the Authority. Here the Authority updates its own property activeFireEffect which, being a synced property, gets sent to the other Clients.

private void ChangeFireState(FireEffect.EffectType newEffectType, string syncConfigID = "")
{
    // Inform other clients
    _sync.SendCommand<Campfire>(nameof(FireStateChanged), MessageTarget.Other, activeFireEffect, newEffectID, syncConfigID);
    
    // Update synced property
    activeFireEffect = newEffectID;
}

But updating that int wouldn't be enough to tell which sound to play, so we send a command to invoke the FireStateChanged() method, passing the CoherenceSyncConfig ID which the non-authoritative campfire instances can use to trace down the object that burned in the CoherenceSyncConfigRegistry.

(4) The non-authoritative clients execute FireStateChanged(), which turn on/off the appropriate fire particles, and play a specific sound.

Picking up when somebody leaves

If the Client (or a Simulator) detaining the authority on the campfire disconnects, we need to make sure that whoever gets assigned authority next can pick up the job exactly where it was left off, and continue simulating the campfire logic without interruption.

That's why in the Campfire.cs class we make sure to sync three values:

• activeFireEffect is an index (expressed as an integer) of which fire effect should be playing right now.

• fireTimer and bigFireTimer are two countdowns that indicate how much time the fire will still burn normally or, when in "big fire mode", brighter.

However, there's an opportunity to be smart here. fireTimer and bigFireTimer are variables that are updated every Update on the Authority, but they are only useful in case the Authority gets transferred. So what we can do using the Optimization panel is to reduce the frequency they are sent to other Clients to a much more manageable value of once every second.

This might not be very precise and would have been unacceptable in the case of a visible timer, but here it doesn't matter. To the players this is going to be invisible, but we avoid a lot of network traffic.

Running this logic on the Server (Simulator)

As mentioned before, this mini state-machine behavior can run perfectly on one of the connected Clients. There is one catch though: this way, if no one is connected, the fire will stop updating because no one is simulating it, and thus it will never burn out.

Try this: connect, throw an object on the fire, disconnect, and reconnect after some time. The value of fireTimer will still be the same and so the fire will still be burning no matter how much time has passed.

Using an Authority transfer, it is trivial to let this behaviour run on a Simulator if there is one connected. Look into the Campfire class, within OnLiveQuerySynced:

// ...
if (SimulatorUtility.IsSimulator)
{
    _sync.RequestAuthority(AuthorityType.Full);
}

With this simple code, whenever a Simulator connects and sees the persistent campfire network entity, it will take Authority over it. If it were ever to go offline and a client is connected, that Client would take back Authority. If the Simulator comes back online, it would steal it again. And so on.

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

Video tutorial

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

Using the Coherence Hub

You can let the coherence Hub guide you through your Prefab setup process. Simply select a Prefab, open the GameObject tab in the coherence Hub (coherence > coherence Hub) and follow the instructions.

Step by step

You can also follow the detailed step-by-step text guide below.

1. Add CoherenceSync to your GameObject

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

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

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

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

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

1.1 Networking an already existing Prefab

If you wish to start networking a Prefab that already exists in your project, you have more options to get started:

• Clicking on the Sync with coherence checkbox at the top of the Prefab inspector.

• Manually adding the CoherenceSync component.

• Drag the Prefab to the CoherenceSync Objects Window you can find in coherence > CoherenceSync Objects.

1.2 (Optional) Prefab variants

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

In our Cube example, instead of adding the component to the original Prefab, you can create a variant called Cube (Networked) and add CoherenceSync to it:

This way, you can retain the original Prefab untouched.

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

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

2. Configure CoherenceSync

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

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

3. Select properties to replicate

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

Click the Configure button in the CoherenceSync Inspector. A new window will open, called Configuration.

Click on the tab Variables. Since position is already selected, add rotation and localScale.

Close the Configuration window.

4. Add an input script

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

Click on Assets > Create > C# Script.

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

using UnityEngine;

public class Move : MonoBehaviour
{
    public float speed = 1f;

    void Update()
    {
        float h = Input.GetAxisRaw("Horizontal");
        float v = Input.GetAxisRaw("Vertical");
    
        var spf = speed * Time.deltaTime;

        transform.position += transform.forward * (v * spf);
        transform.position += transform.right * (h * spf);
    }
}

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

5. Disable input on replicated object

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

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

Under Configure, click Components.

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

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

6. Implementing your own Component Actions

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

using UnityEngine;

[System.Serializable]
public abstract class ComponentAction
{
    [SerializeField] internal Component component;
    public Component Component => component;

    public virtual void OnAuthority() { }
    public virtual void OnRemote() { }
}

Your custom Component Action must implement the following methods:

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

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

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

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

using Coherence.Toolkit;
using UnityEngine;

[ComponentAction(typeof(Behaviour), "Disable")]
public class DisableBehaviourComponentAction : ComponentAction
{
    public override void OnAuthority()
    {
        var b = Component as Behaviour;
        b.enabled = true;
    }

    public override void OnRemote()
    {
        var b = Component as Behaviour;
        b.enabled = false;
    }
}

7. Additional CoherenceSync settings

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

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

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

• On Networked Instantiation (when the GameObject is instantiated)

• On Networked Destruction (when the GameObject is destroyed)

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

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

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

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

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

8. Nested CoherenceSync components

It is possible to nest network entities into each other both at edit and at runtime. Doing it at runtime is semi-automatic, and only if you nest an entity deeply into a hierarchy (like a tool in the hands of a character), you need to add the CoherenceNode component to the nested one.

For edit-time nesting instead, the PrefabSyncGroup needs to be placed on the root object.

Helper scripts

Requirements

Game engine support

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

Unity requirements

• Latest Unity 2021 LTS and 2022 LTS are officially supported. Check LTS Releases.

• The minimum supported version is now Unity 2021.3 LTS.

Video Tutorial

Unity Package Manager

1. Add the Scoped Registry

First, go to Edit > Project Settings. Under Package Manager, add a new Scoped Registry with the following information:

• Name: coherence

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

• Scope(s): io.coherence.sdk

2. Install coherence

Now open Window > Package Manager. Select My Registries in the Packages dropdown.

Highlight the coherence package, and click Install.

Alternative method: edit manifest.json manually

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

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

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

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

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

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

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

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

Running a Replication Server locally

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

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

Building through Coherence Hub

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

Build and Connect

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

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

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

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

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

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

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

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

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

This component is added by CoherenceSync on .

Video tutorial

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

Sign up or log in

Create an account or log into an existing one.

Login through Unity

Open Unity

Open Unity and open the coherence Hub window. Then open the coherence Cloud tab.

Login to Portal

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

Select Organization and Project

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

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

The CoherenceSyncConfigRegistry is a ScriptableObject that will hold a list of references to your existing CoherenceSyncConfig objects.

CoherenceSyncConfig is a separate ScriptableObject that holds the configuration for each of your networked objects.

Since the Registry needs to keep a list of references, in coherence we offer three different ways you can handle your CoherenceSyncConfigRegistry asset:

• Sub Assets: The CoherenceSyncConfig assets will be saved as sub-assets of the CoherenceSyncConfigRegistry asset.

• Standalone Assets: The CoherenceSyncConfig assets will be saved separately in the Assets/coherence/baked folder, the CoherenceSyncConfigRegistry will simply keep a list of references to them.

• Dynamic Standalone Assets: The CoherenceSyncConfig assets will be saved separately in the Assets/coherence/baked folder. The CoherenceSyncConfigRegistry will not be saved to disk but it will be generated on-demand in memory.

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

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

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

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

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

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

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

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

LiveQuery

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

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

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

Script execution order

Check out ScriptExecutionOrder.

Additionally, take a look at your project's Script Execution Order settings by opening Edit > Project Settings and selecting the Script Execution Order category. See this Unity manual article for more details.

CoherenceSync instance lifecycle

When a Prefab instance with CoherenceSync is created at runtime, it will be fully synchronized with the network in the OnEnable method of CoherenceSync. This means that you can expect your custom Components to have fully resolved synchronized values and authority state in your Awake method. It occurs in the following order:

CoherenceSync

1. Awake() is called

   1. Internal initialization.

2. OnEnable() is called

   1. Synchronize with a new or existing Network Entity.

   2. OnBeforeNetworkedInstantiation event is invoked.

   3. Initial component updates are applied (for entities you have no authority over).

   4. OnNetworkedInstantiation event is invoked.

   5. OnStateAuthority or OnStateRemote (for authority or non-authority instances respectively) event is invoked.

User-defined Components

1. Awake() is called

   1. At this point, if you get the CoherenceSync component, you can expect networked variables and authority state to be fully resolved.

Instead of hard referencing Prefabs in your scripts to instantiate them, you can reference a CoherenceSyncConfig and instantiate your local Prefab instances through our API. This will utilize the internal INetworkObjectProvider and INetworkObjectInstantiator interfaces to load and instantiate the Prefab in a given networked scene (a scene with a CoherenceBridge component in it).

using Coherence.Toolkit;
using UnityEngine;

public class CoherenceSyncConfigExample : MonoBehaviour
{
    public CoherenceSyncConfig prefabSyncConfig;
    public CoherenceBridge bridge;
    
    private CoherenceSync instance1;
    private CoherenceSync instance2;
    
    void Start()
    {
        // Load the prefab and instantiate it in the current scene
        instance1 = prefabSyncConfig.GetInstance();
        // Load the prefab and instantiate it in the specific networked scene for the given CoherenceBridge
        instance2 = prefabSyncConfig.GetInstance(bridge, Vector3.zero, Quaternion.identity);
    }
    
    private void OnDestroy()
    {
        // Instances have to be destroyed via the ReleaseInstance method, so that its destruction is handle by the 
        // internal INetworkObjectInstantiator
        prefabSyncConfig.ReleaseInstance(instance1);
        prefabSyncConfig.ReleaseInstance(instance2);
    }
}

You can also hard reference the Prefab in your script, and use our extensions to instantiate the Prefab easily using the internal INetworkObjectInstantiator interface implementation. The main difference is that the previous approach doesn't need a Prefab hard reference, and you won't have to change the code if the way that the Prefab is loaded into memory changes (for example, if you go from Resources to load it via Addressables).

using System;
using Coherence.Toolkit;
using UnityEngine;

public class InstantiatorViaCoherenceSyncComponent : MonoBehaviour
{
    // Serialized prefab reference
    public CoherenceSync prefab;
    public CoherenceBridge bridge;

    private CoherenceSync instance1;
    private CoherenceSync instance2;

    void Start()
    {
        // Instantiate it in the current scene
        instance1 = prefab.GetInstance();
        // Instantiate it in the specific networked scene for the given CoherenceBridge
        instance2 = prefab.GetInstance(bridge, Vector3.zero, Quaternion.identity);
    }

    private void OnDestroy()
    {
        // Instances have to be destroyed via the ReleaseInstance method, so that its destruction is handle by the 
        // internal INetworkObjectInstantiator
        instance1.ReleaseInstance();
        instance2.ReleaseInstance();
    }
}

• bool

• int

• uint

• byte

• char

• short

• ushort

• float

• string

• Vector2

• Vector3

• Quaternion

• GameObject

• Transform

• RectTransform

• CoherenceSync

• SerializeEntityID

• byte[]

• long

• ulong

• Int64

• UInt64

• Color

• double

In this page we will learn about how coherence handles loading CoherenceSync Prefabs into memory and instantiating them when a new remote entity appears in the network. You will also learn how you can hook your own asset loading and instantiation systems seamlessly.

CoherenceSyncConfigRegistry asset

Whenever you start synchronizing one of your prefabs, either by adding the CoherenceSync component manually or clicking the Sync with coherence toggle in the prefab inspector, coherence will automatically create a CoherenceSyncConfig object that will be added to the CoherenceSyncConfigRegistry asset found in the Assets/coherence folder.

This CoherenceSyncConfig object allows us to do the following:

• Hard reference the prefab in Editor, this means that whenever we have to do postprocessing in synced prefabs, we don't have to do a lookup or load them from Resources.

• Serialize the method of loading and instantiating this prefab in runtime.

• Soft reference the prefab in Runtime with a GUID, this means we can access the loading and instantiating implementations without having to load the prefab itself into memory.

All your CoherenceSync prefabs will have a related CoherenceSyncConfig object, you can inspect all your prefabs in the CoherenceSync Objects window, found under the coherence => CoherenceSync Objects menu item:

You can also manually inspect your CoherenceSyncConfig objects by selecting the CoherenceSyncConfigRegistry asset in Assets/coherence/CoherenceSyncConfigRegistry.asset:

You can also find your related CoherenceSyncConfig in the inspector of the CoherenceSync component, you can directly edit your Config from here:

CoherenceSyncConfig Load via option

This option allows you to specify how this prefab will be loaded into memory in runtime, we support three default implementations, or you can create your own. The three default implementations are Resources, Direct Reference or Addressables, these three will be automatically managed by coherence and you won't have to worry much about them.

Resources

Resources loader will be used if your prefab is inside a Resources folder, if you wish to use any other type of loading method, you will be prompted to move the prefab outside of the Resources folder.

Direct Reference

This loader will be used if your prefab is outside of a Resources folder, and the prefab is not marked as Addressable. This means that we will need to hard reference your prefab in the CoherenceSyncConfig, which means it will always be loaded into memory from the moment you start your game.

Addressables

This option is only available if you have the Addressables Unity Package installed.

This loader will be used if your prefab is marked as an Addressable asset, and it will be soft referenced using Addressables AssetReference class.

Creating your own asset loader

You can implement the INetworkObjectProvider interface to create your custom implementations that will be used by coherence when we need to load the prefab into memory.

Custom implementations can be Serializable and have your own custom serialized data.

Implementations of this interface will be automatically selectable via the Load via option in the CoherenceSyncObject asset.

CoherenceSyncConfig Instantiate via option

This option allows you to specify how this prefab will be instantiated in runtime, we support three default implementations, or you can create your own. The three default implementations are Default, Pooling or DestroyCoherenceSync.

Default Instantiator

This instantiator will create a new instance of your prefab, and when the related network entity is destroyed, this prefab instance will also be destroyed.

Pool Instantiator

This instantiator supports object pooling, instead of always creating and destroying instances, the pool instantiator will attempt to reuse existing instances. It has two options:

• Max Size: maximum size of the pool for this prefab, instances that exceed the limit of the pool will be destroyed when returned.

• Initial Size: coherence will create this amount of instances on app startup.

DestroyCoherenceSync Instantiator

This instantiator will create a new instance for your prefab, but instead of completely destroying the object when the related network entity is destroyed, it will destroy or disable the CoherenceSync component instead.

Creating your own instantiator

You can implement the INetworkObjectInstantiator interface to create your custom implementations that will be used by coherence when we need to instantiate a pefab in the scene.

Custom implementations can be Serializable and have your own custom serialized data.

Implementations of this interface will be automatically selectable via the Instantiate via option in the CoherenceSyncObject asset.

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

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

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

A Bridge is associated with the scene it's instantiated on, and keeps track of Entities that are part of that scene. This also allows for multiple connections at the same time coming from the game or within the Unity Editor.

Unity Events

The CoherenceBridge offers a couple of Unity Events in its inspector where you can hook your custom game logic:

OnLiveQuerySynced

This event is invoked when the Replication Server state has been fully synchronized, it is fired after OnConnected.

For example, if you connect to a ongoing game that has five players connected, when this event is fired all the entities and information of all the other players will already be synchronized and available to be polled.

OnConnected

This event is invoked the moment you stablish a connection with the Replication Server, but before any synchronization has happened.

Following the previous example, if you connect to an ongoing game that has five players connected, when this event is fired, you won't have any entities or information available about those five players.

OnDisconnected

This event is invoked when you disconnect from a Replication Server. In the parameters of the event you will be given a ConnectionCloseReason value that will explain why the disconnection happened.

OnConnectionError

This event is invoked when you attempt to connect to a Replication Server, but the connection fails, you will be returned a ConnectionException with information about the error.

Client Connections

The Client Connections system allows you to keep track of how many users are connected and uniquely identify them, as well as easily send server-wide messages.

You can read more about the Client Connections system here.

Connecting to Worlds/Rooms from coherence Cloud

If you have a Developer Portal account, you can connect to Worlds or Rooms hosted in coherence Cloud. You can use the CloudService instance from CoherenceBridge to fetch existing Worlds or create or fetch existing Rooms, after you fetch a valid World or Room, you can use the JoinWorld or JoinRoom methods to easily connect your client.

You can read more about the Unity Cloud Service here.

Persistent Entity limits

Overview

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

Design phase

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

By clicking on the method, you bind to it, defining a command. The grid icon on its right lets you configure the routing mode. Commands with a Send to Authority Only mode can be sent only to the authority of the target CoherenceSync, while ones with the Send to All Instances can be broadcasted to all clients that see it. The routing is enforced by the Replication Server as a security measure, so that outdated or malicious clients don't break the game.

Sending a command on a networked object

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

• The generic type parameter must be the type of the receiving Component. This ensures that the correct method gets called if the receiving GameObject has components that implement methods that share the same name. Example: sync.SendCommand<Transform>(...)

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

• Alternatively, if you want to know which Client sent the command, you can add CoherenceSync sender as the first argument of the command, and the correct value will be automatically filled in by the SDK.

• The second argument is an enum that specifies the MessageTarget of the command. The possible values are:

  • MessageTarget.All – sends the command to each Client that has an instance of this Entity.

  • MessageTarget.AuthorityOnly – send the command only to the Client that has authority over the Entity.

  • MessageTarget.Other - sends the command to every Entity other than the one SendCommand is called on.

• The rest of the arguments (if any) vary depending on the command itself. We must supply as many parameters as are defined in the target method and the schema.

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

var target = enemy.GetComponent<CoherenceSync>();
                    
target.SendCommand<Character>(nameof(Character.SendDamage), 
                MessageTarget.All,
                damageValue, staminaBlockCost,
                staminaRecoveryDelay, ignoreDefense, 
                hitReaction, hitPosition, 
                ConnectionId, isPlayer);

Sending a command to a specific MonoBehaviour instance

If you have the same command bound more than once in the same Prefab hierarchy, you can target a specific MonoBehaviour when sending a message, you can do so via the SendCommand(Action action) method in CoherenceSync.

Additionally, if you want to target every bound MonoBehaviour, you can do so via the SendCommandToChildren method in CoherenceSync.

Receiving a command

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

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

Identifying which Client sent a command

While commands by default carry no information on who sent them in order to optimise traffic, you can create commands that include a Client ID as one of the parameters. Then, on the receiving end, compare that value with a list of connected Clients.

You can create your own implementation for these IDs or, more simply, use coherence's built-in Client Connections feature.

Sending a command to multiple CoherenceSyncs

Sometimes you want to inform a bunch of different CoherenceSyncs about a change. For example, an explosion impact on a few players. To do so, we have to go through the instances we want to notify and send commands to each of them.

using Coherence;
using Coherence.Toolkit;
using UnityEngine;

public class MyCommands : MonoBehaviour
{
    public void MulticastCommand()
    {
        var self = GetComponent<CoherenceSync>();
        var listeners = FindObjectsOfType<CoherenceSync>(); 
        
        foreach (var listener in listeners)
        {
            if (!listener || listener == self)
            {
                continue;
            }
            
            listener.SendCommand<MyCommands>(nameof(ReceiveCommand), MessageTarget.AuthorityOnly);
        }
    }

    // bind to this method via the Bindings window
    public void ReceiveCommand()
    {
        Debug.Log("Received!");
    }
}

In this example, a command will get sent to each CoherenceSync under the state authority of this Client. To make it only affect CoherenceSyncs within certain criteria, you need to filter to which CoherenceSync you send the command to, on your own.

Sending null values in command arguments

Some of the primitive types supported are nullable values, this includes:

• Byte[]

• string

• Entity references: CoherenceSync, Transform, and GameObject

In order to send one of these values as a null (or default) we need to use special syntax to ensure the right method signature is resolved.

using Coherence;
using Coherence.Toolkit;
using UnityEngine;
using System;

public class MyCommand : MonoBehaviour
{
    private CoherenceSync sync;

    public void MyNullableCommand(string someString, Byte[] someArray)
    {
        if (!string.IsNullOrEmpty(someString)) //Could be null or string.Empty
        {
            // Do something with the string
        }

        if (someArray != null && someArray.Length > 0) //Could be null or Byte[0]
        {
            // Do something with the array
        }
    }

    public void SendNullableCommand()
    {
        sync.SendCommand<MyCommand>(nameof(MyNullableCommand),
            MessageTarget.All,
            (typeof(string), (string)null),
            (typeof(Byte[]), (Byte[])null));
    }
}

Null-value arguments need to be passed as a ValueTuple<Type, object> so that their type can be correctly resolved. In the example above sending a null value for a string is written as: (typeof(string), (string)null)

and the null Byte[] argument is written as: (typeof(Byte[]), (Byte[])null)

Mis-ordered arguments, type mis-match, or unresolvable types will result in errors logged and the command not being sent.

Limitations

When a Prefab is not using a baked script there are some restrictions for what types can be sent in a single command:

• 4 entity references

• maximum of 511 bytes total of data in other arguments

• a single Byte[] argument can be no longer than 509 bytes because of overhead

Some network primitive types send extra data when serialized (like Byte arrays and string types) so gauging how many bits a command will use is difficult. If a single command is bigger than the supported packet size, it won't work even with baked code. For a good and performant game experience, always try to keep the total command argument sizes low.

When a Client receives a command targeted at AuthorityOnly but it has already transferred an authority of that entity, the command is simply discarded.

CoherenceSync is a component that should be attached to every networked GameObject. It may be your player, an NPC or an inanimate object such as a ball, a projectile or a banana. Anything that needs to be synchronized over the network and turned into an Entity. You can then select which of the attached public properties and methods of other components you would like to sync across the network.

Synced variables and commands

To start syncing variables and commands, open the Configure window that you can access from the CoherenceSync inspector:

Any components attached to the GameObject 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.

Persistence and authority

Ownership transfer

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

Entity lifetime

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

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

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

Uniqueness

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

• No Duplicates - ensure objects are not duplicated by assigning them a Unique ID.

  • You can set the Unique ID manually in the Prefab, only one Prefab instance will be allowed at runtime, any other instance created with the same UUID will be destroyed.

  • When creating a Prefab instance in the Scene at Editor time, a special Prefab Instance Unique ID is assigned, if the manual UUID is blank, the UUID assigned at runtime will be the Prefab Instance ID:

Uniqueness examples

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

Interactable objects: If you have several instances of a given Prefab, but each instance must be unique (Such as doors, elevators, pickups, etc.), each instance created in Editor time will have a auto-generated Prefab Instance Unique ID. This means that i.e. a door will only spawn once, but still replicate its state across the network.

Entity simulation type

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

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

Authority transfer style

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

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

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

Orphaned entities

By making the GameObject persistent, you ensure that it remains in the game world even after its owner disconnects. But once the GameObject has lost its owner, it will remain frozen in place because no Client is allowed to update or delete it. This is called an orphaned GameObject.

In order to make the orphaned GameObject interactive again, another Client needs to take ownership of it. To do this, enable Auto-adopt orphan.

Transfer request

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

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

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

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

Connection status

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

Baked script

When CoherenceSync variables/components are sent over the network, by default, Reflection Mode is used to sync all the data at runtime. Whilst this is really useful for prototyping quickly and getting things working, it can be quite slow and unperformant. A way to combat this is to bake the CoherenceSync component, creating a compatible schema and then generating code for it.

The schema is a file that defines which data types in your project are synced over the network. It is the source from which coherence SDK generates C# struct types (and helper functions) that are used by the rest of your game. The coherence Replication Server also reads the schema file so that it knows about those types and communicates them with all of its Clients efficiently.

The schema must be baked in the coherence Settings window, before the check box to bake this Prefab can be clicked.

When the CoherenceSync component is baked, it generates a new file in the baked folder called CoherenceSync<AssetIdOfThePrefab>. This class will be instantiated at runtime, and will take care of networked serialization and deserialization, instead of the built-in reflection-based one.

Commands

Commands are public methods from Components that are marked as synced in the Configure window.

Refer to the Commands section.

While the basic case of direct parent-child relationships between CoherenceSync entities is handled automatically by coherence, more complex hierarchies (with multiple levels) need a little extra work.

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

Player > Shoulder > Arm > Hand

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

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

This setup allows you to place instances of the flashlight Prefab anywhere in the hierarchy of the Player (you could even move it from one hand to the other, and it will work).

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

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

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

CoherenceNode works using two public fields which are automatically set to sync using the [Sync] attribute.

[Sync] public string path;
[Sync] public int pathDirtyCounter;

The path variable describes where in the parent's hierarchy the child object should be located. It is a string consisting of comma-separated indexes. Every one of these indexes designates a specific child index in the hierarchy. The child object which has the CoherenceNode component will be placed in the resulting place in the hierarchy.

The pathDirtyCounter variable is a helper variable used to keep track of the applied hierarchy changes. In case the object's position in the parent's hierarchy changes, this variable will be used to help settle and properly sync those changes.

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

Triggers

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

using UnityEngine;
using Coherence;
using Coherence.Toolkit;

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

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

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

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

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

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

Now, bind the PlayJumpAnimator method as a command.

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

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

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

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 LiveQuery. A local reference can only be valid if there's an actual Entity instance to reference. If this becomes a problem, consider switching to using the CoherenceNode component or Parent-Child relationships of prefabs which ensures that another Entity becomes part of the query.

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

• Cyclic references are undefined behavior for now. Therefore multiple entities created on the same Client that reference each other might never get synced properly. This is also holds true for references that exist through intermediate entities (A has reference to B has reference to C has reference A - cyclic).

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.

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

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

To do so, open the Prefab in Prefab Mode by clicking the Open Prefab option in the inspector. This will allow you to select any of the GameObjects that belong to the hierarchy, the Configure window will be updated automatically, showing you everything that is available to be synchronized.

Overview

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

Usage

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

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

Hierarchies with intermediary transforms

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

Level of detail considerations

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

Handling parent destruction

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

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

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

Usage

Let's start with a simple example:

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

Limitations

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

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

Scenes or levels are a common feature of Unity games. They can be loaded from Unity scenes, custom level formats, or even be procedurally generated. In networked games, players should not be able to see entities that are in other scenes. To address this, coherence's scene feature gives you a simple way of controlling what scene you're acting in.

Each Coherence scene is represented by an integer index. You can map this index to your scenes or levels in any way you find appropriate. Projects that don't use scenes will implicitly put all their entities into scene 0.

Keeping a Connection alive between Scene changes

Since the connection to the Replication Server is done through the component, it means that if you switch Scenes, the current CoherenceBridge that holds the connection to the Replication Server will be destroyed.

In order to keep a CoherenceBridge with its connection alive between Scene changes, you will have to set it as Main Bridge in the Component inspector:

Automating Scene transitions

These are the options related to Scene transitions:

• Main Bridge: This CoherenceBridge instance will be saved as DontDestroyOnLoad and its connection to the Replication Server will be kept alive between Scene changes. All other CoherenceBridge components that are instantiated from this point forward will update the target Scene of the Main Bridge, and destroy themselves afterwards.

• Use Build Index as Scene Id: Every Scene needs a unique identifier over the network. This option will automate the creation of this ID by using the Scene Build Index (from the Build Settings window).

• Scene Identifier: If the previous option is unchecked, then you will be able to manually set a Scene Identifier of your own (restricted to unsigned integers).

Authority

A client connection and all the entities it has authority over are always kept in the same coherence scene. Clients cannot have authority over entities in other scenes. This implies two things:

1. When a client changes scene, it will bring along any entities it has authority over.

2. If an entity changes ownership via authority transfer, it will be moved to the new owner's scene.

Orphans

An entity that does not have an owner is an orphan. Orphaned entities will stay in the scene where their previous owner left them.

Implicit destruction of entities when loading Unity scenes

Note that Unity will destroy all game objects not marked as DontDestroyOnLoad whenever a new Unity scene is loaded (non-additively). If the client has authority over any of those entities at that point, coherence will replicate that destruction to all other clients. If that is undesirable and you need to leave entities behind, make sure that authority has been lost or transferred before loading the new Unity scene. You can of course also mark them as DontDestroyOnLoad, which will bring them along to then new scene.

Since this process involves a bit of logic that has to be executed over several frames, coherence provides a LoadScene helper method (co-routine) on CoherenceSceneManager. Here's an example of how to use it:

Limitations

It is not possible to move entities to other scenes without the client connection also moving there. Additionally, you can't currently query for entities in other scenes.

Both of these limitations are planned to be addressed in future versions of coherence.

Custom setup

If your project isn't a good fit for the automatic scene transitioning support described above, it is possible to use a more manual approach. There are a few important things to take care of in such a setup:

If you ever load another Unity scene, the CoherenceBridge that connects to the server needs to be kept alive, or else the client will be disconnected. A straightforward way of doing this is to call Unity's DontDestroyOnLoad method on it. This creates two problems when replicating entities from other Clients:

1. The bridge instantiates remote entities into the scene where it is currently located. To override this behaviour, set the InstantiationScene property on your CoherenceBridge to the desired scene.

2. Any new CoherenceSync instances will look for the bridge in the same scene that they are located. If the bridge is moved to the DontDestroyOnLoad scene, this lookup will fail. You can use the static CoherenceSync.BridgeResolve event to solve this problem (see the code sample in the next section). Alternatively, if you have a reference to a Scene, you can register the appropriate bridge for entities in that scene with CoherenceBridgeStore.RegisterBridge before it is loaded.

Additionally, coherence queries (e.g. CoherenceLiveQuery) also look for their bridge in their own scene, so you might have to set its bridgeResolve event too.

Code sample

Here's a complete code sample of how to use all the above things together:

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

Sync Attribute

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

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

Command Attribute

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

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

Overview

Out of the box, coherence can use C# reflection to sync data at runtime. This is a great way to get started but is very costly performance-wise and has a number of limitations on what features can be used through this system.

For optimal runtime performance and a complete feature set, we need to create a schema and perform code generation specific to our project.

Learn more about this in the section.

coherence calls this mechanism baking.

Baking

Click on the coherence / Bake menu item.

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

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

Baking Settings

Check .

Two bake modes

coherence offers two mechanisms to generate baked scripts: through Assets or through a Source Generator. By default, coherence baked using Assets, but you can change this setting anytime in the coherence Settings window.

Bake mode: Assets

When you bake using Assets, the generated code will output to Asset/coherence/baked. This is a simple solution, allowing for an easy inspection and debugging of the generated files, but it comes with a few drawbacks:

• You should version the baked files, which can clutter your VCS workflow.

• Since baked scripts access your code, changing your code will get you into compilation errors.

Bake mode: Source Generator

When you bake using the Source Generator, the generated code is fed directly to the compilation pipeline, not generating the files in the Assets folder. In this process, coherence can analyze your code syntactically and semantically. This means it can detect cases where changes in your code can affect the baked files, anticipating compiler errors and avoiding them altogether. This mode comes with a few drawbacks too:

• File Assets/coherence/Footprint.cs is created/updated every bake operation, to trigger a recompile on your code. This file (and its .meta) can be ignored in your VCS.

• A bake operation is performed on every recompile. For most projects this is not noticeable. But if your project is heavy or your computer is slow, this can take additional time on top of the normal recompilation time.

• Since baked files are not versioned and have to be generated, the protocol code generator (executable bundled with the SDK package) needs to keep its execute permissions and should have write permission on <project>/Library/coherence. This is usually not a problem, except in continuous integration scenarios, where there might be strict rules on files having the execute permission.

• Harder to debug. Since files are not in Assets anymore, you can't click on them and have proper code completion. The last generation made through the Source Generator is available in Library/coherence/LastBake.

As you can see, there are pros and cons to each mechanism, so we recommend you try both and check what works best for your workflow.

Using the Baked Script in your Prefab

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

Modifying bound data, safe mode and the watchdog

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

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

Like so:

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

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

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

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

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

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

The Configure window lists all variables and methods that can be synced for the selected Prefab. Each selected element in the list is stored in the Prefab as a Binding with an associated Descriptor, which holds information about how to access that data.

By default, coherence uses reflection to gather public fields, properties and methods from each of the Prefab's components. You can specify exactly what to list in the Configure window for a given component by implementing a custom DescriptorProvider. This allows you to sync custom component data over the network.

Take this player inventory for example:

Since the inventory items are not immediately accessible as fields or properties, they are not listed in the Configure window. In order to expose the inventory items so they can be synced across the network, we need to implement a custom DescriptorProvider.

Creating a custom DescriptorProvider

The main job of the DescriptorProvider is to provide the list of Descriptors that you want to show up in the Configure window. You can instantiate new Descriptors using this constructor:

• name: identifying name for this Descriptor.

• ownerType: type of the MonoBehaviour that this Descriptor is for.

• bindingType: type of the ValueBinding class that will be instantiated and serialized in CoherenceSync, when selecting this Descriptor in the Configure window.

• required: if true, every network Prefab that uses a MonoBehaviour of ownerType will always have this Binding active.