Upgrade to major versions

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.

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.

Upgrade process

Step 1. Upgrade your SpatialOS SDK version

Structured project layout

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.

  1. Open a terminal in the root directory of your project.
  2. Run spatial clean.
  3. Open the spatialos.json file at the root of your project.
  4. Replace the sdk_version value and the version value of all dependencies with the desired version (for example: 14.0.0).
  5. Replace all other instances of the version number in the file.

Flexible project layout

Update all calls to spatial package get in your build system to download packages from the desired version (for example: 14.0.0).

Step 2. Address major API breaking changes

See the relevant page for each Worker SDK language and then return to this page for step 3, below.

Step 3. Address remaining API breaking changes

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:

  1. Read through the breaking change release notes. If there's anything that affects your project, make the relevant change.
  2. Run a build (either using spatial worker build if 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.
  3. For each compilation error, find the relevant breaking change release note, and upgrade to the new API.
  4. Run a build again.
  5. 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

Upgrade to major versions

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.