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.

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

Now we can build the project and try out network replication locally. This example will show you how to launch a local Replication Server 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:

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 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 Room connection dialog, a World connection dialog, and a Lobby connection dialog.

The difference between Rooms and Worlds is explained on this page: Rooms and Worlds, while Lobbies 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.

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:

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

Once everything is setup, you should ensure to run the process of Baking: coherence will produce the necessary netcode (i.e. a bunch of C# scripts) to ensure that when the game is running and the Client connects, all of the properties and network messages you might have configured will correctly sync.

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

Helper scripts

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 multi-client testing, but there are several options available to you, each with their own benefits and drawbacks.

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.

ParrelSync

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

Benefits

• Short iteration times.

• Easy debug because it's possible to inspect GameObjects in multiple instances.

Drawbacks

• Requires you to have multiple Unity Editors open.

Caveats

• EditorPrefs are not consistently shared between Editors.

Best practices

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

• Continue development in the original Unity Editor. Never edit files in the clone Editors.

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.

Benefits

• Short iteration times.

• No issues with schema incompatibility.

Drawbacks

• Experimental.

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.

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.

Video tutorial

Step by step

Sign up or log in

At this point, you can create a free account, which will grant you a number of credits that are more than sufficient to go through developing and testing your game in the cloud.

Connect the Unity project to the cloud

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

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

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.