These are the docs for 13.8, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.1 is the newest →

Chunk-based interest (CBI)

Chunk-based interest (CBI) is a way of specifying the entity components that worker types or instances want to receive updates about (their “interest”). Interest is a prerequisite for active read access, which the worker instance needs in order to receive updates about changes to entity components.

CBI is a simpler type of interest than QBI. Using CBI, a worker instance has default areas of interest based on the components it has write access authority over. You can extend these areas of interest by defining a radius around the components it has write access authority over.

Component filters

As well as setting up interest, you must set up the static component filter correctly. This is a whitelist that takes precedence over CBI. You can use the dynamic component filter to override the static component filter during runtime.

For more information, see Component filters.

Default areas of interest

A worker instance with write access authority over a component automatically has interest in any components in the same chunk that this component is in. Chunks are a grid over a SpatialOS world, which you configure as part of your project setup. They are measured in world units.

Extending the areas of interest

You can extend the default areas of interest by defining a radius around the chunks that contain components that the worker instance has write access authority over. (The origin of this radius is the center of each chunk.) You define this per worker type, in the entity_interest field in the bridge configuration section of a worker configuration file.

If you set the radius to 0 world units, a worker instance of that worker type receives updates only for components within its default areas of interest. If the radius is greater than 0, the worker instance receives updates for components in chunks that are completely within or intercept this radius. (If the radius is a decimal, SpatialOS rounds up the value to the nearest integer.)

For example, to ensure a worker instance gets updates from entity components within 10 world units of the centers of the default areas of interest, use the following entity_interest setting:

"entity_interest": {
    "range_entity_interest": {
        "radius": 10

Setting up an entity_interest radius gives worker instances in your world information about entities near to the entities for which they have write access authority over at least one component. This means that the worker instances can correctly simulate the entity components they have write access authority over.

For example, in a world that includes rabbits, foxes, and lettuces, the server-worker instance that has write access authority over a rabbit might have interest in components on every entity within a 100 metre radius of the rabbit, so that the rabbit is aware of the threat of nearby foxes and the food source of nearby lettuces.

Adding streaming queries

You can extend the interest of a worker instance even further than its default area of interest and its entity interest radius using streaming queries. You can use a streaming query to extend a worker instance’s interest one-off events or specific entity components.

For example, in a rabbit, fox, and lettuce game, you can use CBI for the rabbit to behave correctly in relation to nearby lettuces and foxes, and you might use a streaming query for the rabbit to behave correctly in relation to a distant volcano eruption.

Turning off chunk-based interest

You can turn off chunk-based interest for a worker type by omitting the entity_interest setting from the bridge configuration section of the worker configuration file for that worker type.

You might want to turn off chunk-based interest if you’re using QBI - otherwise, worker instances are likely to receive more updates than you want them to. Turning off chunk-based interest can also improve performance.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums