Multiple Connections within a Game Instance

In some cases, you might want your game to create multiple individual connections within the same game instance. This could be the case when you want to support , or to create development environments (interpolation visualization, stress-testing, debug network scenarios, quick prototyping within the Editor, etc.).

To understand how to achieve this, it's important you understand how coherence establishes a connection.

What Makes a Network Connection

CoherenceBridge is the core component that handles a network connection with coherence. This component is responsible of establishing the connection, and also to keep in sync and .

One CoherenceBridge is able to handle one network connection, and keep in sync the network state within one scene: the one it was instantiated on.

1 CoherenceBridge = 1 network connection = 1 scene.

Knowing this crucial rule, if we want N connections, we will need N scenes, each of them with a bridge. Each bridge can establish a connection with any endpoint. So technically, a game instance can simultaneously connect to a combination of Rooms and Worlds. Including several connections to the same Rooms or Worlds, as it would be the case for a split-screen setup.

You can create this scenario by your own means. However, we do provide a solution out-of-the-box that helps handle connections: the CoherenceSceneLoader and CoherenceScene component duo.

Simplifying Connections: CoherenceSceneLoader & CoherenceScene

At its core, what these components orchestrate is loading scenes additively, and associate them with network connections.

Unity Component	Description
CoherenceSceneLoader	Handles loading one scene additively, and holds instructions for how that loaded scene should connect to the network.
CoherenceScene	Reacts when the scene this component is on is loaded via CoherenceSceneLoader. When it does, establishes a connection using the CoherenceBridge on said scene. The connection data used (EndpointData) is facilitated by the CoherenceSceneLoader that triggered the scene load.

One CoherenceSceneLoader can only load/unload one scene at a time. If you want to load N scenes, you will need N CoherenceSceneLoaders.

In the following section we explore a practical use case of this feature.

Tutorial — 4 players, 1 Editor

Let's say we want to prototype a scenario where there's 4 players connected to the network. And we want to do this within one game instance (in this case, within the Editor), to serve as a very quick and rough development environment where we can observe how the network reacts to anything we throw at it.

We can achieve that with CoherenceSceneLoader and CoherenceScene.

We need a total of 3 CoherenceSceneLoaders — these will be our extra connections, so that we have a total of 4 players connecting from within our game instance.

By the end of this tutorial, we will have a setup that looks like this:

Let's get to it. I'm starting with an empty scene that has a Camera, a CoherenceBridge and a CoherenceLiveQuery.

First, let's create the CoherenceSceneLoaders on our scene. Remember, we're creating 3 of them.

GameObject > coherence > Scene Loading > Coherence Scene Loader menu item

CoherenceSyncLoader Inspector

Select the 3 of them, and on the Inspector:

• Enable Attach

• Set the Connection Type to Client

