Introduction to QBI

Before reading this document, make sure you are familiar with:

This page provides a quick overview of the key primitives in query-based interest.


Query-based interest is enabled for an entity by adding the improbable.Interest component to that entity.

Interest is effectively a mapping from a component ID to a list of queries, where each list of queries is only active on the worker that is authoritative over the component with that ID.

For example, if you want to control the interest of a worker responsible for simulating the position of a player entity, you could use the Position component, whose ID is 54, as the key to a set of queries. These queries would then define which components the worker should be interested in.

Note: The InterestTemplate class provides methods to define and manipulate an Interest component.


A query is represented as a constraint. The constraint specifies for which entities we want to receive components . You can either return all components or specify a list of components that should be returned for all entities satisfying the constraint.

Note: The InterestQuery class provides methods to create a query, set a constraint and define what components the query should return.


Constraints are used to define what entities a query should be looking for.

The available constraints with query-based interest are:

Constraint Description
Sphere Entities in a sphere around a given point.
Cylinder Entities in a cylinder around a given point.
Box Entities in a box around a given point.
Relative sphere Entities in a sphere around an entity's Position.
Relative cylinder Entities in a cylinder around an entity's Position.
Relative box Entities in a box around an entity's Position.
Entity ID Entities matching a given entity ID.
Component Entities in the world that have a given component.
And Entities matching all given constraints.
Or Entities matching at least one given constraint.

Note: The static Constraint class provides constructors for each constraint defined in the table above.

Updated about a year ago

Introduction to QBI

Suggested Edits are limited on API Reference Pages

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