Commands / Messages
Overview
Commands are network messages sent from one entity to another entity in the networked world. Commands bind to public methods accessible on the GameObject that CoherenceSync sits on.
Design Phase
In the design phase, you can expose public methods the same way you select fields for synchronization: through the Configure window on your CoherenceSync component.
Selected public methods will be exposed as network commands in the baking process.
The button on the right of the method lets you choose the routing mode. Commands with aSend to Authority Only
mode can be sent only to the authority of the target entity, while ones with the Send to All Instances
can be broadcasted to all clients that have a copy of this entity. The routing is enforced by the Replication Server as a security measure so the outdated or malicious clients don't break the game.
Sending a Command on a Networked Object
To send a command, we call the SendCommand
method on the target CoherenceSync object. It takes a number of arguments:
The type argument (within the
<
and>
) must be the type of the receiving MonoBehaviour. This ensures that the correct method gets called if the receiving GameObject has components that implement methods that share the same name.The first argument is the name of the method on the MonoBehaviour that we want to call. It is good practice to use the C#
nameof
expression when referring to the method name, since it prevents accidentally misspelling it, or forgetting to update the string if the method changes name.The second argument is an enum that specifies the
MessageTarget
of the command. The possible values are:MessageTarget.All
– this will send the command to each client that has an instance of this entity.MessageTarget.AuthorityOnly
– this will send the command only to the client that has authority over the entity.
Mind that the target must be compatible with the routing mode set in the bindings, i.e.
Send to authority
will allow only for theMessageTarget.AuthorityOnly
whileSend to all instances
allows for both values.The rest of the arguments (if any) vary depending on the command itself. We must supply as many parameters as are defined in the target method and the schema.
Here's an example of how to send a command:
Receiving a Command
We don't have to do anything special to receive the command. The system will simply call the corresponding method on the target network entity.
If the target is a locally simulated entity, SendCommand
will recognize that and not send a network command, but instead simply call the method directly.
Sending a Command to multiple entities
Sometimes you want to inform a bunch of different entities about a change. For example, an explosion impact on a few players. To do so, we have to go through the instances we want to notify, and send commands to each of them.
In this example, a command will get sent to each network entity under the authority of this client. To make it only affect entities within certain criteria, you need to filter to which CoherenceSync you send the command to on your own.
Supported types in Commands
When a prefab is not using a baked script there are some restrictions for what types can be sent in a single command:
4 integers
4 floats
4 bools
4 entity references
1 string
1 byte array
If you ever need to send commands containing any other type (like a vector) or a higher quantity (like two strings) you must mark the prefab to use baked code. This will generate a custom command that can handle all the supported primitive types of the coherence SDK.
If a single command is bigger than the supported packet size, it won't work even with baked code. For a good and performant game experience, always try to keep command sizes low.
Last updated