Sites

Menu
These are the docs for 14.0, 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 →

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 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.

Read access permission

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

Interest

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

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 chunk-based interest (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.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums