Get SpatialOS



Get started: 3 - Set up the SpatialOS GDK Starter Template

Before setting up the SpatialOS GDK Starter Template, you need to have followed:

If you are ready to start developing your own game with the GDK, follow the steps below.

Terms used on this page

  • <GameRoot> - The directory that contains your project’s .uproject file and Source folder.
  • <ProjectRoot> - The directory that contains your <GameRoot> directory.
  • <YourProject> - The name of your project and .uproject file (for example, \<GameRoot>\YourProject.uproject).

Create a new project using the Starter Template

After building the Unreal Engine fork, in File Explorer, navigate to UnrealEngine\Engine\Binaries\Win64and double-click UE4Editor.exe to open the Unreal Editor.

  1. In the Project Browser window, select the New Project tab and then the C++ tab.
  2. In this tab, select SpatialOS GDK Starter.
  3. In the Folder field, choose a suitable directory for your project.
  4. In the Name field, enter a project name of your choice.
  5. Select Create Project.

Note: When you create a project, the Unreal Engine automatically creates a directory named after the project name you entered. This page uses <YourProject> as an example project name.

The Unreal Engine Project Browser

Image: The Unreal Engine Project Browser, with the project file path and project name highlighted.

After you have selected Create Project, the Unreal Engine generates the necessary project files and directories, it then closes the Editor and automatically opens Visual Studio.

After Visual Studio has opened, save your solution then close Visual Studio before proceeding to the Clone the GDK step.

Clone the GDK

Now you need to clone the SpatialOS GDK for Unreal into your project. To do this:

  1. In File Explorer, navigate to the <GameRoot> directory and create a Plugins folder in this directory.
  2. In a Git Bash terminal window, navigate to <GameRoot>\Plugins and clone the GDK for Unreal repository by running either:
    • (HTTPS) git clone
    • (SSH) git clone

The GDK’s default branch (GitHub documentation) is release. This means that, at any point during the development of your game, you can get the latest release of the GDK by running git pull inside the UnrealGDK directory. When you pull the latest changes, you must also run git pull inside the UnrealEngine directory, so that your GDK and your Unreal Engine fork remain in sync.

Note: You need to ensure that the root directory of the GDK for Unreal repository is called UnrealGDK so the file path is: <GameRoot>\Plugins\UnrealGDK\...

Build the dependencies

To use the Starter Template, you must build the GDK for Unreal module dependencies and then add the GDK to your project. To do this:

  1. Open File Explorer, navigate to the root directory of the GDK for Unreal repository (<GameRoot>\Plugins\UnrealGDK\...), and double-click Setup.bat. If you haven’t already signed into your SpatialOS account, the SpatialOS developer website may prompt you to sign in.
  2. In File Explorer, navigate to your <GameRoot> directory, right-click <YourProject>.uproject and select Generate Visual Studio Project files.
  3. In the same directory, double-click <YourProject>.sln to open it with Visual Studio.
  4. In the Solution Explorer window, right-click on <YourProject> and select Build.
  5. When Visual Studio has finished building your project, right-click on <YourProject> and select Set as StartUp Project.
  6. Press F5 on your keyboard or select Local Windows Debugger in the Visual Studio toolbar to open your project in the Unreal Editor.
    Visual Studio toolbar
    Image: The Visual Studio toolbar

Note: Ensure that your Visual Studio Solution Configuration is set to Development Editor.

Deploy your project

To test your project, you can launch a local deployment (SpatialOS documentation) or a cloud deployment (SpatialOS documentation).

Deploy locally with multiple clients

