This glossary covers:
- GDK for Unreal terms
- SpatialOS terms - for any SpatialOS terms that are used in the GDK for Unreal documentation
It is important to remember that the GDK for Unreal has SpatialOS implementations which may differ from other SpatialOS products, such as the GDK for Unity.
Actor handover (
handover) is a GDK-specific
UPROPERTY tag. It allows games built in Unreal (which uses single-server architecture) to take advantage of zoning which is one of the GDK's options for multiserver development. See Actor property handover between server-workers.
Note: Zoning is currently in preview.
When a server-worker has authority over an Actor, it can make changes to the Actor by sending updates to the SpatialOS Runtime. A server-worker has authority over an Actor if it has authority over the equivalent entity’s SpatialOS component
Client-workers never have authority over Actors. However, like in native Unreal, they can have ownership.
In a game with just one server-worker instance (which is the default for the GDK), that server-worker has authority over all the Actors in the game. In a game with more than one server-worker instance, different server-workers have authority over different Actors:
- With offloading, the server-worker instance that has authority over an Actor always stays the same.
- With zoning (currently in preview), the server-worker instance that has authority over an Actor can change as the Actor moves around, but only one instance can have authority over an Actor at any one time.
Find out more:
How to set up authority
Cross-server RPCs facilitate zoning by handling all scenarios in which 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 server-worker that doesn't have authority, the execution is routed through SpatialOS to the server-worker that has authority - and this server-worker then executes the RPC. (See the documentation on Cross-server RPCs).
The directory containing your project's
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.)
Find out more
Interest is the manner in which client-workers receive updates about one or more Actors they don’t own. This helps the client-worker correctly manipulate the Actors that it does own, and render the SpatialOS world.
You can define interest in four ways:
NetCullDistanceFrequency- this setting must be used with
Find out more
Game client interest management
In a multiserver game world, load balancing strategies distribute computational load over two or more server-worker instances. This enables games to scale beyond what would be possible with a single Unreal Server. The GDK for Unreal has multiple load balancing strategies:
You are not limited to one load balancing strategy per game. For example, you can offload the AI computation to a dedicated AI server-worker and then you can also implement zoning for the same game with another set of server-workers.
Offloading is a multiserver, load balancing strategy in the GDK - see Load balancing. Offloading distributes computational load over the game world by defining a set of server-worker types that computes one set of Actor types across the game world, such as:
- server-worker instances dedicated to computing process-intensive functionality such as AI-dedicated server-worker instances
AI is a good candidate for offloading as it is computationally expensive but latency-tolerant, leaving your game's main server-worker to run other game systems at a larger scale.
Find out more
The directory containing your
The SchemaDatabase is a
uasset file (named
SchemaDatabase.uasset) that contains information about the
UObjects and associated schema in your project. Information is automatically added to the
SchemaDatabase by the GDK whenever you generate schema. It is a generated file which you cannot manually edit.
A SpatialOS GDK for Unreal toolbar command (within the Unreal Editor) which takes the current set of Unreal classes in a deployment and generates SpatialOS schema. The GDK generates schema files and their contents based on the Actors you have set up for schema generation. Schema generation enables automatic communication between Unreal and SpatialOS.
Find out more
SpatialOS GDK for Unreal toolbar
Spatial Type (
SpatialType) is a SpatialOS-specific class specifier (Unreal documentation) which is used to expose relevant Unreal 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.
The name of your project's
.uproject (for example,
/<GameRoot>/TP_SpatialGDK.uproject). See also: <GameRoot>.
Zoning is a multiserver, load balancing strategy in the GDK - see Load balancing. It involves splitting the world into grid-based areas of authority, with a different server-worker instance responsible for each area. A server-worker instance only computes Actors that are in its area of authority.
Note: Zoning is currently (in preview).
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 alone. While some SpatialOS concepts underpin the GDK for Unreal, the two workflows are not always the same.
An assembly is the binary code created when you build your project. It contains all the files that your game uses.
- Your project’s executable code which is your built-out server-worker and client-worker code in
.zipfiles. SpatialOS uses this to run your game’s deployment in the cloud.
- The project’s GDK-generated schema
.descriptorfile to use with the deployment in the cloud.
- Worker metadata from the
When you configure your project for a cloud deployment, you create a unique name for its assembly (unless you want to overwrite an existing assembly). You can then identify the group of files in the Console using the assembly name.
See SpatialOS component.
The configuration files contain information on how your project runs. There are four configuration files:
- The launch configuration file -
*.jsoncontains the configurations for launching a deployment.
- The worker configuration file -
*.worker.jsontells SpatialOS how to build, launch, and interact with workers.
- The project definition file -
spatialos.jsondefines project settings.
- The worker packages file -
spatialos_worker_packages.jsoncontains the configuration for worker packages.
The Console is the landing page for managing cloud deployments.
There are two Consoles:
- A Console for users outside China that deploys to server nodes outside China - https://console.improbable.io/
- A Console for users in China, deploying to server nodes in China - https://console.spatialoschina.com/
Note: You must be located in China to deploy to server nodes in China.
The Console shows you:
There are two types of deployment: local and cloud.
- Cloud deployments run in the cloud on Improbable-hosted servers, known as nodes.
- You can use a local deployment to test server-side and client-side code on your development machine. When you start a local deployment, you start a local version of the SpatialOS Runtime. (Note that the Launcher does not work with local deployments.)
When you deploy your game to SpatialOS, the SpatialOS Runtime creates the game’s SpatialOS world based on a snapshot. The Runtime then starts up the server-worker(s) needed to run the world. You can share game clients via the Launcher.
A deployment run is an instance (running or stopped) of a deployment. Each deployment run of a cloud deployment is assigned an
int64 number as a unique identifier, which is called the Run ID. (Local deployment runs don't have Run IDs.)
Find out more:
Deployment tags are metadata that you can add to a SpatialOS cloud deployment. You can create your own tags or use SpatialOS system tags.
Useful system tags:
nightly- Keep the deployment running until 5PM UTC the next weekday. (By default all deployments stop running after 6 hours.)
To keep a deployment running for longer, raise a support request (for customers with a service agreement) or ask on our forums.
dev_login- Game clients use authentication during development. Use
dev_loginwhen you are developing game clients to run on mobile devices.
Find out more in Authentication during development.
You can use the SpatialOS Worker SDK to list the system tags by calling
GetDeploymentListAsync. See the API reference for the Worker SDK in C++.
Entities can be either dynamically-spawned or non-dynamic:
- Dynamically-spawned entities correspond to Actors that your game creates during runtime. For example, your game might spawn pick-ups in a level; these are dynamically-spawned entities.
- Non-dynamic entities correspond to Actors that are already in your game’s snapshot or in your game’s Unreal level.
Entities equate to replicated Actors in Unreal. They are the network-enabled objects that you place or that are spawned into your SpatialOS world.
Entities are made up of a collection of SpatialOS components.
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:
Find out more
The launch configuration is how you set up your game’s deployment. You define the launch configurations in the launch configuration file.
The launch configuration file is a
.json file containing the information used to start a deployment.
Find out more
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.
Find out more
Also known as "ops".
Network operations are network messages sent between a worker instance and the SpatialOS Runtime. They carry information about updates to worker instances, entities, entity components, commands, and more.
For more information, see the SpatialOS documentation on operations.
Not to be confused with worker.
The GDK mimics Unreal’s owning connections so that client-workers can manipulate certain Actors.
See Network operations.
Saving entity data in snapshots ensures the entity persists. Most entities in your game world need to persist if you stop a game deployment and start a new one. However, some entities don’t need to persist 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.
Placeholder entities are useful for visualizing multiple server-worker instance’s areas of authority. The GDK auto-populates your local deployment with placeholder entities via the Editor Settings panel which you can access from the Unreal toolbar. From the Play menu, select SpatialOS settings and scroll down to SpatialOS GDK for Unreal.
Your project name is a unique identifier for a game project’s deployment. It’s generated 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.
This is a
spatialos.json file which lives in your project's spatial directory.
Find out more
Project definition file -
Entity queries are useful if you need to get information about an entity at a particular time.
You use the Receptionist connection for:
- Connecting a server-worker instance to a local or cloud deployment
- Connecting a client-worker instance to a local deployment for debugging without authentication
Find out more
A schema is a set of data definitions which represents your game's objects and related commands and events in SpatialOS. Schemas are defined in
.schema files and written in the SpatialOS language “schemalang”.
You do not have to write or edit schema files manually: the GDK generates schema files and their contents based on the Actors you have set up for schema generation. (However, you do have to manually start the schema generation via the GDK toolbar.)
SpatialOS uses schemas to generate APIs specific to the SpatialOS entity components in your project. You can then code these APIs into your game's worker type definitions so their instances can interact with SpatialOS components.
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. They launch inside a standalone cloud deployment and connect to a target cloud deployment.
Find out more
The SpatialOS command-line tool (also known as the “CLI”) provides a set of commands that you use to interact with a SpatialOS project. Among other things, you use it for local and cloud deployments. You can also use the GDK toolbar to build workers and deploy.
Find out more: CLI documentation
- Command-line cloud deployments
- An introduction to the SpatialOS command-line tool. Note that the GDK does not support any
- SpatialOS CLI reference
Find out more: GDK toolbar worker-build and deployment options
Not the same as Unreal Actor Components.
Each entity is made up of SpatialOS components. Common SpatialOS components in a game might be
PlayerControls. In the GDK, you don’t need to manually create entities or components; schema generation does this automatically, based on the Unreal Actors that you set up.
There are three types of data that a SpatialOS component can contain:
- Properties - persistent values that change over time (for example, a property for a
Healthcomponent could be “the current health value for this entity”.) SpatialOS component properties approximate replicated properties in Unreal.
- Events - transient occurrences that can happen to an entity (for example,
- Commands - a worker calls commands which ask the SpatialOS component to do something, optionally returning a value (for example,
Each component can have many properties, events, and commands. An entity can have many components, but it must have a property component called
SpatialOS components can contain properties, which describe persistent values that change over time.
If a worker has interest in an Actor, that worker can:
- Read the current value of the Actor’s component properties
- Watch for changes to the value of these properties
The value of a component’s property forms part of the data about an entity. This data is stored in the SpatialOS Runtime.
Also sometimes just called “SpatialOS”.
The SpatialOS Runtime manages the SpatialOS world of each deployment by storing all entity data, specifically the current state of SpatialOS entity components. Workers interact with the SpatialOS Runtime to read and modify the components of an entity as well as send messages between each other.
The SpatialOS SDKs are the Worker SDK and the Platform SDK, which are low-level SpatialOS integrations available as APIs.
You can use the Worker SDK to extend the functionality of the GDK, or to create low-level worker types for game logic that doesn’t require Unreal.
You can use the Platform SDK to build tools, workflows, and services that integrate with the SpatialOS platform.
This is not the same as the Unreal game world.
Also known as “the world”.
The world is a central concept in SpatialOS. All the world’s data is associated with entities - specifically, their SpatialOS components. SpatialOS manages the world, keeping track of all the entities and what state they’re in and storing this data in the SpatialOS Runtime.
Worker instances make changes to the world by sending updates to the SpatialOS Runtime. Each worker instance has a view onto the world (the part of the world that it has interest in) and receives updates from the Runtime when anything changes in that view.
Workers are server-side and client-side software. They perform the computation associated with a SpatialOS world: they are responsible for keeping the SpatialOS entities up to date as the players interact with the world.
When you develop your game, you set up worker types. These are templates for the worker instances which actually do the 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.
The GDK for Unreal creates worker types for you, so, to get going, you don’t have to manually set them up. You can, however, add additional non-Unreal server-worker types using the Worker SDK.
When you create a worker type using the Worker SDK, you define a worker configuration file (
<worker_type>.worker.json) which tells SpatialOS how to build, launch, and interact with instances of this worker type.
A server-worker instance equates to a running server in native Unreal networking but, unlike Unreal, SpatialOS can have more than one server-worker instance (see Zoning). A server-worker’s lifecycle is managed by SpatialOS. When you run a SpatialOS deployment of your game, the SpatialOS Runtime starts and stops server-workers.
The GDK sets up one server-worker type for you by default: an Unreal server-worker, computing Unreal functionality. Out of the box, you have a single instance of this type. However, there are also two multiserver options for working with SpatialOS: offloading and zoning (note that zoning is currently in preview).
You can also add additional non-Unreal server-worker types. For example, you could set up an additional server-worker type to implement player logic and another to implement AI logic.
Note: In a local deployment, the server-worker instances run on your development computer. In a cloud deployment, the server-worker instances run in the cloud. For more information, see Deployment.
Each player’s game client - that is, the client software - uses a client-worker instance to interact with the SpatialOS world. A client-worker instance allows the game client to visualize what’s happening in the SpatialOS world as well as manage the player’s input to that world.
The lifecycle of a client-worker is managed by the game client. The GDK sets up a client-worker type for you by default.
The worker configuration is how you set up your workers. It is represented in the worker configuration file.
First, see Worker.
Each worker has a worker configuration file. This file tells SpatialOS how to build, launch, and interact with the workers.
The file’s name must be in the format
spatialos.<worker_type>.worker.json: for example,
Find out more
Worker configuration file
2020-09-04 Page updated with editorial review: removed circular link.
2020-08-05 Page updated with editorial review: clarifying terms and removing dead references.
2020-07-14 Page updated with editorial review: removed several references to Playtest Hub.
2019-08-08 Page updated with editorial review: updated Actor groups, offloading, zoning, workers, authority
2019-07-30 Page updated without editorial review: added Actor groups, offloading
2019-06-15 Added layers, non-Unreal layers, network operations (ops)
2019-03-15 Page updated with editorial review
Updated about a year ago