Get SpatialOS

Sites

Menu

Bridge configuration

The bridge field of the worker configuration file specifies the worker’s runtime settings. It has the following overall structure:

"bridge": {
    "worker_attribute_set": {},
    "entity_interest": {},
    "streaming_query": [],
    "component_delivery": {}
}

Worker attribute sets

Required field.

A worker attribute set describes a worker’s capabilities, used to work out which components the worker can have access to, as a list of free-form strings. See the worker attributes page for details.

For example, a UnityWorker would have the following attribute set:

"worker_attribute_set": {
    "attributes": ["physics"]
}

In addition to the attribute set defined here, each worker automatically has the attribute "workerId:<worker ID>". For example, the worker UnityWorker12 would have the attribute "workerId:UnityWorker12" added to it.

Entity interest

Required field.

The entity interest field is about defining which entities a worker gets component updates for.

If a worker is authoritative over an entity, it gets an update whenever that entity’s components change. But it also needs to know about the entities nearby.

By default, workers get component updates for all entities they’re authoritative over, as well as for all other entities in the same chunk (the grid squares of a SpatialOS world). But chunks are square, and so this doesn’t quite work.

You can use the entity interest field to set a radius (in world units, see note below). This is a radius around entities that a worker is authoritative over. If there’s another chunk with any point inside this radius, the worker will get component updates for entities inside that chunk.

For example, to make sure a worker gets updates from entities within 10 world units of any entity the worker has authority over, use the following entity_interest setting:

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

NOTE: Positions and distances are expressed in an arbitrary unit called “world unit”. It is up to the workers that run the simulation to interpret them consistently. Unity workers, for example, interpret one world unit as one meter in the Unity coordinate space.

Streaming queries

Optional field.

SpatialOS is based on the concept that workers are generally only interested in the entities close to them. For example, a player needs to see entities up 50m away from them, but doesn’t need to care about entities further away.

This is usually fine. But sometimes the world contains big objects that should be visible from further away. To get a worker to check out these entities, use streaming entity queries.

The streaming_query field is a list of streaming queries. In each streaming query, you can specify that a worker will check out an entity if it:

  • has a specific component
  • is in a specific radius around entities that a worker is authoritative over

For example, the following snippet subscribes to component updates from

  • all entities with the component improbable.foo.GloballyVisible
  • all entities with the component improbable.foo.HighlyVisible, within 1000 world units
"streaming_query": [
    {
        "global_component_streaming_query":{
            "component_name":"improbable.foo.GloballyVisible"
        }
    },
    {
        "bounded_component_streaming_query":{
            "component_name":"improbable.foo.HighlyVisible",
            "radius":1000
        }
    }
]

Component delivery

Optional field.

This field configures the set of components a worker checks out when they check out an entity, and whether component updates are allowed to be sent in an unreliable manner.

By default:

  • only components with checkout_initially set to true are sent to the worker
  • the transmission for all component updates is RELIABLE_ORDERED

Components to check out initially

To specify the set of components a worker will get when they check out an entity, use the following fields of component_delivery:

  • checkout_all_initially (boolean). By default, this is set to false, which means only the components with checkout_initially set to true are sent to the worker when it checks out an entity.

    If set to true, all components are sent to the worker when it checks out an entity.

  • override maps fully-qualified component names to component delivery settings.

    Components without an override use the default message delivery settings as specified in the default field. They are only checked out initially if checkout_all_initially is true.

Note that the worker can change this set of components at runtime - see the API documentation (C++, C#, Java) for more details.

Transmitting component updates unreliably (“quality of service”)

Component updates can be transmitted reliably or unreliably.

To prevent workers getting overloaded, you can choose to transmit some component updates unreliably. Quality of service describes the concept in more detail.

The default field of component_delivery sets the default way to transmit component updates. This can be either RELIABLE_ORDERED or UNRELIABLE_ORDERED.

This configuration applies only to messages sent to workers, not for messages sent from workers.

Examples

This example reliably transmits updates for all components except Position and Rotation, and mandates that the position component is checked out initially:

"component_delivery": {
    "default": "RELIABLE_ORDERED",
    "override": {
        "improbable.Position": {
            "checkout_initially": true,
            "message_delivery": "UNRELIABLE_ORDERED"
        },
        "mygame.coordinates.Rotation": {
            "message_delivery": "UNRELIABLE_ORDERED"
        }
    }
}

This example mandates that all components are checked out initially (using checkout_all_initially). This setting takes precedence over the individual components’ checkout_initially settings, so we leave them unspecified:

"component_delivery": {
    "default": "RELIABLE_ORDERED",
    "checkout_all_initially": true,
    "override": {
        "improbable.Position": {
            "message_delivery": "UNRELIABLE_ORDERED"
        },
        "mygame.coordinates.Rotation": {
            "message_delivery": "UNRELIABLE_ORDERED"
        }
    }
}

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums