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

coherence provides two types of spaces where realtime gameplay can happen: Rooms and Worlds. In addition to these, Lobbies provide functionality for players to meet before a match, and to chat.

Read the differences between these in this quick overview.

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 (the Room) 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 Worlds API.

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.

Lobbies

Lobbies are a convenient way to do matchmaking between player accounts, filter players based on their attributes, and provide a way for them to communicate among each other.

Use case

Continuing from our MMO example (a World), you have now implemented dungeon instances that take place in Rooms. But how to best allow players to organize themselves into groups to enter these instances? This is what Lobbies are used for. You can create your own restrictions on player count, level, etc., but Lobbies could also allow the players that create them to set specific restrictions based on level or class.

See Lobbies.

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?

What is coherence?

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

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

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

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

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

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

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

Network engine

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

Authority models

The network engine supports multiple authority models:

• Client authority

• Server authority

• Server authority with client prediction

• Authority handover (request, steal)

• Distributed authority (multiple simulators with seamless transition)

• Deterministic client prediction with rollback ("GGPO") - experimental

Persistence

coherence supports persistence out of the box.

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

Engine support

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

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

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

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

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

What is coherence made of?

Replication Server (RS)

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

Game Client

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

Simulation Server ("Simulator")

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

Schema

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

Code generation ("Baking")

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

State replication

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

State Replication

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

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

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

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

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

Using the same scene as in the previous lesson, we now take a look at another way to make Clients communicate: Network Commands. Network Commands are commonly referred to as "RPCs" (Remote Procedure Calls) in other networking frameworks. You can think of them as sending messages to objects, instead of syncing the value of a variable.

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 greet other players. For both of these actions to play their animation, we need to send a command over the network to invoke 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 third tab, Methods:

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

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

sync.SendCommand<Animator>(nameof(Animator.SetTrigger), MessageTarget.Other, "Wave");

Analysing this line of code, we can recognize 5 key parts:

• First, notice how the command is invoked on a specific CoherenceSync (that sync property).

• We want to invoke this command on a component that is an Animator.

• We invoke a method called "Animator.SetTrigger".

• With MessageTarget.Other, we are asking to send this message only to network entities other than the one that has the CoherenceSync we chose to use.

• We pass the string "Wave" as the first parameter of the method to invoke.

animator.SetTrigger("Wave");

In this example we used Network Commands to trigger a transition in an animation state machine, but they can be used to call any instantaneous behavior that has to be replicated over the network. As an example of this, it is also used in the Persistence lesson to change a number in a UI element across all Clients.

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

Scenes

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

1. Basic syncing, animations, sending commands

2. Physics and Authority

3. Areas of interest

4. Parenting entities

5. Complex entity hierarchies

6. Persistence

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

Download the Unity project

The Unity project can be downloaded from its Github repo. The Releases page contains pre-packaged .zip files.

Try a pre-made build

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

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

Make your own build

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

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

You can also upload a build to the cloud and share a link with friends. To do that, follow these steps or watch this quick video to learn how to host builds on the coherence Cloud.

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

In this scene

This scene features 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 begins simulating the physics for them.

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 one) 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:

// Grabbable.cs
if(!_sync.HasStateAuthority)
{
    _sync.RequestAuthority(AuthorityType.Full);
}

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.

_sync.OnStateAuthority.AddListener(OnStateAuthority);
_sync.OnStateRemote.AddListener(OnStateRemote);

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.

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

About uniqueness and persistence

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

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

For this reason, the CoherenceSync is configured so that these crates 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.

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.

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

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.

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

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 keep animation states in sync, making it look like network-instantiated Prefabs on other Clients 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, etc.).

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, just like other regular public properties.

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 can't just enable in the Config window like with other animator parameters. We will see how to sync them in the next lesson, using Network Commands.

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

In this scene

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

How it's set up

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

Direct parenting of network entities in coherence happens exactly like usual, with a simple transform.SetParent(). The player's Move script is set to recognize the moving platforms when it lands on them, and it just parents itself to it.

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

Effects of parenting entities

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

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

Limitations of simple parenting

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

A hierarchy could look like this:

• Platform

  • Player

    • Character graphics

    • Bones

    • ...

  • Platform's graphics

  • ...

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

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

• Spaceship

  • Elevator1

    • Elevator graphics

  • Elevator2

    • Player

      • Crate

      • Character graphics

    • Elevator graphics

  • Spaceship graphics

  • ...

For cases like these, coherence takes care of them automatically. More complex hierarchies require a different handling, and we cover them in another lesson.

We have seen a lot of examples where objects belonging to a Client would disappear with them when they disconnect. We call these objects 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.

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 we explain later).

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:

