2 - Set up the fork and plugin
To use the SpatialOS GDK for Unreal, you first need to download and build the SpatialOS fork of Unreal Engine (UE). You will download and install the GDK for Unreal plugin.
Note: If you cloned an earlier version of the fork and plugin, the setup steps below may cause errors. See the Keep your GDK up to date for guidance on installing the latest versions.
Step 1: Join the Epic Games organization on GitHub
To get access to the SpatialOS Unreal Engine fork, you need to belong to the Epic Games organization on GitHub. If you haven’t already joined, you need to:
- connect your GitHub account to a verified Epic Games account,
- agree to the Unreal Engine End User License Agreement (EULA) and
- accept the invitation to join the Epic Games organization on GitHub.
To do this, see Unreal’s connect accounts documentation. It only takes a few minutes to set up and includes setting up a GitHub account if you don’t already have one. Note: You must follow this step to use the GDK. If you have not joined the Epic Games organization on GitHub, the SpatialOS Unreal Engine fork repository returns a GitHub 404 error and you can’t download it.
Step 2: Clone the fork repository
You can clone the fork repository using the command line, GitHub Desktop, or any third-party GUI for Git. This guide shows the process for the command line and GitHub Desktop.
Note: Third-party GUIs might ignore the default branch: ensure that you clone the latest stable version of the repository by selecting the branch marked default in the Branch dropdown of the SpatialOS Unreal Engine fork repository.
Image: The default branch you need to clone.
Using the command line
- Open a command line window and navigate to a suitable directory to clone the repository to.
- Run either of these commands to clone the example project repository:
Using Github Desktop
- In GitHub Desktop, select File > Clone Repository.
- In the Clone a repository window, select URL.
- In the Repository URL field, enter this URL:
- In the Local Path field, enter a suitable directory path for this repository, or select Choose… to select a directory using File Explorer.
- Select Clone.
Tip: Clone the Unreal Engine fork into your root directory to avoid file path length errors. For example:
Step 3: Add a new SSH key to your GitHub account
If you have not already configured your GitHub account to use an SSH key, you must do this in order to automatically download the GDK repositories as part of the next setup step.
To do this:
- Before you generate an SSH key, you can check to see if you have any existing SSH keys by following GitHub’s tutorial Checking for existing SSH keys.
- If you don’t have an existing key, then generate a new SSH key by following GitHub’s tutorial Adding a new SSH key to your GitHub account.
Step 4: Prepare the fork
To prepare the fork:
- Run Unreal’s
setup.batscript. This is part of Unreal’s UE set-up; it downloads binary content for UE, as well as installing prerequisites and setting up Unreal file associations. To do this: In File Explorer, navigate to the root directory of your clone of the SpatialOS Unreal Engine fork and double-click Setup.bat.
- Run Unreal’s
GenerateProjectFiles.batscript - also part of Unreal’s UE set-up. To do this: In the same directory, double-click GenerateProjectFiles.bat.
Step 5: Clone and install the plugin
You need to clone the SpatialOS GDK plugin and install it into the UE fork and Example Project directory. We recommend that you follow the auto-install method to reduce the number of manual steps needed to get set up. The auto-install installs the GDK as an Engine plugin so you won’t have to clone the GDK for each new project you set up.
There are two branches of the plugin repository and the Example Project: preview and release. We recommend installing from the default release branch of both. The auto-install does this for you, and the manual-install guides you to do this.
The preview branch
The preview branch contains features early in development. We do not recommend using the preview branch as it has had minimal testing and it has no documentation. You can find out more about the different branches in the Versioning scheme documentation.
Once you start working on a game project, we recommend that you update your checked-out branch every two weeks to pick up fixes and changes to the product. You can find out how to keep your branches up to date in the Keep your GDK up to date documentation. However, to follow this Get started guide, you can simply stay on the current release branch, and you don’t need to update your checked-out version of the branches.
Note: As part of auto-install, InstallGDK.bat checks out the release branch of both the plugin repository and Example Project repository. This is what you need now, as part of Get started but note that if you run the script to set up in the future, it will check out the current release branch, even if you have previously checked out the preview branch or checked out an older tagged version of the release branch.
Still in File Explorer, in the root directory of your clone of the SpatialOS Unreal Engine fork, double-click InstallGDK.bat. This process opens a command line window and runs some scripts - it can take a long time to complete. The command line window closes when the process has finished.
What does InstallGDK.bat do?
The script automatically opens a command line window and performs the following:
- Clones the release branch of the UnrealGDK into your UE fork’s
- Clones the release branch of the Example Project into your Engine’s
- Sets up the GDK for use with the Example Project by running
- Generates Visual Studio solution files for the
If you decide not to use the auto-install, you can manually install the GDK as a project plugin by running a set of scripts. Note that the manual-install sets up a project plugin and not an engine plugin, so you will need to run the steps again for each new project you set up.
For further details, see the guide on how to Manually build the SpatialOS Unreal Engine fork. You do not need to follow Step 6: Build the fork in Visual Studio, below.
Step 6: Build the fork in Visual Studio
Once you have followed the steps 1 - 5 on this page, you should have the following on your machine:
- An UnrealEngine fork repository branch ending with -SpatialOSUnrealGDK-release checked out.
- An UnrealGDK plugin repository release branch checked out.
- An UnrealGDKEXampleProject Example Project repository release branch checked out.
Note: You do not need to follow this step if you followed the manual-install instructions above.
Set up Visual Studio to build Unreal Engine; the build can take up to two hours.
- Still in the root directory of your clone of the SpatialOS Unreal Engine fork, double-click on UE4.sln to open it in Visual Studio.
- In Visual Studio’s toolbar, navigate to Build > Configuration Manager. Here, set your active solution configuration to Development Editor and your active solution platform to Win64.
- In Visual Studio’s Solution Explorer window, right-click on the UE4 project and select Set as StartUp Project.
- Still in the Solution Explorer window, right-click on the UE4 project and select Build. (Visual Studio might prompt you to install some dependencies first).
When the build is complete, you can continue to 3 - Set up a project.
> Next: 3 - Set up project
- Set up the Example Project The Example Project is a session-based FPS game. It gives an overview of the GDK and using SpatialOS, including deploying your game to SpatialOS locally and in the cloud.
- Set up the Starter Template Use as a base for creating your own project running on SpatialOS.
—— 2019-11-29 Page updated with editorial review: added note on repository branch selection. 2019-11-28 Page updated with editorial review: improve discussion of the plugin and example branches. 2019-09-27 Page updated without editorial review: clearer explanation of the auto-install flow. 2019-08-12 Page updated with editorial review: terminology and page formatting. 2019-08-08 Page updated with editorial review: added clarification on SSH key and Linux dependencies. 2019-05-30 Page updated with editorial review.