Sign up

Sites

Menu
These are the docs for 14.0, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

Handing over write access authority

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:

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:

Runtime sending a notification that the worker instance is about to lose 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:

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

The write access authority state can only transition from NotAuthoritative to Authoritative, Authoritative to AuthorityLossImminent, and AuthorityLossImminent to NotAuthoritative.

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.

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:

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

Limitations

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 the API documentation for C++/C#.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums