d. Launch a cloud deployment

Although the GDK for Unity makes it easy to iterate locally it is important to regularly build, deploy and test that your game works in the cloud. In this section we’ll look at the launch configuration, building workers, uploading an assembly and launching a deployment with your default snapshot.

As you haven’t yet launched a cloud deployment yet, you’ll first go through the launch configuration to make sure it is set up for our game.

What’s the difference between local and cloud launch configurations?

Open the default_launch.json and cloud_launch.json files at the root of your SpatialOS project. We currently use default_launch for local deployments and will use cloud_launch for cloud deployments, but what’s the difference between them?

The first piece of the configuration is the game template. A game template specifies the compute resources that your deployment needs for both the Runtime and your workers. The current template in the launch configs specifies a worker node of size n1-standard-2, which maps to the similarly named GCP node size.

You can determine the size of the Runtime using the rXXX term in the template, in this case we are currently using a Runtime size of r0500. The bigger the r number, the bigger the Runtime. For example, we use the larger r1000 Runtime in the FPS starter project to handle the increased complexity and scale it comes with.

Click here to read more about game templates!

The next important setting is the world dimensions. Currently this is set to 5000 x 5000, which is far larger than you require for the basic game you have. Change this to 500 x 500 in both the local and cloud launch configurations.

We then cast our eyes to the load_balancing section of the configuration. The Runtime provides several options for load balancing workers:

  • rectangle_grid: Divides the world into a rectangular grid of the specified number of rows and columns. There are no overlapping areas of authority.
  • hex_grid: Tiles the game world as a hexagonal grid and places server-workers with circular authority regions at the center of each tile. There are overlapping authority regions at the boundaries of the tiles.
  • points_of_interest: You specify key locations that should not be simulated by more than one server-worker. The Runtime divides the world into non-overlapping regions of the world that are closest to a given point, similar to a Voronoi diagram using the Manhattan distance.
  • entity_id_sharding: A non-spatial load balancing strategy that distributes work evenly across a configured number of server-workers, without accounting for entity positions.

Read the load balancing documentation to learn more about each strategy.

In the local configuration we’ve defined a 1x1 rectangle grid, but the cloud configuration has a 2x1 config. This means that cloud deployments will have their world divided into a grid with 2 columns and 1 row, with a different worker occupying each half of the grid. On the other hand, local deployments would contain a single worker responsible for the whole world.

Yes! First you’ll need to define a load balancing strategy which requires more than one instance of a given worker type. For example, a rectangle grid of UnityGameLogic instances arranged in 2 columns and 1 row.

