In coherence, it's possible to specify how the Prefab for a network entity will be loaded into memory at runtime using the Load via option on the CoherenceSync.

Built-in asset loaders

We support three default implementations, or you can create your own. The three default implementations are Resources, Direct Reference or Addressables:

Resources

Resources loader will be used if your Prefab is inside a Resources folder. If you wish to use any other type of loading method, you will be prompted to move the Prefab outside of the Resources folder.

Direct Reference

This loader will be used if your Prefab is outside of a Resources folder, and the Prefab is not marked as Addressable. This means that we will need to hard reference the Prefab in the CoherenceSyncConfig, which means it will always be loaded into memory from the moment you start your game.

Addressables

This option is only available if you have the Addressables Package installed.

This loader will be used if your Prefab is marked as an Addressable asset, and it will be soft referenced using Addressables' AssetReference class, meaning it's not loaded in memory at the beginning of the game but it gets loaded on demand, when needed.

When you choose this method, you don't have to implement Addressables code: coherence takes care of doing the loading for you, transparently.

Creating your own asset loader

You can implement the INetworkObjectProvider interface to create your custom implementations that will be used by coherence when we need to load the Prefab into memory.

Custom implementations can be Serializable and have your own custom serialized data.

To begin, use the dropdown menu on the CoherenceSync and use the Create Implementation... option:

Let coherence generate the scripts for you, and customise them as you see fit.

Once created, implementations of this interface will appear in the Load via dropdown shown above, or in the corresponding CoherenceSyncObject asset.

Instead of hard referencing Prefabs in your scripts to instantiate them using Unity's own Instantiate(), you can reference a CoherenceSyncConfig and instantiate Prefab instances through our API. This will respect the custom loading and instantiation rules set on the CoherenceSync component, that is the instantiator specified in Instantiate via and the asset loader specified in the Load via properties.

In code terms, it utilizes the internal INetworkObjectProvider and INetworkObjectInstantiator interfaces to load and instantiate the Prefab in a given networked scene.

Reference to the CoherenceSyncConfig

To instantiate a networked Prefab starting from its CoherenceSyncConfig, you simply need to invoke GetInstance():

using Coherence.Toolkit;
using UnityEngine;

public class CoherenceSyncConfigExample : MonoBehaviour
{
    public CoherenceSyncConfig prefabSyncConfig;
    public CoherenceBridge bridge;
    
    private CoherenceSync instance1;
    private CoherenceSync instance2;
    
    void Start()
    {
        // Load the prefab and instantiate it in the current scene
        instance1 = prefabSyncConfig.GetInstance();
        // Load the prefab and instantiate it in the specific networked scene for the given CoherenceBridge
        instance2 = prefabSyncConfig.GetInstance(bridge, Vector3.zero, Quaternion.identity);
    }
    
    private void OnDestroy()
    {
        // Instances have to be destroyed via the ReleaseInstance method, so that its destruction is handle by the 
        // internal INetworkObjectInstantiator
        prefabSyncConfig.ReleaseInstance(instance1);
        prefabSyncConfig.ReleaseInstance(instance2);
    }
}

Reference to a Prefab ("hard reference")

You can also hard reference the Prefab in your script, and then use our CoherenceSync API to instantiate the Prefab:

using System;
using Coherence.Toolkit;
using UnityEngine;

public class InstantiatorViaPrefabReference : MonoBehaviour
{
    // Serialized Prefab reference
    public GameObject prefab;

    private CoherenceSync instance1;

    void Start()
    {
        CoherenceSync sync = prefab.GetComponent<CoherenceSync>();
        // Instantiate it in the current scene
        instance1 = sync.GetInstance();
    }

    private void OnDestroy()
    {
        // Instances have to be destroyed via the ReleaseInstance method, so that its destruction is handle by the 
        // internal INetworkObjectInstantiator
        instance1.ReleaseInstance();
    }
}

While the end result is the same, the main difference is that referencing a CoherenceSyncConfig instead of a Prefab makes it a much more scalable and future-proof architecture. Since it doesn't need a Prefab hard reference, you won't have to change the code if the way that the Prefab is loaded into memory changes later on (for example, if you go from Resources to load it via Addressables).

In coherence, it is possible to specify how a Prefab is instantiated at runtime using the Instantiate via option on the CoherenceSync component.

Built-in instantiators

We support three implementations out of the box: Default, Pool or DestroyCoherenceSync, but you can also create your own.

Default

This instantiator will create a new instance of your Prefab, and when the related network entity is destroyed, this Prefab instance will also be destroyed.

Pool

This instantiator supports object pooling, instead of always creating and destroying instances, the pool instantiator will attempt to reuse existing instances. It has two options:

• Max Size: maximum size of the pool for this Prefab, instances that exceed the limit of the pool will be destroyed when returned.

• Initial Size: coherence will create this amount of instances on app startup.

DestroyCoherenceSync

This instantiator will create a new instance for your Prefab, but instead of completely destroying the object when the related network entity is destroyed, it will destroy or disable the CoherenceSync component instead.

Creating your own instantiator

You can implement the INetworkObjectInstantiator interface to create your custom implementations that will be used by coherence when it needs to instantiate a Prefab in the scene.

Custom implementations can be Serializable and have their own custom serialized data.

To begin, use the dropdown menu on the CoherenceSync and use the Create Implementation... option:

Let coherence generate the scripts for you, and customise them as you see fit.

Once created, implementations of this interface will appear in the Instantiate via dropdown shown above, or in the corresponding CoherenceSyncObject asset.

In this section we cover in-depth how coherence handles loading networked Prefabs into memory, and how it instantiates them when a new remote entity appears on the network.

CoherenceSyncConfig assets

Whenever you start synchronizing one of your Prefabs, either by adding the CoherenceSync component manually or clicking the Sync with coherence toggle in the Prefab Inspector, coherence will create a CoherenceSyncConfig ScriptableObject to track the existence of this entity, and add it to a registry.

This object holds information on how a certain type of network entity is loaded and instantiated.

As a user, the two main changeable options here are Load via, and Instantiate via.

There is a 1:1 correspondence between a networked Prefab and its CoherenceSyncConfig object, so you can also edit the related CoherenceSyncConfig directly from the Inspector of any CoherenceSync component:

These edits will in fact be saved not in the component, but on the associated CoherenceSyncConfig ScriptableObject.

Behind the scenes, the CoherenceSyncConfig object allows coherence to do the following:

• Hard reference the prefab in Editor, this means that whenever we have to do postprocessing in synced prefabs, we don't have to do a lookup or load them from Resources.

• Serialize the method of loading and instantiating this prefab in runtime.

• Soft reference the prefab in Runtime with a GUID, this means we can access the loading and instantiating implementations without having to load the prefab itself into memory.

The CoherenceSyncConfigRegistry

Every time a CoherenceSyncConfig object is created, it gets added to a registry, represented by a single ScriptableObject of type CoherenceSyncConfigRegistry.

In addition to just inspecting the ScriptableObject, you can see all of the CoherenceSyncConfig assets in one place in the CoherenceSync Objects window, found under the coherence > CoherenceSync Objects menu item:

This is a great way to see the configuration of different entities next to each other, and it allows you to do mass edits by clicking the Edit Mode button.