Instantiate and Destroy Objects

coherence makes it easy to instantiate networked objects. If you instantiate a while the game is running, it automatically instantiates on all connected clients. You don't need to do anything else to make it happen.

However some rules apply, so read on to understand more about the process.

How do I specify a Prefab to spawn for the player?

It is important to understand that coherence has no concept of a "player Prefab" that maps 1:1 with each Client. Clients can control only one network entity, multiple, or none at all.

Clients can also trade authority over them at runtime. For example, a Client might initially have authority over a character, which can then move to another Client during gameplay.

It's up to you to decide what constitutes a "player Prefab": you can instantiate one before connecting, right after connection, or at any point during the simulation. You can even just leave it in the scene, and let each player bring a copy of that into the simulation (in this case, make sure the Prefab is not set to be unique!).

Finally, if you come from other networking frameworks, you might expect a player Prefab to be be instantiated by the network manager (in coherence, the CoherenceBridge), but that is not the case. Like all other network entities, it can be instantiated by any script.

Identifying Clients

You do have the ability to assign a Prefab to each client: the ClientConnection Prefab. This lives and dies with the client's connection, and you can use it to hold important data related to that Client. You can assign it in the Inspector of the CoherenceBridge.

ClientConnection Prefabs are optional.

Instantiating entities

You can instantiate a networked Prefab in the following ways:

• Use GameObject.Instantiate(), and provide a reference to the Prefab:

GameObject newGameObject = Instantiate(prefab);

• Simply include the Prefab in a scene.

• (Editor only, for testing) Drag the Prefab from the Project window to the scene or to the Hierarchy while the game is running.

In all of these cases, the Prefab will be immediately instantiated on all other connected clients and Simulators.

Just ensure to include a CoherenceSync component on the Prefab, and that netcode is baked correctly.

Who gets authority?

Whoever instantiates a Prefab gets full authority over it. All other clients will see it as remote.

The value of the Simulate In property on the CoherenceSync can modify this behaviour. Read more about authority models.

Instantiate objects for other clients

You cannot directly instantiate an entity owned by another Client. The Client that instantiates a Prefab automatically has authority over it.

However, you can transfer authority immediately after instantiation. In code:

// Instantiates a Prefab and immediately gives authority away
public void SpawnAndTransfer(GameObject prefab, ClientID recipientID)
{
        GameObject newGameObject = Instantiate(prefab);
        newGameObject.GetComponent<CoherenceSync>().TransferAuthority(recipientID);
}

(to get other clients' IDs you need to have ClientConnections enabled)

This is a perfectly valid strategy to have a Simulator spawn player characters for connected Clients.

Destroying entities

To destroy a networked Prefab, simply invoke GameObject.Destroy() on it. coherence will automatically destroy all remote copies.

Keep in mind is that only whoever has State authority over it can destroy an entity. If someone else does it, they will get a warning in the console.

Destroying other player's entities

Clients cannot directly destroy entities they don't have authority over. Instead, you may:

• Send a Network Command to ask the owner to destroy it. In code:

private void DestroyNetworkEntity(GameObject objectToRemove)
{
    CoherenceSync sync = objectToRemove.GetComponent<CoherenceSync>();
    
    if (sync.HasStateAuthority)
    {
        // If we have authority, no need to send a command
        Destroy(objectToRemove);
    }
    else
    {
        // Change MyBehaviour here to whatever type will receive the Command
        sync.SendCommand<MyBehaviour>(nameof(MyBehaviour.RemoveObject),
                                            MessageTarget.AuthorityOnly);
    }
}

// The command invoked on the receiving end
[Command]
public void RemoveObject()
{
    Destroy(this.gameObject);
}

• Take authority over the entity first, then destroy it locally. This is slightly slower as it implies a full roundtrip (request > response > destruction), but it's a viable option if the requester needs to verify whether the entity can be destroyed at all. You can implement the conditions under which the other client will approve or deny the request. In code:

private void RequestDestroy(GameObject objectToRemove)
{
    CoherenceSync sync = objectToRemove.GetComponent<CoherenceSync>();
    
    if (sync.HasStateAuthority)
    {
        Destroy(objectToRemove);
    }
    else
    {
        // Listen to authority transfer
        sync.OnStateAuthority.AddListener(() => Destroy(objectToRemove));
        
        sync.RequestAuthority(AuthorityType.Full);
    }
}

Note that we're assuming that the request above always succeeds, and we're not implementing any approval/denial code for the sake of simplicity.

Customise instantiation and destruction

In coherence, you can take full control of how network entities are instantiated.

A typical use for custom instantiation is streaming assets in with the Addressables package, which coherence is fully integrated with. Another typical use case is object pooling.

To use custom instantiation you can't just hard reference the Prefab and invoke Instantiate() or Destroy() as described above. Instead, you have to use its CoherenceSyncConfig to let the chosen instantiator script take over and perform custom operations.

Object pooling

We natively support object pooling, so that newly requested entities don't just get created from scratch, but they are taken from a pre-existing pool.

How to use object pooling

In the CoherenceSync component inspector, you will find an option called Instantiate Via.

Select the option called Pool, and define the initial and max size of the pool:

A CoherenceSync for which the Pool instantiator has been selected

When the game starts, coherence will automatically create a pool of disabled instances of this Prefab in the DontDestroyOnLoad scene. It will then activate these for new remote entities that use this Prefab that other clients created.

If you want to take from the same pooling system to instantiate your own local/authoritative entities, you can do so by using the CoherenceSyncConfig asset corresponding to your Prefab. If you reference this asset, you will be able to instantiate and destroy entities by using its API: these methods will use the underlying pool implementation to do so.

When remote entities are removed or go out of a LiveQuery, they will be automatically deactivated and move back into the pool.

Use your pre-existing object pooling system

If you already have a pooling system in place (even a third-party asset!) and you would like remote objects to leverage it, you can hook your own pool into a custom instantiator using the INetworkObjectInstantiator interface. This is described in the Instantiate Via page.