Authority transfer

Authority over an entity is transferrable, so it is possible to move the authority between different Clients or even to a Simulator. This is useful for things such as balancing the simulation load, or for exchanging items. It is possible for an entity to have no Client or Simulator as the authority - these entities are considered orphaned and are not simulated.

Types of authority transfer

In the design phase, CoherenceSync objects can be configured to handle authority transfer in different ways:

• Request. Authority transfer may be requested, but it may be rejected by the current authority.

• Steal. Authority will always be given to the requesting party on a FCFS ("first come first serve") basis.

• Not transferable. Authority cannot be transferred.

Using the Not transferable option will also disable giving the authority to other Clients, even if you own the entity.

If you want to instantiate entities on the host or Simulator and then transfer the authority to a Client, it is recommended to use the Request option, with Approve by Default set to false.

When using the Request mode, you can use CoherenceSync.OnAuthorityRequest to decide which transfers should go through.

using UnityEngine;
using Coherence.Toolkit;
using Coherence;

public class AuthorityTransferRequestApproval : MonoBehaviour
{
    public CoherenceSync sync;

    private void Awake()
    {
        sync.OnAuthorityRequest.AddListener(OnAuthorityRequest);
    }

    private void OnAuthorityRequest(AuthorityRequest request, CoherenceSync sync)
    {
        // In this example, we want to only allow input authority to be transferred.
        request.Respond(request.AuthorityType == AuthorityType.Input);
    }
}

Auto-adopt Orphan

When Lifetime is set to Persistent, you will see an extra checkbox called Auto-adopt Orphan.

Enabling this option makes it so that if an entity is abandoned by its owner, the Replication Server will assign it to a Client again, as soon as possible. For instance, this can be useful in a big game world, where entities often go out of LiveQueries. When they are first seen again by a Client, the Auto-adopt Orphan option ensures that the Client takes over that entity (i.e. its State authority) without you having to write code for it.

Note: If you abandon an entity but it's still in your LiveQuery, on the next frame the Replication Server might assign it to you again. If you want more control over that, then perhaps you should turn Auto-adopt Orphan off, and implement callbacks to the authority events for that entity.

Requesting authority in code

Requesting authority is very straightforward.

var coherenceSync = target.GetComponent<CoherenceSync>();
bool requestSuccess = coherenceSync.RequestAuthority(AuthorityType.Full);

RequestAuthority returns false if the request was not sent. This can be because of the following reasons:

• The sync is not ready yet.

• The entity is not allowed to be transferred becauseauthorityTransferType is set to NonTransferable.

• There is already a request underway.

• The entity is orphaned, in which case you must call Adopt instead to request authority.

The request itself might fail depending on the response of the current authority.

As the transfer is asynchronous, we have to subscribe to one or more UnityEvents in CoherenceSync to learn the result.

Also because of their asynchronous nature, Clients can receive commands for entities that they have already transferred. Such commands are dropped.

These events are public and available on the CoherenceSync inspector.