Commands

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: by using the Select Bindings interface on your CoherenceSync object.

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 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.

The resulting schema section will look something like this:

command FemZombie_Character_SendDamage [routing "All"]
  damageValue Int
  staminaBlockCost Float
  staminaRecoveryDelay Float
  ignoreDefense Bool
  hitReaction Bool
  hitPosition Vector3
  sourceConnection Int
  isPlayer Bool

where routing metadata can have the following values:

• "All" - (Send to all instances equivalent)

• "AuthorityOnly" - (Send to authority equivalent)

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 recieving MonoBehaviour. This ensures that the correct method gets called if the receiving GameObject has components that implement methods which 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, a 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.

public void MulticastCommand()
{
    var self = GetComponent<CoherenceSync>();
    var listeners = CoherenceSync.instances.Values;
    
    foreach (var listener in listeners)
    {
        if (!listener || listener == self)
        {
            continue;
        }

        listener.SendCommand<MyScript>(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 every network entity known to this client. To make it only affect entities within a 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 using reflection 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.