To launch a local deployment:

  1. In the Unreal Editor, on the GDK toolbar, select Schema to generate schema.
    Image: On the GDK toolbar in the Unreal Editor select Schema
  2. Select Snapshot to generate a snapshot.
    Image: On the GDK toolbar in the Unreal Editor select Snapshot
  3. Select Start. This opens a terminal window and starts a local SpatialOS deployment. Wait until you see the output SpatialOS ready. Access the inspector at http://localhost:21000/inspector in your terminal window.
    Image: On the GDK toolbar in the Unreal Editor select Start
  4. On the Unreal Editor toolbar, open the Play drop-down menu.
  5. Under Modes, select New Editor Window (PIE).
  6. Under Multiplayer Options, set the number of players to 2 and ensure that the check box next to Run Dedicated Server is checked. (If it is unchecked, select the checkbox to enable it.)

    Image: The Unreal Engine Play drop-down menu, with Multiplayer Options and New Editor Window (PIE) highlighted
  7. On the Unreal Engine toolbar, select Play to run the game.
  8. When you’re done, select Stop in the GDK toolbar to stop your local SpatialOS deployment.
    Image: On the GDK toolbar in the Unreal Editor select Stop

If you want to run multiple server-workers in the Editor, see the Toolbar documentation for details on launching multiple PIE server-workers.

Deploy in the cloud

To launch a cloud deployment, you need to prepare your server-worker and client-worker assemblies, and upload them to the cloud.

TIP: Building the assemblies can take a while - we recommend installing IncrediBuild to speed up build times.

Step 1: Set up your SpatialOS project name.

When you signed up for SpatialOS, your account was automatically associated with an organisation and a project, both of which have the same generated name.

  1. Find this name by going to the Console (SpatialOS Documentation). The name should look something like beta_randomword_anotherword_randomnumber. In the example below, it’s beta_yankee_hawaii_621.
    Image: The SpatialOS Console with a project name highlighted.
  2. In File Explorer, navigate to the <YourProject>/spatial directory and open the spatialos.json file in a text editor of your choice.
  3. Replace the name field with the project name shown in the Console. This tells SpatialOS which SpatialOS project you intend to upload to.
Step 2: Build your worker assemblies

An assembly is what’s created when you run BuildWorker.bat. Assemblies are .zip files that contain all the files that your game uses when running in the cloud.

Note: In the following commands, you must replace <YourProject> with the name of your project.

  1. In a terminal window, navigate to your <ProjectRoot> directory.
  2. Build a server-worker assembly by running the following command: Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject>Server Linux Development <YourProject>.uproject
  3. Build a client-worker assembly by running the following command: Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject> Win64 Development <YourProject>.uproject

Upload your game

  1. In a terminal window, navigate to your <ProjectRoot>\spatial\ directory and run the following command: spatial cloud upload <assembly_name>
    Where <assembly_name> is a name of your choice (for example myassembly).

A valid upload command looks like this:

spatial cloud upload myassembly

Launch a cloud deployment

The next step is to launch a cloud deployment using the assembly that you just uploaded. You can only do this through the SpatialOS command-line interface (also known as the spatial CLI.

When launching a cloud deployment you must provide three parameters:

  • the assembly name, which identifies the worker assemblies to use.
  • a launch configuration, which declares the world and load balancing configuration.
  • a name for your deployment, which labels the deployment in the Console.
  1. In a terminal window, navigate to <ProjectRoot>\spatial\ and run: spatial cloud launch --snapshot=snapshots/default.snapshot <assembly_name> two_worker_test.json <deployment_name>
    where assembly_name is the name you gave the assembly in the previous step and deployment_name is a name of your choice. A valid launch command would look like this:

    spatial cloud launch --snapshot=snapshots/default.snapshot myassembly two_worker_test.json mydeployment

Note: This command defaults to deploying to clusters located in the US. If you’re in Europe, add the --cluster_region=eu flag for lower latency.

Play your game

Image: The SpatialOS Console

When your deployment has launched, SpatialOS automatically opens the Console in your browser.

In the Console, Select Launch on the left of the page, and then select the Launch button that appears in the centre of the page to open the SpatialOS Launcher. The Launcher automatically downloads the game client for this deployment and runs it on your local machine.

Image: The SpatialOS console launch window

Note: You install the SpatialOS Launcher during Getting started: 1 - Dependencies.


You’ve successfully set up and launched the Starter Template and the GDK! You are now ready to start developing a game with SpatialOS.

If you have an existing Unreal multiplayer project, follow our detailed porting guide to get it onto the GDK.

2019-04-02 Page updated with limited editorial review

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums