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 link returns a GitHub 404 error and you can’t download it.
Step 2: Clone the fork repository
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 in the UE fork and Example Project directory. You can follow either auto-install or manual-install, we recommend the auto-install.
Tip: Use auto-install as this makes setting up the Example Project and Starter Template quicker. You will be able to follow tutorials based on the Example Project more quickly. If you follow manual-install, you will need to take extra steps to set up the Example Project or Starer Template and follow tutorials.
Manual-install See the guide on how to Manually build the SpatialOS Unreal Engine fork guide. You do not need to follow Step 6: Build the fork in Visual Studio, below.
Auto-install (Recommended) To do this: 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.
The script automatically opens a command line window and performs the following:
- Clones the UnrealGDK into your EU fork’s
- Clones the Example Project (
UnrealGDKExampleProject) into your Engine’s
- Runs the GDK
Setup.batscript to install the plugin into the cloned
- Generates Visual Studio solution files for the
- Clones the UnrealGDK into your EU fork’s
Step 6: Build the fork in Visual Studio
Note: You do not need to follow this step if you followed the manual-install instructions.
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-08-12 Page updated with editorial review: teminology 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.