Comment on page
Custom instantiation and destruction
In many cases, creating and destroying GameObjects like usual will be enough. Just call
Destroy(), and coherence takes care of instantiating and destroying the appropriate Prefab instance on each connected Client.
However, there are moments when it makes sense to customize how exactly coherence does this. To take full control over the lifetime of the object, or to attach custom behavior to these events.
The campsite in this demo has a few pre-placed unique objects in the scene, that can be picked up, moved, and burned on the campfire.
Some pre-placed objects: the boombox, the banjo, a bin
When we burn them, we could in theory just destroy the instance. However the burn code is deeply nested in the
Burnable.csclass which is used not only by these unique objects, but also by the pooled and non-unique wood logs.
In this method we do this:
private IEnumerator GetBurned()
However, by default unique network entities also get disabled, not destroyed. This doesn't work for our special objects!
If you're curious about this code, you can check out the file in the coherence package folder in
We could potentially add an
ifstatement in the
GetBurned()above, detect if the object being destroyed is a log or not, and act differently based on that. Or subclass the
Burnableand implement overrides for
... or we can just create a custom instantiator, and take full control of the object's lifecycle. Let's see the code.
Creating a custom instantiator is trivial. We just need a class to implement the interface
INetworkObjectInstantiator, like so:
[Serializable, DisplayName("UniqueBurnableObjects", "Custom instantiator [...]")]
public class UniqueBurnableInstantiator : INetworkObjectInstantiator
// OnUniqueObjectReplaced() does nothing
public ICoherenceSync Instantiate(CoherenceBridge bridge,
ICoherenceSync prefab, Vector3 position, Quaternion rotation)
return Object.Instantiate(prefab as MonoBehaviour,
position, rotation) as ICoherenceSync;
public void Destroy(ICoherenceSync obj)
var monoBehaviour = obj as MonoBehaviour;
// WarmUpInstantiator() does nothing
// OnApplicationQuit() does nothing
The key parts of this script being that on network entity creation a simple
Object.Instantiate()is performed, and on release
Object.Destroy(). The other methods (omitted here) are actually empty.
We also want to prepend the class with the
DisplayNameattribute so it shows up in the dropdown when we configure a
CoherenceSync. Now the UniqueBurnableObjects instantiator appears alongside the others in the Instantiate via dropdown:
That's it, the instantiator is ready to use.
When we call
ReleaseInstance()now, it will act differently depending on which instantiator the Prefab is configured to use: the wood logs get disabled, but the unique campfire objects get destroyed.
This was a very simple use case for customization, but it illustrates how easy it can be to get in control of the lifetime of Prefab instances associated to network entities.
The first time these special unique objects come online, they spawn a persistent invisible object we call "object anchor". This object holds the original position and rotation of the object, so that the Keeper Robot can come in at a later time and put the recreated object back into its place. You could think of these objects as placeholders.
The anchors, created in Play mode
The Inspector of an anchor holds information about the object it relates to
One interesting thing we do with anchors is that they are themselves unique objects, but because they are spawned at runtime, they need to get their unique ID dynamically at runtime.
The code is in the
private void SpawnAnchor()
// Code simplified for clarity ...
string uniqueID = _sync.ManualUniqueId;
_bridge.UniquenessManager.RegisterUniqueId(uniqueID + "-anchor");
objectAnchorSync = Instantiate(anchorPrefab,
We take the
ManualUniqueIdfrom the object spawning it (i.e., "Boombox"), and we combine with the string "-anchor" to create a new unique ID, "Boombox-anchor". We register this ID to the
CoherenceBridgeto inform it that the next spawned network entity will have that ID. And then we simply call
Because they are set to be Persistent, even though a player has burned something and disconnected, the anchors stay on the Replication Server. When a Simulator connects it will find these placeholders and, thanks to the synced properties, will know exactly what to recreate and where to put it.
The check code is in
First, each anchor's
isObjectPresentproperty is used for a quick scan. This property is synced.
If the object is still present, the robot needs to get a reference to it. It calls
GetLinkedObject()on the anchor, which does this:
public GameObject GetLinkedObject()
UniqueObjectReplacement uor =
bool found = uor.localObject != null;
return found ? ((CoherenceSync)uor.localObject).gameObject : null;
Once again using the UUID of the object this anchor is a placeholder for (
holdingForUUID) as a key, we can now ask the
UniquenessManagerto retrieve an object that has that UUID.
With a reference to this, the robot can now put it back into place using the anchor's position and rotation as a reference.
And if the object has been destroyed (
isObjectPresentis false), the robot proceeds to recreate it.
private Transform RecreateObject(ObjectAnchor objAnchor)
foreach (CoherenceSyncConfig config in configRegistry)
if (config.ID == objAnchor.syncConfigId)
CoherenceSync newSync = config.GetInstance(holdSocket.position, holdSocket.rotation);
Using the anchor's
syncConfigIdas a key, it looks in the
CoherenceSyncConfigRegistryand finds the archetype to recreate. This is similar to how we used the registry as a catalogue when dealing with the campfire object.
After that, like we saw before, the robot registers the newly recreated object with the
UniquenessManagerso that it has the same UUID that it had before being burned.
The object is reinstated, and to a new Client connecting, it will look exactly the same as if it never got removed.