Glossary

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.

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

Authority

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

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.

Cross-server RPCs

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

<GameRoot>

The directory containing your project's .uproject and Source directory.

Global State Manager

The Global State Manager (GSM) 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.)

Find out more
Server travel

Interest

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:

  • NetCullDistanceSquared
  • NetCullDistanceFrequency - this setting must be used with NetCullDistanceSquared
  • ActorInterestComponent
  • AlwaysInterested

Load balancing

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

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.

<ProjectRoot>

The directory containing your <GameRoot>.

SchemaDatabase

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.

Schema generation

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.

Spatial Type

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.

SpatialType

See Spatial Type.

<YourProject>

The name of your project's .uproject (for example, /<GameRoot>/TP_SpatialGDK.uproject). See also: <GameRoot>.

Zoning

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

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 alone. While some SpatialOS concepts underpin the GDK for Unreal, the two workflows are not always the same.

Assembly

An assembly is the binary code created when you build your project. It contains all the files that your game uses.

This includes:

  • Your project’s executable code which is your built-out server-worker and client-worker code in .zip files. SpatialOS uses this to run your game’s deployment in the cloud.
  • The project’s GDK-generated schema .descriptor file to use with the deployment in the cloud.
  • Worker metadata from the worker.json file.

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.

Component

See SpatialOS component.

Command-line tool (CLI)

See Spatial command-line tool (CLI).

Configuration files

The configuration files contain information on how your project runs. There are four configuration files:

Console

The Console is the landing page for managing cloud deployments.

There are two Consoles:

Note: You must be located in China to deploy to server nodes in China.

The Console shows you:

Find out more

Deployment

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.

Deployment run

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

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_login when 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++.

Dynamically-spawned entity

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.

Entity

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.

All the data you store in the SpatialOS Runtime, including the update data that worker instances send and receive, is associated with entities.

Game world

Not to be confused with the 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:

  • Which workers are connected to the deployment.
  • How much load the workers are under.
  • Which entities are in the SpatialOS world.
  • What their SpatialOS componentsproperties are.
  • Which workers have authority over each SpatialOS component.

Find out more
The Inspector

Launch configuration

The launch configuration is how you set up your game’s deployment. You define the launch configurations 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 used to start a deployment.

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.

Find out more
The Launcher

Locator

There are two types of connection workflow between a worker instance and the SpatialOS Runtime: Locator and Receptionist.

You use the Locator to connect a client-worker instance to a cloud deployment. An authenticated Locator service lists cloud deployments and connects the client-worker instance to the right one.

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 Nodes tab of your deployment details in the Console.

Ownership

The GDK mimics Unreal’s owning connections so that client-workers can manipulate certain Actors.

Ops

See Network operations.

Persistence

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

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.

Project name

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

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.

Receptionist

There are two types of connection between a worker instance and the SpatialOS Runtime: Receptionist and Locator.

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

Schema

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.

Find out more

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. They launch inside a standalone cloud deployment and connect to a target cloud deployment.

Find out more
Simulated players

Snapshot

A snapshot is a representation of the state of a SpatialOS world at a given point in time. It stores the values of the SpatialOS component properties on each persistent entity.

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

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 for local and cloud deployments. You can also use the GDK toolbar to build workers and deploy.

Find out more: CLI documentation

Find out more: GDK toolbar worker-build and deployment options

SpatialOS component

Not the same as Unreal Actor Components.

Each entity is made up of SpatialOS components. Common SpatialOS components in a game might be Health, Position, or 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 Health component 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, StartedWalking).
  • Commands - a worker calls commands which ask the SpatialOS component to do something, optionally returning a value (for example, Teleport).

Each component can have many properties, events, and commands. An entity can have many components, but it must have a property component called Position.

All the data that you want the SpatialOS Runtime to store, and the data you want worker instances to update and receive updates about, is associated with properties in entity components.

Find out more
Setting up Actors for schema generation: Spatial Type.

If you plan to extend the functionality of the GDK using the SpatialOS Worker SDK, you’ll need to know about the standard schema library.

SpatialOS component property

SpatialOS components can contain properties, which describe persistent values that change over time.

The worker instance with authority over a particular Actor sends property updates to the SpatialOS Runtime. These updates are then sent on to worker instances that have interest in the Actor.

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.

SpatialOS Runtime

Not to be confused with the SpatialOS world.

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.

SpatialOS SDKs

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.

SpatialOS world

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.

Worker

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.

Worker types and worker instances

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.

Server-workers

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.

Single server vs multiserver

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.

Client-workers

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.

Worker configuration

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

See Worker and Worker configuration file.

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


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


Glossary


Suggested Edits are limited on API Reference Pages

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