When it gets instantiated, the flower writes the current UNIX timestamp into the timePlanted variable. This variable never changes after this, and is used to reconstruct the phase in which the flower is in (see below). Similarly, as the flower is not moving, position and rotation are only synced at the time of planting.

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

coherence supports the ability to have an instance of the game active in the cloud, running some logic all the time (we call this a Simulator). However, this might be an expensive setup, and it's good advice to think things through differently to keep the cost of running your game lower.

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:

// Flower.cs
public void DestroyRemote()
{
    _sync = GetComponent<CoherenceSync>();
    _sync.OnStateAuthority.AddListener(DestroyThis);
    _sync.RequestAuthority(AuthorityType.Full);
}

private void DestroyThis()
{
    _sync.OnStateAuthority.RemoveListener(DestroyThis);
    Destroy(gameObject, .1f);
}

As we discussed in the Physics lesson, switching authority is a network operation that is asynchronous, so we need to wait for the reply from the player who currently has authority.

coherence 1.2.3

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

Get started

If you would like to get started right away, you can check the Installation page to learn how to install coherence in Unity, set up your Scene, Prefabs, interactions, as well as deploy your project to be shared with your friends.

Learn coherence

We have an entire section of content to get you up to speed with coherence: Learn.

If you're new to all of this, you can start with the Beginner's guide to networking which is a great intro to high-level networking.

If you prefer to be hands-on, you can explore the package Samples included directly within the Unity SDK. Or, download one of our pre-made Unity projects First Steps or Campfire, which come with great documentation explaining the thinking behind them.

If you enjoy videos as a learning tool, we have a playlist of video tutorials dedicated to getting started with the Unity SDK.

Update an existing project

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

Join the community

• Get help, ask questions and suggest features in our Community

• Chat with us on Discord

• Contact us at devrel@coherence.io

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.

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

As mentioned in the lesson about Parenting Entities, parenting a network entity to a GameObject that belongs to a chain requires some setup. To be able to pick up the crate with the crane, we equip it with a CoherenceNode component:

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.

Similarly to the crates in the Physics lesson, we don't just want the crate to automatically become non-kinematic when we have authority on it. We want the crate to stay kinematic when authority changes while it's being held by the arm.

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:

crate.GetComponent<Rigidbody>().isKinematic = crate.transform.parent != 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 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!

In this scene

Upon connecting, a script instantiates a character for you. Now you can move and jump around, and you will see other characters move too.

coherence takes care of keeping network entities in sync on all Clients. When another Client connects, an instance of your 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

When you click Connect in the sample UI, the CoherenceBridge opens a connection. The PlayerHandler GameObject on the root of the hierarchy controls character instantiation by responding to that connection event.

Its PlayerHandler script implements something like this:

// PlayerHandler.cs
// Listen to CoherenceBridge events
private void Awake()
{    
    _bridge = FindObjectOfType<CoherenceBridge>();
    _bridge.onConnected.AddListener(OnConnection);
    _bridge.onDisconnected.AddListener(OnDisconnection);
}

// Handle local player lifetime, in response to connection events
private void OnConnection(CoherenceBridge bridge) => SpawnPlayer();
private void OnDisconnection(CoherenceBridge bridge, ConnectionCloseReason reason) => DespawnPlayer();

private void SpawnPlayer()
{
    _player = Instantiate(prefabToSpawn, initialPosition, Quaternion.identity);
}

private void DespawnPlayer()
{
    Destroy(_player);
}

On connection, a character is created. On disconnection, the same script destroys the character's instance. Note how instantiating and removing a network entity is done just with regular Unity Instantiate and Destroy.

Now let's take a look at the Prefab that is being instantiated. You can find it in the /Prefabs/Characters folder.

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

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 for this object. 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.

In First Steps, all the variables are set to public by default. The network code that coherence automatically generates can only access public variables and methods, without them being public syncing would not work.

In your own projects, keep it in mind to always set synced variables to public!

Component Actions

To ensure that Clients don't modify the properties of entities they don't have authority over, we need to make sure that they are not running 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.

While in Play Mode, try selecting a remote player character. You will notice that some of its script have been disabled by coherence:

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

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

Once you follow the instructions to install the coherence SDK package for Unity, you will be able to explore the package Samples with no additional download. You can either:

• Go to: Coherence > Explore Samples

• Open Unity's Package Manager (Window > Package Manager) and navigate to the package samples

Note that the Samples are meant to be self-explanatory, so they come with no documentation.

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 that Entity stays 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.

Topics covered

Object pooling | CoherenceSyncConfigRegistry | CoherenceSyncConfig

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:

CoherenceSync newLog =
    logSyncConfig.GetInstance(transform.position + [...], Quaternion.identity);

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:

