# Authority transfer

### Overview

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.
* **Disabled**. Authority cannot be transferred.

{% hint style="info" %}
**Note** that you need to set up Auto-adopt Orphan if you want orphans to be adopted automatically when an Entity's authority disconnects, otherwise an orphaned Entity is not simulated. Auto-adopt is only allowed for persistent entities.
{% endhint %}

<figure><img src="https://content.gitbook.com/content/4xmLLczbgaGVeoF6vews/blobs/4XQ2cHzLB3GCXNvaWs0I/CoherenceSync_Baked.png" alt=""><figcaption></figcaption></figure>

When using Request, an optional callback `OnAuthorityRequested` can be set on the **CoherenceSync** behaviour. If the callback is set, then the results of the callback will override the Approve Requests setting in the behaviour.

The request can be approved or rejected in the callback.

```csharp
// connectionID is the network connection ID of the requesting client.
// sync is the CoherenceSync behaviour of the object the other client is
// requesting authority over.
public bool OnRequest(ushort connectionID, CoherenceSync sync)
{
    return (sync == theRightSync && connectionID == goodConnectionID);
}
```

{% hint style="info" %}
Support for requests based on [`CoherenceClientConnection.ClientID`](https://docs.coherence.io/1.1/coherence-sdk-for-unity/client-messages) is coming soon.
{% endhint %}

### Requesting authority in code

Requesting authority is very straight-forward.

<pre class="language-csharp"><code class="lang-csharp">var coherenceSync = target.GetComponent&#x3C;CoherenceSync>();
<strong>bool requestSuccess = coherenceSync.RequestAuthority(AuthorityType.Full);
</strong></code></pre>

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

1. The sync is not ready yet.&#x20;
2. The entity is not allowed to be transferred because`authorityTransferType` is set to `NonTransferable`.
3. There is already a request underway.
4. 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.&#x20;

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

Also because of their asynchronous nature, clients can receive [commands](https://docs.coherence.io/1.1/coherence-sdk-for-unity/networking-state-changes/commands) for entities that they have already transferred. Such commands are dropped.&#x20;

```csharp
// There Unity Events in CoherenceSync help us understand 
// what happened with authority requests and act accordingly.

// called when the CoherenceSync entity becomes the simulation authority
public UnityEvent OnStateAuthority;

// called when the CoherenceSync entity loses simulatino authority
public UnityEvent OnStateRemote;

// called when a request to assume authority over the CoherenceSync entity
// is rejected
public UnityEvent OnAuthorityRequestRejected;
```

These events are also exposed in the *Custom Events* section of the **CoherenceSync** inspector.