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 are built-in SpatialOS commands that allow you to create entities (
CreateEntity), delete entities (
DeleteEntity) and query the world for entities (
EntityQueryis used to initially find all PlayerCreator entities in the world.
- When handling a player creation request, the
CreateEntityworld command is called to create the Player entity.
- If the client-worker disconnects or becomes unresponsive, the Heartbeat system steps in to delete the Player entity using a
You can find out more about World Commands here.
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.
Custom player creation
You can also customise this behaviour 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
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.