3 - Set up a project: The Starter Template
If you are ready to start developing your own game with the GDK, follow the steps below to create a new project.
Before setting up the SpatialOS GDK Starter Template, you must follow:
We recommend setting up the Example Project before creating a new project. This gives you an overview of the GDK and using SpatialOS.
Terms used on this page
<GameRoot>- The directory that contains your project’s .uproject file and Source folder.
<ProjectRoot>- The directory that contains your
<YourProject>- The name of your project and .uproject file (for example,
1: Create a new project using the Starter Template
After building the Unreal Engine fork, in File Explorer, navigate to
UE4Editor.exe to open the Unreal Editor.
- In the Project Browser window, select the New Project tab and then the C++ tab.
- In this tab, select SpatialOS GDK Starter.
- In the Folder field, choose a suitable directory for your project.
- In the Name field, enter a project name of your choice.
- Select Create Project.
Note: When you create a project, the Unreal Engine automatically creates a directory named after the project name you entered. This page uses
<YourProject> as an example project name.
Image: The Unreal Engine Project Browser, with the project file path and project name highlighted.
After you have selected Create Project, the Unreal Engine generates the necessary project files and directories, it then closes the Editor and automatically opens Visual Studio.
After Visual Studio has opened, save your solution then close Visual Studio before proceeding to the Clone the GDK step.
2: Clone the GDK
Now you need to clone the SpatialOS GDK for Unreal into your project. To do this:
- In File Explorer, navigate to the
<GameRoot>directory and create a
Pluginsfolder in this directory.
- In a Git Bash terminal window, navigate to
<GameRoot>\Pluginsand clone the GDK for Unreal repository by running either:
git clone https://github.com/spatialos/UnrealGDK.git
git clone firstname.lastname@example.org:spatialos/UnrealGDK.git
The GDK’s default branch (GitHub documentation) is
release. This means that, at any point during the development of your game, you can get the latest release of the GDK by running
git pull inside the
UnrealGDK directory. When you pull the latest changes, you must also run
git pull inside the
UnrealEngine directory, so that your GDK and your Unreal Engine fork remain in sync.
Note: You need to ensure that the root directory of the GDK for Unreal repository is called
UnrealGDK so the file path is:
3: Build the dependencies
To use the Starter Template, you must build the GDK for Unreal module dependencies and then add the GDK to your project. To do this:
- Open File Explorer, navigate to the root directory of the GDK for Unreal repository (
<GameRoot>\Plugins\UnrealGDK\...), and double-click
Setup.bat. If you haven’t already signed into your SpatialOS account, the SpatialOS developer website may prompt you to sign in.
- In File Explorer, navigate to your
<YourProject>.uproject and select Generate Visual Studio Project files.
- In the same directory, double-click
<YourProject>.sln to open it with Visual Studio.
- In the Solution Explorer window, right-click on
<YourProject>and select Build.
- When Visual Studio has finished building your project, right-click on
<YourProject>and select Set as StartUp Project.
- Press F5 on your keyboard or select Local Windows Debugger in the Visual Studio toolbar to open your project in the Unreal Editor.
Image: The Visual Studio toolbar
Note: Ensure that your Visual Studio Solution Configuration is set to Development Editor.
4: Deploy your project
To test your game, you need to launch a deployment. This means launching your game with its own instance of the SpatialOS Runtime, either locally using a local deployment, or in the cloud using a cloud deployment.
5: Deploy locally with multiple clients
- In the Editor, on the GDK Toolbar, open the Schema drop-down menu and select Schema (Full Scan).
Image: On the GDK toolbar in the Editor, select Schema (Full Scan)
- Select Snapshot to generate a snapshot.
Image: On the GDK toolbar in the Unreal Editor, select Snapshot
What is Schema?
Schema is a set of definitions which represent your game’s objects in SpatialOS as entities. Schema is defined in .schema files and written in schemalang by the GDK. Select Schema from the GDK toolbar and the GDK generates schema files and their contents for you, so you do not have to write or edit schema files manually.
You can find out more about schema, including how to generate it from the command line, making schema work with source control, and how to exclude certain directories from schema in the GDK schema documentation
What is an entity?
An entity is the SpatialOS equivalent of an Unreal Actor. It’s made up of a set of SpatialOS components. Each component stores data about the entity. (Note that SpatialOS components are not the same thing as Unreal Actor Components.)
What is a snapshot?
A snapshot is a representation of the state of a SpatialOS world at a given point in time. A snapshot stores the current state of each entity’s component data. You start each deployment with a snapshot; if it’s a re-deployment of an existing game, you can use the snapshot you originally started your deployment with, or use a snapshot that contains the exact state of a deployment before you stopped it.
You can find out more about snapshots in the GDK snapshot documentation.
To launch a local deployment:
Select Start. This opens a terminal window and starts a local SpatialOS deployment. Wait until you see the output
SpatialOS ready. Access the inspector at http://localhost:21000/inspectorin your terminal window.
Image: On the GDK toolbar in the Unreal Editor select Start
Want to debug your project?
On the Unreal Editor toolbar, open the Play drop-down menu.
Under Multiplayer Options, set the number of players to 2 and ensure that the check box next to Run Dedicated Server is checked. (If it is unchecked, select the checkbox to enable it.)
Image: The Unreal Engine Play drop-down menu, with Multiplayer Options and New Editor Window (PIE) highlighted
Under Modes, select New Editor Window (PIE).
On the Unreal Engine toolbar, select Play to run the game, and you should see two clients start.
Image: Two clients running in the Editor, with player Actors replicated by SpatialOS and the GDK
Open the Inspector using the local URL you were given above:
http://localhost:21000/inspector. You should see that a local SpatialOS deployment is running with one server-worker instance and two client-worker instances connected. You can also find and follow around the two player entities.
Image: The Inspector showing the state of your local deployment
When you’re done, select Stop in the GDK toolbar to stop your local SpatialOS deployment.
Image: On the GDK toolbar in the Unreal Editor select Stop
What is the Inspector?
The Inspector is a browser-based tool that you use to explore the internal state of a game’s SpatialOS world. It gives you a real-time view of what’s happening in a local or cloud deployment.
The Inspector we are using here is looking at a local deployment running on your computer and not in the cloud, so we use a local URL for the Inspector as it’s also running locally on your computer. When running locally, the Inspector automatically downloads and caches the latest Inspector client from the internet. When you use the Inspector in a cloud deployment, you access the Inspector through the Console via the web at https://console.improbable.io.
TIP: Check out the local deployment workflow page for a reference diagram of this workflow.
6: Launch a cloud deployment
To launch a cloud deployment, you need to prepare your server-worker and client-worker assemblies, and upload them to the cloud.
TIP: Building the assemblies can take a while - we recommend installing IncrediBuild to speed up build times.
Step 1: Set up your SpatialOS project name
When you signed up for SpatialOS, your account was automatically associated with an organisation and a project, both of which have the same generated name.
- Find this name by going to the Console.
The name should look something like
beta_randomword_anotherword_randomnumber. In the example below, it’s
Image: The SpatialOS Console with a project name highlighted.
- In File Explorer, navigate to the
<YourProject>/spatialdirectory and open the
spatialos.jsonfile in a text editor of your choice.
- Replace the
namefield with the project name shown in the Console. This tells SpatialOS which SpatialOS project you intend to upload to.
What is the Console?
The Console is a web-based tool for managing cloud deployments. It gives you access to information about your games’ SpatialOS project names, the SpatialOS assemblies you have uploaded, the internal state of any games you have running (via the Inspector), as well as logs and metrics.
You can find out more about the Console in the Glossary.
Step 2: Build your workers
Note: You must close the Unreal Editor before building your workers. If the Editor is open when you try to build your workers the command will fail.
Note: Unreal GDK projects default to using Spatial for networking. However, if the
bSpatialNetworking option is present in your
DefaultGame.ini configuration file (located in
<ProjectRoot>\Game\Config directory), ensure that it is set to
True (as in,
bSpatialNetworking=True) to enable networking with Spatial for your cloud deployment.
There are two ways to build your worker assemblies (known as “building workers”):
Build your workers automatically using the
BuildProject.batscript. This script automatically builds both the server-workers and client-workers required to run your game in the cloud. It then compresses your workers and saves them as .zip files to the
<ProjectRoot>\spatial\build\assembly\workerdirectory. Use this script if you want to build server-workers and client-workers at the same time.
Build your workers manually using the command line. Use the SpatialOS CLI command line to build server-workers and client-workers separately, or to use command-line arguments to build different worker configurations for different purposes. For example:
Editorto build server-workers to run on local machine for testing.
Linuxto build server-workers to run on SpatialOS cloud servers.
Build your workers using `BuildProject.bat`
To build your workers using the BuildProject.bat script:
In File Explorer, navigate to the
Double click BuildProject.bat. This opens a command line window and automatically creates your client and server workers.
Build your workers manually using the command line
In a terminal window, navigate to the
Build a server-worker assembly by running the following command:
Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat YourProjectServer Linux Development YourProject.uproject
Build a client-worker assembly by running the following command:
Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject> Win64 Development <YourProject>.uproject
BuildProject.bat can’t find the path specified
If you receive the error
The system cannot find the path specified. Builds failed., open
ProjectPaths.bat in a text editor and ensure that
GAME_NAME are correct.
PROJECT_PATH needs to be the name of your Unreal project folder (usually Game).
GAME_NAME needs to be the same name as your Unreal Project
Step 3: Upload your workers
Before launching a cloud deployment, you must upload your sever-worker and client-worker assemblies to the cloud. To do this:
- In a terminal window, navigate to your
- Run the following command:
spatial cloud upload <assembly_name>
You must replace
<assembly_name> with a name for your assembly (for example:
A valid upload command looks like this:
spatial cloud upload myassembly
Step 4: Launch your cloud deployment
The next step is to launch a cloud deployment using the worker assemblies that you just uploaded. You can only do this through the SpatialOS command-line interface (also known as the “CLI”).
What is the CLI?
The SpatilOS command-line tool (CLI) provides a set of commands that you use to interact with a SpatialOS project. Among other functions, you use it to deploy your game. You installed the CLI in step 1, when you set up your dependencies and installed SpatialOS.
Find out more in the glossary.
When launching a cloud deployment you must provide four parameters:
- The snapshot file - defines the starting state of the game world
- The assembly name - identifies which workers to use for your deployment.
- A launch configuration file - defines the SpatialOS game world and load balancing configuration.
- A name for your deployment - labels the deployment in the Console.
What is a launch configuration file?
Use this file to list the settings of a deployment. These include: how big the SpatialOS game world is, which worker types SpatialOS must use in the deployment, which worker types can create and delete Actors, and your game template. You installed the Launcher in step 1, when you set up your dependencies and installed SpatialOS.
You can find out more about the launch configuration file in the glossary.
In a terminal window, navigate to
<ProjectRoot>\spatial\and run the following command
spatial cloud launch --snapshot=snapshots\default.snapshot <assembly_name> one_worker_test.json <deployment_name>
default.snapshotis the snapshot file we have provided for this Example project.
assembly_nameis the name you gave the assembly in the previous step.
one_worker_test.jsonis the launch configuration file we provided with the GDK Template
deployment_nameis a name of your choice - you create this name when you run this command.
A valid launch command looks like this:
spatial cloud launch --snapshot=snapshots/default.snapshot myassembly one_worker_test.json mydeployment
7. Play your game
Image: The SpatialOS Console
When your deployment has launched, SpatialOS automatically opens the Console in your browser.
In the Console, Select Launch on the left of the page, and then select the Launch button that appears in the centre of the page to open the SpatialOS Launcher. The Launcher automatically downloads the game client for this deployment and runs it on your local machine.
What is the SpatialOS Launcher?
The Launcher is a distribution tool which downloads and launches game clients for your deployment. You access the Launcher from the Console; use the Console to create a URL to give end-users access to a game client for your game.
Find out more in the [glossary]((/unreal/alpha/content/glossary#launcher).
Image: The SpatialOS console launch window
Note: You install the SpatialOS Launcher during Getting started: 1 - Dependencies.
TIP: Check out the cloud deployment workflow page for a reference diagram of this workflow.
You’ve successfully set up and launched the Starter Template and the GDK! You are now ready to start developing a game with SpatialOS.
If you have an existing Unreal multiplayer project, follow the detailed porting guide to get it onto the GDK.
2019-07-02 Page updated with limited editorial review: added debug workaround