Commands

Overview

Commands are network messages sent from one entity to another entity in the networked world. Functionally equivalent to standard RPCs, 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.

CoherenceSync

Select window: accessible from CoherenceSync

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 the MessageTarget.AuthorityOnly while Send 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:

var target = enemy.GetComponent<CoherenceSync>();
                    
target.SendCommand<Character>(nameof(SendDamage), 
                MessageTarget.All,
                damageValue, staminaBlockCost,
                staminaRecoveryDelay, ignoreDefense, 
                hitReaction, hitPosition, 
                ConnectionId, isPlayer);

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.

using Coherence;
using Coherence.Toolkit;
using UnityEngine;

public class MyCommands : MonoBehaviour
{
    public void MulticastCommand()
    {
        var self = GetComponent<CoherenceSync>();
        var listeners = FindObjectsOfType<CoherenceSync>(); 
        
        foreach (var listener in listeners)
        {
            if (!listener || listener == self)
            {
                continue;
            }
            
            listener.SendCommand<MyCommands>(nameof(ReceiveCommand), MessageTarget.AuthorityOnly);
        }
    }

// bind to this method via the Bindings window
    public void ReceiveCommand()
    {
        Debug.Log("Received!");
    }
}

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.

Sending null values in command arguments

Some of the primitive types supported are nullable values, this includes:

• Byte[]

• string

• Entity references: CoherenceSync, Transform, and GameObject

In order to send one of these values as a null (or default) we need to use special syntax to ensure the right method signature is resolved.

using Coherence;
using Coherence.Toolkit;
using UnityEngine;

public class MyCommand : MonoBehaviour
{
    public void MyNullableCommand(string someString, Byte[] someArray)
    {
        if (!string.IsNullOrEmpty(someString)) //Could be null or string.Empty
        {
            // Do something with the string
        }
        
        if (someArray != null && someArray.Length > 0) //Could be null or Byte[0]
        {
            // Do something with the array
        }
    }
}

sync.SendCommand<MyCommand>(nameof(MyNullableCommand), 
    MessageTarget.All, 
    (typeof(string), (string)null), 
    (typeof(Byte[]), (Byte[])null));

Null-value arguments need to be passed as a ValueTuple<Type, object> so that their type can be correctly resolved. In the example above sending a null value for a string is written as: (typeof(string), (string)null)

and the null Byte[] argument is written as: (typeof(Byte[]), (Byte[])null)

Mis-ordered arguments, type mis-match, or unresolvable types will result in errors logged and the command not being sent.

When a null argument is deserialized on a client receiving the command, it is possible that the null value is converted into a non-null default value. For example, sending a null string in a command could result in clients receiving an empty string. As another example, a null Byte[] argument could be deserialized into an empty Byte[0] array. So, receiving code should be ready for either a null value or an equivalent default.

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 entity references

• maximum of 511 bytes total of data in other arguments

• a single Byte[] argument can be no longer than 509 bytes because of overhead

Some network primitive types send extra data when serialized (like Byte arrays and string types) and some are compressed using default compression settings (like int, float, Vector2, and Vector3) so gauging how many bits a command will use is difficult. 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 the total command argument sizes low.

If multiple commands are sent to a single entity or to multiple entities in the same frame or if there is significant network instability, coherence does not guarantee that commands will be received by their targets in the same order as they were sent.