This page explains how to upgrade a SpatialOS project from one major version to the next.
Note: You do not need to follow this guide if you are not changing your major version. If you are using FPL, it’s up to you to download the new version of any packages and follow the release notes. If you are using SPL, follow the minor and patch version upgrade guide instead.
You develop SpatialOS projects against a specific version of the SpatialOS SDK.
- If you're using the structured project layout (SPL), the SDK version that your project builds against is defined in the
spatialos.jsonfile at the root of the project, in the
- If you're using the flexible project layout (FPL),
there is no SDK version defined anywhere in particular. Instead, it is up to you to download the correct packages using
spatial package getdirectly.
Our upgrade guides assume you are upgrading from the previous major version to the next. Features that are removed in a new major are often first deprecated in the previous major with replacement functionality in place. This means that upgrading from the final minor of a major to the next major should be easier; you might be able to migrate your code onto a version with both the deprecated functionality and the replacement.
You can skip major versions, for example upgrading from version 12 to 14. However, our guides do not cover this scenario.
Note: It's very important you start by running
spatial clean. Otherwise, intermediate files won't be cleaned up properly and may cause issues with the new version.
- Open a terminal in the root directory of your project.
- Open the
spatialos.jsonfile at the root of your project.
- Replace the
sdk_versionvalue and the
versionvalue of all dependencies with the desired version (for example:
- Replace all other instances of the version number in the file.
Update all calls to
spatial package get in your build system to download packages from the desired version (for example:
See the relevant page for each Worker SDK language and then return to this page for step 3, below.
The sections above address the largest breaking changes. However, there are a number of smaller adjustments to various APIs that may still need to be made. To address these:
- Read through the breaking change release notes. If there's anything that affects your project, make the relevant change.
- Run a build (either using
spatial worker buildif using the SPL, or using your own build system if using the FPL).
Any errors you see should be caused by a breaking change listed in the release notes.
- For each compilation error, find the relevant breaking change release note, and upgrade to the new API.
- Run a build again.
- Repeat until your project compiles.
You've now upgraded to the latest major version of SpatialOS. Take a look at the release notes to see details about the changes.
Let us know how the upgrade went on the SpatialOS forums.
Updated 11 months ago