Get SpatialOS

Sites

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

How to upgrade Unreal projects to SpatialOS 11.1

This page explains how to upgrade a project from SpatialOS 11.0.2 to 11.1. You only need to follow this guide if your project uses the Unreal SDK.

Background

The project setup you need to use the Unreal SDK has been significantly simplified in 11.1. For example, you no longer need to patch the Unreal engine to be able to cross-compile and run the Linux UnrealWorker.

This upgrade guide will take you through moving your project to use the new, simplified setup.

Other changes: The spatial worker build target flags have changed. development is now called local and production is snow called cloud. For example: spatial worker build UnrealWorker --target=local

Upgrading

1. Upgrade your SpatialOS SDK version

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.

Note: Replace any occurences of <PROJECT_NAME> in the examples below with the literal name of your project.

  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 11.1.0.
  5. Replace all other instances of the version number in the file.
  6. Manually remove the following files and directories
    1. Game\Source\<PROJECT_NAME>\Improbable
    2. Game\Source\<PROJECT_NAME>\SpatialOs
    3. Game\Source\<PROJECT_NAME>\SpatialOsModule.build.cs
    4. Game\spatialos.unreal.worker.build.json
    5. Game\spatialos.unreal.client.build.json

2. Update Unreal Engine

Note: It is recommended to use Unreal Engine 4.16.3 with SpatialOS 11.1.0, however we do also support using Unreal Engine 4.15.1. Some steps below are different depending on your Unreal Engine version.

  1. Install/upgrade Unreal Engine to 4.16.3-release by following EPIC’s install guide.
  2. Set up Linux cross-compilation tools by following the EPIC’s setup guide for UnrealEngine 4.16.
  3. Set your UNREAL_HOME environment variable to point to Unreal Engine 4.16.3 directory.
  4. Follow EPIC’s getting up and running guide to set up and compile the engine.

3. Update your project

