The Starter Template

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 SpatialOS cloud project name.
  • Prepare the game’s server-workers and client-workers by building workers.
  • Upload the built-out worker assemblies to the cloud.

Schema and snapshot
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 generate a schema or snapshot. However, when you do make any changes to the project, you must generate schema and create a snapshot before launching a local or cloud deployment.

Hosting cost
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 Starter Template.

Step 1: Associate your game with a SpatialOS cloud project

When you signed up for SpatialOS, your account was automatically associated with an organisation and a SpatialOS cloud project, both of which have the same generated name. You need to associate your game project (your version of the Unreal Starter Template project) with this SpatialOS cloud project name.

Tip: If you have already associated a game project with this SpatialOS cloud project name, you can associate the Unreal Starter Template project with it too. The cloud project can have different game projects associated with it.

  1. Find the cloud project by going to the Console.
    The name should look something like beta_randomword_anotherword_randomnumber. In the example below, it’s beta_yankee_hawaii_621.

    Image: The SpatialOS Console with a cloud project name highlighted.

  2. In File Explorer, navigate to the <YourProject>/spatial directory and open the spatialos.json file in a text editor of your choice.

  3. In the file, locate the name field at the top - it defaults to demo. Replace demo with the SpatialOS cloud project name shown in the Console (beta_yankee_hawaii_621 using the example above). This associates your Unreal game with your SpatialOS cloud project, telling SpatialOS which cloud project you are uploading your built-out worker assemblies to.

Note: Ensure you only change the name field at the top of the file. If you change any other settings, the deployment could fail.

Step 2: Build workers

Note: Make sure you close your Unreal Editor before you build workers. If the Editor is open when you try to build workers, the command fails.

There are two ways to build workers, and you can choose which one to use. You need to build both server-workers and client-workers.

  • Build workers automatically using the BuildProject.bat script with no flags

    When you use this script with no flags, it automatically builds both the server-workers and client-workers to run your game in the cloud. It then compresses your workers and saves them as .zip files to the <ProjectRoot>\spatial\build\assembly\worker directory, ready to upload. Use the script with no flags if you want to build server-workers and client-workers at the same time.

    To do this:
    1. Close your Unreal Editor - if the Editor is open when you try to build workers, the command fails.
    2. In File Explorer, navigate to the <ProjectRoot> directory.
    3. Double-click BuildProject.bat.
      This opens a command line window and automatically builds your client-workers and server-workers.

      Problems building workers? See the Troubleshooting guide below.

  • Build workers manually using the command line - with optional flags

    Run the BuildProject.bat script with added flags from 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 now, you need to build server-workers and client-workers, so if you haven’t run BuildProject.bat from File Explorer you need to:

    1. Close your Unreal Editor - if the Editor is open when you try to build workers, the command fails.
    2. Open a terminal window and navigate to the <ProjectRoot> directory.
    3. Run the BuildProject.bat command to build a server-worker using the filepath and flags below.
      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>Server Linux Development <YourProject>.uproject

      • Project plugin filepath:

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

    4. Now run the BuildProject.bat command to build a client-worker:

      • 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

Whichever way you built workers, you now have one (or two) built-out worker assemblies as .zip files in your <ProjectRoot>\spatial\build\assembly\worker\ directory. BuildProject.bat creates one .zip file in this directory every time you run it.


Problems with building workers?

Step 3: Upload built-out workers

Now you can upload your built-out sever-worker and client-workers’ assembly .zip file(s) to the cloud.
When you do this, you also create an assembly name for the .zip file(s) that you upload. In this example, we are using myassembly but you can use any name you like with alpha-numberic characters.
The assembly name is how you identify the group of .zip files in this upload on the SpatialOS cloud servers.
To do this:

  1. In a terminal window, navigate to your <ProjectRoot>\spatial\ directory.
  2. Run the following command:
    spatial cloud upload myassembly

    (Remember to replace myassembly with a name for your assembly - for example: mygdktemplateassembly1).

    The upload command looks like this:

    spatial cloud upload mygdktemplateassembly1


Problems with uploading workers?

Step 4: Launch your cloud deployment

The next step is to launch a cloud deployment using the assembly that you just uploaded. You can do this in Unreal Editor or using the SpatialOS CLI’s commands. This guide uses Unreal Editor.

As part of this step, you can choose to launch some simulated players with your deployment. Simulated players are game clients mimicking real players of your game. You can use them for testing client connection flow and server-worker load at scale.

Tip: You can use the CLI’s commands individually from the command line or use them for continuous integration by setting up automated commands to build workers and launch cloud deployments.

To launch a cloud deployment from Unreal Editor:

  1. On the GDK toolbar, select Deploy.

    GDK toolbar "Deploy" button
    Image: The GDK toolbar’s Deploy button

    This opens the Cloud Deployment dialog box:

    Image: The Cloud Deployment dialog box

  2. In the dialog box, enter the following information in the relevant fields:

    • Project Name: The SpatialOS cloud project name you associated with your Unreal project in Step 1, above.
      (In the example it was beta_yankee_hawaii_621.)

    • Assembly Name: The name you gave the assembly you uploaded in Step 3, above.
      (In the example it was myassembly.)

    • Deployment Name: You need to create a name for your deployment and add it here, this name labels the deployment in the Console.
      (In the example dialog box shown, it’s mydeployment but it can be whatever you choose and contain any alpha-numeric characters.)

    • Launch Config File: The absolute filepath the your Unreal project’s .json launch configuration file from C:/.
      This is: C:/...<filepath>.../<ProjectRoot>/spatial/one_worker_test.json.
    • Snapshot File: The absolute filepath to your project’s .snapshot snapshot file from C:/.
      This is: C:/...<filepath>.../<ProjectRoot>/spatial/snapshots/default.snapshot.

    • Region: The real-world geographical location that you want your cloud deployment hosted in.
      You can change this by selecting a different region from the drop-down list. You might prefer the region you are in.

  3. You can also choose to add simulated players via the dialogue box or skip this and move on to step 4.

    Build out the simulated player clients 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 

    Then, back in the Editor Deploy window:

    • Add simulated players: Check the box.

    • Deployment Name: Enter a name for your simulated player deployment. This labels the deployment in the Console. Make it different to your game deployment name.

    • Number of Simulated Players: Choose the number of simulated players you want to start.

    • Region: The real-world geographical location that you want your simulated players cloud deployment hosted in.
  4. Select Launch deployment.
    Your deployment(s) won’t launch instantly - the Editor launches a console window which shows the progress of the deployment.
    When your deployment(s) have launched, you can open the Console at to view them.

Tip: You can set default values for all the fields in the cloud deployment dialog box, using the Cloud section of the SpatialOS Editor Settings panel.

> Next: 4: Play the game

2019-11-14 Page updated without editorial review: added callout for plugins which won’t run on Linux.
2019-10-31 Page updated without editorial review: add missing build step for simulated player clients.
2019-08-12 Page updated with editorial review: updated terms and narrative.
2019-07-22 Page updated with limited editorial review.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums