Handing over write access authority

If you're using the GDK for Unreal, this page does not apply to you. For information about handing over authority over Actors, see the GDK documentation on Actor handover.

Before reading this page, you should read Authority and interest and Write access authority.

During the lifecycle of a SpatialOS deployment, write access authority over a component can pass between different server-worker instances. This could happen if the ACL of a component changes, if load balancing switches which worker instance has write access authority, or if the entity moves into another worker instance's area of authority.

Latency between the Runtime and worker instances can cause lost updates:

Image: Update dropped due to authority loss.

To mitigate this, there's a callback which can notify a worker instance when it's about to lose write access authority:

You can use this to send important updates before the worker instance loses write access authority.

Additionally, a worker instance can send a notification that it's ready to lose write access authority:

Image: Notifying the runtime that the worker instance is ready to lose authority.

Note: A worker instance can only send this notification when the component is in the AuthorityLossImminent state.

Authority states

A worker instance's write access authority over an entity component can be in one of three states (represented by an enum):

  • NotAuthoritative
  • Authoritative
  • AuthorityLossImminent

Deprecation: AuthorityLossImminent

We deprecated AuthorityLossImminent in version 14.7 of the Worker SDK, and will remove it in version 15.0.

In version 15.0, there will be a new load balancing system that you can control at a granular level, so you can implement the functionality of AuthorityLossImminent if necessary.

Worker instances can only transition from NotAuthoritative to Authoritative, Authoritative to AuthorityLossImminent, and AuthorityLossImminent to NotAuthoritative.

When a worker instance transitions to the Authoritative and NotAuthoritative states, it receives a component update for the relevant component.

  • Transition to Authoritative: the worker instance receives the component update before the transition.
  • Transition to NotAuthoritative: the worker instance receives the component update after the transition.

The component update synchronizes the worker instance with the Runtime.

Enabling and configuring AuthorityLossImminent notifications

You can configure the time between AuthorityLossImminent and NotAuthoritative on a per-worker instance, per-component basis using authorityHandoverTimeoutMs in the bridge configuration.

Image: The authority handover timeout specifies the time between the authority loss imminent notification and the authority loss notification.

By default, the timeout is set to 0 milliseconds (meaning there's no time for worker instances to send updates).

You must set the timeout to equal to or longer than the time in milliseconds that it takes for the worker instance to communicate with the SpatialOS Runtime and back. (This time depends upon the server hardware and network configuration, but is likely to be in the region of 50 milliseconds.) If the timeout is less than this, updates might still be dropped:

Image: If the timeout is set too low, updates will still be dropped.


The feature to provide AuthorityLossImminent notifications has the following known limitations:

  • Setting a write access authority handover timeout causes a delay to setting the initial write access authority over a component (which happens when an entity is first spawned).

Client-worker write access authority

In an online game, you often want to give control of some components to client-worker instances.

For example, you could model user input as changes to a PlayerControlsComponent that contains, as properties or events, all the actions a user might make.

You could also choose to give client-worker instances write access authority over other components, like their player entity's position. This can help compensate for network latency. To do this, give write access on the component to the particular client-worker instance that controls the player entity.

Setting up a game client's client-worker instance with write access authority over a player entity's Position component can have unintended consequences, as this opens the possibility of a game-player modifying the client-worker instance to use the write access authority to their advantage during gameplay. For example they might make their character move faster than the game logic allows, or be able to pass through walls.

There are more involved techniques you can use to compensate for network latency while not giving client-worker instances more access than they need, such as Client-Side Prediction.

You can change which worker instance has write access authority over a component during runtime. This means you can switch write access authority between server-worker instances and client-worker instances. You do this by dynamically updating an entity's ACL component.

For more information, see this example of changing write access authority.

Updated about a year ago

Handing over write access authority

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.