Get SpatialOS


These are the docs for 13.6, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 13.8 is the newest →

Component settings

The component settings field allows you to configure various component settings. For now this allows you to set the authority handover timeout period. For more information, see Handing over authority between workers.

The component settings field allows you to configure settings for each individual component or configure a default which is applied to all other components. Below is an example of a typical configuration.

"componentSettings": {
    "perComponentSettings": {
        "improbable.MyFancyComponent": {
            "authorityHandoverTimeoutMs": 300
    "default": {
        "authorityHandoverTimeoutMs": 400

In the example above, improbable.MyFancyComponent will have an authorityHandoverTimeoutMs of 300 and all other components will default to 400.

If no default is set, components will default to having an authorityHandoverTimeoutMs of 0.

Information about what the authorityHandoverTimeoutMs does can be found in Handing over authority between workers.

Delta-compressed component updates

This lets you configure which components you want to delta-compress when they are updated. If you’re sending large component updates, you might want to enable delta-compressed component updates for a component. This means that, instead of sending the entire new state, the component update will be sent as a description of how the state has changed.

Imagine you have submitted your book to an editor, but you want to add an additional page. A delta-compressed update would be sending that page to the editor with a note saying “insert this page after page X”, instead of sending the entire book including that new page.

This is a tradeoff: it saves bandwidth at the cost of CPU overhead and latency.

By default, no worker types have delta compression applied to component updates.

How delta compression works

Delta compression works using diff caches on both the SpatialOS Runtime and worker instances that store the last component state sent and received for a given component. Updates are sent as a binary diff across the network which, for some property types, can have large bandwidth savings.

This works best for small changes to larger property types, e.g. when appending an element to a long list, as opposed to sending the whole list again.

This feature is still in the very early stages. If you want to try it out, we recommend reading the documentation fully and in detail. In particular, if you aren’t careful about which components you delta-compress, it can crash your deployment, because - used badly - sending delta-compressed updates at too high a frequency can overload the SpatialOS Runtime. Because of this, please don’t use this feature in cloud deployments. If you use it in a cloud deployment, we reserve the right to shut your deployment down.


You enable delta compression on a per-worker type, per-component basis. For example, to turn on delta-compressed component updates for improbable.ants.ToNest and improbable.ants.ToFood you would need to modify your worker.json like so:

"component_settings": {
    "per_component_settings": {
        "improbable.ants.ToNest": {
            "encoding": {
                "type": "BINARY_DELTA_COMPRESSION"
        "improbable.ants.ToFood": {
            "encoding": {
                "type": "BINARY_DELTA_COMPRESSION"

Best practices

You should only delta-compress component properties that are large with small, infrequent changes, e.g. appending an item to a long list as opposed to changing all items at once. For example, any of the following:

  • list
  • map
  • string
  • large object types contained within components

We recommend you don’t enable delta compression on:

  • any of the above types that may change dramatically, for example a List that would have half of the contents replaced.
  • smaller types, such as single int fields, due to the overhead of calculating the diff.

You can enable delta compression for other component types, but diffs may be abandoned because:

  • the computed diff actually exceeds the size of the update.
  • the process hits the approximate cutoff time (default 5ms - we’re looking into making this configurable).
  • the process detects before diffing starts that one of the above cases is highly likely to occur.

Diffs that aren’t abandoned can still use CPU on the SpatialOS Runtime or worker instance side to compute.

We would strongly recommend you closely monitor behaviour and metrics (e.g. SpatialOS Runtime CPU usage and latency) after enabling this functionality, as it can cause worker instances to stop responding to pings.


You can measure delta compression through worker instance metrics via the Inspector. Use this to confirm delta compression is working as intended, and get insight into the bandwidth you’re saving and your CPU/lag overhead due to diffs abandoned.

Inspect button

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums