Note: This glossary only contains the concepts you need to understand in order to use the SpatialOS GDK for Unity. See the core concepts (SpatialOS documentation) and glossary (SpatialOS documentation) 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 EntityBuilder 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 (SpatialOS documentation).
The GDK does not support the
spatialcommand-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.
- 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 (SpatialOS documentation).
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.
The GDK does not support the
spatialcommand-line tool command
spatial worker codegen.
- Read the state of SpatialOS entities and their SpatialOS components.
- Send updates (SpatialOS documentation) to SpatialOS components via the SpatialOS Runtime.
Code generation automatically occurs when you open the Unity Project in the Unity editor. You can also manually trigger code generation from inside the 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 by an instance of the
Improbable.Gdk.Core.Worker class. See Connecting to SpatialOS for more information.
Not to be confused with the Unity Console Window
- Your project name
- Your past and present cloud deployments (SpatialOS documentation)
- All of the SpatialOS assemblies you’ve uploaded
- Links to the Inspector, Launcher, and the logs and metrics page for your deployments.
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 (com.improbable.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.
Also referred to as “custom synchronisation”.
Standard replication is a powerful solution that keeps your SpatialOS world and your Unity ECS World synchronized. However, we recognize that it’s not the perfect solution for everyone. Firstly, as a generic solution, it’s not optimized for your specific game. You may wish to apply custom predicates and filters to minimize network traffic. Secondly, you may wish to update a non-spatial endpoint (such as a database).
Both of these use cases are made possible by custom replication, a system that gives you full control over how a SpatialOS component is replicated.
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.
As their name suggests, cloud deployments (SpatialOS documentation) 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.
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/.
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 How to link SpatialOS entities with GameObjects
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.
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 (SpatialOS documentation) or in the cloud (SpatialOS documentation). Among other things, it displays:
- which workers are connected to the deployment
- how much load (SpatialOS documentation) the workers are under
- which SpatialOS entities are in the world
- what their SpatialOS components’ properties (SpatialOS documentation) are
- which workers are authoritative over each SpatialOS component
The Launcher is a tool that can download and launch game clients that connect to cloud deployments (SpatialOS documentation). 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 (SpatialOS documentation), 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
This is the standard flow used to connect a client-worker to a cloud deployment. As such it is used for connecting game clients to the SpatialOS runtime in production. An authenticated locator service is used to enumerate cloud deployments and connect to a chosen one.
Note that there are other ways (SpatialOS documentation) 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 (SpatialOS documentation) in, messages can be either
- Events (SpatialOS documentation): messages about something that happened to a SpatialOS entity that are broadcasted to all workers.
- Commands (SpatialOS documentation): 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
Your project name is randomly generated when you sign up for SpatialOS. It’s usually something like
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 (SpatialOS documentation) and queries (SpatialOS documentation).
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
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.
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”.
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 (SpatialOS documentation) configuration.
Server-workers are usually tasked with implementing game logic and physics simulation.
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.
You define your schema in
.schema files that are written in schemalang (SpatialOS documentation). Schema files are stored in the
schema folder in the root directory of your SpatialOS project.
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 (SpatialOS documentation).
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)
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 (SpatialOS documentation) or
spatial cloud launch (SpatialOS documentation)).
- An introduction to the
spatialcommand-line tool (SpatialOS documentation). Note that the GDK does not support any
spatialreference (SpatialOS documentation)
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
PlayerControls. They’re the storage mechanism for data about the world that you want to be shared between workers.
Components can contain:
- properties (SpatialOS documentation), which describe persistent values that change over time (for example, a property for a
Healthcomponent could be “the current health value for this entity”.)
- events (SpatialOS documentation), which are transient things that can happen to an entity (for example,
- commands (SpatialOS documentation) that another worker can call to ask the component to do something, optionally returning a value (for example,
A SpatialOS entity can have as many components as you like, but it must have at least
Position (SpatialOS documentation) and
EntityAcl. Most entities will have the
Metadata (SpatialOS documentation) 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.
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.
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 (SpatialOS documentation).
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.
Also referred to as “your game”.
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):
- The source code of all workers used by the project
- The project’s schema
- Optional snapshots of the project’s SpatialOS world (SpatialOS documentation)
- Configuration files, mostly containing settings for deployments (for example, launch configuration files (SpatialOS documentation))
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.
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 (SpatialOS documentation)), 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 (SpatialOS documentation). This is why workers must send updates (SpatialOS documentation) 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 (SpatialOS documentation) API to change it.
Also referred to as “automatic synchronization”.
When writing game logic you don’t need to worry about synchronisation code. Standard replication handles this automatically.
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’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
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.
Generated Unity ECS components can be injected into systems, read, and modified just as normal Unity ECS components can. We also provide support for using them in MonoBehaviours. 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.
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.
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.
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 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.
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 (SpatialOS documentation).
Around the SpatialOS entities they have write access to, each worker has an area of the world they are interested in (SpatialOS documentation). A worker can read the current properties of the SpatialOS entities within this area, and SpatialOS sends updates and messages (SpatialOS documentation) about these SpatialOS entities to the worker.
If the worker has write access to a SpatialOS component, it can send updates and messages (SpatialOS documentation): it can update properties (SpatialOS documentation), send and handle commands (SpatialOS documentation) and trigger events (SpatialOS documentation).
See also the Workers in the GDK documentation.
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 (SpatialOS documentation).
A worker flag is a key-value pair that workers can access during runtime. Worker flags can be set in their launch configuration (SpatialOS documentation) or added/changed/removed at runtime through the SpatialOS console. This SpatialOS documentation describes how to define and change worker flags.
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 (SpatialOS documentation). The Worker SDK handles the implementation details of communicating to the SpatialOS runtime and provides a serialization library.
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.
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.
A worker’s view consists of all SpatialOS entities that a worker is currently interested in (SpatialOS documentation) 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.
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 (SpatialOS documentation)), 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.
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 (SpatialOS documentation). However, the list of workers that could possibly gain write access is constrained by the access control lists.