• Set the Scene Name to the name of the current scene (if it's not already)

Values set on the Inspector, as described above

Let's break down why we're doing this:

In this example, we're going to be loading the same scene we're already working on, 3 additional times (one time per CoherenceSceneLoader component). We set Scene Name accordingly (in this case, it's Main).

This is, however, not the only way you can think of setting this environment up. A different approach could be to have 4 CoherenceSceneLoaders, and start from a Menu scene. But in this example I didn't go that route — we're working with our only scene.

Make sure the scene you're working on is part of the Build Profile's Scene List.

With this setup, every time this scene connects to the network, 3 additional scenes will be additively loaded and connected (as Clients, as specified in the Connection Type) to the same space (room or world), meaning there will be a total of 4 players coexisting.

I'm going to use the Rooms Connect Dialog to not care about the connection logic. You can find it in the Explore Samples window (coherence > Explore Samples menu item).

At this point, make sure your baked data is up-to-date.

If using coherence Cloud, make sure the schemas are uploaded. You can do this from the Hub (coherence > Hub menu item).

If using a local Replication Server, make sure it's stopped/started after baking, so it uses the latest generated schema. You can start a local Replication Server from the Hub as well.

Enter Play Mode and connect to coherence using the in-game connection dialog. When creating the room, make sure Max Players is set to 4 or more (default is 10).

Once connected to the room (i.e., the CoherenceBridge establishes connection), the 3 CoherenceSceneLoaders will trigger — as they are attached to the scene's CoherenceBridge — and load 3 additional scenes, that will automatically connect to the network as well.

Hierarchy after entering the room — 4 client connections established!

You can click on the Unity icon at the right side of the GameObject, in the Hierarchy Window, to ping which CoherenceScene is associated with each CoherenceSceneLoader.

Clicking on the Unity icon on CoherenceScene or CoherenceSceneLoader pings its counterpart

The 3 CoherenceSceneLoaders are reacting to the CoherenceBridge getting connected/disconnected. This is because they are attached to CoherenceBridge. If we didn't attach, we'd need to manually call CoherenceSceneLoader.Load(EndpointData) and pass the data needed to perform the operation.

Notice also how the CoherenceScene component has been automatically added for us on each of the loaded scenes. Warnings will appear on the Console window, telling us that a CoherenceScene has been created on-the-fly.

We want to control what happens when we load a scene via CoherenceSceneLoader, so creating a CoherenceScene on our own, and configuring it our way, is what we should do next.

Let's exit Play Mode and add a CoherenceScene:

GameObject / coherence / Scene Loading / Coherence Scene menu item

CoherenceScene Inspector

By default, this component will try to establish a connection once loaded (Connect toggle is on), and also handles reconnects out-of-the-box.

What's interesting for us at this point though, is disabling some logic from the scenes after they are loaded. Specifically, we want the Camera, the EventSystem and the Connection Dialog on the loaded scenes to be disabled, so that they don't interfere with the ones present in the main scene.

CoherenceScene provides a handy Deactivate On Load list that you can use for this matter, but you can also use the On Loaded event to script any logic you might want.

The Deactive On Load list also comes with a Smart Select button, that selects GameObjects found that are generally good candidates to be disabled when working with this feature.

By clicking on it, Camera and EventSystem are populated, and will be disabled after the scene is loaded. We also want to disable the Rooms Connection Dialog, so we reference it there manually.

Let's save the changes and see what's happening now once we enter Play Mode.

1. Via the in-game Connection Dialog, create or join a room.

2. Once joined, notice the on the Hierarchy window.

3. Now, click on the Disconnect button of the Connection Dialog — it should be clickable after we've disabled the EventSystems, Cameras and Connection Dialogs from the additional scenes.
4. After disconnecting, you'll notice the other 3 connection have also disappeared — attaching loads and also unloads when, CoherenceBridge connects/disconnects.

So far we haven't seen anything being networked. So that's what we're going to do next.

Let's create a Cube and network it.

Let's create a Cube

Cube created, now let's network it by clicking Sync with coherence on the Inspector.

All set! Our Cube is now networkable. It's also part of the scene right now.

At this point, make sure you bake, upload schemas and or (re)start the Replication Server, given we've created a new Networkable Prefab. You can do this from within the Hub, from the coherence menu, or from the icon shown in the Project window, next to the Assets/coherence folder.

Now, let's enter Play Mode again.

We now see 4 cubes — one per connection. You can differentiate which one you have authority over, and which ones are the replicated ones (solid coherence logo represents authority, outlined coherence logo represents non-authority / remote).

Now, let's spice it up — let's use this setup to visualize interpolation at runtime.

1. Create two materials. We will use these to differentiate authority and remote. I'll be using red and green.

1. Next, let's assign apply these materials on our Cube, based on authority.

2. Go to the Cube Prefab, and hit Configure on the CoherenceSync Inspector.

3. Once there, click the Components tab.

1. Open the Action dropdown, under Mesh Renderer, and select Handle Material:

1. Use our previously created materials, as such:

We're almost there. Let's enter Play Mode again.

Once connected, select a Cube you from any of the loaded scenes.

Keep the Scene view active, we will use it to visualize what's going on

Drag that Cube around, so that it doesn't overlap with the other (replicated) Cubes.

Do you see those eye icons on the scene headers, on the Hierarchy window? They control what your Scene window is rendering. While the Cube you dragged is selected, let's visualize what's happening on the other connections. Enable rendering on any of the other scenes:

Now, drag the Cube again. Do you see a red Cube following it along? That's the replicated copy, catching up and being interpolated!

Now you can try out how interpolation behaves when using different settings.

Now you have a sandbox you can use to toy around with. Drag and drop Networked Prefabs on the scene, delete them, change authority on-the-fly... and all of that within one Scene view, with the debugging advantages that it brings.

If you've made it all the way here, congratulations! Now you grasp the basics needed to leverage CoherenceSceneLoader / CoherenceScene to create multiple connections within one game instance.

One final note — building a game where different connections coexist on the same build can be challenging, and requires strict rules on which scene can access what. Static access (GameManager and other singletons), physics, graceful error handling...

While this feature is powerful to provide quick development scenarios, it's not necessarily a good foundational feature to build upon to playtest a game itself. For that, we recommend you to either make builds, use Unity's Multiplayer Play Mode or ParrelSync. Read more about our recommendations on how to test your game locally.