2. Design a SpatialOS entity

Define a new SpatialOS entity

Now that we've defined and generated the HealthPickup component and its properties, let's define the HealthPickup entity template!

An entity template simply declares which SpatialOS components are present on the entity, the initial values of those components, and which worker types can read from or write to the components.

The HealthPickup entity is a new type of entity, so we must create a new entity template. To do this, we'll need to add a new function within the FpsEntityTemplates class:

Step 1. In your Unity Editor, locate Assets/Fps/Scripts/Config/FpsEntityTemplates.cs and open it in your code editor.

Step 2. Add using Pickups; and using UnityEngine; to the top of the file to ensure that we can reference the generated Pickups namespace and Unity engine types.

Step 3. Define a new static function within the FpsEntityTemplates class which takes the position of the health pack and the value of the health pack as parameters and returns an EntityTemplate instance:

public static EntityTemplate HealthPickup(Vector3 position, uint healthValue)
    // Create a HealthPickup component snapshot which is initially active and grants "heathValue" on pickup.
    var healthPickupComponent = new Pickups.HealthPickup.Snapshot(true, healthValue);

    var entityTemplate = new EntityTemplate();
    entityTemplate.AddComponent(new Position.Snapshot(Coordinates.FromUnityVector(position)), WorkerUtils.UnityGameLogic);
    entityTemplate.AddComponent(new Metadata.Snapshot("HealthPickup"), WorkerUtils.UnityGameLogic);
    entityTemplate.AddComponent(new Persistence.Snapshot(), WorkerUtils.UnityGameLogic);
    entityTemplate.AddComponent(healthPickupComponent, WorkerUtils.UnityGameLogic);
    entityTemplate.SetReadAccess(WorkerUtils.UnityGameLogic, WorkerUtils.UnityClient); 

    return entityTemplate;

Let's pull out some of the more interesting lines from the above snippet:

  • The line entityTemplate.SetReadAccess(WorkerUtils.UnityGameLogic, WorkerUtils.UnityClient); states that both the server-worker (WorkerUtils.UnityGameLogic) and client-worker (UnityClient) have read access to this entity (that they can see health packs).
  • The line entityTemplate.AddComponent(healthPickupComponent, WorkerUtils.UnityGameLogic); adds an instance of the HealthPickup component to the HealthPickup entity and sets the write access to the UnityGameLogic worker type.

Our design constraints state that we should not trust the client, so we only give write-access to the HealthPickup component to the server-worker. This means that a client cannot change the health value of the health pack or force it to be active.

Position, Metadata, and Persistence are standard library components.

  • Position declares the location of this entity and is used for loadbalancing.
  • Metadata declares the "entity type" and is used to populate the information in the Inspector.
  • Persistence declares whether this entity should be saved to a snapshot.

You can state that a specific client has write-access for a component by passing in a value of workerId: {myWorkerId} for the write access, where myWorkerId is the worker ID of the client.

Some component data should be editable by the player's client, but not by the clients of any other players. In the FPS Starter Project the Player entity template function in FpsEntityTemplates.cs grants the player's client write access over a number of components: clientMovement, clientRotation, clientHeartbeat etc.

You are not restricted to just one worker type being granted write-access. To find out about how to do this, read up about layers.

Updated about a year ago

2. Design a SpatialOS entity

Suggested Edits are limited on API Reference Pages

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