This glossary covers:
- Terms used in this documentation
- Terms relevant to the GDK for Unreal
- SpatialOS terms used in the GDK for Unreal documentation
Many SpatialOS term definitions link to further information in the SpatialOS documentation. This documentation covers the SpatialOS Worker SDK and Platform SDK as well some GDK-relevant tools; the Console, schema, snapshots, and configuration files in particular.
Note that this SpatialOS documentation assumes you are developing a SpatialOS game using the Worker SDK and Platform SDK, so it may reference content relevant to that workflow only. While some of the concepts underpin the GDK for Unreal, the two workflows are not always the same.
GDK for Unreal documentation terms
<GameRoot>- The folder containing your project’s
.uprojectand source folder.
<ProjectRoot>- The folder containing your
<YourProject>- Name of your project’s
GDK for Unreal terms
Actor handover (
handover) is a new
UPROPERTY tag. It allows games built in Unreal (which uses single-server architecture) to take advantage of SpatialOS’ distributed, persistent server architecture. See Actor property handover between server-workers.
To enable the network stacks of Unreal and SpatialOS to interoperate, we’ve implemented Dynamic Typebindings.
Dynamic Typebindings operate at runtime so your that your iteration speed is not affected despite your network code running on a completely different represenetations than Unreal’s.
These handle the scenario where a server-worker needs to execute an operation on an Actor that another server-worker has authority over. When a cross-server RPC is invoked by a non-authoritative server-worker, the execution is routed through SpatialOS to the authoritative server-worker - this authoritative server-worker executes the RPC. (See the documentation on Cross-server RPCs).
Global State Manager
The Global State Manager (GSM):
- Makes sure that Singleton Actors are replicated properly, by only allowing the server-worker with authority over the GSM to execute the initial replication of these Actors. See documentation on Singleton Actors.
- Maintains the configuration of a deployment’s currently-loaded game world. (Note that this is the Unreal game world not the SpatialOS world.)
The GSM lists both the URL of the Map (or Level - see Unreal documentation) that the server-workers have loaded and the
AcceptingPlayers flag. (This flag controls whether or not client-servers can spawn anything in the game world.)
Short for Global State Manager.
A SpatialOS GDK for Unreal toolbar command (within the Unreal Editor) which takes a set of Unreal classes and generates SpatialOS schema that enables automatic communication between Unreal and SpatialOS.
Related: SpatialOS GDK for Unreal toolbar
A server-side authoritative Actor that is restricted to one instantiation on SpatialOS. See documentation on Singleton Actors.
Spatial Type (
SpatialType) is a SpatialOS-specific class specifier (Unreal documentation) which is used to expose network-relevant class information to SpatialOS. There are different categories of Spatial Type, depending on the Actor’s function in your game.
See the documentation on Spatial Type.
See Spatial Type.
Below is a subset of SpatialOS terms most relevant to the GDK for Unreal. See the SpatialOS documentation glossary for a full list of terms specific to SpatialOS.
Note that this SpatialOS documentation glossary assumes you are developing a SpatialOS game using the Worker SDK and Platform SDK, so it may reference content relevant to that workflow only. While some of the concepts underpin the GDK for Unreal, the two workflows are not always the same.
Access control list (ACL)
In order to read from a component, or make changes to a component, workers need to have access, which they get through an access control list.
Access control lists are a component in the standard schema library:
EntityAcl. Every entity needs to have one. The ACL determines:
- which types of workers have read access to an entity
- for each component on the entity, which types of workers can have write access
An assembly is what’s created when you build your project. It contains all the files that your game uses. This includes executable files for the client-workers and server-workers, and the assets these workers use (for example, textures used by a client to visualize the game). When you run a cloud deployment, you have to specify an assembly to use.
Also known as “write access”.
- Write access:
Many workers can connect to a SpatialOS world. For each component on a SpatialOS entity, there can be no more than one worker with write access to it. This worker is the only one able to modify the component’s state and handle commands for it. Workers with write access are said to “have authority” and be “authoritative”; workers without write access are said to be “non-authoritative”. Which types of workers can have write access is governed by each entity’s access control list (ACL). A write ACL is specified per component. The write authority is managed by SpatialOS, and can change regularly due to load balancing (SpatialOS concept documentation).
- Read access:
Read access allows workers to know the state of a SpatialOS component. The access control list (ACL) also controls which workers have read-access to a SpatialOS entity. Read access does not allow a worker to change a component. Read access is at the entity level; if a worker can read from an entity, it is allowed to read from all components on that entity.
- the worker has a local representation of every 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.
A world is split up into chunks: the grid squares of the world. A chunk is the smallest area of space the world can be subdivided into. Every entity is in exactly one chunk. You set the size of chunks for your world in launch configuration files (SpatialOS documentation).
See SpatialOS component.
Command-line tool (CLI)
The configuration files contain information on how elements of your project must work. There are four configuration files:
- The launch configuration file -
*.jsoncontains the information that the “launch a deployment” commands use to use to run a deployment.
- The worker configuration file -
*.worker.jsontells SpatialOS how to build, launch, and interact with workers.
- The project definition file -
- The worker packages file -
- 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.
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 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 clients to it using the Launcher.
See SpatialOS entity.
Not to be confused with SpatialOS world.
Everything in your Unreal game that a player can see or interact with.
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 local or cloud deployment. 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 SpatialOS world.
- what their SpatialOS components’ properties (SpatialOS documentation) are.
- which workers are authoritative over each SpatialOS component.
There are two types of interest: entity interest and component interest.
A worker is interested in all chunks that contain entities it has write access to a component on. It’s also interested in chunks within a configurable radius of those entities: this makes sure that workers are aware of entities nearby. You can set this radius in the worker configuration file. If a worker is interested in a chunk, it will check out all the entities in that chunk.
Not to be confused with the Launcher.
Launch configuration file
The Launcher is a tool that can download and start 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.
Load balancing only applies to server-workers. When an instance of a worker is struggling with a high workload, SpatialOS can start up new instances of the worker, and give them write access to some components on entities.
This means that an entity won’t necessarily stay on the same worker instance, even if that entity doesn’t move. SpatialOS may change which components on which entities a worker instance has write access to: so entities move “from” one worker instance to another. Even though the entity may be staying still, the worker instance’s area of interest is moving.
Not to be confused with worker.
Most entities in your game world need to keep existing if you stop a game deployment and start a new one. However, some entities don’t need to keep existing from one deployment to another; you may want per-deployment player abilities and a per-deployment score, for example.
To facilitate this continuity in an entity’s state between deployments, there is a
persistence component in the standard schema library. It’s optional, but all entities that you want to persist in the world must have this component. Persistence means that entities are saved into snapshots.
Your project name is a unique identifier for your game project as a deployment. It’s generated for you when you sign up for SpatialOS. It’s usually something like
You must specify this name when you run a cloud deployment.
Note that your project name is (usually) not the same as the name of the directory your project is in.
Project definition file
This is a
spatialos.json file which lives in your project’s spatial directory.
It lists the SpatialOS project name assigned to you by Improbable when you sign up as well as the version of SpatialOS SDK your project uses.
Entity queries are useful if you need to get information about an entity at a particular time. If you need regular updates about an entity, use streaming queries instead.
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.
spatial command-line tool (CLI)
spatial command-line tool (also known as the “CLI”) provides a set of commands that you use to interact with a SpatialOS project (SpatialOS documentation). Among other things, you use it to deploy your game (using
spatial local launch (SpatialOS documentation) or
spatial cloud launch (SpatialOS documentation)). You can run the CLI commands
spatial build and
spatial local launch from the GDK toolbar in the Unreal Editor.
- 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 Unreal Actor Components (Unreal documentation
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.
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. A SpatialOS entity approximates to an Unreal Actor.
SpatialOS entities are made up of SpatialOS components, which store data associated with that entity.
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 each other.
This is a set of low-level tools in several programming languages which you can use to integrate your game project with SpatialOS. It consists of the Worker SDK (or “Worker module”) and Platform SDK (or “Platform module”). If you are using the GDK for Unreal, you do not need to use the Worker SDK or Platform SDK, however, you can use the Worker SDK to extend or complement the functionality of the GDK for Unreal.
Not to be confused with the Unreal game world.
Also known as “the 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 entities - specifically, within their components. SpatialOS manages the world, keeping track of all the 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 recognise this fundamental separation between the SpatialOS world and the view of that world that a worker checks out. Workers 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.
A snapshot is a representation of the state of a SpatialOS world at a given point in time. It stores each persistent SpatialOS entity and the values of their SpatialOS components’ properties (SpatialOS documentation).
Streaming queries allow workers to get information about the world outside the region they’re interested in, so that they know about entities that they don’t have checked out (for example, entities that are far away, or that don’t have a physical position).
Streaming queries are useful if you need to get information about an entity periodically - for example, so that a player can see and interact with it.
If you just need information about an entity at one particular time, use queries instead.
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.
A server-worker approximates to a server in native Unreal networking but, unlike Unreal networking, in SpatialOS you can have have more than one server-worker.
Server-worker 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.
You usually set up server-workers to implement 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. If you run a local deployment, the server-workers run on your development computer. If you run a cloud deployment, the server-workers run in the cloud.
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. You usually set up client-workers to visualize what’s happening in the SpatialOS world. They also deal with player input.
More about 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 updates 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. SpatialOS then starts up new workers when needed. This is load balancing (SpatialOS documentation). Around the SpatialOS entities which they have write access to, every worker has an area of the world they are interested in.
A worker can read the current state of components 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).
Worker configuration file
First, see workers.
Each worker needs a worker configuration file. This file tells SpatialOS how to build, launch, and interact with the workers.
The file’s name must be
spatialos.<worker_type>.worker.json: for example,
Once you’ve chosen a label for the worker type (for example, myWorkerType), you use this exact label consistently throughout your project to identify this worker type.
First, see workers.
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, you can define your own worker sub-types to create more specialized workers.