Update your GDK

Join the community on our forums or on Discord. We announce GDK versions there.

Once you start working on a game project, we recommend that you update the following every two weeks to pick up fixes and changes to the product:

When you do the update, you also need to build your game project again (and all other projects you are working on, including the Example Project and Starter Template). On this page, we explain everything you need to do to update your fork and plugin and build your project again.

Note: If you haven’t already downloaded these repositories, you need to follow the Get started guide to do this.

Whenever you update your GDK plugin software, you must first update your SpatialOS Unreal Engine fork (UE fork) software from a separate repository, with the procedure on this page. If you don't, you might get errors from the UE fork and GDK plugin being out of sync. You must also build your game project again because the GDK plugin is not backwards compatible with older versions of the UE fork.

To update your GDK plugin software and UE fork, follow the steps below.

This guide shows you how to update your GDK on Windows only. To set up and run SpatialOS games in the cloud, you need to use a Windows machine for development. We recommend using a Windows machine as your main development environment and macOS for developing and testing game clients on iOS.

Step 1: Check that the GDK plugin and UE fork versions correspond

The GDK plugin supports two versions of the UE fork at a time:

  • the current version
  • the legacy version

For more information, see Unreal Engine version support.

To check which UE fork corresponds to the GDK plugin you have installed, see the GDK plugin repository’s releases page on GitHub.

The notes on each GDK plugin’s release state:
"The corresponding Engine version is: x.xx-SpatialOSUnrealGDK-y.y.y" (where x.xx is the UE fork version and y.y.y is the GDK plugin version it corresponds to).

Notes:

  • The x.xx version name of the UE fork matches Unreal Engine versioning
  • You can also see which GDK plugin the UE fork corresponds to in the UE fork repository’s releases page

For information about version numbering, see Versioning scheme.

Step 2: Ensure you're on the branch you want

If you haven’t already checked out the GDK plugin and UE fork, you need to follow the Get started guide to do this.

For further information, see Which branches to use.

The most stable version is always the release branch, which is set as the default branch for each repository.

Find out which branches you have checked out and how to check out a different branch, by following the instructions below:

  1. Open a terminal window and navigate to the root directory of your clone of the UE fork. For example:
    C:/Dev/UnrealEngine
  2. Run git branch.
    This displays the branch of UE fork you have checked out. For example:
    * 4.25-SpatialOSUnrealGDK-release
    The branch name x.xx-SpatialOSUnrealGDK-<text> includes the UE fork version number (x.xx). Note that the UE fork version number matches the Unreal Engine source code version number it is forked from.
    In the example above, the UE fork and Unreal Engine version number is 4.25 and it is a release version of the software.
    If you need to check out a different branch, run git checkout <branch-name>. For example:
    git checkout 4.24-SpatialOSUnrealGDK-release

If you see a warning similar to error: Your local changes to the following files would be overwritten by checkout: then you need to revert or merge your local changes before checking out the new branch. Revert using git checkout -- <file> or consider creating a merge branch. For more information, see the Atlassian git-merge tutorial.

  1. To find out which branch of the GDK plugin you have checked out, navigate to the root directory of your clone of the GDK plugin. For example:
    C:/Dev/UnrealEngine/Engine/Plugins/UnrealGDK
    Run git status.
    This displays the version of the GDK plugin you have checked out. For example:
    On branch release

You might see the message Not currently on any branch. This can happen if you originally used InstallGDK.bat when you installed the GDK. This is because InstallGDK.bat pulls a tag (Atlassian documentation) and not a branch. If you want to check out a specific branch, you can do this in the next step. If you want the latest release, run git checkout release.

  1. If you want to check out a different branch, run git checkout <branch-name>. For example:
    git checkout release

Step 3: Update your UE fork and GDK plugin

Before you update your UE fork, check the release notes on GitHub so that you know what has changed in it. Pay close attention to the Breaking Changes section (where present), as these changes might require you to make changes to your project.

