Get SpatialOS

Sites

Menu

Glossary

This glossary covers:

  • Terms used in this documentation
  • Terms relevant to the GDK for Unreal
  • SpatialOS terms used in the GDK for Unreal documentation

SpatialOS 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 .uproject and source folder.
  • <ProjectRoot> - The folder containing your <GameRoot>.
  • <YourProject> - Name of your project’s .uproject (for example, \<GameRoot>\TP_SpatialGDK.uproject).

GDK for Unreal terms

Actor handover

Actor handover (handover) is a GDK-specific 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.

Dynamic Typebindings

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.

Cross-server RPCs

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):

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

Related:

Server travel

GSM

Short for Global State Manager.

SchemaDatabase

The SchemaDatabase is a uasset file (named schemadatabase.uasset) that contains information about UObjects and associated schema in your project. Information is automatically added to the SchemaDatabase by the GDK whenever you generate schema. It is an auto-generated file which you cannot manually edit.

Schema generation

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

Singleton Actor

A server-side authoritative Actor that is restricted to one instantiation on SpatialOS. See documentation on Singleton Actors.

Spatial Type

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.

SpatialType

See Spatial Type.

SpatialOS terms

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

Assembly

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.

Authority

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

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

Chunk

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.

Component

See SpatialOS component.

Command-line tool (CLI)

See Spatial command-line tool (CLI).

Configuration files

The configuration files contain information on how elements of your project must work. There are four configuration files:

Console

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

Related:

Deployment

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. Find out more about local deployments in the SpatialOS documentation.

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.

Entity

See SpatialOS entity.

Game world

Not to be confused with SpatialOS world.

Everything in your Unreal game that a player can see or interact with.

Inspector

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:

Related:

The Inspector

Interest

There are two types of interest: entity interest and component interest.

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

Component interest

Each worker, in its worker configuration file, specifies which components it is interested in. SpatialOS only sends updates about components to a worker which is interested in that component.

Related:

Launch

Not to be confused with the Launcher.

In SpatialOS, “launch” means start a game deployment. See also launch configuration file.

Launch configuration

The launch configuration is how you set up the start of your game’s deployment (its launch). It is represented in the launch configuration file. See workers and launch configuration file.

Launch configuration file

The launch configuration file is a .json file containing the information that the “launch a deployment” commands use to start a deployment.

Related:

Launch configuration file

Launcher

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.

Related:

The Launcher

Load balancing

One of the features of SpatialOS is load balancing: dynamically adjusting how many components on entities in the world each worker has write access to, so that workers don’t get overloaded.

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.

Related pages:

Configuring load balancing

Network operations

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.

Node

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.

Ops

See Network operations.

Persistence

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.

Related:

The persistence component in the standard schema library

Project name

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

Related

Project defnition file - spatialos.json

Queries

Queries allow workers to get information about the world outside the region they’re interested in. For more information, see queries.

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.

Read access

See authority.

Schema

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.

Related:

SpatialOS command-line tool (CLI)

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 to deploy your game (using spatial local launch or spatial cloud launch). You can run the CLI commands spatial build and spatial local launch from the GDK toolbar in the Unreal Editor.

Related:

SpatialOS component

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

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

Related:

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. A SpatialOS entity approximates to an Unreal Actor.

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.

Related:

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 each other.

SpatialOS SDK

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.

Related:

Worker SDK: Game development tools overview Platform SDK overview

SpatialOS world

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.

Snapshot

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

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

Related:

Streaming queries

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

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.

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

  • Client-worker

    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.

    Related:

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

Related:

Worker configuration

The worker configuration is how you set up your workers. It is represented in the worker configuration file. See workers and worker configuration file.

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, spatialos.MyWorkerType.worker.json. 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.

Related:

Worker configuration file worker.json

Worker types

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.

Write access

See authority.


2019-03-15 Page updated with full editorial review

2019-03-15 Added layers, non-Unreal layers, network operations (ops)

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums