Basic player creation

Before reading this document, make sure you have read the following documentation on:

By default, the module sends a player creation request as soon as the client-worker instance connects to SpatialOS. The server-worker instance receiving the request spawns a SpatialOS entity to represent the player.

To change this behaviour, read the documentation on custom player creation.

Set up your worker connector

You need to add the underlying player lifecycle systems to your worker. Open your WorkerConnector implementations and add one of the following lines to the HandleWorkerConnectionEstablished method.

If this is a client-worker:


If this is a server-worker:


Note: You may need to override the HandleWorkerConnectionEstablished method in your WorkerConnector implementation if you haven't already.

Define the player entity template

The server-worker responsible for handling requests to spawn player entities needs to know which entity template to use when sending the entity creation request to the SpatialOS Runtime.

Create a method that returns an EntityTemplate object and takes the following parameters:

  • string workerId: The ID of the worker that wants to spawn this player entity.
  • byte[] playerCreationArguments: a serialized byte array of arguments provided by the worker instance sending the player creation request.

When defining the entity template, you need to use the PlayerLifecycleHelper.AddPlayerLifecycleComponents method. This method adds the SpatialOS components that are required by the Player Lifecycle Feature Module to the player entity template.

The following code snippet shows an example on how to implement such a method:

public static class PlayerTemplate
    public static EntityTemplate CreatePlayerEntityTemplate(EntityId entityId, string workerId, byte[] playerCreationArguments)
        // Obtain unique client attribute of the client-worker that requested the player entity
        var clientAttribute = EntityTemplate.GetWorkerAccessAttribute(workerId);

        var entityTemplate = new EntityTemplate();
        entityTemplate.AddComponent(new Position.Snapshot(new Coordinates()), "UnityGameLogic");
        // add all components that you want the player entity to have
        PlayerLifecycleHelper.AddPlayerLifecycleComponents(entityTemplate, workerId, "UnityGameLogic");

        return entityTemplate;

Configure the entity template delegate

You need to configure the Player Lifecycle Feature Module to use the player entity template function you defined above. To do this, set the PlayerLifecycleConfig.CreateEntityTemplate field to the function you defined.

For example, you may wish to set this in the WorkerConnector:

private async void Start()
    PlayerLifecycleConfig.CreatePlayerEntityTemplate = PlayerTemplate.CreatePlayerEntityTemplate;
    await Connect(WorkerUtils.UnityClient, new ForwardingDispatcher()).ConfigureAwait(false);

Add a player creator entity to your snapshot

The Player Lifecycle Feature Module relies on the presence of one or more player creator entities in your snapshot. These entities are responsible for receiving a player's request to spawn a player and handle it accordingly.

An entity is marked as a player creator by adding the PlayerCreator component to that entity, for example:

private static void AddPlayerSpawner(Snapshot snapshot)
    var serverAttribute = UnityGameLogicConnector.WorkerType;

    var template = new EntityTemplate();
    template.AddComponent(new Position.Snapshot(), serverAttribute);
    template.AddComponent(new Metadata.Snapshot("PlayerCreator"), serverAttribute);
    template.AddComponent(new Persistence.Snapshot(), serverAttribute);
    template.AddComponent(new PlayerCreator.Snapshot(), serverAttribute);

    template.SetComponentWriteAccess(EntityAcl.ComponentId, serverAttribute);


When your player's client connects to a deployment, it queries for any entities that have the PlayerCreator component and sends the request to spawn a player to a random player creator entity.

Updated about a year ago

Basic player creation

Suggested Edits are limited on API Reference Pages

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