Command-line cloud deployments

The GDK has some batch commands for cloud deployment and the SpatialOS CLI has a set of commands for managing and developing SpatialOS projects. (You install the CLI when you install SpatialOS as part of Get Started: 1 - Get the dependencies.) In the Example Project and Starter Template tutorials, you build your project’s workers via the Cloud Deployment Configuration dialog box. This is the easiest way to build workers.

However, you can also use the GDK's batch scripts from the command line to build server-workers or client-workers individually. You can also use CLI commands to start cloud deployments. You can use these for continuous integration by setting up automated commands to build workers and start cloud deployments.

There are useful batch scripts and CLI commands below and you can find more detailed information about the CLI in the CLI documentation, in the Tools section of the SpatialOS documentation.

Note: Cloud deployment is only available from Windows.

Useful batch scripts and CLI commands

Build server-worker assembly

The filepath you use depends on whether you have the UnrealGDK plugin set up as an engine plugin or as a project plugin. If you followed the default setup instructions, you have it set up as an engine plugin.

Engine plugin filepath (default):

UnrealEngine\Engine\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject>Server Linux Development <YourProject>.uproject

Project plugin filepath:

<YourProject>\Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject>Server Linux Development <YourProject>.uproject

Replacing <YourProject> with the name of your Unreal project.

For more information on the available options when using BuildWorker.bat, see the Helper scripts reference.

Build client-worker (game client) assembly

The filepath you use depends on whether you have the UnrealGDK plugin set up as an engine plugin or as a project plugin. If you followed the default setup instructions which use the InstallGDK.bat script, you have it set up as an engine plugin.

Engine plugin filepath (default):

UnrealEngine\Engine\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject> Win64 Development <YourProject>.uproject

Project plugin filepath:

<YourProject>\Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject> Win64 Development <YourProject>.uproject

Replacing <YourProject> with the name of your Unreal project.

For more information on the available options when using BuildWorker.bat, please see the Helper scripts reference.

Build simulated player game clients

Build out the simulated player clients (which will run on Linux in the cloud) using the following command:

Engine plugin filepath (default):

UnrealEngine\Engine\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject>SimulatedPlayer Linux Development <YourProject>.uproject 

Project plugin filepath:

<YourProject>\Game\Plugins\UnrealGDK\SpatialGDK\Build\Scripts\BuildWorker.bat <YourProject>SimulatedPlayer Linux Development <YourProject>.uproject

Useful simulated player game client build flags

Skip shaders to speed up game client build
A Linux client build includes building all shaders for the OpenGL Shading Language by default.
When you build Linux clients, building the shaders can take a long time and fail often.
Linux clients do not require shaders, so you can skip shader compilation by adding the flag -skipshadercompile to the BuildWorker.bat command.

Disable game client plugins which don't run on Linux
Simulated players run on Linux in the cloud. If your game clients use any plugins which don't run on Linux clients, you must exclude these plugins from the worker build.
To do this, edit your project's Build.cs file to wrap any non-Linux plugins in a check, such as:
if (Target.Platform != UnrealTargetPlatform.Linux)

Upload assembly

Note: Run this command from the spatial directory of your project.

spatial cloud upload <myassembly>

Replacing <myassembly> with the name you choose to give your assembly.

Start cloud deployment

You can start a cloud deployment using the Unreal Editor or the SpatialOS CLI. Starting via the CLI is useful if you want to start cloud deployments as part of continuous integration.

To launch a cloud deployment via the CLI, in a terminal window, navigate to <ProjectRoot>\spatial\ and run the following command, adding flags depending on where you want to host your game:

USA

spatial cloud launch --snapshot=snapshots/default.snapshot <myassembly> <launch_config>.json <deployment_name>

Note: This command defaults to deploying to clusters located in the US.

Europe

spatial cloud launch --snapshot=snapshots/default.snapshot <myassembly> <launch_config>.json <deployment_name> --cluster_region=eu

China

spatial cloud launch --snapshot=snapshots/default.snapshot <myassembly> <launch_config>.json <deployment_name> --environment=cn-production

Asia-Pacific (not China)

spatial cloud launch --snapshot=snapshots/default.snapshot <myassembly> <launch_config>.json <deployment_name>  --cluster_region=ap

Rest of World

Choose between USA or Europe.

Host your game on servers in the same region as its users for lower network latency during gameplay.

  • <myassembly> identifies the worker assemblies to use (as chosen in the spatial cloud upload command).
  • <launch_config>.json declares the world and load balancing configuration.
  • <deployment_name> labels the deployment for SpatialOS to reference in the Console.

Start cloud deployment: specify a cluster region or cluster

Outside China

Cluster region
With the cluster_region option, you can specify the region that you want your cloud deployment hosted in. The available regions are as follows:

  • us (North and South America)
  • eu (Europe)
  • ap (Asia, Pacific but not China)

For example: --cluster_region=eu

  • If you don’t specify a region, then SpatialOS selects a cluster in the US.
  • If you specify a cluster name with the cluster option (see below), then SpatialOS ignores the cluster_region option.

Cluster
With the cluster option, you can specify the ID of the server-node cluster that you want to use for your cloud deployment. If you leave this empty, SpatialOS picks the most under-utilized available server-node cluster for the region you have chosen.

If you specify a cluster name with the cluster option, then SpatialOS ignores the cluster_region option.

In China

In China, the cluster_region option has no effect.

If you use Tencent Cloud, you can use the cluster option to specify one of the following clusters:

  • cn-prd-sp-tct-ap-shanghai-2-1
  • cn-prd-sp-tct-ap-shanghai-4-1

If you use Amazon Web Services, you can use the cluster option to specify one of the following clusters:

  • cn-prd-sp-aws-cn-northwest-1-1
  • cn-prd-sp-aws-cn-northwest-1-2
  • cn-prd-sp-aws-cn-northwest-1-3

If you don’t specify a cluster, then SpatialOS deploys to Tencent Cloud, on the least-utilized Tencent Cloud cluster above.


2020-11-11 Page updated with editorial review: added section about cluster region and cluster.
2020-08-26 Page updated with editorial review: removed line breaks from CLI calls.
2020-06-26 Page repurposed with editorial review: added intro text, AP region, and standardised existing text.
2020-02-20 Page updated with editorial review: added in-China workflow.
2019-11-14 Page updated without editorial review: added callout for plugins which won't run on Linux.

Updated 10 months ago


Command-line cloud deployments


Suggested Edits are limited on API Reference Pages

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