CoherenceSync
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 then select which of the attached public properties and methods of other components you would like to sync across the network.
Synced variables and commands
To start syncing variables and commands, open the Configure window that you can access from the CoherenceSync inspector:
Any components attached to the GameObject 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.
Persistence and authority
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.
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.
Keep in mind that Entity IDs are assigned locally. This means that the IDs for the same Entity can be different on different Clients.
Allow Duplicates - no restrictions on which objects can be instantiated over the network.
No Duplicates - ensure objects are not duplicated by assigning them a Unique ID.
You can set the Unique ID manually in the Prefab, only one Prefab instance will be allowed at runtime, any other instance created with the same UUID will be destroyed.
When creating a Prefab instance in the Scene at Editor time, a special Prefab Instance Unique ID is assigned, if the manual UUID is blank, the UUID assigned at runtime will be the Prefab Instance ID:
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.), each instance created in Editor time will have a auto-generated Prefab Instance Unique ID. 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.
Transfer request
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.
Connection status
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.
Baked script
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<AssetIdOfThePrefab>. This class will be instantiated at runtime, and will take care of networked serialization and deserialization, instead of the built-in reflection-based one.
Commands
Commands are public methods from Components that are marked as synced in the Configure window.
Refer to the Commands section.
You might also want to check out the CoherenceSync instance lifecycle section at the bottom of the Order of execution article.
Last updated
