Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
Latest Unity LTS releases are officially supported.
The minimum supported Unity LTS versions are:
2021.3.18+
2022.2.5+
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
Now open Window > Package Manager. Select My Registries in the Packages dropdown.
Highlight the coherence package, and click Install.
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:
You will then see the package in the Package Manager under My Registries.
When you successfully install the coherence SDK the Welcome Window will show.
It's quick and easy to set up a networked scene from scratch using the coherence SDK.
The topics of this page are covered in the first minute of this video:
Preparing a scene for network synchronization requires to add three fundamental objects:
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.
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.
You don't have to define a range for the LiveQuery. Leaving the range to 0 means that the range is infinite, so nothing is filtered out.
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.
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 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
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.
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 :
Import the sample in the Samples directory of your project, if it isn't already.
Add the Prefab from the sample to your Scene.
Int the example above, that would be Room Connection Dialog.prefab
.
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.
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.
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
.
Samples are copied to your assets folder, this means you can change and customize the scripts and Prefabs however you like.
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.
If you want the new sample to overwrite the old one, first rename the folder in which the samples are, then import the new version.
If you notice that the samples are non-responsive to input, make sure you have an EventSystem component in the scene.
In this section, we will learn how to prepare a Prefab for network replication.
Setting up basic syncing is explained in this video, from 1:00 and onwards:
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.
You can also follow the detailed step-by-step text guide below.
CoherenceSync
to your GameObjectFor 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:
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.
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:
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.
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.
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.
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.
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:
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
This is it! Setting up a Prefab to be networked doesn't require additional steps.
Spawning a player
Basic inputs to get Game Objects moving
Score keeper
Displaying player names
Camera facing UI
Off-screen spawning of enemies or other Game Objects
Indicator (arrow) for guiding the player towards off-screen Game Objects
Implementing Network Commands and Authority Transfer
Connection Events
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.
The folder to rename is the one that is named after the version number (normally its path would be something like Samples/coherence/1.1.0/
for coherence 1.1.0).
Learn how to create and use Prefab variants in the .
Its Inspector has quite a number of settings. For more information on them, refer to .
Note that you can configure variables, methods and components not only on the root, but also .
Once everything is setup, you should ensure to run the process of : 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.
Now you can run this setup or using the .
Helper scripts and samples can be found . These cover things such as:
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.
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:
Whether you run one for Rooms or for Worlds depends on which setup you plan to use, which in turn requires the correct corresponding Sample UI.
Now it's time to make a standalone build and test network replication.
#protip: Go to Project Settings, Player and change the Fullscreen Mode to Windowed and enable Resizable Window. This will make it much easier to observe standalone builds side-by-side when testing networking.
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.
Congratulations! You've made your first coherence replicated experience. But this is only the beginning. Keep exploring the documentation to take advantage of more advanced coherence features.
Quicker iteration during development
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.
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.
All instances of the game must have identical schemas, so you might want to ensure you are using Assets baking mode rather than Source Generator so the netcode is synced across editors automatically. If you do intend to use Source Generator, you need to remember to bake in each open Unity Editor. In that case, it might make sense to enable Bake Automatically On Enter Play Mode in coherence settings. You can change both of these from the coherence Hub > Baking, or in Project Settings > coherence.
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 Unity Editor. Never edit files in the clone Editors.
When you need to test, ensure the netcode is baked for all editors.
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.
The topics on this page start from around 1:00 in the video below:
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.
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.
Before connecting, make sure everybody selects the same region, and that this region is not local.
For quick and easy testing, we suggest trying out the publish to WebGL option. Anyone with the link can then try the build in a browser.
Keep in mind to add the description of game controls though!
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.
First, you need to build your game to a local folder on your computer as you normally would. Ensure to bake before doing so!
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.
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.
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.
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.
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.
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.
You are now logged into the Portal through Unity. Select the correct Organization and Project, and you are ready to start creating.
In this example we're working with Worlds. Make sure you have created a World before trying to deploy the Replication Server. To create a World, follow the steps described in .
If the status does not say "In Sync", or if you encounter any other issues with the server interface, refer to the section.
If you want an example of WebGL builds, try out our sample projects or (make sure to use Chrome!)
In your web browser, navigate to . Create an account or log into an existing one.