Setting up Unreal as a SpatialOS Worker
Here is what is required to set up Unreal as a SpatialOS worker:
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:
Create a new child class of the
UGameInstance
in your Unreal Enigine 4 project using Unreal Engine 4 editor: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 functionGetSpatialOS()
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 functionGetSpatialOS()
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 functionGetSpatialOS()
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 functionGetSpatialOS()
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.