The Example Project
3: Launch a cloud deployment
Before launching a cloud deployment, as well as generating schema and a snapshot, you also need to:
- Associate your game with its cloud project name.
- Prepare the game’s server-workers and client-workers by building them
- Upload the prepared workers to the cloud.
What is a worker?
Workers are programs that connect to a SpatialOS world. They perform the computation associated with a world: they can read what’s happening, watch for changes, and make changes of their own. You prepare both your server-workers and client-workers for upload to the cloud by building their assemblies from their
.uproject files. We call this “building your workers”.
You can find out more about workers in the GDK workers documentation
As you already generated schema and a snapshot for the Example project when you launched a local deployment, and haven’t changed the project since, you don’t need to do this again. If you make any changes to the project, you must generate schema and create a snapshot before launching a local or cloud deployment.
Everyone who signs up for SpatialOS automatically has free cloud deployment hosting via the free tier, so you can use free tier hosting for this Example project.
What is the free tier?
The free tier is ideal for starting development, prototyping a game, conducting technical evaluation, or just learning how to use SpatialOS. It gives you the ability to run one cloud deployment at any time using a specified game template. With the free tier you can also use SpatialOS on your local machine, and we offer free support via the forums.
All the hosting options are available as game templates. For information about which game templates you can use on the free tier, and what they provide, see Pricing details>.”
Step 1: Associate your game with a cloud project name
When you signed up for SpatialOS, your account was automatically given a SpatialOS cloud organization name and a SpatialOS cloud project name, both of which are the same generated name.
- Find this name by going to the Console at https://console.improbable.io. 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.
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.
- In File Explorer, navigate to the
UnrealGDKExampleProject\Game\spatialdirectory and open the
spatialos.jsonfile in a text editor of your choice.
- In the file, replace the
namefield with the project name shown in the Console. This associates your SpatialOS cloud project with your Unreal game, telling SpatialOS which cloud project you are uploading your prepared workers to..
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.
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
UnrealGDKExampleProject\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 command line when you want to build your server-workers and client-workers separately, or, if you want to build different worker configurations, for example: Editor, Test, Shipping or Linux.
Build your workers using
To build your workers using the BuildProject.bat script:
In File Explorer, navigate to the
UnrealGDKExampleProjectdirectory. 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 UnrealGDKExampleProject directory. Build a server-worker assembly by running the following command:
Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat GDKShooterServer Linux Development GDKShooter.uprojectBuild a client-worker assembly by running the following command:
Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat GDKShooter Win64 Development GDKShooter.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:
- Open a terminal window and navigate to
- 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 exampleprojectassembly
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
UnrealGDKExampleProject\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 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 provided for this Example project.
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 exampleprojectassembly one_worker_test.json mydeployment
When your deployment has launched, SpatialOS automatically opens the Console in your browser. > Next: 4: Play the game
2019-05-21 Page added with editorial review