This glossary contains the terms you need in order to use the SpatialOS GDK for Unity.

See the SpatialOS Overview documentation for generic SpatialOS terms and concepts:

Access Control List (ACL)

A worker must have access to a SpatalOS component to read or modify it. An access control list (ACL) defines whether a worker is allowed read or write access. The ACL determines:

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

The EntityAcl component describes a SpatialOS entity's ACl and is required on every SpatialOS entity.

In the GDK for Unity, the EntityTemplate class allows you to build an entity's ACL.


Authority (write access)

Many worker instances can connect to a SpatialOS world. However, at most one worker instance is authoritative over each component on a SpatialOS Entity. This worker instance is the only one that can modify the component’s state and handle commands for that component.

An entity’s access control list (ACL) governs which worker types can have authority (or write access) over each component.

SpatialOS manages which specific worker instance has write access over a component. This can change regularly due to load balancing.



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.

Note: The GDK does not support the spatial CLI command spatial worker build.

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.


Code generation

The code generator generates code from schema. Worker instances use generated code to interact with SpatialOS entities.

Code generation 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 manually generate code when you have:

  • Edited the schema
  • Created a new worker type

Note: The GDK does not support the spatial CLI command spatial worker codegen.


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.

  1. Local deployments allow you to start the SpatialOS Runtime locally to test changes quickly.
  2. Cloud deployments run in the cloud. 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 GDK for Unity offers a number of feature modules. Feature modules are optional features that you can choose to include in your game (player lifecycle, for example).

They are intended to:

  • give you a head-start in the development of your game
  • act as reference material for best practices


Game client

A game client is a binary that you use to launch your game. This binary instantiates a client-worker to connect to SpatialOS.


In the GDK, each SpatialOS entity that a worker instance has checked out can be represented as a GameObject.

See the GameObject Creation feature module documentation for more info.



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

In the MonoBehaviour workflow, the GDK performs injection on fields that have the [Require] attribute. A MonoBehaviour is only enabled when all those fields are populated.


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, both 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 from the SpatialOS assembly you uploaded. It is available as an application for Windows and macOS.

From the SpatialOS Console for your cloud deployment, you can use the Launcher to download your game client or generate a share link so anyone with the link can download your game client and join your game.


Locator connection flow

Use this connection flow to:

  • Connect a client worker instance to a cloud deployment via the SpatialOS Launcher.
  • Connect a mobile worker instance to a cloud deployment.
  • Connect a client worker instance to a cloud deployment via your Unity Editor so that you can debug using the development authentication flow.



A worker instance can send and receive messages to and from the SpatialOS Runtime. These messages can be:

  • Component updates: Messages that describe property updates for any SpatialOS component
  • Events: Messages about something that happened to a SpatialOS entity that are broadcasted to all workers.
  • Commands: Messages that are sent directly 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.


Project name

Your project name is randomly generated when you sign up for SpatialOS. It’s usually something like beta_someword_anotherword_000. You can find your project name in the Console.

You must specify this name in the spatialos.json file in the root of your SpatialOS project.


This is a SpatialOS component that denotes whether an entity will be saved into a snapshot. If this component is present on an entity, the entity will be captured in a snapshot. If it is not present, it will not be captured,

Not all entities belong in a snapshot. 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.


This is a SpatialOS component defining the position of an entity in the SpatialOS world. Every SpatialOS entities must have this component.

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

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 to a local deployment
  • connect a server-worker to a cloud deployment
  • connect 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.



Schema is how you define SpatialOS components in your SpatialOS world.

You define your SpatialOS components in .schema files that are written in schemalang.

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


Simulated player

A simulated player is a client-worker instance that is controlled by simulated player logic as opposed to real player input. You can use simulated players to scale-test your game.

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 components' properties.

You use a snapshot as the starting point for your SpatialOS world when you deploy your game.


SpatialOS Assembly

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, an executable and the assets your workers require.

The SpatialOS assembly is stored locally at build\assembly in the root directory of your SpatialOS project. Any SpatialOS assembly that has been uploaded is accessible from the Console.


spatial command-line tool (CLI)

We recommend that you use the in-Editor tooling for interacting with the spatial CLI. Some commands may not work out of the box otherwise.

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

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 your entities that you want to be shared between workers. Components are defined as files in your schema.

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.

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


SpatialOS Console

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


SpatialOS 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.


SpatialOS project

A SpatialOS project is the source code, assets, and configuration of a game that runs on SpatialOS.

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


SpatialOS Runtime

A SpatialOS Runtime instance manages the SpatialOS world of its 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.

SpatialOS 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 and understand the difference between the SpatialOS world and a worker's view.

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 data-driven pattern of writing code. 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

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

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

Generated Unity ECS components can be injected into systems, read, and modified just as normal Unity ECS components can.


Unity ECS 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 write 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

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 coupled to its ECS world.


Unity packages

In Unity there are two types of packages:

  • 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. 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 packages are Unity packages.

Unity Project

A Unity project using the SpatialOS GDK contains the source code and assets of a SpatialOS game's Unity workers.

Update Order

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.



Workers are server-side and client-side software. They perform the computation associated with a SpatialOS world: they are responsible for iterating on the game simulation and updating the definitive state of the game.

Worker types and worker instances

When you develop your game, you set up worker types. These are like molds for the worker instances which do the actual computation.

Worker instances are the programs that compute and connect a SpatialOS world. In general, you use one or more server-worker instances to compute the world, and each player’s client software uses a client-worker instance to interact with the world.


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 typically tasked with visualizing what’s happening in the SpatialOS world and handling player input.


A server-worker is a worker instance 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 typically tasked with running game logic and physics simulation.


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.

Worker flags can be modified at runtime through:


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 checked 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’s view

A worker’s view consists of all SpatialOS entities that a worker is 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 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.

Write access

Many worker instances can connect to a SpatialOS world. However, at most one worker instance can have write acesss on a component on a SpatialOS entity. This worker instance is the only one that can modify the component’s state and handle commands for that component.

An entity’s access control list (ACL) governs which worker types can have write access (or authority) over each component.

SpatialOS manages which specific worker instance has write access over a component. This can change regularly due to load balancing.


Updated about a year ago


Suggested Edits are limited on API Reference Pages

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