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.
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
A worker instance's write access authority over an entity component can be in one of three states (represented by an
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
When a worker instance transitions to the
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.
You can configure the time between
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).
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