c. GDK player lifecycle

As you can see, the GDK's Player Lifecycle module creates an entity representing a player when a client-worker connects, and manages the lifecycle of this entity with the Heartbeat system (which we’ll cover later).

At a high-level, the client-worker finds all PlayerCreator entities in the world, sends a request to one of them, and waits for a server-worker to create the requested player entity in the world. To do this, the module makes use of World Commands.

World commands

World commands are built-in SpatialOS commands that allow you to create entities (CreateEntity), delete entities (DeleteEntity) and query the world for entities (EntityQuery).

  1. An EntityQuery is used to initially find all PlayerCreator entities in the world.
  2. When handling a player creation request, the CreateEntity world command is called to create the Player entity.
  3. If the client-worker disconnects or becomes unresponsive, the Heartbeat system steps in to delete the Player entity using a DeleteEntity world command.

You can find out more about World Commands here.

Player creation

By default, the module sends a player creation request to a randomly chosen PlayerCreator entity as soon as the client-worker instance connects to SpatialOS. The server-worker instance responsible for simulating the PlayerCreator instance receives the request and then spawns a SpatialOS entity to represent the player. By choosing a random PlayerCreator entity for each request, you can distribute the load of player creation requests across multiple server-workers.

TIP: Custom player creation

You can also customize this behavior to not automatically create a Player entity, instead opting to manually send the player creation request. This option allows you to provide arbitrary serialized data that you can deserialize on a server-worker when handling the request. It also allows you to register a callback on the client-worker, which is run when it receives a player creation response.

You can find out more about custom player creation here.


To ensure that the deployment is not polluted with player entities of unresponsive or disconnected client-workers, the module implements a technique known as heartbeating to periodically remove unresponsive or disconnected clients.

To demonstrate this, first look at the top-right corner of your local Inspector. You should see that a UnityClient and UnityGameLogic worker instance are connected. Select the UnityClient from the list of workers and then select the red Stop worker button.

Image: Stop the client-worker instance UnityClient-*

This displays a Stop worker confirmation dialog box asking if you’re sure. We are - so select Stop worker from the window to kill the client-worker. Immediately you should notice that the UnityGameLogic worker is still there and the UnityClient-worker entity has been removed, but the player entity is still in the world!

Image: Stop worker confirmation dialog box

Not to fear, because after a few seconds you’ll notice the player entity is swiftly removed from the world. The UnityClient-worker entity is managed by SpatialOS, which means that it is deleted as soon as the respective client-worker is disconnected.

The delay in removing the player entity exists because the Heartbeat system requires a minimum number of failed heartbeats before deleting the Player entity. This is to allow some failure tolerance from the client-worker, to avoid removing players for being a little slow at responding to heartbeat requests.

To understand more about how this works, read the Heartbeating documentation.

Updated about a year ago

c. GDK player lifecycle

Suggested Edits are limited on API Reference Pages

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