Upgrade to the new bridge
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.
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.
How to upgrade
1. Opt in
In your deployment configuration files
default_launch.json), change the template to
<size> is one of
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
ComponentUpdatenow 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.
AddComponentsmay 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
position, and you receive these in the order
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
positionbefore 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.