In this page we will learn about how coherence handles loading CoherenceSync Prefabs into memory and instantiating them when a new remote entity appears in the network. You will also learn how you can hook your own asset loading and instantiation systems seamlessly.
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 automatically create a CoherenceSyncConfig object that will be added to the CoherenceSyncConfigRegistry asset found in the Assets/coherence folder.
This CoherenceSyncConfig object allows us 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.
All your CoherenceSync prefabs will have a related CoherenceSyncConfig object, you can inspect all your prefabs in the CoherenceSync Objects window, found under the coherence => CoherenceSync Objects menu item:
You can also manually inspect your CoherenceSyncConfig objects by selecting the CoherenceSyncConfigRegistry asset in Assets/coherence/CoherenceSyncConfigRegistry.asset:
You can also find your related CoherenceSyncConfig in the inspector of the CoherenceSync component, you can directly edit your Config from here:
This option allows you to specify how this prefab will be loaded into memory in runtime, we support three default implementations, or you can create your own. The three default implementations are Resources, Direct Reference or Addressables, these three will be automatically managed by coherence and you won't have to worry much about them.
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.
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 your 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 Unity 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.
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.
Implementations of this interface will be automatically selectable via the Load via option in the CoherenceSyncObject asset.
This option allows you to specify how this prefab will be instantiated in runtime, we support three default implementations, or you can create your own. The three default implementations are Default, Pooling or DestroyCoherenceSync.
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.
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.
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.
You can implement the INetworkObjectInstantiator interface to create your custom implementations that will be used by coherence when we need to instantiate a pefab in the scene.
Custom implementations can be Serializable and have your own custom serialized data.
Implementations of this interface will be automatically selectable via the Instantiate via option in the CoherenceSyncObject asset.
Instead of hard referencing Prefabs in your scripts to instantiate them, you can reference a CoherenceSyncConfig and instantiate your local Prefab instances through our API. This will utilize the internal INetworkObjectProvider and INetworkObjectInstantiator interfaces to load and instantiate the Prefab in a given networked scene (a scene with a CoherenceBridge component in it).
You can also hard reference the Prefab in your script, and use our extensions to instantiate the Prefab easily using the internal INetworkObjectInstantiator interface implementation. The main difference is that the previous approach doesn't need a Prefab hard reference, and you won't have to change the code if the way that the Prefab is loaded into memory changes (for example, if you go from Resources to load it via Addressables).
The CoherenceSyncConfigRegistry is a ScriptableObject that will hold a list of references to your existing CoherenceSyncConfig objects.
CoherenceSyncConfig is a separate ScriptableObject that holds the configuration for each of your networked objects.
Since the Registry needs to keep a list of references, in coherence we offer three different ways you can handle your CoherenceSyncConfigRegistry asset:
Sub Assets: The CoherenceSyncConfig assets will be saved as sub-assets of the CoherenceSyncConfigRegistry asset.
This option generates the least amount of assets on the disk but it is highly susceptible to version control conflicts.
Standalone Assets: The CoherenceSyncConfig assets will be saved separately in the Assets/coherence/baked folder, the CoherenceSyncConfigRegistry will simply keep a list of references to them.
This options creates more assets on the disk but it is less susceptible to version control conflicts.
Dynamic Standalone Assets: The CoherenceSyncConfig assets will be saved separately in the Assets/coherence/baked folder. The CoherenceSyncConfigRegistry will not be saved to disk but it will be generated on-demand in memory.
This option is recommended for large development teams, to avoid version control conflicts.