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

Upgrade to the new bridge

The new bridge is compatible with all versions of SpatialOS from 11.0 onwards.

The bridge: background

The bridge is a concept that users don’t directly interact with much. Bridges are in charge of communicating with workers: they send workers information and updates about the SpatialOS game world, and receive updates from workers the other way too.

What’s changing

The bridge is changing from a pipeline-based algorithm (updates arriving at the bridge were passed through a pipeline to be processed and sent to a worker) to a diff-based algorithm (the bridge knows what data the worker should see and what it currently sees, and figures out the difference).

The new algorithm:

  • is purpose-built for the upcoming entity database architecture
  • is more robust for rate-limiting and re-establishing connections
  • paves the way for
    • sending only the part of a component that’s changed in an update, rather than the whole thing (which minimises bandwidth)
    • sensible load balancing (see below)
    • more efficient queries
    • degrading gracefully when a worker gets overloaded
    • more powerful, flexible systems for expressing a worker’s interest

The user-facing consequences are mostly around changes in the order/groupings of checking out entities, and sending only changes in updates.

The new bridge won’t support the Authority Loss Imminent operation until we release the upgraded load-balancing system. If your project makes use of Authority Loss Imminent, please wait until we release the new load-balancing system before upgrading to the new bridge.

How to upgrade

1. Opt in

In your deployment configuration files (eg default_launch.json), change the template to <size>_bridge_v2, where <size> is one of small, medium, large.

2. Check potential changes in behaviour

Look for these problems in your code, but you should also run a deployment and check for these issues.

  • Updates may not contain values for all fields, because ComponentUpdate now only sends the field that’s changed.

    Make sure you’re not relying on the update for current component value; instead, get any properties you need from the component itself.

  • Checkout order/grouping may change.

    Entities are no longer grouped in chunks, so workers may check them out in a different order now. You can’t rely on a worker having a set of entities checked out, or a group being checked out at the same time.

    For example, a cup entity that’s meant to be sitting on a table entity won’t necessarily get checked out before the table entity.

    There aren’t any mitigations for this - we’ll help you if you’re really relying on this.

  • AddComponents may arrive in a different order.

    Be careful with code that relies on accessing one component immediately when another one is added (ie as a callback for OnPositionAdded). For example, say you have an entity with a velocity and a position, and you receive these in the order velocity, position. If you have some logic that reads new position = position + velocity * tick_time, this won’t work, because the logic is trying to access position before it’s been set up.

    You might hit an issue like this even if you haven’t come across it (or even if you’ve fixed it previously) when using the old bridge.

The new bridge may have a performance degradation, with up to a 20% increase in CPU usage. If you notice anything higher than that, please let the team know.

This is caused by a shim layer that we’re using to provide compatibility with the old architecture before enabling the entity database for use. We expect performance to go back to normal (or better) if you upgrade to the new entity database, which we plan to release in the next few months.

Once you’ve upgraded to the new bridge, you can upgrade to the new load balancer.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums