3. Start a cloud deployment

This tutorial is for developers located outside China, using hosting outside China

If you are located in China and using hosting inside China, see the [CN] Example Project quick-start tutorial.

Example Project quick-start: 3 - Start a cloud deployment

Note: You can start cloud deployments from Windows development machines only. You cannot start cloud deployments from macOS development machines.

Before starting a cloud deployment, in addition to generating schema, you also need to:

  • Identify your SpatialOS cloud project name.
  • Select cloud deployment options for your game.
  • Prepare your game’s server-workers and client-workers by building workers.
  • Define your game’s assembly (which contains the built-out workers).

The GDK prepares both your server-workers and client-workers for upload to the cloud by building their executable code from the code in their .uproject files.

We call this "building workers", and the resulting executable code "built-out workers". The GDK generates .zip files for the built-out workers which are then part of the game’s assembly.

An assembly is a collection of files that SpatialOS uses to run your game’s SpatialOS deployment in the cloud.
It contains:

  • Your project’s executable code which is your built-out server-worker and client-worker code in .zip files. SpatialOS uses this to run your game’s deployment in the cloud.
  • The project’s GDK-generated schema .descriptor file to use with the deployment in the cloud.
  • Worker metadata from the worker.json file.
  • When you configure your project for a cloud deployment, you create a unique name for its assembly (unless you want to overwrite an existing assembly).
    You can then identify the group of files in the Console using the assembly name.

    Simulated players
    You have the option to add simulated players to your game before you start a cloud 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.

    Schema
    When you started a local deployment, you generated a schema for it. If you haven’t changed the project since, you don’t need to regenerate a schema. However, when you do make any changes to the project, you must regenerate schema before starting either 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 Example Project.

    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.

    For information about the free tier, and what it provides, see Managed networking services: Free tier.

    For more information about which game templates you can use, see the game templates documentation.

    Step 1: Identify your SpatialOS cloud project

    When you signed up for SpatialOS, your account was automatically associated with an organization and a SpatialOS cloud project, both of which have the same generated name. You need to identify your account’s cloud project name so you can later associate your game project (your version of the Example 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 Example Project with it too. The cloud project can have multiple game projects associated with it.

    1. Find the cloud project name at the Console: https://console.improbable.io/.

    The name should look something like beta_randomword_anotherword_randomnumber.
    In the example below, it’s unreal_gdk (it doesn’t follow the name format!).

    Image: The SpatialOS Console with a cloud project name highlighted

    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 game assemblies you have uploaded, the internal state of any games you have running (via the Inspector), as well as logs, metrics and the Launcher. You will find out more about the Launcher in later steps.

    You can find out more about the Console in the Glossary.

    1. Make a note of the cloud project name; you will need the name later when you set up your cloud deployment configuration.

    Step 2: Prepare the assembly and start a cloud deployment

    As part of this step, you can choose to start some simulated players with your deployment. In the Example Project, simulated players are already set up. However, if you want to use simulated players in your own project, you need to set them up before you can build them.

    For detailed steps, see the simulated players documentation.

    You can also explore the source code of simulated players for insight on how they are set up: search for SimulatedPlayerCharacter_BP in your clone of the Example Project.

    You do not need to set up simulated players in the Example Project to complete this tutorial.

    To start a cloud deployment on Windows:

    1. Open the Example Project in the Unreal Editor.
    2. On the GDK toolbar, select Cloud. This opens the Cloud Deployment Configuration dialog box.
    3. Complete the dialog box, as shown below.

    Image: The GDK toolbar's Cloud button

    The Cloud Deployment Configuration dialog box

    There are three sections to the dialog box: the cloud deployment options, Simulated Players, and Assembly Configuration. Then you can start the deployment.

    Image: The Cloud Deployment Configuration dialog box

    Set up your game’s cloud deployment

    In the dialog box, complete the following information in the relevant fields. Note that to start a cloud deployment, you must complete the starred (*) fields.

    • Project Name*: Enter the SpatialOS cloud project name you want to associate with your Unreal project.
      You made a note of this cloud project name in Step 1: Identify your SpatialOS cloud project, above. In the example in Step 1, it was unreal_gdk.
      Associating your Unreal project with a SpatialOS cloud project name tells SpatialOS which cloud project you are uploading your game’s assembly to.
    • Assembly Name*: Enter a name for your game’s assembly and make a note of it, so that you can refer back to it later.
      You create the name when you enter it here. (In the example shown, it's myassembly but it can be whatever you choose between 5 and 64 characters. It can contain only alpha-numeric characters and _ (underscores), . (dots), and - (dashes).)
      You always use a unique name unless you want to overwrite an existing assembly. To complete this tutorial, use a unique name.
      The Force Overwrite on Upload setting below has more information on overwriting an existing assembly.
    • Use GDK Pinned Version For Cloud: Select this box so it's checked.
      This ensures you use the default (pinned) version of the SpatialOS Runtime. You will rarely need to use an unpinned version.
    • Runtime Version: You can’t change the content of this field when Use GDK Pinned Version For Cloud is selected. It shows which version of the SpatialOS Runtime the GDK uses.
    • Deployment Name*: Enter a name to label the deployment in the Console and make a note of it, so that you can refer back to it later.
      You create the name when you enter it here. (In the example shown, it's mydeployment but it can be whatever you choose between 2 and 32 characters. It can contain only alpha-numeric characters and _ (underscores).)
    • Snapshot File*: Enter the absolute file path to your project's default .snapshot file, located in /UnrealGDKExampleProject/spatial/ snapshots/default.snapshot.
    • Automatically Generate Launch Configuration: Select this box so it's checked.
      When you select this, the GDK generates a .json launch configuration file automatically from your current region settings, and the configuration settings of the map you currently have open.
    • Launch Config File*: Do not edit this. You cannot edit this field with Automatically Generate Launch Configuration selected.
      The GDK will populate this field with a path to the file it generates.
      If you have created a .json launch configuration file manually, you can use this field to enter a file path to it. To complete the tutorial, you do not need to create a launch configuration file.
      • Open Launch Configuration editor: Do not select this.
        You cannot select this with Automatically Generate Launch Configuration selected.
        If you have created or want to create a .json launch configuration file manually, you can use this to open the Launch Configuration editor so you can create or modify the file. To complete this tutorial, you do not need to manually create or modify the launch configuration file.
    • Region: Select the real-world geographical location you are in:
      US (north and south America), EU (Europe), AP (Asia, Pacific but not China).
      The region is the location you want your cloud deployment hosted in.
      (If you are in China, you don’t see this setting, as you are automatically assigned hosting in China.)
    • Deployment Cluster: Leave this empty.
      You can specify the server-node cluster ID you want to use for your cloud deployment. If you leave this empty, SpatialOS picks the most appropriate server-node cluster for the region you have chosen.
      To avoid an invalid region-cluster pairing, if you enter a server-node cluster ID here, you cannot choose a Region setting.
    • Deployment Tags: Leave this empty.
      The GDK automatically adds the tags: dev_login and unreal_deployment_launcher.

    We recommend you always leave the Use GDK Pinned Version For Cloud box selected. Only use an unpinned version of the Runtime on advice from Improbable support engineers.

    By selecting this option, you ensure your game’s cloud deployment has the same configuration as its local deployment.

    The GDK generates the .json launch configuration file, using GDK Editor settings (which have a default), your current region settings, and the configuration settings of the map you currently have open.

    You can check the GDK Editor settings in the SpatialOS Editor Settings panel.
    In your Editor, go to: Edit > Project Settings > SpatialOS GDK For Unreal > Editor Settings > Launch and select the Launch drop-down menu.
    To complete this tutorial, you can leave these on the default settings.

    See the SpatialOS Editor Settings panel for more information.

    This .json file contains the configuration parameters for starting a deployment, including:

  • The game template - defines the compute resources your deployment needs (see the documentation on game templates).
  • dimensionsInWorldUnits - defines the size of your SpatialOS game world in X and Y.
  • Worker types - lists the worker type names you have set up for your project. For the Example Project, this is the two out-of-the-box worker types: the Unreal server-worker UnrealWorker and the Unreal client-worker UnrealClient.

    You can create your own launch configuration .json file and you can call it any name you choose, using alpha-numeric characters. However, for the Example Project tutorial, you use a GDK-generated file by selecting Automatically Generate Launch Configuration.

    You can find out more about the launch configuration file in the SpatialOS Worker SDK documentation: launch configuration file. Note that this may contain additional details on parameters that are not relevant to Unreal projects.

  • dev_login instructs the SpatialOS Runtime to allow a deployment’s simulated players and game clients to bypass the usual client authentication when they connect to the deployment. This enables you to test your game during development.
    Find out more in the documentation on authentication during development.

    unreal_deployment_launcher indicates to you that you started the deployment via the Cloud Deployment Configuration dialog box.

    dev_login and unreal_deployment_launcher are deployment tags. Deployment tags are metadata that you can add to a SpatialOS cloud deployment. Find out more about deployment tagsin the glossary.

    Set up simulated players

    You can choose to add simulated players via the dialog box, or skip this. We recommend you add simulated players as part of this tutorial.
    To do this, complete the following information in the relevant fields:

    • Add simulated players: Select this box so it’s checked.
    • Deployment Name: Enter a name for your simulated player deployment.
      You create the name when you enter it here: in the example shown, it's simdeployment but it can be whatever you choose between 2 and 32 characters. It can contain only alpha-numeric characters and _ (underscores).)
      Make it different to your game deployment name and your game’s assembly name.
    • Number of Simulated Players: Enter 10.
      Choose the number of simulated players you want in your game.
    • Region: Select the real-world geographical location you are in:
      US (north and south America), EU (Europe), AP (Asia, Pacific but not China).
      The region is the location you want your cloud deployment hosted in.
      (If you are in China, you don’t see this setting, as you are automatically assigned hosting in China.)
    • Deployment Cluster: Leave this empty.
      You can specify the server-node cluster ID you want to use for your cloud deployment. If you leave this empty, SpatialOS picks the most appropriate server-node cluster for the region you have chosen.
      To avoid an invalid region-cluster pairing, if you enter a server-node cluster ID here, you cannot choose a Region setting.

    You can specify up to 10 simulated players on the free tier. If you specify more than 10, you might find that your simulated players do not connect. To increase the limit, get in touch.

    Set up your game’s assembly configuration

    Before you start the cloud deployment, the GDK builds the game’s workers and its assembly. You have some options to configure the build and assembly.

    • Build and Upload Assembly: Select this box if it isn’t already checked.
      This instructs the GDK to build the game’s workers and upload its assembly when you select Start Deployment.
    • Generate Schema: Select this box if it isn’t already checked.
      This instructs the GDK to regenerate the schema for your project and adds the schema file to the game’s assembly.
    • Generate Snapshot: Select this box if it isn’t already checked.
      This instructs the GDK to generate a new snapshot for your project to upload the snapshot with the assembly.
    • Build Configuration: Select Development.
      This is Unreal’s build configuration which is the one you usually use during game development.
    • Build Client Worker: Select this box if it isn’t already checked.
      This instructs the GDK to build Windows game clients which you can use for testing. You find out more about these game clients in a later step in this tutorial.
      Clear this box only when you're testing your cloud deployment with game clients running on a mobile device. This tutorial tests with Windows game clients, not mobile game clients.
    • Force Overwrite on Upload: Clear this box so it's not checked.
      This ensures the GDK does not overwrite an existing version of the project assembly. If you select this option and the name of your current assembly is the same as an existing assembly, then the existing assembly is overwritten.
      If you re-use an assembly name that is already associated with an existing cloud deployment then you must select this, otherwise, your assembly upload will fail.

    When you started a local deployment of the Example Project, you generated the schema and a snapshot for it. If you haven’t changed the project since (and if you are following this Example Project tutorial closely, you won’t have), you don’t need to generate the schema or a snapshot again.

    However, when you do make any changes to the project, you must regenerate the schema and a snapshot before starting a local or cloud deployment. We recommend always generating the schema and a snapshot, just in case there are changes.

    These are Unreal’s build configuration options. See the Unreal documentation.

    Once your deployments have started, you can find out about them in the your SpatialOS cloud project's Deployments List page in the Console.
    You can select Open Deployment Page to access the page. You do not need to do this as part of the Example Project tutorial.

    TIP

    In this Example Project tutorial, 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 SpatialOS CLI from the command line to build server-workers or client-workers individually. You can also use CLI commands in continuous integration by setting up automated commands to build workers and launch cloud deployments.
    (You do not need to use the CLI to complete this Example Project tutorial.)

    The SpatialOS CLI has a set of commands for managing and developing SpatialOS projects. You installed the CLI when you installed SpatialOS as part of Get Started: 1 - Get the dependencies.

    For more information on the CLI commands for building workers and launching cloud deployments, see:

  • the the glossary or, for more detail,
  • the Command line cloud deployments documentation.

  • Start the deployment

    Now that you have entered the settings, you can start the deployment:

    • Select Start Deployment to initiate a cloud deployment.

    The default GDK setting auto-connects players' game clients to the cloud deployment. For this tutorial you are auto-connecting game clients. However, for your own game, you might prefer to direct players to a lobby before they connect.

    To stop game clients auto-connecting, enable Prevent Client Cloud Deployment Auto Connect before you select Start Deployment.

    To do this, select the Prevent Client Cloud Deployment Auto Connect checkbox in the SpatialOS Runtime Settings panel (menu: Settings > Project Settings > Runtime Settings).

    See the documentation on the SpatialOS Runtime Settings panel for more information.

    Note: You do not need to select this setting to follow this tutorial.

    When you select Start Deployment, your deployment won’t start instantly. Give it a little time. The GDK runs processes based on your settings in the Cloud Deployment Configuration dialog box before it starts the deployments for your project and simulated players: it generates the schema and a snapshot, and then builds and uploads the assembly before it starts the deployments for your project and simulated players.

    While each process is running, you see a message in a pop-up window in the bottom-right of the Unreal Editor (for example: Building Assembly…). The processes are done when you see the message: Cloud Deployment Started! and the pop-up window closes.

    Troubleshooting building workers

    • Have you changed the SpatialOS networking switch?
      You might need to reset the SpatialOS networking checkbox.
      By default, SpatialOS networking is enabled for GDK projects, including the Example Project, and you selected this in 2. Start a local deployment: Step 2: Start and play.
      However, if you have changed the networking option for this project, you need to reset it to SpatialOS networking before you build workers.
      In addition to this Example Project tutorial, there is information on the switch in reference documentation on the toolbar.

    TIP

    In addition to using the Editor to see and switch your project between native Unreal networking and SpatialOS networking, you can look in its DefaultGame.ini configuration file (located in the /Game/Config directory).
    If there is a bSpatialNetworking option in the file, set it to True to enable SpatialOS networking.
    If there is no SpatialNetworking option, you do not have to do anything, as all GDK sample projects default to using SpatialOS networking.

    There is a summary on when to generate schema, the cloud deployment settings, and how to start your cloud deployment in the Cloud deployment workflow page.
    It is the same workflow as the one you have followed in this Example Project tutorial.

    With the game now deployed in the cloud, you can start playing it by downloading game clients.

    During your game’s development, you can use either downloaded game clients or Play in Editor (PIE) as a game client to playtest your game. For this tutorial, you use downloaded game clients.

    You can connect your PIE client-worker instances to a cloud deployment using spatial cloud connect external. For information, see Connect a client-worker instance to a cloud deployment.


    2020-09-11 Page updated with editorial review: added material about PIE connections to cloud.
    2020-08-10 Page updated with editorial review: clarification of launch configuration settings, remove generate schema before deploying.
    2020-06-23 Page updated with editorial review: added MacOS, mobile, UI and deployment workflow changes.
    2019-05-23 Page added with editorial review.

    Updated 9 months ago



    3. Start 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.