These are the docs for 12.1, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

The SpatialOS Unreal integration is currently in beta. We’re very open to feedback - don’t hesitate to get in touch on the forums if you have any thoughts.

Running workers from the Unreal editor

UnrealClients and UnrealWorkers can be started and debugged from the Unreal Editor to connect to a running SpatialOS deployment. The following guide shows you how:


You need to follow these steps before you can connect workers and clients.

  1. Enable the SpatialOS editor settings by loading the SpatialOS module in your .uproject:

    "Modules": [
            "Name": "UnrealStarterProject",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "AdditionalDependencies": [
            "Name": "SpatialOS",
            "Type": "Runtime",
            "LoadingPhase": "Default"
    1. Turn off Unreal auto connect: In the ▷ Play drop-down menu, select Advanced Settings.

    Set value of a property

    Make sure that - Run Dedicated Server is disabled. - Auto Connect To Server is disabled. (Set the Number of Players option to a value higher than 1 to make this option editable.) - Use Single Process is enabled.

    1. Open the Project Settings in Unreal Editor, scroll down to the Improbable section and select SpatialOS.

    Set up the worker configurations you want to use when running workers from the Unreal Editor:

    Set value of a property

    Note: You can set up multiple worker configuration instances if you want to run multiple worker instances at the same time.

    1. Edit your code that performs the connection to SpatialOS so that it supplies a WorldContext struct to the ApplyWorkerConfiguration() call:
    void AStarterProjectGameMode::StartPlay()
        auto SpatialOS = GetSpatialOS();
        if (SpatialOS != nullptr)
            auto CurrentWorldContext = GetGameInstance()->GetWorldContext();
            if (CurrentWorldContext != nullptr)

    This will override each of the workers’ configurations with the settings specified in the Project Settings. The worker configuration settings are applied to the first worker instances started up based on the PIEInstance field of their respective WorldContext. If there are more worker instances than worker configurations, no worker configuration is applied to the remaining worker instances.

  2. Set up the number of worker instances to start: In the ▷ Play drop-down menu, change the Number of Players to specify how many Unreal workers or clients you want to start.

    Set value of a property

    For example, if you want to launch one worker and one client:

    • Set the Number of Players to 2
    • Have one Worker Configuration set up with UnrealClient specified in SpatialOS Application > Worker Platform
    • Have one Worker Configuration set up with UnrealWorker specified in SpatialOS Application > Worker Platform

Connect workers and clients

  1. Set up a launch configuration that waits for a manual worker and client. For instructions on how to do this, see Singleton workers. Alternatively, open default_launch.json in your project directory, and modify the num_workers field under load_balancing to 0.
  2. In a terminal, run a local deployment by running spatial local launch.
  3. Press ▷ Play to launch your workers and clients and connect to SpatialOS.

Note: If your client automatically connects to SpatialOS on launch, make sure there is a short delay in the client code or Blueprints to allow the worker to start up and initialise first.

Deploying to the cloud

For information about deploying to the cloud, see Deploying to the cloud.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums