Set up your game

Before you set up your game for offloading, you need to prepare your project.

To set up your game for offloading, you must enable SpatialOS multiserver functionality by enabling multiple workers in the Unreal Editor. In addition, if you do not want to use the default Blueprint classes, you must define a load balancing Blueprint class for each type of offloaded worker you want to run.

To do this, there are several steps.

Summary of steps

  1. Specify the number of server-worker instances you want to use.
  2. Define Blueprint classes: Define a Blueprint class for each offloading scenario you need.
  3. Select an offloading scenario for each map in your game.
  4. Test your changes locally: Launch a local deployment.
  5. Test your changes in the cloud: Launch a cloud deployment.

This page explains how to set up your game for multiserver offloading on Windows only. To set up and run SpatialOS games in the cloud, you need to use a Windows machine for development. We recommend using a Windows machine as your main development environment and macOS for developing and testing game clients on iOS.

Steps in detail

1. Specify the number of server-worker instances you want to use

You can define the total number of server-worker instances that will run, but in most cases, you can allow the SpatialOS Runtime to calculate this, based on your offloading settings.

  1. Open your game project in the Unreal Editor.
  2. In the GDK toolbar, open the Start Deployment drop-down menu.
  3. Select Editor Settings > Launch > Server Worker Config > Automatically compute number of instances to launch in Editor.
    If you want to specify an exact total number of worker instances, for all worker types, you can do so in Instances to launch in editor.

2. Define Blueprint classes

You must select a Blueprint class for each offloading scenario you want to use in your game. You can either:

  • Use one of the pre-defined Blueprint classes in the GDK or
  • Define your own Blueprint class

For example, if you want to offload AI and in-game chat on separate server-worker instances, you might define a single Blueprint to use for both of these offloading scenarios.

If you want to use a predefined Blueprint class, you can skip the rest of this step.

Note: We call each server-worker type a “layer”.

To define your own offloading Blueprint class:

  1. Open your game project in the Unreal Editor.
  2. Define a new Blueprint class, with the parent class SpatialMultiWorkerSettings.
    For information on creating a Blueprint Class, see Unreal’s documentation on Blueprint creation.
  3. In the properties for SpatialMultiWorkerSettings, select the + icon next to Worker Layers.
    This adds a new worker layer (for example worker layer 1).
    Note that there is already a worker layer 0 called DefaultLayer, which you do not need to change. DefaultLayer is the main Unreal server-worker, which handles everything except the server-worker types you define here.

Image: The initial multiworker properties for an offloading Blueprint Class

  1. Expand the new worker layer, for example worker layer 1.
  2. In Name, give the offloaded sever-worker type an appropriate name. It can consist of any alpha-numeric characters, such as NPC.
  3. Declare each Actor class that the offloaded server-worker type will have authority over.
    a. Next to Actor Classes, select the + icon.
    b. In the drop-down next to the element number, select the Actor class you want to offload. See the following image for an example of two Actor Classes (NPCSpawner and Character_NPC) in one server-worker type (NPC).

Image: Example server-worker type and Actor Class settings in the Blueprint Class

  1. Repeat step 6 for each additional Actor class you want the offloaded server-worker type to have authority over. For example, if you want the offloaded server-worker type to have authority over the AI and the weather system, you would add each of these Actor classes to the worker layer (server-worker type) here.
  2. For Load Balance Strategy, select SingleWorkerStrategy.
  3. Repeat steps 3-8 for each additional offloaded server-worker type you want for this offloading scenario.
  4. Compile and save the Blueprint Class.

3. Select an offloading scenario for each map

For each map in your game, you can specify which offloading Blueprint it uses. This means you can have different offloading scenarios for different maps in your game.

Complete the following steps to specify which Blueprint you want to use for a map:

  1. Open your map in the Unreal Editor.
  2. In the World Settings window, select Enable Multi Worker.
  3. In World Settings > Multi- Worker > Multi Worker Settings Class, select the Blueprint you created in section 2.

Snapshots

A deployment requires a snapshot to start successfully. Generating a snapshot sets the authority and interest configurations for SpatialOS Runtime-managed entities, based on the server-worker types and the instances of them that you launch in the deployment. The GDK creates a snapshot for you automatically when you start a deployment (local or cloud).

4. Test your changes locally

Generate schema, and play the game in the Editor. To do this:

  1. In the Unreal Editor’s GDK toolbar, select Schema Generation Options > Schema (Full Scan).
  2. In the Unreal Editor toolbar, select Play.

For more information, see the Local deployment workflow.

5. Test your changes in the cloud

You create a cloud deployment with offloaded worker types in the same way as you did with the standard Unreal GDK cloud deployment.

  1. In the GDK toolbar, select Cloud.
  2. In Project Name, enter your project name. This will be something like beta_someword_anotherword_000, and you can find it in the Console.
  3. In the Assembly Name field, enter a name for the assembly. It can be whatever you choose and contain any alpha-numeric characters.
  4. In the Deployment Name field, enter a name for your deployment. This labels the deployment in the Console. It can be whatever you choose and contain any alpha-numeric characters.
  5. In Snapshot File, select the snapshot you want to use, such as /UnrealGDKExampleProject/spatial/ snapshots/default.snapshot.
  6. Select Automatically Generate Launch Configuration. The GDK for Unreal generates a launch configuration file for you, based on the map you have open in the Unreal Editor.
  7. (Optional) If needed, change the Region.
  8. In the Assembly Configuration section, set the options as follows:
    • Select the Build and Upload Assembly check box
    • Select the Generate Schema check box
    • Select Generate Snapshot check box
    • From the Build Configuration drop-down menu, select Development
      For more information, see Build configurations Reference (Unreal documentation)
    • Select the Build Client Worker check box
    • Select the Force Overwrite on Upload check box
  9. Select Start Deployment.

Image: The Cloud Deployment Configuration dialog box

For more information about building workers and deploying a server-worker assembly to the cloud, see the Cloud deployment workflow.


2020-08-12 Page updated with editorial review: rewrite for new offloading UI and workflow
2020-06-23 Page updated with editorial review: rewrite for new offloading features

Updated about a year ago


Set up your game


Suggested Edits are limited on API Reference Pages

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