coherence uses the concept of ownership to determine who is responsible for simulating each Entity. By default, each Client that connects to the Replication Server owns and simulates the Entities they create. There are a lot of situations where this setup is not adequate. For example:

• The number of Entities could be too large to be simulated by the players on their own, especially if there are few players and the World is very large.

• The game might have an advanced AI that requires a lot of coordination, which makes it hard to split up the work between Clients.

• It is often desirable to have an authoritative object that ensures a single source of truth for certain data. State replication and "eventual correctness" doesn't give us these guarantees.

• Perhaps the game should run a persistent simulation, even while no one is playing.

With coherence, all of these situations can be solved using dedicated Simulators. They behave very much like normal Clients, except they run on their own with no player involved. Usually, they also have special code that only they run (and not the clients). It is up to the game developer to create and run these programs somewhere in the cloud, based on the demands of their particular game.

Creating a Simulator

If you have determined that you need one or more Simulator for your game, there are multiple ways you can go about implementing these. You could create a separate Unity project and write the specific code for the Simulator there (while making sure you use the same schema as your original project).

An easier way is to use your existing Unity project and modify it in a way so that it can be started either as a normal Client, or as a Simulator. This will ensure that you maximize code sharing between Clients and Servers - they both do simulation of Entities in the same Game World after all.

To force a build to start as a Simulator, you can use the following command line argument:

$ ./Game --coherence-simulation-server

Simulators in coherence Cloud

The Simulator is started with the following parameters in coherence Cloud:

--coherence-region             // region where the simulator is started
--coherence-world-id           // unique world id (in world mode)
--coherence-http-server-port   // REST access for starting / stopping rooms
--coherence-auth-token         // token to authorize access
--coherence-simulation-server  // identify as simulation server
--coherence-simulator-type     // Room or World

// the following should be used also when starting a local simulation server to 
// successfully connect to the local replication server

--coherence-ip                 // address of the replication server (eg 127.0.0.1)
--coherence-port               // port of the replication server
--coherence-room-id            // room id when connecting to a room
--coherence-unique-room-id     // unique room id to connect to in room mode
--coherence-room-tags          // tags used when creating the room
--coherence-room-kv            // key values supplied when creating the room

SimulatorUtility

The SDK provides a static helper class to access all the above parameters in the C# code called SimulatorUtility.

static class SimulatorUtility
{
    public enum Type
    {
        Undefined = 0,
        World = 1,
        Rooms = 2
    }
    
    public static Type SimulatorType;         // Type of simulator: Room / World.
    public string Region;                     // Region where simulator was spawned.
    public string Ip;                         // Ip of the replication server.
    public int Port;                          // UDP port of the replication server.
    public int RoomId;                        // RoomId for current session. 
    public ulong UniqueRoomId;                // Unique RoomId.
    public ulong WorldId;                     // World Id (in worlds mode).
    public int HttpServerPort;                // Port used for REST commands.
    public string AuthToken;                  // Auth token used for authentication.
    public List<string> RoomTags;             // Tags for the room. 
    public Dictionary<string,string> RoomKV;  // Key Values for the room.
    public bool IsInvokedAsSimulator;         // Whether the instance was invoked as a simulator.
    public bool IsInvokedInCommandLine;       // Whether the instance was invoked on the commandline.
    public bool IsSimulator;                  // Identify whether simulator.  
}

Building simulators

To build Simulators, it's best to use headless mode (Unity 2020) or the Linux Dedicated Server Build Target.

This is great for Simulators since we're not interested in rendering any graphics on these outside of local development. You will also get a leaner executable that is smaller and faster to be published in coherence Cloud.

When a room has only Simulators (no Clients) it shuts down automatically after a short period of time.

Build and deploy

Refer to the Simulator: Build and deploy section.

Connecting Simulators to the Internet is a paid-only feature. If you are currently on a Free Tier Subscription and need your Simulators to connect to external services, please upgrade your Subscription.

Before deploying a Simulation Server, testing and debugging locally can significantly improve development and iteration times. There are a few ways of accomplishing this.

Running the Editor as a Simulator

Using the Unity Editor as a Simulator allows us to easily debug the Simulator. This way we can see logs, examine the state of scenes and GameObjects and test fixes very rapidly.

To run the Editor as a Simulator, run the Editor from the command line with the proper parameters:

• --coherence-simulation-server: used to specify that the program should run as a coherence Simulator.

• --coherence-simulator-type: tells the Simulator what kind of connection to make with the Replication Server, can be Rooms or World.

• --coherence-region: tells the Simulator which region the Replication Server is running in: EU, US or local.

• --coherence-ip: tells the Simulator which IP it should connect to. Using 127.0.0.1 will connect the Simulator to a local server, if one is running.

• --coherence-port: specifies the port the Simulator will use.

• --coherence-world-id: specifies the World ID to connect to, used only when set to Worlds.

• --coherence-room-id: specifies the Room ID to connect to, used only when set to Rooms.

• --coherence-unique-room-id: specifies the unique Room ID to connect to, used only when set to Rooms.

• --coherence-auth-token: specifies your local dev authentication token, that you get from pressing the coherence Hub > Simulators > Run local simulator build > Fetch Last Endpoint button. This will change in the near future and will no longer be a required parameter.

For example:

<Editor path> -projectPath <project path>
--coherence-simulation-server 
--coherence-simulator-type rooms
--coherence-region local
--coherence-ip 127.0.0.1 
--coherence-port 32001 
--coherence-room-id [room-id]
--coherence-unique-room-id [room-uid]
--coherence-auth-token [auth-token-string]

If you're not sure which values should be used, adding a COHERENCE_LOG_DEBUG define symbol will let you see detailed logs. Among them are logs that describe which IP, port and such the Client is connecting to. This can be done in the Player settings: Project Settings > Player > Other Settings > Script Compilation > Scripting Define Symbols.

Running a Simulator build locally from the command line

Another option is making a Simulator build and running it locally. This option emulates more closely what will happen when the Simulator is running after being uploaded.

You can run a Simulator executable build in the same way you run the Editor.

"simulator build path"
--coherence-simulation-server 
--coherence-ip 127.0.0.1 
--coherence-port 32001 
--coherence-world-id 0 
--coherence-room-id [room-id]
--coherence-unique-room-id [room-uid]

This allows you to test a Simulator build before it is uploaded or if you are having trouble debugging it.

Running a Simulator build locally from the Unity Editor

You can also run existing Simulator build from coherence Hub > Simulators > Run local simulator build.

Use the Fetch Last Endpoint button to autofill the required fields.

Connecting a Simulator to a Room

When using a Rooms-based setup, you first have to create a Room in the local Replication Server (e.g. by using the connect dialog in the Client).

The local Replication Server will print out the Room ID and unique Room ID that you can use when connecting the Simulator.

Am I a Simulator ?

Ask Coherence.SimulatorUtility.IsSimulator.

using Coherence;
using UnityEngine;

public class SimualatorClass : MonoBehaviour
{
    public void Awake()
    {
        if (SimulatorUtility.IsSimulator)
        {
            // I'm a simulator!
        }
    }
}

There are two ways you can tell coherence if the game build should behave as a Simulator:

• COHERENCE_SIMULATOR preprocessor define.

• --coherence-simulation-server command-line argument.

Connect and ConnectionType

The Connect method on Coherence.Network accepts a ConnectionType parameter.

using Coherence;
using Coherence.Connection;
using Coherence.Toolkit;
using UnityEngine;

public class ConnectAsSimulator : MonoBehaviour
{
    void Start()
    {
        var endpoint = new EndpointData
        {
            region = EndpointData.LocalRegion,
            host = "127.0.0.1",
            port = 32001,
            schemaId = RuntimeSettings.instance.SchemaID,
        };

        var monoBridge = FindObjectOfType<CoherenceMonoBridge>();
        monoBridge.Connect(endpoint, ConnectionType.Simulator);
    }
}

COHERENCE_SIMULATOR

#if COHERENCE_SIMULATOR

// simulator-specific code

#endif

Whenever the project compiles with the COHERENCE_SIMULATOR preprocessor define, coherence understands that the game will act as a Simulator.

Command-line argument

Launching the game with --coherence-simulation-server will let coherence know that the loaded instance must act as a Simulator.

Server-side simulation

You can define who simulates the object in the CoherenceSync inspector.

Auto-reconnect

The sample UI provided includes auto-reconnect behaviour out of the box for Room- and World-based simulators. The root GameObject has AutoReconnect components attached to it.

Simulators per room can be enabled in the dashboard for the project. The Simulator used is matched according to the Simulator slug in the RuntimeSettings scriptable object file. This is set automatically when you upload a Simulator.

For each new Room, a Simulator will be created with the command line parameters described in the Simulators section. The Simulator is shutdown automatically when the Room is closed.

World Simulators are started and shut down with the World. They can be enabled and assigned in the Worlds section of the Developer Portal.

World simulation servers are started with the command line parameters described in the Simulators section.

When using the Simulators tab in the coherence Hub, you can specify a Simulator slug. This is simply a unique identifier for a Simulator. This value is automatically saved in RuntimeSettings when an upload is complete, and Room creation requests will use this value to identify which Simulator should be started alongside your room.

The Simulator slug can be any string value, but we recommend using something descriptive. If the same slug is used between two uploads, the later upload will overwrite the previous Simulator.

A list of uploaded Simulators and their corresponding slugs can be found in the Developer Portal:

coherence allows us to use multiple Simulators to split up a large game world with many entities between them. This is called spatial load balancing.

Multi-Room Simulators are Room Simulators which are able to simulate multiple game rooms at the same time - one sim to rule them all!

In order to achieve this, the game code should be defensive on which room it is affecting. Game state should be kept per Room, meaning game managers, singletons (static data), etc. need to account for this.

Each Room is held in a different scene. So for every Room created, the Multi-Room Simulator should open a connection to it, hence loading additively a scene and stablishing a Simulator connection (via MonoBridge).

How do they work?

By using Multi-Room Simulators, the coherence Developer Portal is able to instruct your Simulator which room to join and start simulating.

This communication happens via HTTP. An HTTP server is started by your game build when the MultiRoomSimulator component is active. This component listens to HTTP requests made by the coherence __ Developer Portal.

For offline local development, you can use a MultiRoomSimulatorLocalForwarder component on your clients, which will create HTTP requests against your local simulator upon client connection, like joining a room.

Once the MultiRoomSimulator receives a request to join a room, it spawns a CoherenceSceneLoader that will be in charge of loading additively the scene specified.

Setting up Multi-Room Simulators

The quickest way to get Multi-Room Simulators set up is by using the provided wizard.

It will take you through the GameObjects and Components needed to make it happen.

Manually setting up Multi-Room Simulators

Here's a quick overview video of the setup:

These are the pieces needed for Multi-Room Simulators to work:

• Simulators

  • In the initialization scene (splash, init, menu, ...)

    • MultiRoomSimulator — listens to join room requests and delegates scene loading (by instantiating CoherenceSceneLoaders)

• Clients

  • (Only for local development) In the scene where you connect to a Room (where you have the Sample UI or your custom connection logic)

    • MultiRoomSimulatorLocalForwarder — requests the local MultiRoomSimulator to join rooms when the Client connects.

• Independently

  • In the scene where the networked game logic is (game, Room, main, ...)

    • MonoBridge — handles the connection

    • LiveQuery — filters Entities by distance

    • CoherenceScene — when the scene is loaded via CoherenceSceneLoader, it will try to connect using the data given by it. It attaches to the MonoBridge, creates a connection, and handles auto reconnection. If a scene loaded through CoherenceSceneLoader doesn't have a CoherenceScene on it, one will be created on the fly.

There are two components that can help you fork Client and Simulator logic, for example, by enabling or disabling the MultiRoomSimulator component depending on whether it's a Simulator or a Client build. These are optional but can come in handy.

• SimulatorEventHandler — events on the build type (Client/Simulator).

• ConnectionEventHandler — events on the connection stablished by the MonoBridge associated with that Scene.

In-editor debugging

It is possible to visualize each individual Room the Multi-Room Simulator is working on. By default, Simulator connections to Rooms are hidden, as shown in the image above. You can toggle the visibility per scene by clicking the Eye icon. You can also change the default visibility of the loaded scene (defaults to hidden) on the CoherenceScene component:

Limitations

Working with Multi-Room Simulators needs your logic to be constrained to the scene. Methods like FindObjectsOfType will return objects in all scenes — you could affect other game sessions!

This is also true for static members, e.g. singletons. When using Multi-Room Simulators, there need to be as many isolated instances of your managers as there are open simulated rooms.

For example, if you were to access your Game Manager through GameManager.instance, now you'll need a per-scene API like GameManager.GetInstance(scene).

There may be third-party or Unity-provided features that can't be accessed per scene, and that affect the whole game.

Loading operations, garbage collections, frame-rate spikes... all these will affect performance on other sessions, since everything is running within the same game instance.

Allowing Multi-Room Simulators in the Developer Portal

Build a Simulator to be uploaded to the cloud

A Simulator build is a built Unity Player for the Linux 64-bit platform that you can upload to coherence straight from the Unity Editor.

Open Coherence Hub and select the Simulators tab.

From here you can build and upload Simulators.

Configuring your Simulator build

You can change your Simulator build options by editing the SimulatorBuildOptions object, or in the coherence Hub Simulators tab.

There are several settings you might want to change.

• Specify the scenes you want to get in the build via the Scenes To Build field.

• For a local build, you can choose to enable/disable the Headless Mode by ticking the checkbox. For a cloud build, Headless Mode is always enabled by default.

Create and upload the build

Press the coherence Hub > Simulators > Build And Upload Headless Linux Client button.

When the build is finished, it will be uploaded to your currently selected organization and project in the Developer Portal.

Connecting your Simulator to a Room or World

You'll see in the developer dashboard when your Simulator is ready to be associated with a Room or World.

Reducing Simulator build size (experimental ⚠️)

You can set the values for the Build Size Optimizations in the drop-down list of the build configuration inspector. It looks like this:

Select the desired optimizations depending on your needs.