v15-upgrade-log.md

Upgrade log for SpatialOS 15.0.0

This log explains the changes we made to this project to upgrade it from SpatialOS 14.9.0 to SpatialOS 15.0.0. You can follow a similar sequence of steps to upgrade your project.

For more information, see the release notes and the SpatialOS 15.0.0 documentation.

Migrate away from deprecated functionality

With our project still in 14.9.0, we migrated away from any deprecated functionality wherever this was possible.

This step very much depends on what functionality your project uses, and whether or not you have already made similar changes when APIs got deprecated in a minor version release.

Use the new logging API instead of LogMessageOps. For simplicity, we log all messages with log-level Warning and above, and Info messages related to establishing the connection.

Upgrade to SpatialOS 15.0.0

Next, we upgraded to SpatialOS 15.0.0. We did the following:

1. Update the version numbers used in spatialos.json.

2. Remove unsupported bridge settings from all worker.jsons.

   The settings were used for legacy load balancing and interest systems. Both of these systems have been re-worked and replaced, and these options are no longer relevant.

3. Update which worker packages are used by the project.

   Debug packages are no longer available by default, and Linux packages have been renamed to reflect compiler upgrades. Static linking against a release library when building in debug mode on Windows is problematic, and so we switch our project to link against the Worker SDK dynamically to keep things simple. Refer to the full release notes to see how this changed the runtime requirements. For example, the required minimum version of glibc has increased on Linux, which might cause incompatibility with old Linux distributions.

4. Update the connection types.

   For simplicity, we are using Insecure connections for all workers. If we were to use TLS or DTLS connection security, we would have to turn this off when running locally, because the Runtime Local Edition does not support establishing secure connections.

5. Address changes to entity queries.

   The only result type is now the snapshot result type.

6. Remove the use of EntityAcl from code, because it is no longer available.

   We will deal with fixing the snapshot and getting authority to work later.

7. Address any changes made to command request op metadata.

   We only have to change some logging messages for now.

8. Add component sets.

   The physics worker always had authority over the EntityAcl, the Position, and the Login component, while the client had authority over the ClientData component. We will therefore need two component sets to represent the two different units of authority in our project. We could replace the EntityAcl with the AuthorityDelegation component, but with the new user-space load balancing, we won't need to update authority dynamically.

9. Update the component registry for the C++ physics worker.

   We use the worker::Schema template to combine components and component sets. We need both, because component sets are now the unit of authority.

10. Create and implement an authority model.

    Our requirements in this example are very simple. We want two different workers to be authoritative over two distinct component sets on one entity. We will therefore need two partitions. To keep things clean, we will use two separate entities to represent the partitions. We will fix the snapshot later. For now, let's assume that these partitions have IDs 2 for the physics simulation, and 3 for the client simulation. We only have one entity we want to simulate, and the authority delegation can be fully static. All we need to do is the following:

    • When the physics worker starts, it must assign the partition with ID 2 to itself.
    • When a client-worker requests authority, the physics worker needs to assign it the partition with ID 3.
    • We need to ensure the physics worker has the right permissions to send system commands. We will address this later, when fixing the launch configurations.

    Please note that this is the very simplest example of how to distribute work and authority. The number of partitions in the world can be dynamic. The mapping of workers to partitions can be dynamic, and a worker can simulate multiple partitions at once. The delegation of component sets to partitions can be dynamic. Which component sets are delegated can be dynamic too, as long as they don't overlap at any time, on any given entity.

11. Fix the initial snapshot.

    We need to remove the EntityAcl and replace it with AuthorityDelegation. We will also need the entities which serve as our Partitions. Additionally, interest is now defined in terms of component sets rather than components to match the authority model, and so we will need to address that as well. We modify the json snapshot directly to account for the changes mentioned above, and update the binary snapshot by converting the json one using the following command: spatial project history snapshot convert --input snapshots/default.json --input-format=text --output snapshots/default.snapshot --output-format=binary.

    Note that we had to manually add some new fields to the json snapshot, because the json format requires all fields to be specified (even if they are empty).

12. As a drive-by fix, we make sure we only attempt to send updates when we have authority.

13. Fix up the launch configurations.

    We only have one, default_launch.json. As we now need the physics worker to send system entity commands, we add this permission. We are also starting the physics worker as a managed worker, and so would need to address the breaking change where layer no longer refers to an attribute, but refers to a worker type instead. However, because the attribute matched the worker type to begin with, we don't have to make any changes. We also take the opportunity to remove some flags which are no longer necessary.

We can now run the project.

Other SpatialOS features

This project does not use all of the SpatialOS features. For the features it uses, it might not use them in the same way that your project does. This document gives an illustration of what an upgrade might look like. You must assess the changes you need to make to your project on a case-by-case basis. For a full list of changes in SpatialOS 15.0.0, see the release notes.

In particular, this project does not use the following SpatialOS features:

• AuthorityChangeOp. SpatialOS 15 replaces this with ComponentSetAuthorityChangeOp.
• The schema AST format. This is removed in SpatialOS 15.
• The Flexible Project Layout (this project uses the Structured Project Layout).
• The legacy interest APIs.