Get started

3 - Set up a project: The Starter Template

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


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

1: 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.

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.

2: 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\...

3: 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.

4: Deploy your project

To test your game, you need to launch a deployment. This means launching your game with its own instance of the SpatialOS Runtime, either locally using a local deployment, or in the cloud using a cloud deployment.

When you launch a deployment, SpatialOS sets up the world based on a snapshot, and then starts up the worker instances needed to run the game world.

5: Deploy locally with multiple clients

Before you launch a deployment (local or cloud) you must generate schema and a snapshot.

  1. In the Editor, on the GDK Toolbar, open the Schema drop-down menu and select Schema (Full Scan).
    Image: On the GDK toolbar in the Editor, select Schema (Full Scan)
  2. Select Snapshot to generate a snapshot.
    Image: On the GDK toolbar in the Unreal Editor, select Snapshot

To launch a local deployment:

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

    Want to debug your project?

    There is a known issue debugging local deployments using C++ or Blueprint breakpoints. For a workaround, follow these steps.

  2. On the Unreal Editor toolbar, open the Play drop-down menu.

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

  4. Under Modes, select New Editor Window (PIE).

  5. On the Unreal Engine toolbar, select Play to run the game, and you should see two clients start.

    Image: Two clients running in the Editor, with player Actors replicated by SpatialOS and the GDK

  6. Open the Inspector using the local URL you were given above: http://localhost:21000/inspector.
    You should see that a local SpatialOS deployment is running with one server-worker instance and two client-worker instances connected. You can also find and follow around the two player entities.

    Image: The Inspector showing the state of your local deployment

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

TIP: Check out the local deployment workflow page for a reference diagram of this workflow.

6: Launch a cloud deployment

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

Note: You must close the Unreal Editor before building your workers. If the Editor is open when you try to build your workers the command will fail.

Note: Unreal GDK projects default to using Spatial for networking. However, if the bSpatialNetworking option is present in your DefaultGame.ini configuration file (located in <ProjectRoot>\Game\Config directory), ensure that it is set to True (as in, bSpatialNetworking=True) to enable networking with Spatial for your cloud deployment.

There are two ways to build your worker assemblies (known as “building workers”):

  • Build your workers automatically using the BuildProject.bat script.
    This script automatically builds both the server-workers and client-workers required to run your game in the cloud. It then compresses your workers and saves them as .zip files to the <ProjectRoot>\spatial\build\assembly\worker directory. Use this script if you want to build server-workers and client-workers at the same time.

  • Build your workers manually using the command line.
    Use the SpatialOS CLI command line to build server-workers and client-workers separately, or to use command-line arguments to build different worker configurations for different purposes.
    For example:

    • Editor to build server-workers to run on local machine for testing.
    • Linux to build server-workers to run on SpatialOS cloud servers.


Step 3: Upload your workers

Before launching a cloud deployment, you must upload your sever-worker and client-worker assemblies to the cloud. To do this:

  1. In a terminal window, navigate to your <ProjectRoot>\spatial\ directory
  2. Run the following command: spatial cloud upload <assembly_name>

You must replace <assembly_name> with a name for your assembly (for example: gdktemplateassembly).

A valid upload command looks like this:

spatial cloud upload myassembly

Step 4: Launch your cloud deployment

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

When launching a cloud deployment you must provide four parameters:

  • The snapshot file - defines the starting state of the game world
  • The assembly name - identifies which workers to use for your deployment.
  • A launch configuration file - defines the SpatialOS game world and load balancing configuration.
  • A name for your deployment - labels the deployment in the Console.
  1. In a terminal window, navigate to <ProjectRoot>\spatial\ and run the following command

    spatial cloud launch --snapshot=snapshots\default.snapshot <assembly_name> one_worker_test.json <deployment_name>


  • default.snapshot is the snapshot file we have provided for this Example project.
  •  assembly_name is the name you gave the assembly in the previous step.
  • one_worker_test.json is the launch configuration file we provided with the GDK Template
  •  deployment_name is a name of your choice - you create this name when you run this command.

A valid launch command looks like this:

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

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

TIP: Check out the cloud deployment workflow page for a reference diagram of this workflow.


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 the detailed porting guide to get it onto the GDK.

2019-07-02 Page updated with limited editorial review: added debug workaround

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums