1. Set up

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.

5. Get the FPS Starter Project source code

To run the the FPS Starter Project, you need to download the source code. There are two ways you can do this: either get the source code as one zip file download or clone the repository using Git. (To find out more about Git, see github.io).

We recommend using Git, as Git's version control makes it easier for you to get updates in the future.

Zip file download

While we recommend using Git, if you prefer to, you can get the source code for the FPS Starter Project by downloading one zip file here. Please download the latest release, the file should be called something like Source code.

If you have downloaded the source code via a zip file move on to the next section of this page: Open the FPS Starter Project in your Unity Editor.

Clone the repository using Git

If you haven't downloaded the zip file, you need the the FPS Starter Project repository.

Clone the FPS Starter Project repository

Clone the FPS Starter Project using one of the following commands:

HTTPS git clone https://github.com/spatialos/gdk-for-unity-fps-starter-project.git
SSH git clone [email protected]:spatialos/gdk-for-unity-fps-starter-project.git

Note: You can only clone via SSH if you have already set up SSH keys (GitHub) with your GitHub account.

6. Configure package registry

Outside of China

No action is required.

In China

Note: Only follow the in-China instructions if you are located in China and deploying your game to server nodes hosted in China. You must be located in China to deploy to server nodes hosted in China. Note that in the documentation, "China" refers to mainland China only.

In a text editor, open workers/unity/Packages/manifest.json and replace https://npm.improbable.io/gdk-for-unity/ with https://npm.spatialoschina.com/repository/unity/.

It should look like the following when you're done:

{
  "dependencies": {
		...,
  },
  "registry": "https://packages.unity.com",
  "scopedRegistries": [
    {
      "name": "Improbable",
      "url": "https://npm.spatialoschina.com/repository/unity/",
      "scopes": [
        "io.improbable"
      ]
    }
  ]
}

7. Open the FPS Starter Project in your Unity Editor

Launch your Unity Editor. It should automatically detect the project but if it doesn't, select Open and then select gdk-for-unity-fps-starter-project/workers/unity.

Note: The first time you open the Starter Project in your Unity Editor, It takes about 10 minutes; it's much quicker to open after this. (While you are waiting, you could look at our blog.)

Updated about a year ago



1. Set up


Suggested Edits are limited on API Reference Pages

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