Get SpatialOS




Note: This glossary only contains the concepts you need to understand in order to use the SpatialOS GDK for Unity. See the core concepts and glossary sections for a full glossary of generic SpatialOS concepts.

Note: There are many concepts in this glossary that mean different things in different contexts. When semantically overloaded words or phrases are unavoidable, we explicitly prefix them to avoid confusion. .NET assemblies (.NET documentation) and SpatialOS assemblies are an example of this.

Access Control List (ACL)

In order to read or modify a SpatalOS component, a worker needs to have access to that component. Whether a worker is allowed read or write access is defined by an access control list (ACL). ACLs are components themselves, and are required on every SpatialOS entity. The ACL determines:

  • At an entity level, which workers have read access
  • At a component level, which workers may have write access

In the SpatialOS GDK, the EntityTemplate implementation allows you to add ACL components to entities.



Also known as “write access”.

Many workers can connect to a SpatialOS world. Each component on a SpatialOS Entity has no more than one worker that is authoritative over it. This worker is the only one able to modify the component’s state and handling commands for that component. Authority is sometimes called write-access.

Which types of workers can have authority (or write access) is governed by each entity’s access control list (ACL). Which specific worker actually has write access is managed by SpatialOS, and can change regularly due to load balancing.



The GDK does not support the spatial command-line tool command spatial worker build.

If you want to start a cloud deployment, you must first build your game in order to be able to upload the resulting binaries to your cloud deployment.

The guide on how to build your game explains this process step by step.

Checking out

Each individual worker checks out only part of the SpatialOS world. This happens on a chunk-by-chunk basis. A worker “checking out a chunk” means that:

  • The worker has a local representation of every SpatialOS entity in that chunk
  • The SpatialOS Runtime sends updates about those entities to the worker

A worker checks out all chunks that it is interested in.



Not to be confused with Game client

While the lifecycle of a server-worker is managed by the SpatialOS Runtime, the lifecycle of a client-worker is managed by the game client.

Client-workers are mostly tasked with visualizing what’s happening in the SpatialOS world. They also deal with player input.


Code generation

The GDK does not support the spatial command-line tool command spatial worker codegen.

Generated code is generated from the schema. It is used by workers to interact with SpatialOS entities. Using generated code, workers can:

Code generation automatically occurs when you open the Unity Project in your Unity editor. You can also manually trigger code generation from inside your Unity Editor by selecting SpatialOS > Generate code. You only need to do this when you have:

  • Edited the schema
  • Created a new worker



Before the worker can interact with the SpatialOS world, the worker must connect to SpatialOS. The connection is established using the Improbable.Gdk.Core.Worker class. See Connecting to SpatialOS for more information.



Not to be confused with the Unity Console Window

The Console is the main landing page for managing cloud deployments. It shows you:


Core module

