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

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

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

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

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

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

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

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

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

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

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

Requirements

Game engine support

coherence currently supports Unity. For custom engine integration,. For updates regarding Unreal Engine support, please check the page.

For custom engine integration,.

Unity requirements

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

• A Windows, Linux or macOS system.

Video Tutorial

Unity Package Manager

1. Add the Scoped Registry

• Name: coherence

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

• Scope(s): io.coherence.sdk

• Enable Preview / Pre-release Packages: yes

2. Install coherence

Now open the Window / Package Manager.

Select My Registries in the Packages dropdown.

Under coherence, click Install.

Alternative method: edit manifest.json manually

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:

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

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

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

Running a Replication Server locally

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

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

Building through Coherence Hub

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

Build and Connect

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

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

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

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

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

Connect across the local network

If you want to connect to the local Replication Server from another local device (such as another PC, Mac, Mobile or VR device), you can find your IPv4 address and use that as your server address in the Connect dialog. These devices need to be connected to the same network.

You can find your IPv4 address by going to your command line tool and type ipconfig . Remember to include the port number, for example 192.168.1.185:32001.

Setup video tutorial

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

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

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

1. Add MonoBridge

coherence > Scene Setup > Create MonoBridge

This object takes care of connected GameObject lifetimes and allows us to develop using traditional MonoBehaviour scripts.

2. Add LiveQuery - hierarchy

coherence > Scene Setup > Create LiveQuery

3. Add the sample UI

coherence > Scene Setup > Add Sample UI

Creates a Canvas (and Event System if not already present in the scene) with a sample UI that helps you connect to a local or remote Replication Server. You can create your own connection dialog, this one is just a quick way to get started.

Using the coherence Hub window

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

coherence > coherence Hub

Automatic issue solving

If we have identified any issues in your project, the Overview tab provides a one-click solution to solving it. In the example below, simply click the blue link next to the warning messages and coherence will redirect you to the correct place to learn more about how to fix the issue.

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

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

ParrelSync

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

Benefits

• Short iteration times.

• Easily debuggable instances.

Drawbacks

• Requires you to have multiple Editors open.

Caveats

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

• EditorPrefs are not consistently shared between Editors.

Best practice

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

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

• Continue development in the original Editor.

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

Building an executable

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

Benefits

• Easy to distribute amongst team members.

• Well-understood workflow.

Drawbacks

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

• Harder to debug the executables.

Caveats

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

Multiplayer Play Mode

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

MPPM Info

Benefits

• Short iteration times.

• No issues with schema incompatibility.

Drawbacks

• Experimental.

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

Video tutorial

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

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

Upload Schemas

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

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

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

Run project

The Connect Dialog fetches all the regions available for your project. This depends on the project configuration (e.g., the regions that you have selected for your project in the Portal).

You can now build the project again and send the build to your friends for testing.

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

Video tutorial

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

Sign up or log in

In your web browser, navigate to https://coherence.io/dev.

Create an account or log into an existing one.

Login through Unity

Open Unity

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

Login to Portal

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

Select Organization and Project

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

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

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

Build the game

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

Upload to coherence

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

Share your build

Now that build has been updated (signified by the green tick), you can share it by enabling and sharing the public URL. Anyone with this link can access the build.

WebGL

If you uploaded a WebGL build, the public link allows for instant play.

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

Video tutorial

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

Alternatively, you can follow the text guide below.

1. Add CoherenceSync to your GameObject

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

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

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

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

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

1.1 (Optional) Using Prefab Variants

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

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

This way, you can retain the original Prefab untouched.

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

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

2. Configure CoherenceSync

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

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

3. (Optional) Prefabs outside of the Resources folders

In order for coherence to know which Prefab to instantiate through the network, they must be located in Resources folders or added to the Prefab Mapper. The Prefab Mapper is simply a ScriptableObject that holds Prefabs we want to sync.

When a CoherenceSync Prefab outside the Resources folder is not present in the Prefab Mapper, the Add to Prefab Mapper button appears.

3.1. Addressables

If you are using the Addressables Package (1.15.0 or newer), the Prefab Mapper also supports that. The Prefab Mapper has a list for direct references and a list for addressables referenced using AddressableAssets.AssetReference. The directly referenced assets will be loaded at game start, while the addressables will be asynchronously loaded when needed.

Remember, in order for coherence to load assets as addressables, you need to follow Unity's default workflow for using Addressables which entails building the Addressables Group Bundles whenever the Prefab changes.

3.2. Prefab Mapper utilities

When adding a new Prefab to the mapper, it will automatically make sure to add it to the correct list (addressable or not), but if the Prefab already exists in the mapper and you have changed how it is loaded, simply press the Validate Mapping Lists button.

If you have a number of valid Prefabs that have not yet been added to the Prefab Mapper you can press the Add all CoherenceSync prefabs button.

If you have empty entries in the Prefab Mapper you can remove them by pressing Remove empty entries. This is optional.

4. Select variables to replicate

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

Under Configure, click Variables.

In the Configuration dialog, select position, rotation and scale.

Close the Configuration dialog.

5. Add an input script

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

Click on Assets > Create > C# Script.

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

using UnityEngine;

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

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

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

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

6. Disable input on replicated object

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

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

Under Configure, click Components.

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

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

7. Implementing your own Component Actions

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

using UnityEngine;

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

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

Your custom Component Action must implement the following methods:

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

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

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

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

using Coherence.Toolkit;
using UnityEngine;

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

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

8. Additional CoherenceSync settings

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

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

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

• On Networked Instantiation (when the GameObject is instantiated)

• On Networked Destruction (when the GameObject is destroyed)

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

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

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

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

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

Using the Coherence Hub

If you prefer, you can let the Coherence Hub guide you through your Prefab setup process. Simply select a Prefab, open the Synced Object tab in Coherence Hub and follow the instructions.

Extras

9. Constraints

There are some constraints when setting up a Prefab with CoherenceSync, hereafter referred to as Sync Prefab.

1. A Sync Prefab has one, and only one CoherenceSync component in its hierarchy

2. The CoherenceSync component must be at the Sync Prefab root

3. A Sync Prefab cannot contain instances of other Sync Prefabs

4. A hierarchy in a scene can contain multiple Sync Prefabs. However, such a hierarchy cannot be saved as a Sync Prefab as that would break rule 1-3.

9.1. Examples of valid setup

9.2. Examples of disallowed setup