Get SpatialOS



Manual setup guide for Windows

Note: For a simpler setup experience, try the SpatialOS setup guide that uses Chocolatey.

This guide will prepare your Windows machine for local development with the SpatialOS SDK.

1. System requirements

We support up-to-date versions of Windows 7 and 10.

Before following the setup guide check that your machine meets the hardware requirements.

2. Set up the SpatialOS CLI

To set up the SpatialOS CLI (spatial):

  1. Download spatial for Windows (64bit): Download.

    By downloading spatial, you agree to the SpatialOS EULA.

  2. Put spatial.exe in a directory where you have administrator privileges.

  3. Add the directory containing spatial.exe to your PATH by following these instructions.

  4. Check this succeeded by running spatial update in your terminal. You should get the output:

    Current version of the 'spatial' command-line tool: <version number>

    Attempting to download the latest version...

3. Set up external development tools

You need some external software in order to develop a SpatialOS application.

3.1. Java Runtime Environment (JRE)

Download and install the 64-bit JRE 8 for Windows. You’ll need to install the 1.8.0_65 version or newer.

We don’t support Java 9 yet.

Check it worked by running in a terminal: java -version

Expected output: java version "1.8.0_x"

3.2. Visual C++ Redistributable for Visual Studio 2015

If you haven’t got it installed already, download and install Visual C++ Redistributable for Visual Studio 2015.

3.3. (optional) Unity

To use the Unity SDK, even if you’ve already got Unity installed, you must follow these steps, because SpatialOS only supports specific versions of Unity, and requires specific build support.

Unity versions 5.5.3 and 5.6.0 have been tested with SpatialOS. Later versions may work fine, but have not been extensively tested.

  1. Go to the Unity Download Archive.
  2. Next to version 5.6.0, from the “Downloads (Win)” dropdown, click “Unity Installer” (which downloads the installer).
  3. Run the installer.

    • If you already have Unity 5.6.0 installed:

      Select Linux Build Support and Mac Build Support. De-select all the other checkboxes:

      Unity screenshot

    • If you have another version of Unity, or don’t have it installed at all:

      IMPORTANT: In addition to the defaults, select Linux Build Support and Mac Build Support:

      Unity screenshot

  4. Install Unity into the default installation directory: %PROGRAMFILES%\Unity.

    Alternatively, you can set the environment variable UNITY_HOME to your customized Unity installation folder. For example, if you installed Unity to C:\Unity 5.6.0, then set UNITY_HOME to C:\Unity 5.6.0.

  5. Launch Unity and complete the registration process.

3.4. (optional) Unreal

To use the Unreal SDK, you must build the Unreal engine from source:

3.4.1. Install dependencies

  1. In a terminal, run the following command to install JRE and MSVC Redistributable (required for working with SpatialOS):

    spatial setup install-dependencies --sdk-version=12.0.4 [<flags>...]

    By running this command you agree with the individual terms of each separate dependency.

    Run spatial setup install-dependencies --sdk-version=12.0.4 --help for more information.

  2. Restart your computer to complete the install process.

  3. If you don’t have it already, install Visual Studio 2015.

  4. If you don’t have it already, install the Windows SDK 8.1.

3.4.2. Get the Unreal Engine source

To use the Unreal 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 by running either of these commands in a Git bash terminal:

    • 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 system 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 $env:UNREAL_HOME (PowerShell) or echo %UNREAL_HOME% (cmd) 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.4.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 the previous step.
  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. (optional) Install the launcher

If you want to run a game client to connect to a SpatialOS game running in the cloud, you must install the Launcher.

  1. Download the Launcher.
  2. Follow the instructions in the installation wizard.

5. Next steps

You’ve now set up your machine for development with SpatialOS!

Recommended: To learn how to use SpatialOS and experiment with its main APIs, try our tutorials:

If you’d just like to find out about what SpatialOS is:

To get started building something of your own, go to and use one of the repositories there as a starting point.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums