These are the docs for 14.3, an old version of SpatialOS. 14.5 is the newest →

How to upgrade to SpatialOS 14

This page explains how to upgrade a project from SpatialOS 13 to 14.

Note: This is a guide for upgrading to the new major version, SpatialOS 14. To upgrade to minor and patch versions, follow the minor and patch version upgrade guide instead.


SpatialOS projects are developed 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.json file at the root of the project, in the sdk_version field.
  • 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 get directly.

You must upgrade through major SDK versions in order. For example, to upgrade from 12 to 14, you must first upgrade to the latest minor of 13, then to the latest minor of 14. To find upgrade guides for older versions, look at the documentation for that version of SpatialOS.

Upgrade process

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 14 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 14 version (for example: 14.0.0).

2. Address major API breaking changes

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!

The end

You’ve now upgraded to SpatialOS 14. Great! Take a look at the release notes to learn more about what’s new.

Let us know how the upgrade went on the SpatialOS forums!

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums