Get SpatialOS



SpatialOS entities: How to link SpatialOS entities with GameObjects

This document relates to the MonoBehaviour workflow.

Before reading this document, make sure you are familiar with:

As described in the SpatialOS entity background documentation, you represent SpatialOS entities with GameObjects in a Scene by creating the SpatialOS entity first, then linking it to a GameObject in a Scene.

This document is a guide on how to link a SpatialOS entity with a GameObject using the GameObject Creation Feature Module.

You create SpatialOS entities by creating setting up entity templates. Find out how to do this in the Entity templates documentation.

When you are using the MonoBehaviour workflow, you interact with SpatialOS entities in the Runtime by using Readers and Writers for every SpatialOS entity’s component in schema. Find out how to use interact with SpatialOS entities in the Reader and Writers.

The Creation Feature Module

How to use the GameObject Creation Feature Module

The GameObject Creation Feature Module is a default implementation of how to link SpatialOS entities to GameObjects. To enable the Creation Feature Module in your project:

  1. Set up your project to use the Creation Feature Module.
    • In your Unity project’s Packages directory, locate the Unity Packages manifest manifest.json. Add the Creation Feature Module to the manifest by adding: "com.improbable.gdk.gameobjectcreation": "file:<path-to-gdk>/workers/unity/Packages/com.improbable.gdk.gameobjectcreation"
  2. Set up your workers to use the Creation Feature Module when the WorkerConnector initializes them. To do this, when you use the Worker Connector, call GameObjectCreationHelper.EnableStandardGameObjectCreation(Worker.World). In your project, create a prefab for any SpatialOS entity you want to represent as a GameObject. Where you store the prefab depends on which worker is going to create the GameObject.
    • For any worker, use the Resources/Prefabs/Common/ directory.
    • For specific worker types, use the Resources/Prefabs/<WorkerType> directory where <WorkerType> is the type of worker which is going to make this prefab. (Using this directory makes the prefab available for only for a specific worker type.)
  3. For the SpatialOS entity, you want to represent as a GameObject, in its entity template, set the value of its Metadata component to the name of the prefab you have just set up.

Do not proactively destroy GameObjects representing SpatialOS entities. The GDK manages the lifecycle of these GameObjects so by not destroying these GameObjects, you ensure that your worker’s internal state is not corrupted.

How to customize the GameObject Creation Feature Module

To customize the creation of GameObjects, implement the IEntityGameObjectCreator interface. This interface provides the following methods that the GDK calls:

IEntityGameObjectCreator interface

GameObject OnEntityCreated(SpatialOSEntity entity);


  • SpatialOSEntity entity: A SpatialOS entity that entered your worker’s view.

Returns: The GameObject that should represent the entity. Return null to not link a GameObject to the SpatialOS entity.

void OnEntityRemoved(EntityId entityId, GameObject linkedGameObject);


  • EntityId entityId: The entity ID of the SpatialOS entity that was just removed from your worker.
  • GameObject linkedGameObject: The GameObject that was linked to the SpatialOS entity or null if none was linked.


This is a wrapper around an ECS entity which you can use to easily access its data.

bool HasComponent<T>()

Returns: True, if the ECS entity contains the specified ECS component representing a SpatialOS component, denoted as T.

T GetComponent<T>()

Returns: If the ECS entity has it, returns the ECS component, denoted as T. If it doesn’t have the ECS component, it returns a struct of type T with all its fields initialized with their default values.

Example GameObject creator

This is an example of a simple implementation of a GameObject creator.

 public class YourGameObjectCreator : IEntityGameObjectCreator
    public GameObject OnEntityCreated(SpatialOSEntity entity)
        if (!entity.HasComponent<Metadata.Component>())
            return null;

        var prefabName = entity.GetComponent<Metadata.Component>().EntityType;
        var prefab = Resources.Load<GameObject>(Path.Combine("Prefabs", prefabName));
        if (prefab == null)
            return null;

        return Object.Instantiate(prefab,, Quaternion.identity);

    public void OnEntityRemoved(EntityId entityId, GameObject linkedGameObject)
	     // The linkedGameObject is null here if the method above has returned null
        if (linkedGameObject != null)

To use your own IEntityGameObjectCreator implementation in the GameObject Creation Feature Module, you must call EnableStandardGameObjectCreation(Worker.World, new YourEntityGameObjectCreator()) when initializing your worker.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums