Cloud deployment configuration

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

If you are located in China and using hosting in China, see [CN] Cloud deployment configuration.

The quickest way to start a cloud deployment is to use the Cloud Deployment Configuration dialog box. You can also use the command line for more granular control of worker builds. (See Command-line cloud deployments for more information.)

Note: Cloud deployment is only available from Windows.

Open the dialog box
To open the dialog box, select Cloud on the GDK toolbar.

Image: The GDK toolbar's Cloud button

Complete the 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.
    Associating your Unreal project with a SpatialOS cloud project name tells SpatialOS which cloud project you are uploading your game’s assembly to.

Find your cloud project name at the Console. The name should look something like beta_randomword_anotherword_randomnumber. In the example above, it’s unreal_gdk (it doesn’t follow the name format!).

  • Assembly Name*: Enter a name for your game’s assembly.
    You create the name when you enter it here. In the example shown, it's myassembly but it can be whatever you choose. It can contain alpha-numeric characters, _ (underscores), . (dots), and - (dashes).
    You always use a unique name unless you want to overwrite an existing assembly.
    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. We recommend you leave this box selected. Do not use an unpinned version of the Runtime unless Improbable support engineers advise you to do so.
  • 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. It can contain 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: You usually select this box so it's checked.
    When you select this option, the following happens:
    • The GDK generates a .json launch configuration file automatically from your current region settings and the configuration settings of the map you 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.
    • Your game’s cloud deployment has the same configuration as its local deployment.
  • Launch Config File*: You cannot edit this field with Automatically Generate Launch Configuration selected.
    With Automatically Generate Launch Configuration, the GDK will populate this field with a path to the file it generates. See What is the launch config file? for details.
    If you have created a .json launch configuration file manually, you can use this field to enter a file path to it.
    • Open Launch Configuration editor: 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 and 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: You usually 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: You usually leave this empty.
    If you leave this empty, the GDK automatically adds the tags dev_login and unreal_deployment_launcher.
    Deployment tags are metadata that you can add to a SpatialOS cloud deployment.
    • 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 that you started the deployment with the Cloud Deployment Configuration dialog box.

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 GDK's sample projects, 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 quick and easy cloud deployments, you can 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.

  • Set up simulated players

    You can choose to add simulated players with the dialog box, or skip this section.

    • Add simulated players: Select this box if you want to start simulated players with your game.
    • 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. It can contain alpha-numeric characters and _ (underscores).
      Make it different from your game deployment name and your game’s assembly name.
    • Number of Simulated Players: Enter a number.
      Choose the number of simulated players you want in your game.
      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.
    • 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 simulated players' 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.

    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: You usually select this box so it's checked.
      This instructs the GDK to build the game’s workers and upload its assembly when you select Start Deployment.
    • Generate Schema: You usually select this box so it's checked.
      This instructs the GDK to regenerate the schema for your project and adds the schema file to the game’s assembly.
      When you make changes to your project, you must regenerate the schema before starting a local or cloud deployment. We recommend always generating the schema just in case there are changes.
    • Generate Snapshot: You usually select this box so it's 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. For information, see the Unreal documentation.
    • Build Client Worker: You usually select this box so it's checked.
      This instructs the GDK to build Windows game clients which you can use for testing.
      You only clear this box so it's not checked if you are testing your cloud deployment with game clients running on a mobile device.
    • Force Overwrite on Upload: You usually clear this box so it's not checked.
      If you select this box and the name of your current assembly is the same as an existing assembly, then the GDK overwrites the existing assembly.
      If you clear this box, the GDK does not overwrite any existing version of the project assembly.
      If you re-use an assembly name that is already associated with an existing cloud deployment then you must select this box, otherwise, your assembly upload will fail.

    Once your deployments have started, you can find out about them in your SpatialOS cloud project's Deployments List page in the Console.
    You can select Open Deployment Page to access the page.

    Start the deployment

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

    • Select Start Deployment to initiate a cloud 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. However, if you have changed the networking option for this project, you need to reset it to SpatialOS networking before you build workers.
      There is information on the switch in reference documentation on the toolbar.

    2020-09-08 Page updated with editorial review: added link to the Launch Configuration Editor page.
    2020-08-25 Page added with editorial review: revised the advice and descriptions.
    2020-06-27 Page added with editorial review.

    Updated 11 months ago


    Cloud deployment configuration


    Suggested Edits are limited on API Reference Pages

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