Glossary

Authority and interest

The core idea of SpatialOS is that worker instances have access only to a part of the game world. This access is governed both by what the worker instance has authority over and what it has interest in.

More information:

Write access authority

(Not relevant if you're using the GDK for Unreal.)
A worker instance has write access authority over a component on an entity when it is sending updates about that component to the entity database, so that other worker instances can receive updates about the changes to the component.

More information:

Active read access

(Not relevant if you're using the GDK for Unreal.)
A worker instance has active read access to a component on an entity when it is receiving updates about that component from the entity database.

More information: Active read access

Interest

When a worker instance wants to receive updates about entity components from the entity database, we say it has interest.

Bridge

A bridge is a part of the SpatialOS Runtime. Instances of server-workers and client-workers connect to it so that they can send and receive updates about the game world.

Sometimes you might see the bridge referred to as the 'connection manager'.

Console

The Console (outside of China/in China) is the main landing page for managing cloud deployments. It shows you:

  • your cloud project name
  • running and previous cloud deployments using that cloud project name
  • all the assemblies you’ve uploaded using that cloud project name
  • a page for each deployment, which shows its status, and gives you access to the Inspector, Logs, and Metrics pages for that deployment.

Deploying

SpatialOS hosts the server element of your multiplayer game. You set up the server hosting via SpatialOS deployments. This means launching your game with its own instance of SpatialOS. This SpatialOS instance sets up the world based on a snapshot, then starts up the worker instances needed to run the game world.

More information:

Local deployment

A local deployment is a deployment of your game/project on your local development machine.

More information:

Cloud deployment

A cloud deployment is a deployment of your game/project in the cloud.

More information:

Deployment name

A deployment name is a label to identify a cloud deployment in the Console. You enter this name when you run a cloud deployment.

Entity

All of the objects inside a SpatialOS world are entities: they’re the basic building block of the world. Examples include players, NPCs, and objects in the world like trees.

Entities are made up of components, which store the data associated with that entity.

More information:

Component

An 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 worker instances.

More information:

Property

Properties are one of the things that can be contained in a component. Properties describe persistent values that change over time.

More information:

Event

Events are one of the things that can be contained in a component. Unlike a property, an event is not persistent (the data in it isn't saved).

More information:

Command

Commands are one of the things that can be contained in a component. They're essentially a remote procedure call (RPC). Commands facilitate communication in the other direction to events and properties: they allow any worker instance to send a request to the worker instance with write access authority to a specific component. The receiving worker instance can take action and should respond to the request.

More information:

Short-circuiting

(Not relevant if you're using the GDK for Unreal.)
Commands are routed through SpatialOS by default. You can choose to bypass this and short-circuit commands when the worker instance sending the command believes to have write access authority over the target component. However, doing this might lead to a worker executing a command despite having just lost authority over the command's component.

More information: Commands

Standard schema library components

EntityACL (required)

(Not relevant if you're using the GDK for Unreal.)
The access control list (ACL) is a component called EntityAcl that is required on every entity. You use it to define whether a worker type has write access permission and/or read access permission to the components on an entity.

More information:

Position (required)

(Not relevant if you're using the GDK for Unreal.)
Position is a component in the standard schema library; all entities must have this component. It lets SpatialOS know what the position of an entity in the world is.

More information:

EntityId

(Not relevant if you're using the GDK for Unreal.)
An EntityId uniquely identifies each entity in the world and in a snapshot.

Entity specification

(Not relevant if you're using the GDK for Unreal.)
You create an entity specification when you send a request to the Runtime to create an entity. The entity specification defines what components the entity has. If the request succeeds, then the Runtime creates an entity as defined by the entity specification. When the request completes, either in success or failure, then the entity specification ceases to exist.

The method you use to define an entity specification (and therefore the entity it creates) varies depending on the programming language you use. In general, you create a new entity object, then add components to it and finally send a request to the Runtime to create the entity.

Game template

A game template defines the compute resources that your deployment needs. You must specify a game template in your launch configuration file before you can start a deployment.

More information:

Launch configuration file

A launch configuration file contains settings that the SpatialOS CLI uses when it launches a deployment.

More information:

Node

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.

Project

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

More information: Project

Assembly

An assembly is what's created when you build. It contains all the files that your game uses.

More information:

Cloud project name

Your cloud project name is a name which is used to label your project. It’s generated for you when you sign up for SpatialOS. It’s usually something like beta_someword_anotherword_000.

More information:

Queries

Queries allow worker instances to get information about the world outside the area they have interest in.

More information:

Schema

The schema is where you define all the components in your world.

Schema is defined in .schema files, written in schemalang. Schema files are stored in the schema/ directory of your project.

SpatialOS uses the schema to generate code in various languages (including C#, C++, and Java). You can use this generated code in your worker instances to interact with entities in the world.

More information:

Schemalang

(Not relevant if you're using the GDK for Unreal.)
Schemalang is SpatialOS’s language for writing a component schemas.

More information: Schemalang reference

Schema descriptor

(Not relevant if you're using the GDK for Unreal.)
The schema descriptor is a build artifact of a SpatialOS project assembly. It allows the SpatialOS Runtime to interpret your project’s schema and is necessary for starting a SpatialOS deployment both locally and in the cloud. You can generate a schema descriptor using the schema compiler tool.

More information: Build a schema descriptor

Sending an update

If a worker instance has write access authority over a component, it can send an update about it to the entity database in the SpatialOS Runtime. An update can change the value of a property, or trigger an event. You can change multiple properties and trigger multiple events in one update.

More information:

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

More information:

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.

World unit

(Not relevant if you're using the GDK for Unreal or the GDK for Unity.)
World units are an arbitrary unit that worker instances can interpret as they choose.

Snapshot

A snapshot is a representation of the state of a world at some point in time.

More information:

Worker configuration (worker.json)

Each worker type must have a worker configuration file, with the name spatialos.<worker_type>.worker.json: for example, spatialos.MyCSharpWorker.worker.json.

More information:

Worker ID

Each worker instance has a worker ID, used to uniquely identify it. Worker instances automatically have an attribute which includes their ID: "workerId:<worker ID>".

Worker scheduler

(Not relevant if you're using the GDK for Unreal.)
The worker scheduler is responsible for starting up worker instances according to your load balancing strategy.

More information: Worker scheduler

Worker types and worker instances

When you develop your game, you set up worker types. These are like molds for the worker instances which do the actual computation.

More information:

Server-worker

A server-worker instance has its lifecycle managed by SpatialOS.

More information:

Unmanaged worker

If you want to test what would usually be a server-worker instance by stopping and starting it manually in your game development environment, you can make that worker instance unmanaged in a local deployment or cloud deployment of your game.

More information: Unmanaged worker

Client-worker

A client-worker instance is part of a player's game client; that is, their game executable program.

More information:

Worker SDK

The Worker SDK is a low-level integration, available in several programming languages. Use the Worker SDK to create server-worker types and client-worker types which make your game work as a SpatialOS deployment.

More information: SDKs and Data overview

2020-10-07 Page updated with editorial review: added "Entity specification" entry.
2020-06-22 Page updated with editorial review: added "Game template" and "Launch configuration file" entries.

Updated 6 months 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.