Manage do-once logic

In a single server SpatialOS environment, you can be confident that logic you need to execute only once does execute only once, because there is only one server to implement the logic.

In the SpatialOS multiserver environment, server-worker instances transfer authority over an Actor between servers. You need a mechanism to ensure that do-once logic, such as spawning a particular Actor, occurs only once during your game’s deployment run.

The GDK has an “authority check” mechanism to limit an Actor re-spawning due to its multiserver environment. You can use this to manage do-one logic in your game.

Actor spawning and the authority check

The GDK is set up to ensure that during the execution of an Actor’s BeginPlay function, a call to HasAuthority returns true only once. It returns true only during the initial Actor spawn called by the server-worker instance that has initial authority over it.

If any other server-worker instance gains authority over an Actor, and so triggers a call to BeginPlay, the HasAuthority function returns false and BeginPlay doesn't execute.

The HasAuthority check ensures that only one server-worker instance triggers BeginPlay on an Actor during a deployment run.

Using the authority check for do-once logic

Some Actor types are already guaranteed to exist only once within your deployment: these are core Actors such as the GameMode or GameState and Actors which are statically placed in one Level. These Actor types also have the HasAuthority check. Given this, you can use them as a mechanism to execute do-once logic in your deployment and be certain the logic does execute only once.

Implementation example

For example: you want your game to spawn a global manager Actor at the beginning of your deployment run.

To do this, you can place the global manager’s object construction call inside the HasAuthority check within the BeginPlay function of your GameMode Actor.

Because HasAuthority is only true once in BeginPlay over the lifetime of your game’s deployment run, regardless of how many server-worker instances subsequently have authority over the GameMode Actor, and GameMode is already guaranteed to exist only once in your game’s deployment, you’re guaranteed that the server-worker instances only ever spawn one global manager Actor.

Actor handover

For information on how to handle Actor authority in games built in Unreal, see Actor handover.

2020-09-23 Page updated with editorial review: added link to Actor handover page
2020-08-11 Page created with editorial review

Updated about a year ago

Manage do-once logic

Suggested Edits are limited on API Reference Pages

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