Get SpatialOS



The SpatialOS Unreal integration is currently in beta. We're very open to feedback - don't hesitate to get in touch on the forums if you have any thoughts.

Setting up an Unreal SDK project

To set up the Unreal SDK and run your first Unreal project, you need to:

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

You don’t need to install Unreal Engine, as this guide will take you through compiling it from source.

1. Set up your machine

To develop a project that uses the Unreal SDK, you’ll need:

2. Get the Unreal Engine source

To use the SDK, 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.16.3-release branch. This can be done in a shell by running either:

    • via HTTPS: git clone -b 4.16.3-release
    • via SSH: git clone -b 4.16.3-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. This should output the path to the directory you cloned into above. For example, D:\Work\UnrealEngine.

3. Build the Unreal Engine

To build Unreal workers for SpatialOS deployments, you need to build targeting Linux, which requires cross-compilation of your SpatialOS project and Unreal Engine.

Note: Building Unreal Engine from source could take up to a few hours. Just so you know!

  1. Follow the compiling for Linux setup guide for UnrealEngine 4.16, installing the Linux-x86_64 cross compile toolchain. You don’t need to follow the “Packaging for Linux” section.
  2. After following the Linux setup instructions, restart your terminal and run echo $LINUX_MULTIARCH_ROOT to make sure that the new environment variable is registered. This should output the path to the clang v8 directory that you installed in step 1.
  3. Navigate to the directory you cloned the Unreal Engine source code into. For example, D:\Work\UnrealEngine.
  4. In this folder, run the batch file Setup.bat.

    This will install prerequisites for building Unreal Engine 4.

  5. 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.

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

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

  7. Open UE4.sln in Visual Studio 2015.

  8. In the Build > Configuration Manager window, set your solution configuration to Development Editor and your solution platform to Win64.

  9. In the Solution Explorer, right-click on the UE4 target and select Build (you may be prompted to install some dependencies first).

    UE4 target

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

  10. Once the build succeeds, search for Automation Tool project in the solution explorer, right-click it and click Build.

You have now built UnrealEngine 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.

4. Build the project

For starters, you’ll need a SpatialOS project. Check out the UnrealStarterProject if you don’t have one yet. Next, you need to build the project itself. To do this:

If you are not using one of our starter projects, you have to add "SpatialOS" to your PublicDependencyModuleNames in your Build.cs file. This will set up your include paths next time you generate VS project files.

  1. Open a terminal, navigate to the root folder of your project and run spatial worker codegen.
  2. Locate the Unreal project file for your project. This can be found in PROJECT_ROOT/workers/unreal/Game.
  3. Right-click on your project’s .uproject file and select Switch Unreal Engine version:
  4. Switch engine versions to the source-built version you just built.
  5. Run spatial worker build. This may take an hour or more.

This will build an assembly used for both local and cloud SpatialOS deployments.

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

If you open your project with another version of Unreal Engine, it will rebuild the entire project.

5. 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 your SpatialOS 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 that was built when you built the project earlier. <assembly name> is a label that you can choose for this assembly, for example my_unreal_project_1.
  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