1. Set up your project

Tip: See Get started first

You can set up your project without going through 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.

To use the SpatialOS GDK for Unity in your Unity project, you need to:

  1. Set up and install the dependencies of the GDK for Unity.
    See the separate Setup and installation guide.

  2. Setup the SpatialOS project structure in your Unity project.
    See the section below.

  3. Add the GDK packages to your Unity project. (This is how you install the GDK.)
    See the section below.

Setup a SpatialOS project

A SpatialOS project needs to have a specific directory layout and configuration files in order to function properly.

Step 1. Setup the directory layout.

In the root of your SpatialOS project, you need to create the following directories: schema and workers.

  • schema: This directory contains your *.schema files.
  • workers: This directory contains your worker code and configuration.
<project_root>
  ├── schema/
  ├── workers/

Step 2. Create the required configuration files.

In the root of your SpatialOS project, create two files:

  • spatialos.json, copy and paste in the following content:
{
    "name": "my_project",
    "project_version": "0.0.1",
    "sdk_version": "14.6.1"
}

Note: to replace the value of the name field with your own project name, which you can find in the SpatialOS Console.

  • default_launch.json, copy and paste in the following content:
{
  "template": "w2_r0500_e5",
  "world": {
    "chunkEdgeLengthMeters": 50,
    "snapshots": {
      "snapshotWritePeriodSeconds": 0
    },
    "dimensions": {
      "xMeters": 1000,
      "zMeters": 1000
    },
    "legacy_flags": [
      {
        "name": "interest_queries_components_are_filtered_by_component_delivery",
        "value": "false"
      }
    ]
  },
  "load_balancing": {
    "layer_configurations": [
      {
        "layer": "UnityGameLogic",
        "points_of_interest": {
          "num_workers": 1,
          "points": [
            {
              "x": 0,
              "z": 0
            }
          ]
        },
        "options": {
          "manual_worker_connection_only": true
        }
      }
    ]
  },
  "workers": [
    {
      "worker_type": "UnityGameLogic",
      "permissions": [
        {
          "all": {}
        }
      ]
    },
    {
      "worker_type": "UnityClient",
      "permissions": [
        {
          "all": {}
        }
      ]
    }
  ]
}
<project_root>
  ├── schema/
  ├── workers/
  ├── spatialos.json
  ├── default_launch.json

Step 3. Create a new Unity project.

You need to put the new Unity project in the workers directory. For example workers/my-unity-project/.

<project_root>
  ├── schema/
  ├── workers/
      ├── my-unity-project/
  ├── spatialos.json
  ├── default_launch.json

Step 4. Add worker configurations.

For a basic set up of two worker types, an UnityGameLogic and UnityClient, we recommend you to reuse these files:

Copy these files into workers/my-unity-project/.

<project_root>
  ├── schema/
  ├── workers/
      ├── my-unity-project/
          ├── spatialos.UnityGameLogic.worker.json
          ├── spatialos.UnityClient.worker.json
  ├── spatialos.json
  ├── default_launch.json

Tip: Find out more

Find out more about the SpatialOS project structure in the SpatialOS Overview documentation.
The GDK for Unity uses the structured project layout.

Add the GDK packages

Step 1. Create a asmdef for generated code.

In order to ensure that the generated code can access its dependencies, you will need to create an asmdef for the generated code. We recommend that you reuse the following file:

Copy this file into workers/my-unity-project/Assets/Generated/Improbable.Gdk.Generated.asmdef.

Note: You will need to create the Generated folder.

Step 2. Add package references to your manifest.json.

Unity loads the packages that are declared in the manifest.json file into your Unity project.

Note: There may already be some dependencies listed in your manifest.json. If there are, do not remove them - just add to the list.

Open the manifest.json in the workers/my-unity-project/Packages/ directory and add the following:

Outside of China

{
  "dependencies": {
    "io.improbable.gdk.core": "0.4.0",
    "io.improbable.gdk.buildsystem": "0.4.0"
  },
  "scopedRegistries": [
    {
      "name": "Improbable",
      "url": "https://npm.improbable.io/gdk-for-unity/",
      "scopes": [
        "io.improbable"
      ]
    }
  ]
}

See our FPS Starter Project for an example.

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.

{
  "dependencies": {
    "io.improbable.gdk.core": "0.4.0",
    "io.improbable.gdk.buildsystem": "0.4.0"
  },
  "scopedRegistries": [
    {
      "name": "Improbable",
      "url": "https://npm.spatialoschina.com/repository/unity/",
      "scopes": [
        "io.improbable"
      ]
    }
  ]
}

The packages listed above are just the minimum set required to get started with the GDK.

You can add additional feature module packages by referencing them the same way.

Step 3. Create a GDK tools configuration file.

The GDK for Unity uses a configuration file when generating code. We recommend that you reuse this file:

Copy this file into workers/my-unity-project/Assets/Config/GdkToolsConfiguration.json

Note: You will need to create the Assets/Config folder.

Step 4. Open your Unity project.

Open your Unity project located at workers/my-unity-project. This triggers code generation for your project.

Note: Unity generates code from the schema files defined in your SpatialOS project.

<project_root>
  ├── schema/
  ├── workers/
      ├── my-unity-project/
          ├── Assets/
              ├── Config/
                  ├── GdkToolsConfiguration.json
              ├── Generated/
                  ├── Improbable.Gdk.Generated.asmdef
                  ├── ...
              ├── ...
          ├── spatialos.UnityGameLogic.worker.json
          ├── spatialos.UnityClient.worker.json
          ├── ...
  ├── spatialos.json
  ├── default_launch.json

Updated about a year ago



1. Set up your project


Suggested Edits are limited on API Reference Pages

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