Tutorials and guides

Port your project to SpatialOS

Please be aware of the GDK’s support level of different Unreal features. If you need to port your game, please contact us via our forums, or Discord so we can best support you.

This guide shows you how to port your own Unreal project to the GDK. By the end of this guide, your game will run on a single server-worker on SpatialOS.

Get to know the GDK before porting your game
We recommend following steps 1 to 3 of the Get started guide and setting up the Example Project before porting your project. This gives you an overview of the GDK and using SpatialOS.

Tip: Reference project
As you port your own Unreal project to SpatialOS, you could use our pre-ported Unreal Shooter Game as a reference. You should already have this project as it is included in the Samples directory of the SpatialOS Unreal Engine fork which you downloaded as part of the Get started steps.
(If you want to see the game running, there’s a video on youtube to check out.)

Terms used in this guide
* <GameRoot> - The directory containing your project’s .uproject file and Source directory.
* <ProjectRoot> - The directory containing your <GameRoot>.
* <YourProject> - The name of your project’s .uproject file (for example, \<GameRoot>\TP_SpatialGDK.uproject).

1. Before you start

Before porting your project:

2. Set up the project structure

  1. Create a new empty directory to represent your <ProjectRoot> and move your <GameRoot> directory inside of it.

    Your project structure should be: \<ProjectRoot>\<GameRoot>\<YourProject>.uproject

    For example: \MyProject\Game\TP_SpatialGDK.uproject

  2. Your project needs some extra files and folders to run with the GDK. Copy these files from the template project that you set up earlier in the Before you start section.

    To do this: either in a terminal window or your file manager, navigate to the root of the StarterTemplate repository and copy all of the files and directories below to your <ProjectRoot>:


    Your project’s directory structure should now resemble:


    Note: You must place the spatial directory in the directory above your <GameRoot>.

  3. You need to configure the GDK helper scripts to work with your project.

Follow this step to set up your project paths:

  • Open \<ProjectRoot>\ProjectPaths.bat in a text editor.

    * In `set PROJECT_PATH=Game`, replace `Game` with your `<GameRoot>` folder name.  
    * In `set GAME_NAME= TP_SpatialGDK `, replace `TP_SpatialGDK ` with the name of your game's `.uproject` (`<YourProject>` [terms used in this guide](#terms-used-in-this-guide)).  

    Note: The helper scripts LaunchClient.bat and LaunchServer.bat will not work if you do not follow this step correctly.

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

      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. Run Setup.bat which is in the root directory of the GDK repository (this should be <ProjectRoot>\<GameRoot>\Plugins\UnrealGDK\). To do this either:

    • In a terminal window, navigate to the root directory of the GDK and run: Setup.bat or
    • In your file manager, double-click the Setup.bat file.

    Note:Setup.bat will automatically open the SpatialOS authorization page in your default browser. You may be prompted to sign into your SpatialOS account if you have not already.

4. Add the SpatialGDK module to your project

  1. In File Explorer, navigate to \<ProjectRoot>\<GameRoot>\Source\<YourProject>\.
  2. Open the <YourProject>.build.cs file in a code editor and add add "SpatialGDK" to PublicDependencyModuleNames.

    For example:

                new string[] {

    5. Build your project

    Set up your Unreal project to work with the GDK for Unreal fork of the Unreal Engine, which you cloned and installed in the Before you start section. To do this:

    1. In File Explorer, navigate to <ProjectRoot>\<GameRoot>.
    2. Right-click your <YourProject>.uproject file and select Switch Unreal Engine version.
    3. Select the path to the Unreal Engine fork you cloned earlier.
    4. In File Explorer, right-click <YourProject>.uproject and select Generate Visual Studio Project files. This automatically generates a Visual Studio solution file for your project called <YourProject.sln>
    5. In the same directory, double-click <YourProject>.sln to open it with Visual Studio.
    6. On the Visual Studio toolbar, set your Solution configuration to Development Editor.
      Visual studio toolbar
      Image: The Visual Studio toolbar, with the Development Editor Solution configuration highlighted in red.
    7. In the Solution Explorer window, right-click on <YourProject> and select Build.

    6. Modify Unreal classes for GDK compatibility

    You must modify your GameInstance class to work properly with the GDK.

    1. Make your GameInstance inherit from SpatialGameInstance.

    If you have not made a GameInstance for your game and are still using the default GameInstance, you must either create a Blueprint or a native GameInstance class now. Remember to configure your Project Settings to use this new GameInstance by default, under Project Settings > Project Maps and Modes > Game Instance > Game Instance Class.

    • If your game’s GameInstance is a C++ class, locate its header file and add the following #include: "SpatialGameInstance.h"

    For example:

    #include "CoreMinimal.h"
    #include "SpatialGameInstance.h"
    #include "YourProjectGameInstance.generated.h"

    Then, under UCLASS(), change the parent class from UGameInstance to USpatialGameInstance:

    For example:

    class YOURPROJECT_API UYourProjectGameInstance : public USpatialGameInstance
    • If your GameInstance is a Blueprint class, you need to open and edit it in the Blueprint Editor:
      • From the Blueprint Editor toolbar, navigate to the Class Settings. In Class Options set the Parent Class to SpatialGameInstance.

    spatial game instance reparent
    Image: The Blueprint class settings screen

    7. Generate schema and a snapshot

    You need to generate schema and generate a snapshot before you start your deployment. To do this:

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

    8. Launch your game

    1. Switch your game project to use the SpatialOS networking. To do this:
    • In the Unreal Editor, from the toolbar, open the Play drop-down menu and check two checkboxes:
    • Check the box for Run Dedicated Server
    • Check the box for Spatial Networking

    Image: The Unreal Engine launch settings drop-down menu

    You can increase the number of servers that you launch by changing the Number of servers value. Leave this value at 1 for now. This is because there is currently no multiserver logic in your code. After you have completed this guide you can start building multiserver game logic.

    1. On the GDK toolbar, select Start. This builds your worker configuration file and launches your game in a local deployment.

      Image: On the GDK toolbar in the Unreal Editor select Start

      Selecting Start opens a terminal window and runs two SpatialOS command line interface (CLI commands: spatial build build-config and spatial local launch. Your deployment has started when you see SpatialOS ready in the terminal window.

    2. On the main Unreal toolbar, select Play.
      Image: On the Unreal Engine toolbar Play

    3. From the SpatialOS GDK toolbar select Inspector, which opens a local SpatialOS Inspector in your default web browser. Here you can see the entities and their components present in your deployment.
      Image: On the GDK toolbar in the Unreal Editor select Inspector

    For running a local deployment with managed workers or a cloud deployment take a look at the glossary section for deployments

    You have now ported your Unreal game to run on SpatialOS. Move around and look at the changes reflected in the inspector.

    If you have encountered any problems please check out our troubleshooting and known-issues.


    You can find Spatial log files for your local deployments in <ProjectRoot>\spatial\logs\.

    • spatial_<datetime>.log contains all of the logs printed to your terminal during the local deployment.
    • There are also timestamped folders here which contain additional logs:
    • <ProjectRoot>\spatial\logs\workers\ contain managed worker logs which are the workers started by SpatialOS, specified in your launch configuration.
    • <ProjectRoot>\spatial\logs\runtime.log contains the logs printed by the SpatialOS Runtime. These are the services required for SpatialOS to run a local deployment.

    If you require additional debugging logs you can run spatial local launch with the flag --log_level=debug.

    Modify the default behavior

    You can modify some of the GDK settings from the Unreal Editor toolbar at Edit > Project Settings >SpatialOS Unreal GDK > Toolbar. You can change:

    • the snapshot file’s filename and location
    • the launch configuration

    Next steps:

    If you haven’t already, check out:

    Also check out the documentation on cross-server RPCs, handover and Singleton Actors.

    2019-06-27 Added Shooter Game as a reference project 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