Operations: how workers communicate with SpatialOS

If you’re building a worker from scratch with our C++, C# or Java SDKs or writing your own engine integration, you’ll need to learn how workers interact with SpatialOS through operations.

SpatialOS worlds are simulated by a number of workers, each of which has a view on a part of the entire world, determined by the checkout area. Operations are granular, high-throughput messages sent between workers and SpatialOS. They update each worker on changes within the worker’s local view of the world, and notify SpatialOS of the changes workers make to entities and components they control.

This page gives a high-level overview of operations - defining their purpose and properties in order to give you an idea of how to handle operations when writing a SpatialOS worker.

What are operations?

Operations are messages sent between each worker and SpatialOS, carrying information about updates to workers, entities and components. Workers can subscribe to some or all incoming operations in order to:

• keep local entity and component state in sync with the canonical versions maintained by SpatialOS
• respond to incoming events and commands associated with entities simulated by the worker
• receive and propagate SpatialOS metrics

Operations communicate updates at a granular level - for example, a ComponentUpdate operation carries information about a single entity component’s change in value, and may be sent hundreds of times a second to each worker.

The Worker SDK Connection object is used to receive operations, which can then be passed to a Dispatcher object in order to subscribe custom handlers for each type of operation.

The protocol does not automatically keep track of what entities and components a worker has checked out. However, the View object is available as a means of keeping track of entities and components present in the worker’s view of the world.

Operations received by a SpatialOS worker

This section explores all of the operations available in SpatialOS, organised into several groups for ease of reading. Please note that these groups are not reflected in the API itself.

Worker-related operations

Operation	Description
Disconnect	The worker is disconnected from SpatialOS.
FlagUpdate	A worker flag has been created or deleted, or its value has changed.
LogMessage	The SDK issues a log message for the worker to print.
Metrics	The SDK reports built-in internal metrics.
CriticalSection	A critical section is about to be entered or has just been left.

Entity-related operations

Operation	Description
AddEntity	An entity is added to the worker’s view of the world. This operation does not suggest that an entity was created in the world, rather that it has entered the worker’s view.
RemoveEntity	An entity is removed from the worker’s view of the world. This operation does not suggest that the entity has been deleted from the world.
ReserveEntityIdResponse	The worker has received a response for an entity ID reservation it requested.
ReserveEntityIdsResponse	The worker has received a response for a reservation of an entity ID range it requested.
CreateEntityResponse	The worker has received a response for an entity creation it requested.
DeleteEntityResponse	The worker has received a response for an entity deletion it requested.
EntityQueryResponse	The worker has received a response for an entity query it requested.

Component-related operations

Operation	Description
AddComponent	A component is added to an existing entity in the worker’s view of the world.
RemoveComponent	A component is removed from an existing entity in the worker’s view of the world.
AuthorityChange	The worker’s authority state over a component is changed to Authoritative, Not Authoritative or Authority Loss Imminent.
ComponentUpdate	A component for an entity in the worker’s view of the world has been updated.
CommandRequest	The worker has received a command request for a component on an entity over which it has authority.
CommandResponse	The worker has received a command response for a request it issued previously.

The Dispatcher and the View

Your worker implementation handles data received from SpatialOS using the Dispatcher object, used to subscribe a custom handling function for each type of operation received.

The Dispatcher does not process the incoming operations in any way: it’s your responsibility to keep track of the state of the entities and components in your worker’s view. One way to do this would be to keep an in-memory data structure that keeps track of visible entities and components, and update it when entities and components are added to and removed from the worker’s view (through the corresponding operations).

Alternatively, you can use the View object: a special type of dispatcher that automatically keeps track of the entities and components available in your worker’s local view of the world. It works by reading incoming operations before passing them to your subscribed handling functions. You can use a View instance instead of a Dispatcher instance if your worker needs to keep track of the entities and components in its checkout area.

Example of operation handling in a worker implementation

To help you understand how a custom worker may handle operations received from SpatialOS, let’s consider as a scenario a simple world with many non-player characters (NPCs) running on SpatialOS. A particular NPC is moving a large distance across the world, during which it crosses the boundaries of two workers:

The NPC is controlled by an AI running on the workers. There are three important points in time during this scenario:

1. When the NPC enters the checkout area of worker 2, the worker receives operations containing the data needed to add the NPC to its local view of the world.
2. When the NPC leaves the authoritative area of worker 1 and enters the authoritative area of worker 2, worker 2 receives operations telling it about newly gained authority over the NPC. Worker 1 receives operations to allow it to propagate any local AI state to SpatialOS, and revoking its authority over the NPCs components.
3. When the NPC leaves the checkout area of worker 1, the worker receives operations telling it to remove the NPC from its local view.

The diagram below shows some of the operations sent to the workers by SpatialOS, along with a sensible way in which these operations may be handled by a custom worker implementation. Workers receive many other operations, such as ComponentUpdate, sent every time the NPCs position changes within the simulation. However, these operations are not included in the diagram, to make it easier to understand.

Let’s look at the individual operations in the scenario above, when they are sent to workers and how they can be handled.

AddEntity

AddEntity is sent to worker 2 when the NPC moves into the worker’s checkout area. This operation tells the worker that there is a new entity in its local view of the world. We store this information in the worker’s memory using a sensible data structure - such as a hash map from the entity id to a list of the entity’s components.

AddComponent

AddComponent operations are sent to worker 2 after AddEntity, in order to inform the worker of all of the components available on the NPC entity. Each operation provides the data for a particular entity component, allowing the worker to store this information in-memory. Two AddComponent operations are received by the worker - one for the position and another for the ai_state component.

AuthorityChange

AuthorityChange operations are sent to both worker 1 and worker 2 at different points in time within the scenario. This type of operation tells workers that their authority over a particular component has changed. The values received in our scenario are:

• Authority Loss Imminent - sent to worker 1 when the NPC leaves the worker’s authoritative area. This value alerts the worker that it’s about to lose authority over NPC components, giving our implementation a chance to push any in-memory state related to each component to SpatialOS through component updates. In our case, we want to push any state relating to the NPC’s AI (such as the current path followed by the AI) to SpatialOS, so that worker 2 can take over the NPCs simulation where worker 1 left off.

• Not Authoritative - sent to worker 1 after Authority Loss Imminent to tell the worker that it no longer has authority over the NPC’s components. We handle this by flagging the authority loss on each component, and ensure that our worker implementation stops sending component updates for the NPC.

• Authoritative - sent to worker 2 when the NPC enters worker 2’s authoritative area. We handle this by flagging the authority gain on each component, triggering the worker to begin simulating the NPC using the values in ai_state, picking up from where worker 1 left off.

ComponentUpdate

ComponentUpdate operations are sent to each worker when any of the components on the NPC are updated. Each operation carries the value of a particular component after the update. For example, as worker 1 simulates the NPC and changes its position, worker 2 will receive each update as a ComponentUpdate operation (as long as the NPC is in worker 2’s checkout area). We handle this operation by writing the new values to the worker’s in-memory store.

RemoveComponent

RemoveComponent operations are sent to worker 1 when the NPC leaves the worker’s authoritative area. These tell the worker that the component is no longer visible to the worker, and hence that it will no longer receive component updates for that component. We handle this by removing the component from our in-memory store.

RemoveEntity

RemoveEntity operations are sent to worker 1 when the NPC leaves the worker’s authoritative area, and after every RemoveComponent operation for the entity. This tells the worker that the entity is no longer visible, and we handle this by removing the entry for the entity from the worker’s in-memory store.

Next steps

Now that you have learned about operations, you are ready to build a custom worker or an engine integration for your SpatialOS project! Learn more by reading our C++, C# or Java worker SDK documentation.