Query-based interest

GDK for Unreal

If you're using the GDK for Unreal, this page does not apply to you. See the GDK documentation on game client interest management.


You use query-based interest (QBI) to control the data that worker instances receive. QBI is granular, so you can choose exactly what data each worker instance receives, and how frequently it receives updates to that data. This granular control means that you can have a high density of entities without an overwhelming amount of network traffic.

For each component on an entity (for example, the position component on a player entity), there is one worker instance that can make changes to the component’s value. This worker instance has write access authority over the component. In order to compute the value of the component that it has write access authority over, the worker instance requires data about other components in the game, for context.

For example, a physics worker instance Physics1 might have write access authority over a player’s position component. To compute the next value for position, the Physics1 needs to receive data about components that represent:

  • the player's joystick position
  • the obstacles in close proximity

You use QBI to express the dependencies between these components, and the SpatialOS Runtime uses these dependencies to control the information that the Physics1 receives.

For example, you can use a radius to specify the area around a player, so that Physics1 doesn’t receive unnecessary information about distant obstacles. You can also limit how frequently the Runtime sends updates about specific components, to save bandwidth.

How QBI works

You set up QBI using a component on each entity. This component is called improbable.Interest, and it contains a list of component IDs that map to queries.

Each query needs:

  • a QueryConstraint, which can contain any combination of constraints. The constraints control which entities are matched by the query.
  • a result type, which controls the components that the worker instance receives updates about on the entities that match the QueryConstraint.

The combination of query constraints and result types for each entity create a query map for any worker instance with write access authority over it.

For example, an entity PlayerX might have an improbable.Interest component that looks something like this:

When a worker instance gains write access authority over one of the components in the list of IDs, it also gains interest in any components that match the queries associated with that component.

In the diagram above, for example, when a worker instance gains authority over component 41, this initiates interest in entity 5's joystick component. We refer to component 41 as the initiating component and entity 5's joystick component as a component of interest.

You set up the queries based on the updates that a worker instance needs to receive about entity components that it doesn't have write access authority over, in order to simulate the entity components that it does have write access authority over.

Example of where you could use QBI

A player entity might have a health component and a player component. In order to compute the health of the player entity, the worker instance that has write access authority over its health would want to know about all nearby entities with a weapon component, because events relating to a nearby weapon component could lead to a changes in the value of the health component of the player entity. For example, the player character could get shot and injured by another a character with a gun.

At the same time, to render a map to the player that shows the positions of all other players in the game, the worker instance that has write access authority over the player component would want to know about the position component of all other players in the game.

So, to compute the health and player components for this player entity, a worker instance needs interest in the position component of other player entities and the weapon component of nearby entities. In this case, the player entity's improbable.Interest component would contain queries that look something like this:

  • health
    • Constraint: relative sphere constraint AND weapon component constraint
    • Result type: weapon component
  • player
    • Constraint: player component constraint
    • Result type: position component

This means that:

  • whichever worker instance has write access authority over the entity's health component will have interest in weapon components that are within a sphere of a specified size around the entity.
  • whichever worker instance has write access authority over the entity's player component will have interest in the position of all entities.

The same worker instance might have write access authority over both health and player, in which case both of the queries form part of its interest map, and it has interest in weapon components within a sphere and also position components anywhere in the world.

2020-05-01 Page updated with editorial review: Moved in-depth information onto child page, and added new introduction.
2019-12-10 Page updated with editorial review: Added information on frequency.
2019-11-15 Page updated with editorial review: Added tip, introduction, and diagram. Clarified wording.

Updated about 12 hours ago

Query-based interest

Suggested Edits are limited on API Reference Pages

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