Actions

Synchronizing execution and parameters

As explained in the Actions page, Actions that inherit from the BroadcastObjectAction class are used to synchronize the execution of code for all the users in the session. If the Persistence type has a value different to None, the Actions will be restored for users joining later than the actual execution of the Action.

When a user is connected to the Session and the Action's Execute method is called, after the signal to run the Action is sent through the network, each player runs its LocalExecuteImplementation method.

The Execute and LocalExecuteImplementation methods of Actions receive a string parameter that is synchronized (and stored for persistent actions) with the execution of the Action itself. Its purpose is to provide users the possibility to pass untyped parameters to the execution of the Action (a simple string, a more complex structure serialized in Json format...).

In the following example we have created a public function called ExecuteCommand1 that will call the Execute function passing data to it to change the behaviour of the action depending on that data. This public function can be called from your own code or from the scene.

public class CustomAction : BroadcastObjectAction
{
    public void ExecuteCommand1()
    {
        Execute("command1");
    }

    protected override void LocalExecuteImplementation(string data)
    {
        switch (data)
        {
            case "command1":
                // Do command 1 related logic
                break;
            case "command2":
                // Do command 2 related logic
                break;
        }
    }
}

Take into account that each time a persistent Action is executed, both the identifier and parameters of the Action are added to a list in the server that contains all run actions ordered by time of execution. This means that if you use an Action as a means of transferring data among the users of the session and this action is persisted, when a users joins the session, they won't receive just the last data associated to the last execution of the action, they will receive all the data associated to all executions.

That's why, Actions shouldn't be used as a means to synchronize data.

Restoring the state of ran actions

A user could join the scene after this Action has been executed once or several times. To make the scene of that user, who has joined late or has recovered from a network disconnection, consistent with that of the rest of the users, the Actions run the RestoreState method on startup, once for each of the times the Action has been executed, and with the data it has received for each of the executions.

Since the RestoreState method is called for each of the stored executions of that action, it is recommended to avoid time consuming operations, like animations or tweens, and directly setting the state that running the Action would achieve with the received data (e.g.: set the end position instead of triggering a move animation).

public class CustomAction : BroadcastObjectAction
{
    public void ExecuteCommand1()
    {
        Execute("command1");
    }

    protected override void LocalExecuteImplementation(string data)
    {
        switch (data)
        {
            case "command1":
                // Do command 1 related logic
                break;
            case "command2":
                // Do command 2 related logic
                break;
        }
    }

    public override void RestoreState(string data)
    {
        base.RestoreState(data);

        switch (data)
        {
            case "command1":
                // Set final state for command 1 related logic
                break;
            case "command2":
                // Set final state for command 2 related logic
                break;
        }
    }
}