To update your UE fork and GDK plugin to the latest version, complete the following steps:

  1. Open a terminal window, and navigate to the root directory of your clone of the UE fork. For example:
    C:/Dev/UnrealEngine
  2. Run git pull to update your clone of the UE fork.
  3. Run git restore . (Use the full-stop to restore all files in the current directory.)
    Git restore ensures you have no errors when you build the UE4 project in a later step.
    For information on the errors you might get, see the UE forums.
  4. Now navigate to the root directory of your clone of the GDK plugin. For example:
    C:/Dev/UnrealEngine/Engine/Plugins/UnrealGDK
  5. Run git pull to update your clone of the GDK plugin.

Step 4: Update your clang version, rebuild your Unreal Engine, and build your game project again

Only follow this step if you either:

  • checked out a new branch of the UE fork. For example, if you moved from 4.24-SpatialOSUnrealGDK-release to 4.25-SpatialOSUnrealGDK-release
  • installed the GDK prior to version 0.11.0.

If you didn't do either of these, skip this step and go to Step 5: Regenerate your schema.

  1. Download and install the version of clang that corresponds to your UE fork and Unreal Engine version.
  2. Recommended: Run spatial update to update your SpatialOS CLI.
    It doesn’t matter which directory you are in when you run this command.
  3. To download and install the latest binary content and associated files for the Unreal Engine:
    a. Navigate to the root directory of your clone of the UE fork. For example: C:/Dev/UnrealEngine
    b. Run Setup.bat.
  4. Run GenerateProjectFiles.bat from the same root directory to regenerate the UE fork’s project files.
  5. Run InstallGDK.bat from the same root directory to update the GDK. You are asked the following:
    • Whether you want to deploy in China (only possible if you are in China)
    • Whether you want to develop for mobile
      Answer y or n as appropriate to each of these questions.
      The batch file then updates the GDK plugin accordingly. If you haven’t already signed in to your
      SpatialOS account, the SpatialOS developer website might prompt you to sign in.
  6. In File Explorer, navigate to the root directory of your clone of the UE fork and double-click UE4.sln. This opens the Unreal Engine source code as a project in Visual Studio called UE4.
  7. In Visual Studio's Solution Explorer window, right-click the UE4 project and select Build.
  8. Close Visual Studio.
  9. In File Explorer, navigate to your Unreal Example Project folder. For example, UnrealEngine/Samples/UnrealGDKExampleProject. Run git clean -xdf to remove any files built by a previous version.
    Note: This command forces the deletion of untracked files and directories.
  10. Go to the /spatial/snapshots subdirectory. Delete any .snapshot files there.
  11. To build your game project again, in File Explorer, navigate to the game root directory of your Unreal game project. This is the directory which contains its .uproject file. For example:
    UnrealEngine/Samples/UnrealGDKExampleProject/Game
  12. Right-click your game project’s .uproject file and select Generate Visual Studio Project Files.
  13. Double-click your game project's .sln file to open it in Visual Studio.
  14. In Visual Studio's Solution Explorer window, right-click the game project and select Build. For example:
  1. When Visual Studio has finished building the project, set it as a startup project:
    In the Solution Explorer window, right-click the game project and select Set as StartUp Project.
  2. Open the project in the Unreal Editor:
    Press F5 on your keyboard or select Local Windows Debugger in the Visual Studio toolbar.

You are now on the latest GDK plugin and the latest UE fork.

Step 5: Regenerate your schema

In the Unreal Editor, on the GDK toolbar select Schema Generation Options > Schema (Full Scan).
Starting a local or cloud deployment automatically creates a snapshot, so you do not need to create one manually.


2020-08-12 Page updated with editorial review: removed step to manually create a snapshot
2020-07-28 Page updated with editorial review: changed version references to Unreal Engine versions 4.25 and 4.24, and GDK version 0.11.0
2020-06-25 Page updated with full editorial review: updated to reflect new workflow
2020-02-28 Page updated with full editorial review
2019-11-14 Page updated with limited editorial review
2019-07-31 Page updated with limited editorial review

Updated 22 days ago


Update your GDK


Suggested Edits are limited on API Reference Pages

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