Active read access
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
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.
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
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
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 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.
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 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.