CoherenceSync
Last updated
Last updated
CoherenceSync is a component that should be attached to every networked GameObject. It may be your player, an NPC or an inanimate object such as a ball, a projectile or a banana. Anything that needs to be synchronized over the network and turned into an Entity. You can select which of the attached components you would like to sync across the network as well as individual public properties.
All networked Entities need to be placed in the Resources folder.
Any scripts attached to the component with CoherenceSync that have public variables will be shown here and can be synced across the network. Enable the script + the variable to sync, it's that easy. Those variables with a lightning bolt next to them signify a public method that can be activated via commands.
Ownership transfer
When you create a networked GameObject, you automatically become the owner of that GameObject. That means only you are allowed to update or destroy it. But sometimes it is necessary to pass ownership from one player to another. For example, you could snatch the football in a soccer game or throw a mind control spell in a strategy game. In this case, you will need to transfer ownership from one Client to another.
Entity lifetime
When a player disconnects, all the GameObjects created by that player are usually destroyed. If you want any GameObjects to stay in the Game World after the owner disconnects, you need to set Entity lifetime type of that GameObject to Persistent.
Session Based - will be removed when the Client disconnects. GameObjects will stay on the scene of the Client who is an Authority owner for session-based objects until the scene reloads.
Persistence - Entities with this option will persist as long as the server is running. For more details, see Configuring persistence.
Uniqueness
Allow Duplicates - no restrictions on which objects can be instantiated over the network.
No Duplicates - ensure objects are not duplicated by marking them with a UUID.
You can set the UUID manually
If you leave the field blank a GUID will be assigned at runtime (This is rarely what you want)
Use the CoherenceUUID component helper to generate GUIDs for you at editor time. CoherenceUUID is an design time only tool for assigning unique UUIDs to prefab instances.
Uniqueness examples
Manager: If your game has a prefab, of which there can only be 1 in-game instance at any time (Such as a Game Controller), assign a UUID manually on the prefab asset.
Interactable objects: If you have several instances of a given prefab, but each instance must be unique (Such as doors, elevators, pickups etc) you should add the CoherenceUUID script and set it to Auto-generate in scene. This means that i.e. a door will only spawn once, but still replicate its state across the network.
Entity simulation type
Client Side - Simulates everything on the local Client and passes the information to the Replication Server to distribute that information to the other Clients.
Other forms of simulation (Server; Server with Client Input).
Authority transfer style
Not Transferable - The default value is Not Transferable because most often objects are not meant to be transferred.
Stealing - Allows the GameObject to be transferred to another Client.
Request - This option is intended for conditional transfers, which is not yet supported.
Orphaned entities
By making the GameObject persistent, you ensure that it remains in the game world even after its owner disconnects. But once the GameObject has lost its owner, it will remain frozen in place because no Client is allowed to update or delete it. This is called an orphaned GameObject.
In order to make the orphaned GameObject interactive again, another Client needs to take ownership of it. To do this, enable Auto-adopt orphan.
Once you have set the transfer style to Stealing, any Client can request ownership by calling the RequestAuthority() method on the CoherenceSync component of that GameObject:
someGameObject.GetComponent<CoherenceSync>().RequestAuthority();
A request will be sent to the GameObject's current owner. The current owner will then accept the request and complete the transfer.
You are now the new owner of the GameObject. This means the isSimulated flag has been set to true, indicating that you are now in full control of the GameObject. The previous owner is no longer allowed to update or destroy it.
Helper scripts with a custom implementation of authority transfer can be found here.
The state of the CoherenceSync.isSimulated flag is not guaranteed to have a proper value during the Awake() callback (right after an object is created). All scripts that use this flag should wait at least until the Start() callback.
You can set up Custom Events for handling user connection and disconnection. Manual Destroy is useful for session based objects that you want to keep "semi-persistent" which would be removed when all the Clients disconnect.
When CoherenceSync variables/components are sent over the network, by default, Reflection Mode is used to sync all the data at runtime. Whilst this is really useful for prototyping quickly and getting things working, it can be quite slow and unperformant. A way to combat this is to bake the CoherenceSync component, creating a compatible schema and then generating code for it.
The schema is a file that defines which data types in your project are synced over the network. It is the source from which coherence SDK generates C# struct types (and helper functions) that are used by the rest of your game. The coherence Replication Server also reads the schema file so that it knows about those types and communicates them with all of its Clients efficiently.
The schema must be baked in the coherence Settings window, before the check box to bake this Prefab can be clicked.
When the CoherenceSync component is baked, it generates a new file in the baked folder called CoherenceSync<NameOfThePrefab>. This component will be instantiated at runtime, and will take care of networked serialization and deserialization, instead of the built-in reflection-based one.
Refer to the Commands section.
