Active read access

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.

To get updates about an entity component's data, a worker instance must have active read access. For background on why a worker instance might want to receive this data, see the introduction to authority and interest.

A worker instance’s active read access to an entity component depends on three things:

  • Read access permission
    Its worker type must have read access permission to that component type: that is, instances of the worker type must be allowed to read from the component type. Read access permission is controlled by a dedicated component on each entity. This component is called EntityAcl.

  • Interest
    Which components the worker type or instance wants to receive updates about. You use interest to make sure that entities in the world behave correctly around other entities. How you set up interest depends on which type of interest you're using.

  • Component filters
    You must set up the static and dynamic component filters correctly. How you set up the filters depends on which filter you're using, and whether you're using chunk-based interest (CBI) or only query-based interest (QBI).

Read access permission

You define read access permission in an EntityAcl (access control list) component, in the read_acl field.


There are two main ways to define interest:

  • query-based interest (QBI), which gives you precise, granular control

  • chunk-based interest (CBI), which gives you less precise, simple control

Deprecating chunk-based interest

We recommend that you move towards using only query-based interest (QBI), because chunk-based interest (CBI) is deprecated and we'll remove it in version 15 of the Worker SDK. QBI is a more precise, granular alternative to CBI.

When you are designing a worker type’s interest, the components that a worker type has write access authority over are significant in determining the components that the worker type needs to have interest in.

For example, an NPC moving around the world might need to behave differently depending on what’s nearby. A rabbit might run towards a nearby lettuce, or away from a nearby fox. The rabbit needs to behave correctly in relation to these other entities, regardless of which worker instance’s area of authority each of them is in.

To deal with this, a worker instance has interest. That is, it wants to read the state of entity components, even if it doesn’t have write access authority over them. For example, a server-worker instance that’s simulating a rabbit might have interest in every entity within a 100m radius of the rabbit, so that the rabbit is aware of the nearby foxes and lettuces.

Note that interest doesn’t apply to server-workers only: a client-worker instance might have interest in both entities nearby, and really big entities far away, such as distant mountains. Distant mountains might be relevant to a client-worker instance because it needs to render them so that the player can see them as they play the game.

For more information, see:

Component filters

Component filters determine which components a worker instance can receive updates about. You need to set them up so that interest and active read access work correctly. If you don't, then by default your worker instances won't receive any updates.

For more information, see Component filters.

Extending interest (CBI only)

You can extend chunk-based interest using streaming queries and entity queries.

Streaming queries

You can use streaming queries in conjunction with CBI to extend a worker instance's interest for one-off events or specific components on entities.

In the rabbit example, if you are using CBI so that the rabbit behaves correctly in relation to nearby lettuces and foxes, you might use a streaming query so that the rabbit behaves correctly in relation to a distant volcano eruption.

For more details, see Streaming queries.

Entity queries

Entity queries are useful if you need to get information about an entity at a particular time.

For more details, see Queries.

2019-11-15 Page updated with editorial review: Added warning about deprecating CBI.

Updated about a year ago

Active read access

Suggested Edits are limited on API Reference Pages

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