_sync.ReleaseInstance();

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

private void OnDisable()
{
    isBeingCarried = false;
    _rigidbody.isKinematic = false;
    _collider.enabled = true;
    
    // ... in addition to removing any listener set in OnEnable
}

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.

Before we dive into the networking-specific topics, in this introductory page we'll quickly go over how the whole gameplay is structured and set up. We'll cover it both from a point of view of Prefabs and of code so you know where to look for what.

Controls

Player characters, interactions

You'll find the Player Prefab in Prefabs/Characters.

When connecting, an instance of the Player is instantiated in the scene by the PlayerHandler script, which listens to the corresponding event fired by CoherenceBridge.

The player character is a Rigidbody-driven kinematic capsule that is hovering above the ground slightly, and detecting the ground via a raycast. Movement values are provided by the Move script on its root, which is in turn informed by the PlayerInput component. When instantiated over the network both these components are disabled, and the Rigidbody is set to be kinematic.

Besides movement, other actions are controlled by scripts on three child GameObjects: Interactions, Emotes, and Chat.

When pressing the interaction key, the right action will be carried on by one of the scripts ChopAction, SitAction, and GrabAction, depending on the type of the object highlighted (a ChoppableTree, a Chair, or a Grabbable).

The chat system is described here. Other actions are described below.

Chopping down trees

The trees have an Interactable script that indicates which mesh gets highlighted.

They have an amount of energy that determines the number of times they need to be chopped to be cut down. When they run out, they transition to a chopped state and spawn a tree log. A coroutine makes them spring out again after a certain amount of time.

Read more about how characters interact with remote trees in this page about dealing with a non-authority object.

The campfire

The campfire is at the center of this demo. Players can burn anything they can pick up by simply throwing the object into it. The campfire exists only in one instance and is pre-placed in the scene, and marked as unique on the network by setting the Uniqueness property of its CoherenceSync to No Duplicates.

Most of the logic of the campfire is in the Campfire component. This handles a lot of the networking flow, and can be run by a Client but, if a Simulator connects, they will take over.

In addition to calculating which fire effect to display, it's also in charge of replicating the sound of burning an object on all Clients (read more about effects here).

Learn more about the campfire's logic on this page.

Carrying and burning objects

They are all Prefab Variants of a base Prefab called Base_BurnableObject, which you can inspect to get a sense of the common functionality.

The objects have several scripts: Grabbable provides the ability for them to be picked up, carried and thrown, while Burnable grants the ability to be burnt on the campfire.

They have a collider at the root which determines collisions, but a child GameObject named Interaction (and its Interactable script) has the trigger collider that makes it interactive, and allows to pick the object up. The Interactable script also holds a reference to the objects to highlight when the player's interaction trigger intersects the object.

Burnable types

The logs that are spawned when chopping down trees are not unique, and they are set to Allow Duplicates. Check this page for more info on the logs and how they are recycled using an object pool.

Instead, the other burnable objects are pre-placed in the scene, and set to be unique (No Duplicates): the banjo, the cooler, the bins, the mushrooms, and more. More details on the lifetime of these pre-placed objects in the section below.

The server-side Keeper Robot

The Keeper Robot is an NPC designed to be run by a Simulator (aka, the "server"), to restore the campsite to its initial state even when no-one is connected.

Its script will cycle through all unique campfire objects every X seconds. If an object has been destroyed, it will recreate it and put it in its place. If it has been moved, it will just chase it down and put it back into its place.

The way the robot knows about destroyed objects is because the objects, when created the first time, spawn an invisible marker (that we call an "object anchor") which the robot can inspect to know which object has disappeared, and where it was originally placed. The page about custom instantiation has more info on these objects and their anchors.

Read more about this server-side NPC works on its dedicated page.

Chairs and sitting

Sitting is one of the three actions that can be performed by interacting with objects. It doesn't have networking effects, so it's not covered in this tutorial pages.

Topics covered

Authority | Authority transfer | Network Commands

In a networked game, an object's logic is always run by one node on the network, whether it's a Client or a Server (which we call a Simulator in coherence). We say that the node "has authority" on the network entity.

There are cases where it makes sense to transfer authority, like it happens in this project with objects that can be picked up. When the player grabs an object, the Client performing it requests authority over the network entity. Once it gets authority it starts running its scripts and has full control over it. This is a very good way to go when only one player can interact with a certain object at a given time.

However, there are cases when we don't want to change who has authority on an entity. In the case of an object that many players can interact with at the same time, it wouldn't make sense to continuously move authority between nodes.

The interaction with such remote entities then needs to happen entirely through Network Commands.

Our use case

