These are the docs for 12.1, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

How to upgrade Unreal projects to SpatialOS 12.1

This page explains how to upgrade a project from SpatialOS 12.0 to 12.1.

You only need to follow this guide if your project uses the Unreal SDK. Otherwise, you can just follow the Upgrading to minor or patch versions guide to upgrade to 12.1.


SpatialOS projects are developed against a specific version of the SpatialOS SDK. The SDK version your project builds against is defined in the spatialos.json file at the root of the project, in the sdk_version field.


1. Upgrade your SpatialOS SDK 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 12.1.1.
  5. Replace all other instances of the version number in the file.

2. Upgrade your Unreal project

2.1. (optional) Add SpatialOS as an Unreal module

In order to load the SpatialOS library and take advantage of running multiple workers from the Unreal Editor, you need to add the SpatialOS module to your project’s .uproject file.

For example,

"Modules": [
        "Name": "RpgDemo",
        "Type": "Runtime",
        "LoadingPhase": "Default",
        "AdditionalDependencies": [
        "Name": "SpatialOS",
        "Type": "Runtime",
        "LoadingPhase": "Default"

2.2. (optional) Change the way you trigger events

In SpatialOS 12.1, there’s a new way to trigger events, which works like Unreal Engine’s RPC functions. For each event, we now generate a dedicated event trigger function that you use to initiate the event on the owning component. You no longer have to go through the component update object to create an event.

The old method of triggering events is now deprecated, and will be removed in an upcoming release. We recommend you move to using the new way of triggering events.

For documentation on how to use the new way, see triggering an event.

2.3. (optional) Change the way you send manual component updates

Previously, if you wanted to send a manual component update, you still had to construct an update object (e.g. UExampleComponentUpdate) and pass it to SendComponentUpdate(). From 12.1, you can directly set the property you would like to change (like you would with an automatic update), and then call TriggerManualComponentUpdate on the component:

fooComponent->Bar = bar;

The old method of sending manual component updates is now deprecated, and will be removed in an upcoming release. We recommend moving to the new method

See the manual state replication guide for more details.

3. (optional) Deprecations

We recommend looking at the deprecation release notes and upgrading to the new APIs.

The end

You’ve now upgraded to SpatialOS 12.1.1. 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