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:
Set up and install the dependencies of the GDK for Unity.
See the separate Setup and installation guide.Setup the SpatialOS project structure in your Unity project.
See the section below.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 4 months ago