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.
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).
x.xxversion 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.
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:
- Open a terminal window and navigate to the root directory of your clone of the UE fork. For example:
This displays the branch of UE fork you have checked out. For example:
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.25and it is a
releaseversion 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.
- 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:
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.
- If you want to check out a different branch, run
git checkout <branch-name>. For example:
git checkout release
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:
- Open a terminal window, and navigate to the root directory of your clone of the UE fork. For example:
git pullto update your clone of the UE fork.
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
UE4project in a later step.
For information on the errors you might get, see the UE forums.
- Now navigate to the root directory of your clone of the GDK plugin. For example:
git pullto update your clone of the GDK plugin.
Only follow this step if you either:
- checked out a new branch of the UE fork. For example, if you moved from
- 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.
- Download and install the version of clang that corresponds to your UE fork and Unreal Engine version.
- Recommended: Run
spatial updateto update your SpatialOS CLI.
It doesn’t matter which directory you are in when you run this command.
- 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:
GenerateProjectFiles.batfrom the same root directory to regenerate the UE fork’s project files.
InstallGDK.batfrom 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
nas 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.
- 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
- In Visual Studio's Solution Explorer window, right-click the
UE4project and select Build.
- Close Visual Studio.
- In File Explorer, navigate to your Unreal Example Project folder. For example,
git clean -xdfto remove any files built by a previous version.
Note: This command forces the deletion of untracked files and directories.
- Go to the
/spatial/snapshotssubdirectory. Delete any
- 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
.uprojectfile. For example:
- Right-click your game project’s
.uprojectfile and select Generate Visual Studio Project Files.
- Double-click your game project's
.slnfile to open it in Visual Studio.
- In Visual Studio's Solution Explorer window, right-click the game project and select Build. For example:
- 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.
- 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.
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 about a year ago