Handing over 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:
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:
(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):
NotAuthoritativeAuthoritativeAuthorityLossImminent
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.
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:
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.
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.