2. Set up the fork and plugin

Get started: 2 - Set up the fork and plugin

To use the GDK for Unreal, you first need to download and build the SpatialOS Unreal Engine fork (UE fork). This download includes the Starter Template, which is a sample project that you might use in later steps.

You then download and install the GDK plugin and the Example Project, which is another sample project that you will use in later steps

Note: If you have followed and completed 2: Set up the fork and plugin already, you might have downloaded an earlier version of the UE fork and GDK plugin. If so, the setup steps below may cause errors, so see Update your GDK for guidance on installing the latest versions and then go to 3. Set up a project.

Versions

The SpatialOS GDK for Unreal version 0.11.0 consists of:

  • GDK plugin version 0.11.0
  • Unreal Engine fork version 4.25
    We support Unreal Engine fork version 4.24 as a legacy version. See the versioning scheme for more information.

Step 1: Join the Epic Games organization on GitHub

To get access to the SpatialOS Unreal Engine fork (UE 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.

Image: GitHub 404 screenshot

Step 2: Clone the UE fork repository

To download the UE fork, you clone the latest branch of the UE fork’s Git repository. You can clone the UE fork repository’s latest branch 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.

TIP

Check your UE fork repository's branch is the correct one.

If you are using a third-party GUI for Git: 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.

TIP

Clone the UE fork into a directory that is as close to the root of your directory structure as possible. You need to do this to avoid file path length errors.

For example:

  • Windows: C:/Dev/UnrealEngine
  • macOS: /Users/<my-name>/UnrealEngine

Your location
The process you follow depends on where you are located: outside China or in China.

  • If you are located in China, use the in-China instructions.
  • Only use the in-China instructions if you are located in China, using hosting in China.
  • Note that in the documentation, "China" refers to mainland China only.

Outside China

1. Open a command-line window and navigate to a suitable directory to clone the repository to.
2. Run either of these commands to clone the repository:

HTTPS git clone https://github.com/improbableio/UnrealEngine.git
SSH git clone [email protected]:improbableio/UnrealEngine.git

Or

1. In GitHub Desktop, select File > Clone Repository.
2. In the Clone a repository window, select URL.
3. In the Repository URL field, enter this URL:
https://github.com/improbableio/UnrealEngine.git.
4. In the Local Path field, enter a suitable directory path for this repository, or select Choose… to select a directory using File Explorer.
5. Select Clone.


In China

Note: Only follow the in-China instructions if you are located in China, using hosting in China.

1. Open a command-line window and navigate to a suitable directory to clone the repository to.
2. Run either of these commands to clone the repository:

HTTPS git clone https://github.com/improbableio/UnrealEngine.git
SSH git clone [email protected]:improbableio/UnrealEngine.git

3. Update the repository’s remote URL to point to Improbable’s Unreal Engine fork:
cd UnrealEngine
git remote set-url origin [email protected]:improbableio/UnrealEngine.git
4. Update the repository and check out the release branch:
git pull
git checkout 4.25-SpatialOSUnrealGDK-release

Or

1. In GitHub Desktop, select File > Clone Repository.
2. In the Clone a repository window, select URL.
3. In the Repository URL field, enter this URL:
https://github.com/improbableio/UnrealEngine.git.
4. In the Local Path field, enter a suitable directory path for this repository, or select Choose… to select a directory using File Explorer.
5. Select Clone.
6. When the download is complete, go to Repository > Repository Settings.
7. In the Remote field, enter this URL:
https://github.com/Improbableio/UnrealEngine.git
The repository automatically updates from the new URL.
8. Select the Current branch drop-down and switch to the branch
origin/4.25-SpatialOSUnrealGDK-release


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 plugin repository as part of a later setup step.

To do this:

  1. 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.
  2. 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 UE fork on Windows or macOS, you need to run two scripts. The process is exactly the same for macOS and Windows, except for the script file names:


  1. Run Unreal's Setup.bat script.
    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:
    Go to the root directory of your clone of the UE fork and run Setup.bat. (Windows might prompt you to install some dependencies first.)
  2. Run Unreal's GenerateProjectFiles.bat script - also part of Unreal's UE set-up.
    To do this:
    In the same directory, run GenerateProjectFiles.bat.

  1. Run Unreal's Setup.sh script.
    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:
    Go to the root directory of your clone of the UE fork and run Setup.sh.
  2. Run Unreal's GenerateProjectFiles.sh script - also part of Unreal's UE set-up.
    To do this:
    In the same directory, run GenerateProjectFiles.sh.

If GenerateProjectFiles.sh fails with the following error message in the terminal window’s output log:

ERROR: Invalid SDK MacOSX.sdk, not found in /Library/Developer/CommandLineTools/Platforms/MacOSX.platform/Developer/SDKs

check you have installed the XCode CommandLine Tools (see 1. Get the dependencies: Step 3: Software for more details).

If you have already installed the XCode CommandLine Tools, the default file path for the Tools might be incorrect. This affects the commands you enter in the terminal window.

To reset the file path:
In the terminal window, from the same directory, run sudo xcode-select --reset to reset the file path.

Step 5: Clone and install the plugin

To download the SpatialOS GDK plugin, you clone the latest branch of its repository. You need to clone the plugin into the UE fork directory. The InstallGDK script clones and installs the plugin into your UE fork directory. This means the GDK is available for each new project you set up.

If you prefer to install the GDK as a project plugin and not an Unreal Engine plugin, you can clone it into your UE game project’s plugins directory, and not into the UE fork. Note that if you choose this, you will need to copy the GDK plugin into every UE game project you want to use with SpatialOS.

This Get Started guide and all other GDK documentation assume you have installed the GDK as an Unreal Engine plugin.

For further information on project plugins, see the Unreal documentation.

After you start working on a game project, we recommend that you update your cloned UE fork and GDK plugin repository branches 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, as you are following this Get started guide, you don’t need to update your clones of the branches.

Note: As part of your installation, the script, InstallGDK clones the correct repository branches you need for the GDK plugin. It also clones the correct repository branch for the Example Project, which is one of the sample projects you will use in later tutorials.

To clone the SpatialOS GDK plugin and install it:


  1. Go to the root directory of your clone of the UE fork. For example:
    C:/Dev/UnrealEngine

  2. From this directory, run InstallGDK.bat.
    This InstallGDK script clones the GDK plugin and installs it to the UE fork and Example Project directory (by default this is UnrealEngine/Samples/UnrealGDKExampleProject).

  3. The InstallGDK script asks you: Are you located in China?

    • If you are outside China: enter n at the prompt.
    • If you are in China: enter y at the prompt.
      (If you do not enter y, the script defaults to n.)
  4. The InstallGDK script asks you: Do you want to develop for mobile?

    • Enter y at the prompt.
      This ensures you can set up your game with game clients which run on mobile (Android or iOS).
  5. The InstallGDK script now opens a command-line window and runs a number of other scripts.
    This can take a few minutes to complete. The command-line window closes when the script has finished.


  1. Go to the root directory of your clone of the UE fork. For example:
    /Users/<my-name>/UnrealEngine

  2. From this directory, run InstallGDK.sh.
    This InstallGDK script clones the GDK plugin and installs it to the UE fork and Example Project directory (by default this is UnrealEngine/Samples/UnrealGDKExampleProject).

  3. The InstallGDK script asks you: Are you located in China?

    • If you are outside China: enter n at the prompt.
    • If you are in China: enter y at the prompt.
      (If you do not enter y, the script defaults to n.)
  4. The InstallGDK script asks you: Do you want to develop for mobile?

    • Enter y at the prompt.
      This ensures you can set up your game with game clients which run on mobile (Android or iOS).
  5. The InstallGDK script now opens a command-line window and runs a number of other scripts.
    This can take a few minutes to complete. The command-line window closes when the script has finished.


The script automatically opens a command line window and does the following:

  • Clones the latest release branch of the UnrealGDK into your UE fork's Plugins directory.
  • Clones the latest branch of the Example Project into your Engine's Samples directory.
  • Sets up the GDK plugin for use with the UE fork by running the Setup script.
  • Generates Visual Studio solution files (Windows) or XCode workspace (macOS) for the UnrealGDKExampleProject.


  • Step 6: Build the fork

    Once you have followed the steps 1 - 5 on this page, you should have the following on your machine:

    • The UE fork repository.
    • The GDK plugin repository.
    • The Example Project repository.

    On Windows, use Visual Studio to build the Unreal Editor; the build can take up to two hours.
    To do this:

    1. Still in the root directory of your clone of the UE fork double-click on UE4.sln to open it in Visual Studio. (Visual Studio might prompt you to install some dependencies first).
    2. 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.
    3. In Visual Studio's Solution Explorer window, right-click on the UE4 project and select Set as StartUp Project.
    4. Still in the Solution Explorer window, right-click on the UE4 project and select Build.

    On macOS, use XCode to build the Unreal Editor; the build can take several hours.
    To do this:

    1. Still in the root directory of your clone of the UE fork, double-click on UE4.xcworkspace to open it in XCode.
    2. Ensure that UE4 is selected as the active scheme.
    3. Select the Play button to start the Editor build.

    2020-11-27 Page updated with editorial review: moved the prompt about VS dependencies and added one about Windows
    2020-09-04 Page updated with editorial review: reinstated prepare-the-fork step
    2020-08-10 Page updated with editorial review: added guidance on in-China UE fork clone, removed prepare-the-fork section
    2020-08-06 Page update with editorial review: updated InstallGDK script functionality
    2020-07-28 Page updated with editorial review: references to Unreal Engine versions 4.25 and 4.24, and GDK version 0.11.0
    2020-06-23 Page updated with editorial review: added MacOS, mobile, UI and deployment workflow changes

    Updated 2 months ago


    2. Set up the fork and plugin


    Suggested Edits are limited on API Reference Pages

    You can only suggest edits to Markdown body content, but not to the API spec.