Setup and install

Tip: See Get started first

You can set up and install the SpatialOS GDK for Unity without following the Get started guide's FPS Starter Project tutorial, however, we recommend starting by following the FPS Starter Project tutorial to become familiar with the SpatialOS workflow.

1. Sign up or log in

If you have not signed up before, you can do this here.

If you have already signed up, make sure you are logged into Improbable.io. If you are logged in, you should see your picture in the top right of this page; if you are not logged in, select Sign in at the top of this page and follow the instructions.

2. Hardware

Ensure your machine meets the minimum system requirements for Unity development.

Refer to the Unity system requirements for further information about the minimum hardware requirements.

3. Network settings

To configure your network to work with SpatialOS, refer to the SpatialOS network settings.

4. Install the GDK dependencies

Setup for Windows

Step 1. Install Unity 2020.1.2f1

Ensure you install this exact version as other Unity versions may not work with the GDK.

You can download Unity 2020.1.2f1 from the Unity download archive.

Make sure you download the Installer version, and refer to the matrix below for which options to install :

Option Required? Why?
Linux Build Support Yes All server-workers in a cloud deployment run in a Linux environment.
Mac Build Support No Only required if you wish to build clients compatible with MacOS.
Android Build Support No Only required if you wish to build mobile clients for Android.
iOS Build Support No Only required if you wish to build mobile clients for iOS.

Step 2. Install .NET Core SDK (x64)

  • Verified with version 3.1.3xx.

Note: After installing the .NET Core SDK, you should restart any Unity and Unity Hub processes. This will prevent errors where Unity cannot find the dotnet executable.

Step 3. Run the SpatialOS Installer

Step 4. Install a code editor if you don't have one already

Step 5. Install Git

The SpatialOS GDK for Unity source code is hosted on GitHub. You need to download and install Git or GitHub Desktop in order to clone the GDK repositories.

Note: If you do not want to use Git you can also download a .zip file containing the GDK repo from the GDK GitHub Page. However, you will not be able to easily download updates to the GDK if you do not use Git to clone the repository.

Step 6. Restart your machine.

Note: If you do not restart your machine, you may experience errors when opening a GDK project.

Code editor set up

Using Visual Studio?

You need to install the .NET Core cross-platform development and Game development with Unity workloads. To to this:

  • As you install Visual Studio, select the Workloads tab in the Installer. If you already have Visual Studio installed, you can find the Workloads tab by opening Visual Studio Installer and, in the Products section, selecting Modify for Visual Studio 2017. If you can't see the Modify option, select More.

Once you have navigated to the Workloads tab:

  • Select .NET Core cross-platform development.
  • Select Game development with Unity:
    • Deselect any options in the Summary on the right that mention a Unity Editor (for example, Unity 2017.2 64-bit Editor or Unity 2018.1 64-bit Editor).
    • The SpatialOS GDK for Unity requires Unity 2020.1.2f1, which you already installed in step 1.
    • Make sure Visual Studio Tools for Unity is included (there should be a tick next to it).

Warning: Older versions of Visual Studio 2017 have been known to cause some issues with Unity 2020.1.2f1 - the issues are projects loading and unloading frequently, and Intellisense breaking. If you do experience these issues, try updating to the latest version of Visual Studio 2017.

Using Rider?

Once you have installed Rider, install the Unity Support plugin for a better experience.

Setup for Mac

Step 1. Install Unity 2020.1.2f1

Ensure you install this exact version as other Unity versions may not work with the GDK.

You can download Unity 2020.1.2f1 from the Unity download archive.

Make sure you download the Installer version, and refer to the matrix below for which options to install :

Option Required? Why?
Linux Build Support Yes All server-workers in a cloud deployment run in a Linux environment.
Windows Build Support No Only required if you wish to build clients compatible with Windows.
Android Build Support No Only required if you wish to build mobile clients for Android.
iOS Build Support No Only required if you wish to build mobile clients for iOS.

Step 2. Install .NET Core SDK (x64)

  • Verified with version 3.1.3xx.

Note: After installing the .NET Core SDK, you should restart any Unity and Unity Hub processes. This will prevent errors where Unity cannot find the dotnet executable.

Step 3. Run the SpatialOS installer

Step 4. Install a code editor if you don't have one already

Step 5. Install Git

The SpatialOS GDK for Unity source code is hosted on GitHub. You need to download and install Git or GitHub Desktop in order to clone the GDK repositories.

Note: If you do not want to use Git you can also download a .zip file containing the GDK repo from the GDK GitHub Page. However, you will not be able to easily download updates to the GDK if you do not use Git to clone the repository.

Step 6. Restart your machine.

Note: If you do not restart your machine, you may experience errors when opening a GDK project.

Code editor set up

Using Visual Studio?

Once you have installed Visual Studio, within the Visual Studio Installer, select .NET Core + ASP .NET Core.

Using Rider?

Once you have installed Rider, install the Unity Support plugin for a better experience.

Updated about a year ago


Setup and install


Suggested Edits are limited on API Reference Pages

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