In SpatialOS 11.1, you no longer need to maintain custom spatialos.unreal.*.build.json files, or build and cook Win64 Client/Server in order to test locally.

  • Update your spatialos.UnrealWorker.worker.json:

    1. Change the “build” section to:

      "build": {
          "tasks_filename": "Game/Intermediate/Improbable/spatialos.unreal.worker.build.json",
          "generated_build_scripts_type": "unreal"
      }
      
    2. Change the “managed” / “windows” section to:

      "managed": {
          "windows": {
              "artifact_name": "UnrealEditor@Windows.zip",
              "command": "StartServer.bat",
              "arguments": [
                  "-server",
                  "-stdout",
                  "-nowrite",
                  "-unattended",
                  "-nologtimes",
                  "-nopause",
                  "-messaging",
                  "-SaveToUserDir",
                  "+appName",
                  "${IMPROBABLE_PROJECT_NAME}",
                  "+receptionistIp",
                  "${IMPROBABLE_RECEPTIONIST_HOST}",
                  "+receptionistPort",
                  "${IMPROBABLE_RECEPTIONIST_PORT}",
                  "+workerType",
                  "${IMPROBABLE_WORKER_NAME}",
                  "+workerId",
                  "${IMPROBABLE_WORKER_ID}",
                  "+linkProtocol",
                  "RakNet",
                  "log=${IMPROBABLE_LOG_FILE}"
              ]
          },
      
    3. Change the “external” / “default” section to:

      "external": {
          "default": {
              "run_type": "EXECUTABLE",
              "windows": {
                  "command": "${UNREAL_HOME}\\Engine\\Binaries\\Win64\\UE4Editor.exe",
                  "arguments": [
                      "${IMPROBABLE_WORKER_DIR}/Game/<PROJECT_NAME>.uproject",
                      "-server",
                      "-stdout",
                      "-nowrite",
                      "-unattended",
                      "-nologtimes",
                      "-nopause",
                      "-messaging",
                      "-SaveToUserDir",
                      "+workerType",
                      "UnrealWorker",
                      "log=UnrealWorker.log"
                  ]
              }
      
    4. Update the Linux worker argument:

      The second argument in the argument list for Linux managed workers was previously <PROJECT_NAME>Server. This should now be updated to be only <PROJECT_NAME>. Like the example below:

      "linux": {
        "artifact_name": "UnrealWorker@Linux.zip",
        "command": "StartServer.sh",
        "arguments": [
           "${IMPROBABLE_WORKER_ID}",
           "<PROJECT_NAME>",
           "+appName",
           "${IMPROBABLE_PROJECT_NAME}",
           "+receptionistIp",
           "${IMPROBABLE_RECEPTIONIST_HOST}",
           "+receptionistPort",
           "${IMPROBABLE_RECEPTIONIST_PORT}",
           "+workerType",
           "${IMPROBABLE_WORKER_NAME}",
           "+workerId",
           "${IMPROBABLE_WORKER_ID}",
           "+linkProtocol",
           "RakNet"
        ]
      }
      
    5. Update your spatialos.UnrealClient.worker.json:

    6. Change the “build” section to:

      "build": {
          "tasks_filename": "Game/Intermediate/Improbable/spatialos.unreal.client.build.json",
          "generated_build_scripts_type": "unreal"
          },
      
    7. Change the “external” / “default” section to:

      "default": {
            "run_type": "EXECUTABLE",
            "windows": {
              "command": "${UNREAL_HOME}\\Engine\\Binaries\\Win64\\UE4Editor.exe",
              "arguments": [
                  "${IMPROBABLE_WORKER_DIR}/Game/<PROJECT_NAME>.uproject",
                  "-game",
                  "-stdout",
                  "+workerType",
                  "UnrealClient"
              ]
          }
      }
      
    • #### Update your *.Target.cs files:
    1. Update <PROJECT_NAME>.Target.cs:

      For Unreal Engine 4.16.3

      public class <PROJECT_NAME>Target : TargetRules
      {
          public <PROJECT_NAME>Target(TargetInfo Target) : base(Target)
          {
              Type = TargetType.Game;
              ExtraModuleNames.AddRange(new[] { "<PROJECT_NAME>" });
          }
      }
      

      For example, if your project name is RpgDemo it would look like:

      public class RpgDemoTarget : TargetRules
      {
          public RpgDemoTarget(TargetInfo Target) : base(Target)
          {
              Type = TargetType.Game;
              ExtraModuleNames.AddRange(new[] { "RpgDemo" });
          }
      }
      

      For Unreal Engine 4.15.1

      public class <PROJECT_NAME>Target : TargetRules
      {
          public <PROJECT_NAME>Target(TargetInfo Target)
          {
              Type = TargetType.Game;
          }
      
          public override void SetupBinaries(
              TargetInfo Target,
              ref List<UEBuildBinaryConfiguration> OutBuildBinaryConfigurations,
              ref List<string> OutExtraModuleNames
              )
          {
              OutExtraModuleNames.AddRange(new[] { "<PROJECT_NAME>" });
          }
      }
      
    2. Update <PROJECT_NAME>Editor.Target.cs:

      For Unreal Engine 4.16.3

      public class <PROJECT_NAME>EditorTarget : TargetRules
      {
          public <PROJECT_NAME>EditorTarget(TargetInfo Target) : base(Target)
          {
              Type = TargetType.Editor;
              ExtraModuleNames.AddRange(new[] { "<PROJECT_NAME>" });
          }
      }
      

      For Unreal Engine 4.15.1

      public class <PROJECT_NAME>EditorTarget : TargetRules
      {
          public <PROJECT_NAME>EditorTarget(TargetInfo Target)
          {
              Type = TargetType.Editor;
          }
      
          public override void SetupBinaries(
              TargetInfo Target,
              ref List<UEBuildBinaryConfiguration> OutBuildBinaryConfigurations,
              ref List<string> OutExtraModuleNames
              )
          {
              OutExtraModuleNames.AddRange(new[] { "<PROJECT_NAME>" });
          }
      }
      
    3. Update <PROJECT_NAME>Server.Target.cs:

      For Unreal Engine 4.16.3

      public class <PROJECT_NAME>ServerTarget : TargetRules
      {
          public <PROJECT_NAME>ServerTarget(TargetInfo Target) : base(Target)
          {
              Type = TargetType.Server;
              ExtraModuleNames.AddRange(new[] { "<PROJECT_NAME>" });
          }
      }
      

      For Unreal Engine 4.15.1

      public class <PROJECT_NAME>ServerTarget : TargetRules
      {
          public <PROJECT_NAME>ServerTarget(TargetInfo Target)
          {
              Type = TargetType.Server;
          }
      
          public override void SetupBinaries(
              TargetInfo Target,
              ref List<UEBuildBinaryConfiguration> OutBuildBinaryConfigurations,
              ref List<string> OutExtraModuleNames
              )
          {
              OutExtraModuleNames.AddRange(new [] { "<PROJECT_NAME>" });
          }
      }
      
    • #### Update your <PROJECT_NAME>.Build.cs file to add a dependency to SpatialOS, for example:

    For Unreal Engine 4.16.3

    public class <PROJECT_NAME> : ModuleRules
    {
        public <PROJECT_NAME>(ReadOnlyTargetRules Target) : base(Target)
        {
            PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "SpatialOS" });        
        }
    }
    

    For Unreal Engine 4.15.1

    public class <PROJECT_NAME> : ModuleRules
    {
        public <PROJECT_NAME>(TargetInfo Target)
        {
            PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "SpatialOS" });        
        }
    }
    
    • #### Update source control ignore:

    Add the following files to your .gitignore or .p4ignore inside the workers/unreal directory to remove them from source control:

    # Generated build files and sources
    Game/Intermediate/Improbable/spatialos.unreal.client.build.json
    Game/Intermediate/Improbable/spatialos.unreal.client.build.json
    Game/Intermediate/Improbable/spatialos_worker_packages.json
    Game/Source/SpatialOS/
    

    4. Update your code

    Update your include paths for generated code. For example, this:

    #include "Improbable/Generated/cpp/unreal/PositionComponent.h"
    

should now be:

#include "PositionComponent.h"

5. Update your Blueprints

SpatialOS classes and generated code have been moved to a new SpatialOS module. To move to the new layout:

  1. Run spatial worker codegen. This will generate a list of redirects to help migrate existing blueprints to the new project layout, found in Game/Source/SpatialOS/Generated/UClasses/SpatialOSRedirects.ini

  2. Add the contents of SpatialOSRedirects.ini in to Game/Config/DefaultEngine.ini.

  3. Open the Unreal Editor and make sure that your blueprints compile.

  4. In the Unreal Editor, right-click on any folders that contain blueprints and choose “Fix Up Redirectors”.

  5. Once you’ve resaved all of your blueprints, you can remove what you added to Game/Config/DefaultEngine.ini in the first step - the move should should now be complete.

The end

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

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