Ensure that the `manual_worker_connection_only` option is set to true, to let the Runtime know that you will be connecting the UnityGameLogic workers manually.

  "load_balancing": {
    "layer_configurations": [
        "layer": "UnityGameLogic",
        "rectangle_grid": {
          "cols": 2,
          "rows": 1
        "options": {
          "manual_worker_connection_only": true

Once that is done, duplicate the worker prefab for the worker type above and move them so their worker origins are further apart. The number of expected worker instances defined in the configuration should match the number of worker prefabs in the DevelopmentScene. In the example strategy with 2 columns and 1 row, you should have 2 GameLogicWorker worker prefabs in the scene.

Once you’ve confirmed that your worker prefabs are all at different offsets, launch a local deployment and play the development scene. You should now have multiple server-workers connected to the deployment, in addition to your client-worker!

Normally it’s the Runtime’s job to run the built-out versions of workers. However, we want to use the DevelopmentScene in the blank project to run both UnityClient and UnityGameLogic workers simultaneously, for faster iteration. That’s why the local launch configuration contains the manual_worker_connection_only option. This flag tells the Runtime not to launch its own UnityGameLogic workers, but to wait for you to connect UnityGameLogic workers manually.

Build for cloud

Select the SpatialOS > Build for cloud > All workers menu option to start building your workers. This will build and package UnityClient workers for Windows or Mac, depending on which support you have installed, and a UnityGameLogic worker for Linux.

While waiting for your workers to build, continue reading to learn more about the Deployment Launcher.

Intro to the Deployment Launcher

The Deployment Launcher is a Unity Editor window that lets you upload assemblies and manage SpatialOS deployments. For more information, read the Feature Module documentation.

Using the Deployment Launcher

To open the Deployment Launcher, select the SpatialOS > Deployment Launcher menu item.

An assembly contains all the files that your cloud deployment will need to run. You must specify which assembly to use when launching a cloud deployment, so you need to upload one first. Pick an assembly name or let the Deployment Launcher generate one for you in the {projectName}_{DateTime.Now:MMdd_HHmm} format.

Ensure the `Project Name` matches your own project in the SpatialOS console.

For example if the SpatialOS console says your project is called beta_ray_cyrus, your project name should also be beta_ray_cyrus. To update the project name update the spatialos.json file at the root of your project and click the refresh button in the Deployment Launcher.

Once you’re happy with the name, select “Upload assembly”.

Note the Runtime version may be different with up-to-date versions of the GDK.

You should see a notification indicating that the upload is in progress.

Once the assembly is uploaded the notification should disappear and you should see a log indicating the upload is complete.

Select “Assign assembly name to deployments” to update the current deployment’s configuration to use the name of the assembly you just uploaded. Then choose a name for your deployment, for example my_first_deployment, and then check that the deployment location suits your region.

China setup

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.

When you’re done, the window should look similar to the image below. Select “Launch deployment” to launch a cloud deployment, and wait for SpatialOS to spin up your game.

The SpatialOS platform first allocates and then spins up the machines that will be running your Runtime and server-workers. The specified assembly and starting snapshot are loaded before running the required number of worker executables.

The Deployment Launcher will automatically open the overview page in the SpatialOS console for your newly-launched deployment when ready.

Launch a client

Once the deployment status is green, select the Launch button at the top of the page. A dialogue will open asking you to install the SpatialOS Launcher which you should already have by now after following the setup guide. Select Launch again.

The SpatialOS Launcher window should pop up, informing you that it is launching a game from your project.

Select Confirm to start your game client!

Test it out

Open the New Inspector from the deployment overview page to help you validate that movement is being replicated properly.

Choose the [Default] Workers view and select “Run Query”, to start streaming world data.

In case you forgot, here’s a reminder of what to test in the game:

  • Use WASD and mouse to move and rotate the camera.
  • Hit spacebar to spawn new spheres in the world.
  • Make sure spheres are moving periodically.

A major difference between the local and cloud deployments is that you now have two UnityGameLogic workers, as the worker table below might show.

Fortunately, the New Inspector makes it easy to see which workers are authoritative over a given entity through coloured indicators. For example, the connected UnityClient worker and one of the UnityGameLogic workers are authoritative over the player entity of a connected client.

When moving your player, you should notice that the colour of one of these indicators changes depending on the area of the world your player entity is in.

In the example below, pay attention to the dark gold indicator on the player entity in the top-left quadrant of the world. When the player moves to the bottom-right quadrant the dark gold indicator becomes purple, matching that of other entities in that half of the world.

If you keep spawning more spheres you’ll eventually see that the worker boundary lies straight down the middle of the world to form a grid with 2 columns and 1 row, just like you specified in the launch configuration.

Stopping the deployment

Once you’ve finished playing with the deployment, select the Stop button from the SpatialOS console.

What happens if you don’t stop the deployment? Will it run forever?

By default, deployments are stopped automatically 6 hours after they start. To keep the deployments running until 5pm UTC on the next weekday, add the nightly tag.

For longer running deployments, raise a support request (for customers with a service agreement) or ask on our forums.


In this episode, you:

  • Added movement logic to the player and sphere Prefabs.
  • Set up the Transform Synchronization module.
  • Learned about Transform Synchronization strategies.
  • Set up the Transform Synchronization module for our sphere and player objects, so that movement is replicated across workers.
  • Made a custom GameObject creator, based on the default one, that utilised the TransformInternal - component to spawn GameObjects with the correct position and rotation.
  • Learned about the tooling available for managing a cloud deployment.
  • Built out and deployed our game to the cloud!

Updated about a year ago

d. Launch a cloud deployment

Suggested Edits are limited on API Reference Pages

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