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.

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.

Usage

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.

Metrics

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.

Search results