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.


In order to update component data appropriately, a worker requires data about other components in the game that it might not have write access authority over. For example, if a worker has write access authority over a player’s position component, in order to compute the next value for position, the worker needs data about components that represent the player's joystick position and the obstacles in close proximity.

You use query-based interest (QBI) to specify the component data a worker has interest in for the purpose of updating the components it has authority over. If you design QBI well, it supports a high density of entities in a game without using excessive computing and network resources.

QBI manages the dependencies between related components so that the Runtime provides each worker with only the specific component data it needs.

How QBI works

You can specify queries for component data by adding the improbable.Interest component to entities.

You use improbable.Interest to define interest based on the components a worker has write access authority over. It maps those component IDs to a list of queries. The standard schema library defines improbable.Interest like this:

component Interest {
   id = 58;
   map<uint32, ComponentInterest> component_interest = 1;
type ComponentInterest {
   list<Query> queries = 1;

A query contains a constraint and a result type. Constraints define which entities the query matches, and result types define the set of component updates the worker receives for the matched entities.

This means that when a worker gains write access authority over one of the components listed in improbable.Interest, it also gains interest in the components matched by the query associated with that component.

You design queries that provide workers with component data they don’t have write access authority over, in order to simulate the entity components they do have write access authority over.

To see an example of QBI in action, go to QBI code examples.

2020-09-03 Page content clarified with editorial review.
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 15 days 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.