Setting up Unreal as a SpatialOS Worker

Here is what is required to set up Unreal as a SpatialOS worker:

• Directory structure
• The SpatialOS object
• Game instances
• Setting up a connection
• Processing events

Directory structure

For information about the required directory structure (including the mandatory worker.json file which contains most of the configuration), see the Unreal directory structure page.

The SpatialOS object

Use the SpatialOS object to set up a worker and manage its connection. You can also use it to set up callbacks to handle both successful and failed attempts to connect to SpatialOS as well as disconnection callbacks.

Game instances

Note: This step is not necessary, however it is advised as it simplifies the setup of a worker.

We recommend delegating the ownership of the SpatialOS object to an object with a lifetime that matches that of your game (although it can in theory be owned by any class in your project). For example, the class UGameInstance will work well.

To create a new game instance:

1. Create a new child class of the UGameInstance in your Unreal Enigine 4 project using Unreal Engine 4 editor:

   

2. Once created, you need to specify your new game instance in your DefaultEngine.ini file. This can be done either by manually adding the line GameInstanceClass=/Script/YourGameInstanceName under the [/Script/EngineSettings.GameMapsSettings] section or using the Unreal Engine 4 editor:

   

For examples on how to set up the SpatialOS object with a UGameInstance, refer to the RPG demo game instance.

For further documentation on UGameInstance and its usage, refer to the GameInstance tutorial and UGameInstance API reference

Setting up a connection

Set up the OnConnected, OnConnectionFailed and OnDisconnected callbacks

Before you create the connection, register three callbacks on the SpatialOS object which allow you to perform game specific logic as a response to successful/unsuccessful connections as well as disconnection events. For example:

// Get the SpatialOS object from the GameInstance.
auto SpatialOS = GameInstance->GetSpatialOS();
if (SpatialOS != nullptr)
{
    SpatialOS->OnConnectedDelegate.AddDynamic(...);
    SpatialOS->OnConnectionFailedDelegate.AddDynamic(...);
    SpatialOS->OnDisconnectedDelegate.AddDynamic(...); 
}

Note:

• In the code section above, the GameInstance is of the same type as your custom game instance such that access to the function GetSpatialOS() is available.
• The SpatialOS object uses delegates for callback registration. For more info on how to use such delegates, refer to the delegate documentation. Further examples can also be found in the RPG demo.

Creating the connection

To create a connection:

auto SpatialOS = GameInstance->GetSpatialOS();

if (SpatialOS != nullptr)
{
    auto WorkerConfig = FSOSWorkerConfigurationData();

    // populate the worker configuration
    
    // ...

    SpatialOS->ApplyConfiguration(WorkerConfig);
    SpatialOS->Connect();
}

Note: In the code section above, the GameInstance is of the same type as your custom game instance such that access to the function GetSpatialOS() is available.

Use the FSOSWorkerConfigurationData object to specify the configuration of your worker, including properties related to debugging, networking and assembly configuration. For more information, see the in-code documentation for FSOSWorkerConfigurationData.

For examples, see the RPG demo.

Disconnecting a worker

The SpatialOS object is also responsible for initiating the disconnection process and removing all callbacks registered on the SpatialOS object. The example below triggers the disconnection and removes the registered callbacks OnSpatialOsConnected, OnSpatialOsFailedToConnect and OnSpatialOsDisconnect which are member functions of an arbitrary class AClassName:

// Get the SpatialOS object from the GameInstance.
auto SpatialOS = GameInstance->GetSpatialOS();
if (SpatialOS != nullptr)
{
    SpatialOS->Disconnect();

    SpatialOS->OnConnectedDelegate.RemoveDynamic(...);
    SpatialOS->OnConnectionFailedDelegate.RemoveDynamic(...);
    SpatialOS->OnDisconnectedDelegate.RemoveDynamic(...);
}

Note:

• In the code section above, the GameInstance is of the same type as your custom game instance such that access to the function GetSpatialOS() is available.
• The SpatialOS object uses Unreal Engine 4 delegates for callback registration. For more info on how to use such delegates, refer to the Unreal Engine 4 delegate documentation. Furhter examples can also be found in the RPG demo.

Processing events

You can use the SpatialOS object to process incoming ops from the connection. This should ideally be done at a relatively frequent rate such as once per frame.

// Get the SpatialOS object from the GameInstance.
auto SpatialOS = GameInstance->GetSpatialOS();
if (SpatialOS != nullptr)
{
    SpatialOS->ProcessOps();
}

Note:

• In the code section above, the GameInstance is of the same type as your custom game instance such that access to the function GetSpatialOS() is available.
• We recommend calling ProcessOps() in the update function of your active game mode. For further examples on how to do this, refer to the RPG demo.