In this project, it is the case of the chairs placed in the scene. The first Client or Simulator to connect will take authority over them, and it will keep it until they disconnect.

When a player wants to sit down on a chair, they inform the Authority that they are doing so. The client holding authority will then set the chair as busy, which prevents other players from sitting on it next time they try.

However, for the sake of simplicity and to illustrate the point, we intentionally left this interaction a bit flaky. Can you guess why? What could go wrong with this setup?

The code

The action originates in SitAction.cs:

public void Sit(Chair chairComponent)
{
    if (!_chair.isBusy)
    {
        _chair.Occupy();
    }
{

SitAction checks if the isBusy property of the chair is set to true (by the authority, of course). If so, it means someone else is already sat on the chair. If false, we can sit. So it invokes Chair.Occupy().

[Sync] public bool isBusy;

And further down, the essence of the interaction:

public void Occupy()
{
    if (sync.HasStateAuthority) ChangeState(true);
    else sync.SendCommand<Chair>(nameof(ChangeState), MessageTarget.AuthorityOnly, true);
}

public void Free()
{
    if (sync.HasStateAuthority) ChangeState(false);
    else sync.SendCommand<Chair>(nameof(ChangeState), MessageTarget.AuthorityOnly, false);
}

[Command(defaultRouting = MessageTarget.AuthorityOnly)]
public void ChangeState(bool newBusyState)
{
    isBusy = newBusyState;
    // Deactivates the collider so the chair can't be even selected
}

So both when occupying a chair (Occupy()) or standing up (Free()), the player executing the action invokes the ChangeState method, either directly or as a Network Command - depending if they are the one with authority.

So one way or the other, ChangeState gets executed on the authority, who sets the isBusy property to its new value. On the next coherence update, the property will be sent to the other Clients.

What could go wrong?

The answer: Clients are using the isBusy property as a check for whether they can sit or not. It is possible that two players will approach a chair at the same time, check if isBusy is false (and yes, it will be false), at which point they will inform the authority that want to sit down on it.

The authority performs no additional checks, so you will see both players successfully sitting on the chair, overlapping on each other.

Thankfully we also coded the rest of the interaction so that this doesn't break the game. So while this incidence and the consequences for this interaction are low-risk, if you're looking to create a more robust system it could make sense to implement a check on the authority, and have the Client wait for an answer before they sit down.

We do this in other parts of the demo, like when chopping a tree or when picking up an object. Check the following section on chopping trees to explore this similar but more complex use case.

Once you have learned the basics using the 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 .

Download the Unity project

The Unity project can be downloaded from its . 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 . 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

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.

Topics covered

| Flexible authority

Even when creating a game that is mainly client-driven, we can still run some of the code on a Simulator. This is very useful to create, for instance, an NPC that operates even when all Clients (players) are disconnected, to give a semblance of a living world.

Our use case

In this project we used this pattern for the little yellow robot that sits beside the camp. If players move one of the camp's key objects out of place, the robot will tidy up after them. It can even recreate burned objects out of thin air!

Because this behavior is run by a Simulator, even if no-one is connected, given enough time all objects will be back in their place.

Prefab setup

To setup the robot Prefab to be run by a Simulator couldn't be simpler. The only thing we need to do is to set the Simulate In property of the CoherenceSync to Server Side.

We also set both the KeeperRobot script and the NavMeshAgent to disable on remote instances from the coherence Configuration panel, so they automatically turns themselves off on Client machines.

The code

Besides the simple state machine code that runs it, only one thing is worth noting here.

The exact moment when the robot starts acting is not in Start like usual. We imagined this behavior for an always-on world, so that it could start acting even long after other Clients disconnected. To ensure this, we hook into the onLiveQuerySynced event of the CoherenceBridge:

This way, the Simulator has the time to sync up with whatever happened to the campfire objects on the Replication Server, before even beginning to act.

This means that while gameplay can benefit from the presence of this NPC, it's not dependent on it. The Simulator can be always online, or connect and disconnect at times, or to be online only at certain times of the day, and so on.

Coding behaviors like this can open up many creative possibilities in the game's design.

Hiding code from the Clients

One typical pattern here is to wrap any server-side logic in the conditional compilation directive #if COHERENCE_SIMULATOR. This is a great idea especially if the code needs to be obfuscated to normal Client builds, because by doing so, it won't be compiled in the Client at all.

We did it, but we were careful to leave some things out:

As you can see, we left out the 4 Network Commands used to play sounds, and the properties they need to do it. The idea here is that the authoritative instance of the robot, which is running the logic on the Simulator, instructs the non-authoritative instances to play sounds when needed.

Remember that disabling a script only prevents Unity functions to be called (Awake, Start, Update...), but it doesn't prevent invoking its methods.

Testing server behavior on a Client in the Editor

Finally, you might have noticed how we not only compile this code for Simulator builds, but also when in the Unity editor:

This allows us to quickly test the behavior of this robot without adding and removing compilation directives. By simply changing the Simulate In property of the CoherenceSync to Client Side, we can hit the Play button and see the robot move, as if a Simulator was connected.

This is a great way to speed up development and one of the advantages of coherence's flexible authority model: you don't need to code a behavior in a special way to change it from Client to Server side and vice versa.

It is good practice though to switch the robot to Server Side again at regular intervals, and test the game by making an actual Simulator build, in order to create the whole network scenario with all its actors.

This will help locate bugs that have to do with timing, connection speed, authority transfers, etc.

Topics covered

Networked audio | Networked particles | Animation Events

Usually, visual feedback can be expressed via syncing variables like Animator parameters, positions, and rotations. But sometimes we have the need to play sounds and particles, which are not types that can be automatically set to sync, or that we can send as arguments of . So how to do it?

Our use case

This project has a lot of moments where particles and sounds need to play, and we used different strategies for different cases, depending on how fast, repeated, or slow the action is.

The simple way: controlling AudioSource or ParticleSystem directly

The most straightforward solution to play a sound is to use a Network Command. Using Commands, you can remotely invoke methods on AudioSource or ParticleSystem components.

To do that, you could simply open the coherence Configuration panel (from the CoherenceSync), and check the methods you're interested in.

While this is a perfectly fine way of doing things, it requires you to call multiple Network Commands in case you wanted to play a sound and particles at the same time. This could lead to desynchronisation between sound and visuals.

As such, in this project we preferred compacting these calls into methods on their own that are invoked as one Network Command, often without parameters to minimize the data being sent across.

Triggering a sound associated to an action

Connected to the above, let's see how to create our own Network Commands to play sounds (or particles) as a result of an event that happened remotely.

For these sounds, we isolated the sound-playing behavior into Commands of their own. At the end of the KeeperRobot.cs class, we have:

(soundHandler is a script attached to the same gameObject)

Each of these methods is invoked as a Network Command, like so:

You can see how we don't play the sound over the network, that would be bandwidth-consuming for no reason, but we just communicate the intention to play it.

Alternative: building an index

Because we only have 4 sounds, we sort of "brute-forced" this, and created an individual Network Command for each sound. This is not a bad idea from the point of view of network traffic: sending a Network Command with no parameter produces less traffic than sending one with.

But it could be unwieldy if we had - say - 100 different sounds to play.

This solution also requires us to bake and produce a new schema if we add or remove one of these Commands. So for a more flexible solution, it could be nice to index the sounds and maybe create a generic Command like:

In this case though, it was ok to go for individual Commands.

Audio and particles tied to animations

There are actions that are really quick or short, and asking to play a sound via a command might result in a mismatch between the visuals (an animation) and the sound, due to network delay.

For instance, it wouldn't make sense to send a Command to inform other Clients to play the sound of a footstep. Chances are, by the time they receive the Command, another two-three footsteps have happened.

A script called PlayAnimationEvents.cs (remember to add it to the same object as the Animator!) listens to these events. An example from it:

This ensures an immediate playback, in sync with the animation. Plus, it produces zero network traffic.

So yes, fun fact: to "network" sounds and particles often you can do without networking anything at all!

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

Synchronicity is important

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

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

Player character representation

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

Client-side simulation

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

Topics covered

Chat |

Communication is an inherent part of online games and a chat, however simple, is a great way to enhance the range of expression for the players.

Our use case

We wanted to implement a very simple chat system. By pressing Enter, a small screen-space UI opens up and allows the player to compose a message. When they press Enter again, a balloon on top of their character displays the message to them, and to all connected Clients.

This is done in three parts.

The Chat script on the player reads the input, requests ChatComposerUI to display the chat composer that is part of the screen-space scene UI.

When the player sends a chat message, Chat is informed by an event sent by ChatComposerUI, and sends a Network Command SendChatMessage to all other clients.

Finally, the received message is displayed in world-space over the player's head the script ChatVisualiserUI present in the Player Prefab.

Getting extra mileage with byte[]

By default, coherence's Network Commands have a limit in the length that can be sent in one command. This is limited by the length of a UDP packet. While this limitation might be removed in the future, for now it means that chat messages can't be longer than a certain amount.

This amount, however, is quite different depending if you use a parameter of type string or of type byte[] (byte array). If you send a string, you will be able to pass on around 50 characters. This is really not much for a chat system.

If you use byte[] though, the number of characters goes up to (around) 500. Now we're talking!

So what we do in this demo is that first we convert the string that the player has typed in the UI into a byte array, and we send that via Network Command:

Then, on the receiving side, we reconvert it back into a string:

This simple trick allows us to send longer messages, or to send the same message generating less traffic.

Never miss a chat message

Because we are sending the chat messages on the CoherenceSync that is on the Player Prefab, it means that if that particular player instance is not visible to a Client because it's outside of their LiveQuery, they won't receive the Network Command and thus the chat message. This is maybe desirable in this demo, where the chat is visualised on top of the player.

Long-form chats

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

| |

We saw in the previous section about how sometimes it makes sense not to move authority around between Clients. At this point, Network Commands are the way to interact with a remote object.

Now let's take a look at another case of remote object, where the interactions with it need to be validated by the one holding authority, to avoid nasty cases of concurrency.

Our use case

In this project, it is the case of the trees that are placed in the scene. The first Client or Simulator to connect will take authority over them, and it will keep it until they disconnect.

When a player wants to chop a tree, they request the Authority to subtract 1 unit of energy. When the energy runs out, it's the Authority that spawns a new Log instance.

This centralization, as opposed to passing authority around, allows multiple players to chop the same tree at the same time and prevents many race conditions, because the important action (destroying the tree and spawning the log) is all resolved on the Client with Authority.

Conceptually, we can imagine the event flow to go like this:

(1) Chop action happens on a Client -> (2) Authority is notified, elaborates new state -> (3) Authority sends result to all others -> (4) All other Clients play out animation and effects

The code

You can find this flow in practice in the ChoppableTree.cs script. In this script, only one variable is synchronized, the energy of the tree:

The flow goes like this:

(1) A player presses the button to chop down the tree.

It locally invokes the method TryChop(), which checks if the tree hasn't been already chopped down, subtracts energy locally, and also invokes the Chop() method, locally or remotely depending if authority on this tree is here or not.

(2) On the Authority, the Chop() method is called, and checks if the tree needs to be effectively cut down based on its energy:

(3) If so, CutDown() is invoked locally, spawning the log and informing all other clients to play the animation of the tree disappearing:

(4) Finally, other Clients play animation, particles and sound locally in ChangeState(). They will also see the log spawn thanks to the automatic network-instantiation.

Changing a synced variable on non-authoritative Clients

Why do we subtract energy from a synced variable in TryChop() when we are not the Authority?

Ultimately, the final word on whether the tree has been chopped down completely is always on the Authority's side, of course. But by subtracting energy locally and immediately, we can deal with cases where the player manages to produce two or more chop inputs before the Network Command has travelled to the Authority (and back) with a result.

Imagine: the tree has 1 energy. If we didn't subtract energy locally, the player would be able to chop several times because until the Authority tells them that the tree is down, they still think it has 1 energy.

In fact, it would send several Chop() Network Commands for no reason, which the Authority would have do discard on arrival.

Instead, if we immediately change the value on the variable and we use it as an indication of whether we can chop or not this will stop the chopping after one hit, as it should be.

Soon, the Authority will have elaborated on its side that the tree has gone down, and will inform our Client (with ChangeState()). Because energy is a synced variable, it will be overwritten again with the value computed on the Authority - which of course will be 0 at this point, so it will match.

So nothing is lost and no state is compromised, but with this little trick we get immediate feedback and we avoid some unneeded network traffic.

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.

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

Persistence

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

Optimization by range

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

Optmizations using LOD

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

Simulators

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

Instance dungeons

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

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

Deterministic simulation

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

Deep bindings

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

It's quick and easy to set up a networked scene from scratch using the coherence SDK.

Setup video tutorial

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

Step by step

Preparing a scene for network synchronization requires to add three fundamental objects:

1. Add a CoherenceBridge

coherence > Scene Setup > Create CoherenceBridge

This object manages the connection with coherence's relay, the Replication Server, and is the centre of many connection-related events.

2. Add a LiveQuery

coherence > Scene Setup > Create LiveQuery

Creates a LiveQuery, which allows to define what are of the world the application is interested in when requesting data from the Replication Server. You can surround your entire scene in one query or can attach it to an object such as the player or a camera.

3. Add a Connect Dialog UI

coherence > Explore Samples

A Connect dialog UI provides an interface to the player to connect to the Replication Server, once the game is played. You can create your own connection dialog, but we provide a few samples as a quick way to get started.

If you're unsure about which dialog to add, choose Rooms for now. You can read more about Rooms and Worlds.

The connection dialog samples we provide are here for you to completely customize, you can read more in the section dedicated to Samples.

Using the coherence Hub window

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

To open it, go to coherence > coherence Hub

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 LTS releases are officially supported.

• The minimum supported Unity LTS versions are:

  • 2021.3.18+

  • 2022.2.5+

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.

An easy way to test your game locally is to simply create a build, and open several instances of it. Additionally, you can connect using the Editor, with the extra benefit of being able to inspect the hierarchy and the state of its GameObjects.

Pros

• Easy to distribute amongst team members

• Well-understood workflow

• Can test with device-specific constraints (smartphones, consoles, ...)

Cons

• Not the shortest iteration time, as you need to continuously make builds

• Harder to debug on the builds (requires custom tooling on your side to do so)

How to use?

Let's create a standalone build.

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 Unity by just hitting Play).

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

The coherence package comes with several samples you can choose to add to your project. Each provides Prefabs and scripts that you can add to your Scene and edit however you want.

There are currently 3 samples available: a , a , and a Lobby connection dialog.

The difference between Rooms and Worlds is explained on this page: , while have somewhat of a different role in that they are usually used in addition to Rooms in a game flow.

Adding a dialog to the scene

Each sample comes with a Prefab that can be added to your Scene. You can add them via coherence > Explore Samples.

Effectively these do two things for you :

1. Import the sample in the Samples directory of your project, if it isn't already.
2. Add the Prefab from the sample to your Scene. Int the example above, that would be Room Connection Dialog.prefab.

Room connect dialog

The Rooms Connect Dialog has a few helpful components that are explained below.

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

• Next is a toggle between Cloud and Local. You can switch to Local if you want to connect to a Rooms Server that is running on your computer.

• Next is a dropdown for region selection. This dropdown is populated when regions are fetched from the coherence cloud. The default selection is the first available region. This is not enabled when you switch from Cloud to Local. This is also only relevant if you deploy your game to several different regions.

• Next is a dropdown of available Rooms in the selected region (or in your local server if using the Local mode).

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

• If you know someone has created a room but you don't see it, you can manually refresh the rooms list using the Refresh button.

Creating a room

The Create a room section adds a Room to the selected region.

This section contains controls for setting a Room's name and maximum player capacity. Pressing the Create button will create a Room with the specified parameters and immediately add it to the Room Dropdown above. Create and Join will create the Room, and also join it immediately.

World connect dialog

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

If you start a local World server, it will appear as LocalWorld.

Modifying a sample

Samples are copied to your assets folder, this means you can change and customize the scripts and Prefabs however you like.

Upgrading samples

Future versions of coherence won't override your changes. If you upgrade to a newer version of coherence and import a new sample, they will be imported in a separate folder named after the coherence version.

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 of the game to it.

Running a Replication Server locally

You can run a local Replication Server from:

coherence > Local Replication Server > Run for Rooms / Run for Worlds

As with most features found in the menu, you can find local Replication Server functionality in the coherence Hub as well.

Open the Replication Servers tab and run a Room or a World Replication Server:

Regardless of how you launch it, a new terminal window will open and display the running Replication Server:

Testing the Game

is an open-source project which allows you to open multiple Unity Editor instances, all pointing to the same Unity project (using Symbolic links).

Pros

• Short iteration times

• Easy to debug since every client is an Editor

Cons

• Requires you to have multiple Unity Editors open

How to use?

• Install ParrelSync as described in their

  • UPM Package installation is preferred as coherence supports it out-of-the-box

  • If installing via .unitypackage, you need to set accordingly by yourself. For example, by adding the following script to an Editor folder in your project:

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

• Continue development in the main Editor. Don't edit files in the clone Editors.

• Enter Play Mode on each Editor.

coherence tells apart ParrelSync clones from the main Editor, so it's easier for you to not edit assets in clones by mistake.

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, we add the CoherenceSync component to Cube.

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:

(Optional) Networking an already existing Prefab

If you wish to start networking a Prefab that already exists in your project, you have several options to do it. Remember that they all lead to the same result.

You can:

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

• Manually add the CoherenceSync component.

• Drag the Prefab to the CoherenceSync Objects window. You can find it in coherence > CoherenceSync Objects.

(Optional) Prefab variants

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

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

This way, you can retain the original Prefab untouched, and build all the network functionality separately, in its own Prefab.

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.

The Prefab variant inherits the network settings from its parent, and you change those 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 line next to 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.

In its Inspector you can configure settings for Lifetime (Session-based or Persistent), Authority transfer (Not Transferable, Request or Steal), Simulate In (Client Side, Server Side or Server Side with Client Input) and Adoption settings for when persistent entities become orphaned, and more.

There are also a host of Events that are triggered at different times.

For now, we can leave these settings to their defaults.

2.1 Select variables to replicate

CoherenceSync allows you to automatically network all public variables and methods on any of the attached components, from Unity components such as Transform, Animator , etc. to any custom script, including scripts that came with the Asset Store packages that you may have downloaded.

To set it up, click on the Configure button in the CoherenceSync's Inspector. This brings up the Configuration window. Here you can select which variables you would like to sync across the network:

You will notice that position is already selected, and can't be removed. For our use case, let's add rotation and scale.

Close the Configuration dialog.

3. Add a movement script

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

Click on Assets > Create > C# Script. Name it Move.cs. Copy-paste the following content into the file:

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

4. Disable the component on replicated objects

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 want the position to be replicated over the network without keyboard input interfering with it.

In the Configuration window, click the Components tab:

Here you will see a list of Component Actions that you can apply to non-authoritative entities 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:

This ensures that, if a copy of this Prefab is instantiated on a Client with no authority, this script will be disabled and won't interfere with the position that is being synced on the network.

5. Bake the netcode

This process is very quick, and can be done in different ways:

• From the menu item coherence > Bake

• Within the coherence Hub, in the Baking tab, using Bake Now:

• When a Prefab contains changes that need baking, its Inspector will warn you. Pressing Bake here will actually bake all code for all Prefabs:

To recap

In short, setting up a Prefab for networking requires:

• A Prefab with a CoherenceSync added to it

  • Optionally, setting some of its properties

• Configuring what to sync in the Configure window

• Disabling components on remote entities, in the Configure > Components tab

• Baking the netcode

If you wish to get started and install the coherence Unity SDK, please refer to the page.

Upgrading to a new version

Open Unity Package Manager under Window > Package Manager and check the Packages - coherence section. It will state the currently installed version and if there are any recommended updates available:

Upgrade Guides

For example, if your project is on 0.7 and would like to upgrade to 1.0, upgrade from 0.7 to 0.8, then from 0.8 to 0.9, and so on. Always back up your project before upgrading, to avoid any risk of losing your data.

Versions prior to 0.9 are considered legacy. We don't provide a detailed upgrade guide for those versions.

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

Video tutorial

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

Step by step

Upload Schema

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

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

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

Run the project

You can now build the project and send the build to friends or colleagues for testing.

If you used one of the Connect Dialog samples, once you play the game it will fetch all the regions available for your project. This depends on the project configuration (e.g., the regions that you have selected for your project in the Dashboard).

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

Major changes for CoherenceSyncConfigRegistry

There has been a major refactor on how we deal with the registry.

First off, we're deprecating the registry holding configs as sub-assets. This has been the default up to 1.1, but on 1.2, it has been changed to store the configs in the Assets/coherence/CoherenceSyncConfigs folder.

For 1.2, we have avoided manual migration of existing subassets. You can trigger this operation from the registry inspector (Assets/coherence/CoherenceSyncRegistry). We don't automate this operation, since the extraction changes the asset GUIDs of the configs, which could lead to missing references. This is specially true if your project is referencing the configs directly, instead of going through the registry. Keep this in mind when you decide to extract existing subassets.

Compilation Errors

Client Hosting

In this update, bundling the Replication Server has been revamped to work with Streaming Assets. On the Settings window, instead of different toggles per platform, there's now one unified toggle:

is Unity's official solution for local multiplayer testing, available for Unity 2023.2+.

Pros

• Short iteration times

• Tighter integration within the Editor, doesn't require multiple (standalone) Editors open

Cons

• Requires Unity 2023.2+

• Can be more resource demanding than other solutions - this might change in upcoming MPPM updates

How to use?

• Install MPPM as described in their

• Open Window > Multiplayer Play Mode

• Enable up to 4 Virtual Players

• Make sure that the is up-to-date before starting to test, and that the Replication Server is running with the latest schema generated by it

• Enter Play Mode

coherence tells apart Virtual Players from the main Editor, so it's easier for you to not edit assets in clones by mistake.

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

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

Build the game

First, you need to build your game to a local folder on your computer as you normally would. Ensure to bake before doing so!

Upload to the coherence Cloud

In the coherence Hub window, select the coherence Cloud tab.

You can upload your build from the Share Build section of the tab. Select the platform, browse for the previously-created build, and click on the Begin Upload button.

Share your build

Now that build has been uploaded, you can share it by enabling and sharing the public URL on the coherence Cloud Dashboard:

Here you can customise the page to a degree. Don't forget to include instructions in the description, if your game doesn't have any!

By unchecking the Enabled option, you can obscure the page altogether, without having to remove builds.

Click on the Game Builds tab to manage builds for different platforms.

The public page

If you uploaded a WebGL build, the public link now allows for instant play directly in the browser:

If you uploaded builds for other platforms, they will be downloadable by clicking on the icons right below the WebGL build.