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

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:

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:

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.

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:

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 examples,
refer to the Unreal Starter Project.

ProcessOps() gets a list of operations from the lower level worker connection API and and passes
them to the dispatcher for processing. For more information about worker connection API,
please see worker::Connection class.

If components are set to use automatic state replication,
you need to add USpatialOSComponentUpdater->UpdateComponents(EntityRegistry, DeltaTime) in every tick
after USpatialOS->ProcessOps() is called.

USpatialOSComponentUpdater->UpdateComponents(EntityRegistry, DeltaTime) will replicate the changes of components of every entity registered in EntityRegistry, except those entities which are destroyed or marked as PendingToBeKilled.