The Unity project inside the GDK consists of the core module and a number of feature modules. The core module is compulsory. It provides core functionality to enable your game to run on SpatialOS. It is located at UnityGDK/workers/unity/Packages/com.improbable.gdk.core and consists out of the following Unity packages:

  • SpatialOS GDK Core (com.improbable.gdk.core)
  • SpatialOS GDK Test Utils (com.improbable.gdk.testutils)
  • SpatialOS GDK Tools (

These packages provide the the basic implementation to synchronize with the SpatialOS Runtime and additional tooling for generating code and testing your game.



When you want to try out your game, you need to deploy it. This means launching SpatialOS itself. SpatialOS sets up the world based on a snapshot, then starts up the server-workers needed to run the world. There are two types of deployment: local and cloud.

Local deployments allow you to start the SpatialOS Runtime locally to test changes quickly.

As their name suggests, cloud deployments run in the cloud on nodes. They allow you to share your game with other people, and run your game at a scale not possible on one local machine. Once a cloud deployment is running, you can connect game clients to it using the Launcher.


Feature modules

The Unity project inside the GDK consists of the Core module and a number of feature modules. Feature modules are optional features that you can choose to include or exclude from your game (player lifecycle, for example). They are intended both to give you a head-start in the development of your game, and act as reference material for best practices to use when writing your own features.

The core module and all feature modules are Unity packages and located at <path to GDK repo>/workers/unity/Packages/.


Game client

Not to be confused with client-worker

A game client is a binary. A client-worker is an object instantiated by said binary.


In the GDK, each SpatialOS entity that a worker has checked out is represented as a Unity ECS Entity. Additionally, you can represent a SpatialOS entity as a GameObject. See the GameObject Creation feature module documentation for more info.



The term “inject” refers to when a field is populated automatically, either by Unity or the SpatialOS GDK.

In the MonoBehaviour workflow the GDK performs injection via reflection using the [Require] attribute to allow you to interact with SpatialOS. A MonoBehaviour is only enabled when all of its dependencies are populated.

In the ECS workflow, Unity performs injection via reflection using the Inject attribute inside systems to iterate over all the Unity ECS Entities matching a required Unity ECS component type.


The Inspector is a web-based tool that you use to explore the internal state of a SpatialOS world. It gives you a real time view of what’s happening in a deployment, locally or in the cloud. Among other things, it displays:



The Launcher is a tool that can download and launch game clients that connect to cloud deployments. It’s available as an application for Windows and macOS. From the Console, you can use the Launcher to connect a game client to your own cloud deployment, or generate a share link so anyone with the link can download a game client and join your game.

The Launcher downloads the client executable from the SpatialOS assembly you uploaded.


Locator connection flow

From SpatialOS v13.5, there are two versions of the Locator connection. The new v13.5+ Locator, in alpha, has additional functionality to the existing v10.4+ Locator which is the stable version.

v10.4+ Locator connection flow (stable version)

Use this Locator connection flow to: * Connect a client-worker to a cloud deployment via the SpatialOS Launcher - see SpatialOS documentation on the Launcher

New v13.5+ Locator connection flow (alpha version)

Use this Locator connection flow to:

Note that there are other ways to connect a client-worker to a cloud deployment without using the Locator flow.



A worker can send and receive updates and messages to and from the SpatialOS Runtime. While updates are simply property updates for any SpatialOS component that the worker is interested in, messages can be either

  • Events: messages about something that happened to a SpatialOS entity that are broadcasted to all workers.
  • Commands: Messages used to send a direct message to another worker that has write access over the corresponding SpatialOS component.



A MonoBehaviour stores the data and logic that defines the behaviour of the GameObject they are attached to. We provide support to interact with SpatialOS using MonoBehaviours. This allows you to use the traditional MonoBehaviour workflow using GameObjects from the very beginning, without having to worry about the ECS.



Not to be confused with Worker

A node refers to a single machine used by a cloud deployment. Its name indicates the role it plays in your deployment. You can see these on the advanced tab of your deployment details in the Console.

Project name

Not to be confused with SpatialOS Project or Unity Project.

Your project name is randomly generated when you sign up for SpatialOS. It’s usually something like beta_someword_anotherword_000.

You must specify this name in the spatialos.json file in the root of your SpatialOS project when you run a cloud deployment.

You can find your project name in the Console.


Persistence is a SpatialOS component in the standard schema library. It’s optional, but all SpatialOS entities that you want to persist in the world must have this component. Persistence means that entities are saved into snapshots.

If an entity doesn’t have this component, it won’t be captured in snapshots. This is fine for transient entities. For example, you probably don’t want the entities associated with players to be saved into a snapshot you take of a deployment, because the players won’t be connected when you restart the deployment.


Position is a component in the standard schema library; all SpatialOS entities must have this component. It lets SpatialOS know what the position of an entity in the world is.

This is used by SpatialOS few specific purposes, like load balancing and queries.

Reactive component

Reactive components are a special type of Unity ECS component that are used to react to changes and messages received by the SpatialOS Runtime. The SpatialOS Runtime attaches reactive components to a Unity ECS Entity representing a SpatialOS entity for the duration of one update.

An example reactive component is the ComponentAdded component. It is added to an Unity ECS Entity representing a SpatialOS entity when a new SpatialOS component has been added to the SpatialOS entity. The GDK adds the corresponding ECS component automatically to the ECS entity, however you might want to run additional systems to react to this change in the current update loop. The ComponentAdded component is removed when the CleanReactiveComponentsSystem runs.

Reactive components contain all updates and messages received during the last update loop. In every update loop, the contents of a reactive component are processed by whichever Unity ECS System is set up to react to those state changes or messages.


Receptionist connection flow

The Receptionist service allows for a direct connection to the SpatialOS runtime and is the standard flow used to * connect any type of worker in a local deployment * connecting a server-worker in a cloud deployment * connecting a client-worker when using spatial cloud connect external.


Read access

Access control lists define which workers can have read access over an entity. Read access is defined at the entity level: if a worker can read from an entity, it is allowed to read from all components on that entity.



Also referred to as “synchronization”.

Replication is the process by which all workers in the SpatialOS world maintain a consistent model of that world. It can be achieved using standard replication.


A server-worker is a worker whose lifecycle is managed by SpatialOS. When running a deployment, the SpatialOS Runtime starts and stops server-workers based on your chosen load balancing configuration.

Server-workers are usually tasked with implementing game logic and physics simulation.

You can have one server-worker connected to your deployment, or dozens, depending on the size and complexity of your SpatialOS world.



In the GDK, a Unity Scene stores GameObjects that you might use to represent your SpatialOS entities. Each Scene can interact with multiple Unity ECS worlds.

Scenes are an abstraction used to represent the part of the SpatialOS world that the workers defined in the Scene have checked out. > Related: Unity Manual: Scenes


The schema is where you define all the SpatialOS components in your SpatialOS world.

You define your schema in .schema files that are written in schemalang. Schema files are stored in the schema folder in the root directory of your SpatialOS project.

SpatialOS uses the schema to generate code. You can use this generated code in your workers to interact with SpatialOS entities in the SpatialOS world.


Simulated Player

Simulated players are client-worker instances running in the cloud, mimicking real players of your game from a connection-flow and server-worker load perspective. To SpatialOS they are indistinguishable from real players, so this is the recommended approach to regular scale testing.

In the FPS Starter Project, simulated players are hosted in a separate deployment to ensure that they do not share resources with UnityGameLogic server-worker instances. They are managed by Simulated Player Coordinator worker-instances.

Simulated Player Coordinator

A simulated player coordinator is a server-worker responsible for launching simulated players, connecting them into a game deployment, and managing their lifetime.


A snapshot is a representation of the state of a SpatialOS world at some point in time. It stores each persistent SpatialOS entity and the values of their SpatialOS componentsproperties.

You’ll use a snapshot as the starting point (an initial snapshot) for your SpatialOS world when you deploy your game.


SpatialOS Assembly

Not to be confused with .NET assembly (.NET documentation).

A SpatialOS assembly is created when you build your workers. It contains all the files that your game uses at runtime. This includes the compiled code and an executable and the assets your workers use (like models and textures used by a client to visualize the game).

The SpatialOS assembly is stored locally at build\assembly in the root directory of your SpatialOS project. When you start a cloud deployment, your SpatialOS assembly is uploaded and becomes accessible from the Console.


spatial command-line tool (CLI)

The spatial command-line tool provides a set of commands that you use to interact with a SpatialOS project. Among other things, you use it to deploy your game (using spatial local launch or spatial cloud launch).


SpatialOS component

Not to be confused with a Unity ECS component

A SpatialOS entity is defined by a set of components. Common components in a game might be things like Health, Position, or PlayerControls. They’re the storage mechanism for data about the world that you want to be shared between workers.

Components can contain:

  • properties, which describe persistent values that change over time (for example, a property for a Health component could be “the current health value for this entity”.)
  • events, which are transient things that can happen to an entity (for example, StartedWalking)
  • commands that another worker can call to ask the component to do something, optionally returning a value (for example, Teleport)

A SpatialOS entity can have as many components as you like, but it must have at least Position and EntityAcl. Most entities will have the Metadata component.

Unlike Unity ECS components, it is not possible to add or remove SpatialOS components on already existing SpatialOS entities.

Components are defined as files in your schema.

Entity access control lists govern which workers can read from or write to each component on an entity.


SpatialOS entity

Not to be confused with a Unity ECS Entity.

All of the objects inside a SpatialOS world are SpatialOS entities: they’re the basic building blocks of the world. Examples include players, NPCs, and objects in the world like trees.

SpatialOS entities are made up of SpatialOS components, which store data associated with that entity.

Workers can only see the entities they’re interested in.

For example, for client-workers built using Unity, you might want to have a prefab associated with each entity type, and spawn a GameObject for each entity the worker has checked out.

You can have other objects that are not entities locally on workers - like UI for a player - but no other worker will be able to see them, because they’re not part of the SpatialOS world.


SpatialOS project

Also referred to as “your game”.

Not to be confused with Unity Project or project name.

A SpatialOS project is the source code of a game that runs on SpatialOS. We often use this to refer to the directory that contains the source code, the UnityGDK directory in this case.

A SpatialOS project includes (but isn’t limited to):


SpatialOS Runtime

Not to be confused with the SpatialOS world Also sometimes just called “SpatialOS”.

A SpatialOS Runtime instance manages the SpatialOS world of each deployment by storing all SpatialOS entities and the current state of their SpatialOS components. Workers interact with the SpatialOS Runtime to read and modify the components of an entity as well as send messages between workers.

New SpatialOS Runtime (available from SpatialOS version 13.4)

From SpatialOS version 13.4 there is a new SpatialOS Runtime. It consists of three elements:

It also contains a new feature: Query-based interest.

The GDK for Unity version Alpha 0.1.4, uses the new SpatialOS Runtime (available from SpatialOS version 13.4); wherever the documentation refers to the “Runtime”, it means the new v13.4+ SpatialOS Runtime.


SpatialOS world

Not to be confused with the Unity ECS World

The SpatialOS world is a central concept in SpatialOS. It’s the canonical source of truth about your game. All the world’s data is stored within SpatialOS entities - specifically, within their SpatialOS components.

SpatialOS manages the world, keeping track of all entities and their state.

Changes to the world are made by workers. Each worker has a view onto the world (the part of the world that they’re interested in), and SpatialOS sends them updates when anything changes in that view.

It’s important to recognize this fundamental separation between the SpatialOS world and the subset view of that world that an individual worker checks out. This is why workers must send updates to SpatialOS when they want to change the world: they don’t control the canonical state of the world, they must use the Worker SDK API to change it.

Standard replication

Also referred to as “automatic synchronization”.

The GDK performs replication in the Unity ECS world via the Improbable.Gdk.Core.SpatialOSSendSystem system, which generates replication handlers for all SpatialOS components defined in the schema.

When writing game logic you don’t need to worry about synchronisation code. Standard replication handles this automatically.

Starter project

The GDK has two starter projects, the First Person Shooter (FPS) Starter Project and the Blank Starter Project. They provide a solid foundation for you to build an entirely new game on-top of SpatialOS GDK for Unity.

Temporary Components

Temporary components are a special type of Unity ECS components. By adding the [RemoveAtEnd] attribute to an ECS component, the GDK will remove components at the end of an update.

Unity Assembly Definition files

We use .NET assemblies (.NET documentation) to structure the GDK. Unity Assembly Definition (.asmdef) files define a set of scripts as a .NET assembly. They also define how, and under what circumstances, these .NET assemblies should be generated.

The benefits of using Unity assembly definition files are:

  • A comprehensible Unity project structure.
  • A guarantee that scripts will only run on the platforms (Unity documentation) that they are intended for.
  • A guarantee that scripts will only run when they are required. This minimizes build times.


Unity ECS

Unity’s Entity Component System (ECS) is a way of writing code that focuses on the data and behavior that make up your game. It is distinct from Unity’s existing MonoBehaviour based workflow.

The GDK uses the Unity ECS as the underlying implementation of its Core while enabling users to follow the traditional MonoBehaviour workflow.


Unity ECS component

Not to be confused with a SpatialOS component

Just as Unity ECS Entities represent SpatialOS entities, Unity ECS components represent SpatialOS components in the Unity ECS World.

Unity ECS components contain only data and are represented as structs rather than classes. This means that they are passed by value instead of by reference. Any behaviour that you want to associate with an ECS component needs to be defined in a Unity ECS system.

The GDK generates ECS components from schema. This enables you to interact with SpatialOS components using familiar workflows in your Unity Editor.

Generated Unity ECS components can be injected into systems, read, and modified just as normal Unity ECS components can. Additionally, the generated code enables you to send and receive updates and messages from and to SpatialOS.


Unity ECS Entity

Not to be confused with a SpatialOS entity

In the GDK you represent a SpatialOS entity as a Unity ECS Entity. Every SpatialOS component that belongs to a SpatialOS entity is represented as an Unity ECS component on the corresponding ECS Entity.


Unity ECS system

The code you use to perform operations on Unity ECS Entities and their components exist in the form of Unity ECS Systems that can be added to ECS worlds. They act, in bulk, on all of the entities in the Unity ECS world that contain the components you tell them to act on. For example, a health system might iterate over all entities that have health and damage components, and decrement health components by the value of the damage components.

Unity ECS world

Not to be confused with the SpatialOS world

The Unity ECS world is a new abstraction introduced by Unity to enable their Entity Component Systems. An ECS world contains a collection of ECS entities and systems to perform logic on these entities.

In the GDK, ECS worlds (and everything in them) are an abstraction used to represent the part of the SpatialOS world that a worker has checked out. A worker is tightly coupled to its ECS world and defines which ECS entities belong to this world and which systems are run.


Unity packages

In Unity there are two types of packages (Unity documentation):

  • Asset packages, available on the Unity Asset Store, which allow you to share and re-use Unity Projects and collections of Assets.
  • Unity packages, available through the Package Manager window (Unity documentation). You can import a wide range of Assets, including plugins directly into Unity with this type of package.

In the GDK each feature module, and the core module, consists of Unity packages. They are located at UnityGDK/workers/unity/Packages/. This allows you to choose which feature modules you want to include in your game.

Unity Project

Not to be confused with SpatialOS Project or project name.

A Unity project is the source code and assets of a SpatialOS game’s Unity workers. We often use this to refer to the directory that contains Unity code and assets, <path to the GDK repo>/workers/unity in this case.

Update Loop

The Unity ECS updates all systems on the main thread. The order in which they are updated is based on constraints that you can add to your systems.



The SpatialOS Runtime manages the SpatialOS world: it keeps track of all the SpatialOS entities and their SpatialOS components. But on its own, it doesn’t make any changes to the world.

Workers are programs that connect to a SpatialOS world. They perform the computation associated with a world: they can read what’s happening, watch for changes, and make changes of their own.

There are two types of workers, server-workers and client-workers.

In order to achieve huge scale, SpatialOS divides up the SpatialOS entities in the world between workers, balancing the work so none of them are overloaded. For each SpatialOS entity in the world, it decides which worker should have write access to each SpatialOS component on the SpatialOS entity. To prevent multiple workers writing to a component at the same time, only one worker at a time can have write access to a SpatialOS component.

As the world changes over time, the position of SpatialOS entities and the amount of work associated with them changes. Server-workers report back to SpatialOS how much load they’re under, and SpatialOS adjusts which workers have write access to components on which SpatialOS entities (and starts up new workers when needed). This is called load balancing.

Around the SpatialOS entities they have write access to, each worker has an area of the world they are interested in.

A worker can read the current properties of the SpatialOS entities within this area, and SpatialOS sends updates and messages about these SpatialOS entities to the worker.

If the worker has write access to a SpatialOS component, it can send updates and messages: it can update properties, send and handle commands and trigger events.

See also the Workers in the GDK documentation.


Worker attribute

Worker attributes are used to denote a worker’s capabilities. The SpatialOS runtime uses these attributes to delegate authority over SpatialOS components in combination with the defined ACL. A worker’s attributes are defined in its worker configuration JSON.


Worker flags

A worker flag is a key-value pair that workers can access during runtime. Worker flags can be set in their launch configuration or added/changed/removed at runtime through the SpatialOS console. This SpatialOS documentation describes how to define and change worker flags.

Worker SDK

The GDK is built on top of a specialized version of the C# Worker SDK. This specialized C# Worker SDK is itself built on top of the C API. The Worker SDK handles the implementation details of communicating to the SpatialOS runtime and provides a serialization library.


Worker Origin

The worker origin allows you to translate the origin of all SpatialOS entities checkout out by a given worker. When connecting multiple workers in the same scene, you can use this origin as an offset to ensure no unwanted physical interactions between those game objects occur.

Worker types

There are two generic types of worker that define how you would want to connect these workers and what kind of capabilities they have:

Within these broad types, users can define their own worker sub-types to create more specialized workers.

Worker’s view

A worker’s view consists of all SpatialOS entities that a worker is currently interested in and has checked out. In the GDK, this view is used to populate the worker’s world and to synchronize any changes between the worker’s view and the worker’s world.

Worker’s world

In the GDK, during the creation of a worker, the worker connects to the SpatialOS Runtime and creates an ECS world. The GDK populates this world with ECS entities that represent SpatialOS entities and are currently in the worker’s view. Additionally, the worker adds ECS systems to this world to define the logic that should be run on those ECS entities. The GDK synchronizes this world with the worker’s view stored in the SpatialOS runtime.


The SpatialOS world, also known as “the world” and “the game world”. The world is a central concept in SpatialOS. It’s the canonical source of truth about your game. All the world’s data is stored within SpatialOS entities; specifically, within their components.

SpatialOS manages the world, keeping track of all the SpatialOS entities and what state they’re in. Changes to the world are made by workers. Each worker has a view onto the world (the part of the world that they’re interested in), and SpatialOS sends them updates when anything changes in that view.

It’s important to recognize this fundamental separation between the SpatialOS world and the view (or representation) of that world that a worker checks out locally. This is why workers must send updates to SpatialOS when they want to change the world: they don’t control the canonical state of the world, they must use SpatialOS APIs to change it.

Write access

Also referred to as “authority”.

Many workers can connect to a SpatialOS world. To prevent them from clashing, SpatialOS only allows one worker at a time to write to each SpatialOS component. Write access is defined at the component level.

Which individual worker actually has write access is managed by SpatialOS, and can change regularly because of load balancing. However, the list of workers that could possibly gain write access is constrained by the access control lists.


Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums