Streaming queries

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.

Streaming queries are a way to extend chunk-based interest (CBI) so that worker instances can have active read access to distant entity components. Find out about the different types of interest and about setting up active read access in the active read access documentation.

Deprecating CBI and streaming queries

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

When you use CBI, worker instances have default areas of interest which you can extend to include nearby entities using the entity_interest radius.

Sometimes, worker instances need updates about components on entities which aren't in the default or extended area of interest. For example, a client-worker instance that is rendering the game to a player might need to receive updates about distant mountains which should be visible to the player, or a server-worker instance might need updates on components on distant entities for weather systems or world-wide communications. You can use streaming queries to achieve this.

streaming_query is an optional field in the bridge configuration section of a worker configuration file.

Entity queries or streaming queries?

If you want information about an entity, but you don't need regular updates about it, use an
entity query instead.

If you need regular updates about an entity, it's better to use streaming queries: they return information periodically, and they only return the new information about a component, rather than all the information about it.

How streaming queries work

If you set up a streaming query for a component, for entities with that component, the worker instance receives updates about it. Effectively, to the worker instance, it looks like the entity is within its interest area.

The worker instance gets updates to this entity’s components at specific time intervals. You can configure this (see below).

Limitations

Streaming queries have some limitations:

  • The worker instance doesn't receive all of the updates for each component of an entity:
    • It only gets updates at the time interval you set (see below).
    • It doesn't receive any event updates.
  • You can only set the time interval globally for all streaming queries within a deployment.
  • You can’t change streaming queries at runtime.
  • You have to specify components to query, rather than entities.
  • Component filtering dictates which components a worker instance receives updates on as a result of a streaming query.

  • Streaming queries generally have more processing overhead than CBI, so use them sparingly.
  • The processing cost of a streaming query is similar to the cost of an entity query. If you'd expect an entity query to be expensive (for example, if it searches a large area), a similar streaming query would be expensive too.
  • Each streaming query has its own overhead, which means you can optimise by merging several streaming queries into one.
  • The more worker instances you have, the more times your streaming queries will be run, and so the higher their overall cost will be.
  • Setting up a streaming query

    First, you need to pick a component. By default, for every entity with that component, a streaming query will return updates to all components on that entity. However, it's good practice to improve efficiency and bandwidth use by narrowing down which updates are returned.

    To do this, specify:

    • which components (on the entities returned by the streaming query) you want updates for
    • a radius (around entities that a worker instance has write access authority over) that an entity must be within

    You always need to include the improbable.Position component, and, if you're writing a streaming query for a Unity or Unreal worker type, you also need to include the improbable.Metadata component.

    For example, the following snippet will send this worker instance:

    • updates to the components your.game.Status, your.game.Health, and your.game.Flammable for all entities with the component your.game.GloballyVisible
    • updates to all components from all entities with the component your.game.HighlyVisible, within a radius of 1000 world units around an entity that the worker instance has write access authority over.
    "streaming_query": [
        {
            "global_component_streaming_query": {
                "component_name": "your.game.GloballyVisible"
            },
            "components_streamed": {
                "specific_components": {
                    "components": [
                        "improbable.Position"
                        "your.game.Status",
                        "your.game.Health",
                        "your.game.Flammable"
                    ]
                }
            }
        },
        {
        "bounded_component_streaming_query": {
            "component_name": "your.game.HighlyVisible",
            "radius": 1000
            }
        }
    ]

    Configuring the time interval

    To configure the time interval between streaming queries, set streaming_query_interval in your
    launch configuration file.

    The default time interval is 4 seconds.


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

    Updated about a year ago


    Streaming queries


    Suggested Edits are limited on API Reference Pages

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