Get SpatialOS



Next steps: Set up the GDK with the Starter Project

Before starting this, you need to have followed:

This step has three parts; clone the repositories, build the dependencies and deploy the game. You can deploy locally on your development machine and in the cloud.

Clone the repositories

Now, you are going to clone the Starter Project repository and then clone the GDK repository into your copy of the Starter Project. Note that the GDK needs to go into the Starter Project’s Plugins directory.

  1. Clone the Starter Project repository by running either:
    • (HTTPS) git clone
    • (SSH) git clone
  2. Navigate into <StarterProjectRepoRoot>\Game\ and create a Plugins folder.
  3. In a Git Bash terminal window, navigate to <StarterProjectRepoRoot>\Game\Plugins and clone the GDK for Unreal repository by running either:
    • (HTTPS) git clone
    • (SSH) git clone

Note You need to ensure that the root folder of the GDK for Unreal repository is called UnrealGDK so its path is: <StarterProjectRepoRoot>\Game\Plugins\UnrealGDK\...

Build dependencies

In this step, you’re going to build the GDK for Unreal module dependencies, which the Starter Project needs to work with the GDK. You are then going to add the GDK for Unreal to the Starter Project.

  1. Open File Explorer, navigate to the root directory of the GDK for Unreal repository, and double-click Setup.bat. You may be prompted to sign into your SpatialOS account if you have not already.
  2. Set the Starter Project to work with the Unreal Engine fork you cloned and installed earlier. To do this:
    1. In File Explorer, navigate to the root directory of the GDK for Unreal Starter Project repository, and then to the Game directory within it.
    2. Right-click StarterProject.uproject and select Switch Unreal Engine version.
    3. Select the path to the Unreal Engine fork you cloned earlier.
  3. In the same directory, open StarterProject.sln with Visual Studio.
  4. In the Solution Explorer window, right-click on StarterProject and select Build.
  5. Open StarterProject.uproject in the Unreal Editor



Deploy the Starter Project

Deploy locally

  1. In the Unreal Editor, on the SpatialOS GDK toolbar, click Start. Wait until you see the output SpatialOS ready. Access the inspector at http://localhost:21000/inspector.
  2. On the Unreal Editor toolbar, open the Play drop-down menu.
  3. Under Multiplayer Options, enter the number of players as 2 and check the box next to Run Dedicated Server. Then, under Modes, select New Editor Window (PIE).
  4. On the toolbar, click Play to run the game.
  5. When you’re done, click Stop to stop the client-workers and server-workers, and click the Stop button in the SpatialOS section of the toolbar to stop your local SpatialOS deployment.

If you would like to run multiple server-workers in editor, see the Toolbar documentation regarding launching multiple PIE server-workers

Deploy in the cloud

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

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

  1. Change the name of the project
    1. In File Explorer, navigate to the root directory of the Starter Project repository, then to spatial, and open the spatialos.json file in an editor of your choice.
    2. Change the name field to the name of your project. You can find this in the Console. It’ll be something like beta_someword_anotherword_000.
  2. In a terminal window, navigate to the root directory of the Starter Project repository.
  3. Build a server-worker assembly: Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat StarterProjectServer Linux Development StarterProject.uproject
  4. Build a client-worker assembly: Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat StarterProject Win64 Development StarterProject.uproject
  5. Navigate to StarterProject/spatial.
  6. Upload the assemblies to the cloud, specifying an assembly name (this includes both client-worker and server-worker assemblies): spatial cloud upload <assembly_name>
  7. Launch a deployment, specifying a deployment name: spatial cloud launch <assembly_name> one_worker_test.json <deployment_name> --snapshot=snapshots\default.snapshot
  8. On your deployment’s page in the SpatialOS Web Console click Play to launch the game.


You’ve successfully set up and launched the Starter Project and the GDK! If you haven’t already, we recommend following our Multiserver Shooter tutorial where you can try out the GDK’s development experience by adding a new feature to a project, and test it across two servers.

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

You are now ready to add multiserver functionality on top of the Starter Project. Check out the documentation on cross-server RPCs, handover and Singleton Actors.

We will be releasing more tutorials and examples as the GDK matures. Stay tuned!

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums