1.4 - 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.


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.

A dialogue window should appear 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!

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.

Next: Summary

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums