Get SpatialOS


You are viewing the docs for 11.0, an old version of SpatialOS. 12.0 is the newest →

The SpatialOS Unreal integration is currently experimental. It's usable, but definitely has some sharp edges! We're very open to feedback - don't hesitate to get in touch on the forums if you have any thoughts.

Setting up the example project

The example SpatialOS project RPG demo uses the Unreal integration:

RPG demo

A basic example of how to create an project with RPG-esque controls using the SpatialOS integration for Unreal Engine 4. It demonstrates basic features such as component updates, sending commands and the blueprint integration.

To set it up, you need to:

  1. Set up your machine.
  2. Get the source.
  3. Build the project.
  4. Deploy the project, locally or in the cloud.

1. Set up your machine

To run the example project, you’ll need:

2. Get the source

To use the example project, you need to build the Unreal Engine 4 from source. To get the source and set it up to build:

  1. Check if you have access to the Unreal Engine 4 GitHub repository.

    If you don’t, follow these instructions to get access.

  2. Clone the repository and checkout the 4.15.1-release branch by running either:

    • via HTTPS: git clone -b 4.15.1-release
    • via SSH: git clone -b 4.15.1-release
  3. Navigate to the root of the cloned repo.

  4. Add a user environment variable (Control Panel > System and Security > System > Advanced system settings > Advanced > Environment variables) named UNREAL_HOME.

    The value should be the path to the directory you cloned into above. For example, D:\Work\UnrealEngine.

  5. Restart your terminal and run echo $UNREAL_HOME to make sure that the new environment variable is registered.

  6. Clone the RPG demo project from its repository into a folder of your choice. For example, D:\Work\RPGdemo.

3. Build the project for the first time

To build Unreal workers for SpatialOS deployments, you need to build targeting Linux, which requires cross-compilation of your SpatialOS project and Unreal Engine. To make this work, you’ll need to patch the Unreal Engine source code.

Patch Unreal Engine 4 with SpatialOS

Note: Building Unreal Engine from source often takes a few hours. Just so you know!

The RPG demo project contains a git patch, 0001-Make-linux-work-with-WorkerSdk.patch. This patch contains the required modifications to the 4.15.1 branch of Unreal Engine 4.

To apply the patch:

  1. cd to the directory you cloned the Unreal source into. For example, cd D:\Work\UnrealEngine.
  2. Apply the patch to the Unreal Engine source repository using the command

    git apply --ignore-space-change --ignore-whitespace <path to patch>

    For example: git apply --ignore-space-change --ignore-whitespace ../RpgDemo/0001-Make-linux-work-with-WorkerSdk.patch

  3. Download the Linux cross compile toolchain for Unreal Engine 4.

  4. Extract the contents to a folder of choice. For example, D:\Work.

  5. Add a user environment variable (Control Panel > System and Security > System > Advanced system settings > Advanced > Environment variables) named LINUX_MULTIARCH_ROOT.

    The value should be the path to the clang v8 directory containing the multiple Linux architecture directories, inside the directory you extracted the Linux toolchain to. For example, D:\Work\v8_clang-3.9.0-centos7.

  6. Restart your terminal and run echo $LINUX_MULTIARCH_ROOT to make sure that the new environment variable is registered.

  7. Navigate to the directory you cloned the Unreal Engine source code into. For example, D:\Work\UnrealEngine.

  8. In this folder, run the batch file Setup.bat.

    This will install prerequisites for building Unreal Engine 4.

  9. While running the batch file, you should see Checking dependencies (excluding Mac, Android).... If it says excluding Linux too, make sure that you set the environment variable LINUX_MULTIARCH_ROOT correctly, and run the batch file again.

  10. In the same directory, run the batch file GenerateProjectFiles.bat.

    This sets up the project files required to build Unreal Engine 4.

  11. Open UE4.sln in Visual Studio 2015.

  12. Set your solution configuration to Development Editor and your solution platform to Win64.

  13. Right-click on the UE4 target and select Build.

    This builds Unreal Engine, which can take a couple of hours.

  14. Once the build succeeds, right-click on the project Automation Tool in the solution explorer and click Build.

  15. Navigate to the root folder of your project.

  16. In this directory, open a terminal and run spatial worker codegen.

  17. Locate the Unreal project file for your project. For example, for the RPG demo, RpgDemo.uproject within the path RPG_DEMO_REPOSITORY_ROOT/workers/unreal/Game.

  18. Right-click on your project’s .uproject file and select Switch Unreal Engine version:

    Generate visual studio project files

  19. Switch engine versions to the source-built version you just built.

You have now applied the patch and built Unreal Engine 4 to support cross-compilation for Linux.

Warning: Once you’ve built the Unreal Engine, don’t move it into another directory: that will break the integration.

Build the project

Next, you need to build the project itself. To do this:

  1. In a terminal, cd to the root of the SpatialOS example project.
  2. Run spatial worker build.

This will build the packages required for both local and cloud SpatialOS deployments.

If you only want to deploy the project locally, you can run spatial worker build --target=development. Similarly, if you only want to deploy the project to the cloud, run spatial worker build --target=production.

4. Deploy the project

To run your project, deploy and run it on SpatialOS. You can run it as a local deployment, or in the cloud.

Deploying the project locally

To deploy locally:

  1. In a terminal, cd to the root of the SpatialOS example project.
  2. Run spatial local launch default_launch.json to start the local deployment.
  3. Open your Unreal project in the Unreal Editor.
  4. Press the ▷ Play button to join the game as a new player.

Deploying the project to the cloud

To deploy to the cloud:

  1. In the project’s root directory, open spatialos.json. Change the name field to your assigned SpatialOS project name.
  2. Run spatial cloud upload <assembly name> to upload the assembly you built earlier. <assembly name> is a label for the assembly.
  3. Run spatial cloud launch <assembly name> default_launch.json <deployment name> --snapshot=snapshots/default.snapshot.

    <deployment name> is a label for the deployment.

  4. If you don’t already have it, install the Improbable Launcher (Windows / Mac).

  5. Go to your console.

  6. Click on the deployment’s name.

  7. Launch a player client by clicking ▷ Launch.

What’s next?

See the rest of the documentation to learn how to:

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums