Get SpatialOS

Sites

Menu

Concepts glossary

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.

A project includes (but isn’t limited to):

Related pages:

Project name

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

Note that your project name is (usually) not the same as the name of the directory your project is in.

You must specify this name when you run a cloud deployment. You can either:

You can find out what your project name is in the Console.

Related pages:

Assembly

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

This includes executable files for the client-worker types and server-worker types, and the assets your worker instances use (like models and textures used by a client to visualize the game).

When you run a cloud deployment, you have to specify an assembly to use.

Related pages:

Structured project layout (SPL)

Directory layout of a SpatialOS project.

Related pages:

Flexible project layout (FPL)

New directory layout of a SpatialOS project designed to replace the structured project layout. Currently in beta.

Related pages:

The SpatialOS CLI

The SpatialOS CLI provides a set of commands that you use to interact with a SpatialOS project. Among other things, you use it to:

Related pages:

Building

When you make changes to the code of a worker type, you need to build those changes before you can try them out in a local or cloud deployment.

You can:

We recommend only building the bits of your project that you’ve changed, to save time. For example, if you’ve only changed the source code of one worker type, you should only build that worker type’s code.

You can build all worker types in your project using the command spatial worker build.

Related pages:

Deploying

When you want to try out your game, you need to run a deployment of the game/project. 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.

Once the deployment is running, you can connect client-worker instances to it. You can then use these to play the game.

You can run a deployment:

Related pages:

Local deployment

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

Before you run a local deployment, you need to:

You can launch a local deployment using the command spatial local launch.

Launching a local deployment runs SpatialOS locally. SpatialOS will start (and stop) the server-worker instances needed by the game world.

Once the deployment is running, you can connect client-worker instances to it in order to play the game (only on your local machine) using the command spatial local worker launch

Related pages:

Cloud deployment

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

Before you can run a cloud deployment, you need to:

You can launch a cloud deployment using command spatial cloud launch.

When you run the launch command, you specify:

Launching a deployment runs SpatialOS in the cloud. SpatialOS will start (and stop) the server-worker instances needed by the game world.

Once the deployment is running, you can connect client-worker instances to it, using the command spatial cloud connect external <deployment name>

Related pages:

Deployment name

A deployment name is a label to identify a cloud deployment in the Console. You choose/make up this name when you run a cloud deployment.

Launch configuration file

A launch configuration file contains settings that the SpatialOS CLI uses when it launches a deployment. This includes things like how big the world is, which worker types to use in the deployment, and what permissions to give them.

Easily confused with the launch configuration section in the worker configuration file (worker.json).

Related pages:

Inspector

The Inspector is a web-based tool that you use to explore the internal state of a SpatialOS world. It gives you realtime view of what’s happening in a deployment, locally or in the cloud. Among other things, it displays:

Related pages:

Launcher

You use the Launcher to connect client-worker instances to a cloud deployment. You can run the Launcher from the Console, or (from the Console) generate share links so anyone with the link can join.

The Launcher gets the executable for the client-worker type from the assembly you uploaded.

Related pages:

Locator

The Locator is the SpatialOS service responsible for connecting a client-worker instance to a deployment.

From SpatialOS 13.5 onwards, client-worker instances can connect to both cloud and local deployments using the Locator. Previously, it was only possible to connect to cloud deployments.

Console

The Console (console.improbable.io) is the main landing page for managing cloud deployments. It shows you:

  • your project name
  • running and previous cloud deployments using that project name
  • all the assemblies you’ve uploaded using that 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.

Related pages:

Worker types and worker instances

Worker instances are the programs that connect to a SpatialOS world. In general, you use server-worker instances simulate the world, and players use client-worker instances to connect to your game.

A worker type is a template for a worker instance. Each worker type has a worker configuration file (<worker_type>.worker.json) where you define how SpatialOS should build, launch, and interact with instances of this worker type.

For example, you could create a server-worker type called PhysicsWorker, and your deployment could have many worker instances of this worker type simulating the physics of the game world.

If a particular worker type has write access permission on an entity component (via the entity’s EntityAcl), this means that worker instances of that type could potentially have write access to the component (make changes to it). However, only one worker instance can have write access to an entity component at any one time. Which worker instance this is depends on your load balancing strategy and on the location of the entity.

Around the entities they have write access to, each worker instance has an area of the world they have interest in. A worker instance can read the current properties of the entities within this area, and SpatialOS sends updates about these entities to the worker instance.

You can set up worker types using:

Related pages:

Server-worker

Also known as “managed worker”, “server-side worker”.

A server-worker instance has its lifecycle managed by SpatialOS. That means in a running deployment, SpatialOS is in charge of starting it up and stopping it, as part of load balancing - unlike a client-worker instance.

Server-worker instances are usually tasked with implementing game logic and physics simulation.

You might have just one server-worker instance connecting to a SpatialOS world, or dozens, depending on the size of the world.

You tell SpatialOS how to launch a worker instance as a server-worker instance in its worker configuration file (worker.json).

Related pages:

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.

Note that these worker instances are not client-worker instances (external worker instances), even though client-worker instances are also not managed by SpatialOS. Unmanaged server-worker instances access the deployment in a different way to client-worker instances.

Server-side worker

See server-worker.

Managed worker

See server-worker.

Unity Worker

Also known as “UnityWorker” A term sometimes used for a server-worker instance in the GDK for Unity.

Unreal Worker

Also known as “UnrealWorker” A term sometimes used for a server-worker instance in the GDK for Unreal.

Client-worker

Also known as “external worker”, “client-side worker”, or “client”.

A client-worker instance is run by a player, in their game executable program; their game executable program uses it to connect to and interact with the SpatialOS world.

You tell SpatialOS how to launch a worker instance as a client-worker instance in its worker configuration file (worker.json).

Unlike a server-worker instance, a client-worker instance’s lifecycle is not managed by SpatialOS. In a running deployment, there will be one client-worker instance per player, and the players start and stop their client-worker instance.

Client-worker instances are mostly tasked with visualising what’s happening in the world. You’d also use them for dealing with player input. In general, you want to give client-worker instances write access to as few components as possible, to make cheating difficult.

Related pages:

Client

See client-worker.

Client-side worker

See client-worker.

External worker

See client-worker.

Unity Client

Also known as “UnityClient” A term sometimes used for a client-worker type in the GDK for Unity.

Unreal Client

Also known as “UnrealClient” A term sometimes used for a client-worker type in the GDK for Unreal.

Worker attribute sets

In its bridge configuration, each worker type specifies an attribute that says what layer it belongs to, for example “physics”. This attribute is used in access control lists, which specify which attribute a worker type must have in order for instances of that worker type to get read or write access to a component.

Related pages:

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

Related pages:

Sending an update

If a worker instance has write access to a component, it can send an update to it. 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.

Related pages:

Bridge

A bridge is what connects an instance of a server-worker or client-worker to the Runtime so that it can send and receive updates about the game world.

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

Related pages:

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. This file:

  • sets the process used to build the worker type
  • configures settings to do with how instances of this worker type communicate with SpatialOS, including information like what components the worker instances are interested in
  • sets whether a worker type is a server-worker or a client-worker
  • for server-workers, tells SpatialOS how to run the worker instances in the cloud
  • for client-workers, specifies how to launch the worker instances on the game player’s local computer

Related pages:

Worker scheduler

The worker scheduler is responsible for starting up worker instances according to your load balancing strategy.

For example, if you have a server-worker type called PhysicsWorker for which you’re using the rectangle_grid strategy with two rows and two columns, the worker scheduler starts up four PhysicsWorker instances.

The worker scheduler is also responsible for restoring worker instances if they break, to make sure you always have the right number of worker instances running for each worker type.

Load balancer

The load balancer is part of the SpatialOS Runtime. It is responsible for making sure each server-worker instance has write access to the correct components on entities.

For example, if you have a server-worker type called PhysicsWorker for which you’re using the rectangle_grid strategy with two rows and two columns, the load balancer splits the world into four areas and makes sure the correct worker instances get the correct write access to each entity component.

Related pages:

Interest

There are three types of interest: entity interest, component interest, and query-based interest.

Entity interest

A worker instance 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.

The consequence of a worker instance being interested in a chunk is that it will check out all the entities in that chunk.

Component interest

Each worker type, in its worker configuration (worker.json), specifies which components it is interested in. A worker instance of a particular type will only get sent updates about components it’s interested in.

This means that, for entities inside a chunk that a worker instance is interested in, it may only be interested in (and therefore only check out) particular components on that entity.

The component delivery settings in a worker configuration specify which components a worker instance is interested in. By default, a worker instance is only interested in the components with checkout_initially explicitly set to true in its worker type’s worker configuration.

Which components a worker instance is interested can change at runtime:

  • If a worker instance is given write access to a component, it becomes interested in that component.
  • You can manually update which components a worker instance is interested in at runtime.

Related pages:

Query-based interest

Query-based interest is a per-component way of specifying what a worker instance is interested in using queries. It is intended as a replacement for streaming queries and component delivery settings.

You enable query-based interest on individual entities, rather than universally. This means you can selectively enable query-based interest only on the entities for which you currently use streaming queries or component delivery settings. (You can enable it for all entities, but you don’t have to, because entity interest still works.)

Related pages:

Checking out

Each individual worker instance checks out only part of the world. This happens on a chunk-by-chunk basis. A worker instance “checking out a chunk” means that:

  • it will have a local representation of every entity in that chunk
  • SpatialOS will send it updates about those entities

A worker instance will check out all chunks that it is interested in.

Related pages:

Streaming queries

Streaming queries allow worker instances 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.

For more information on the advantages and limitations of streaming queries, go to Bridge configuration: streaming queries.

Worker flag

Worker flags let you change values that worker instances use, either at the start of a deployment or dynamically while it’s running. For example, you could vary the walking speed of your entities and see how this affects the world.

Worker flags (and their values) are defined in the launch configuration file.

A worker instance can query the value of a flag at any time. You can set the value of flags for a running deployment from the Console, or using the command-line.

Related pages:

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.

SpatialOS world

Also known as “the world” and “the game 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 worker instances. Each worker instance 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/representation of that world that a worker instance checks out locally. This is why worker instances must 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.

Layers

Layers are a concept that organises both the components in your game world, and the worker instances that simulate the world.

You can look at layers in two ways:

  • A layer is a group of components on entities in the game world.
  • A layer comprises the worker instances that have authority over one of those groups.

For details, see Layers.

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.

Related pages:

World unit

World units are an arbitrary unit that worker instances can interpret as they choose.

Settings in world units:

Related pages:

Queries

Queries allow worker instances to get information about the world outside the region they’re interested in.

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.

Queries can search for entities with the following attributes:

and any combination of the above, using AND/OR.

Based on the set of entities that match it, a query can return:

  • snapshots of those entities, including all components
  • snapshots of those entities, including only the components you specify
  • the number of entities

You should keep queries as limited as possible. All queries hit the network and cause a runtime lookup, which is expensive even in the best cases. This means you should:

  • always limit queries to a specific sphere of the world
  • only return the information you need from queries: specify which components you need to know about
  • if you’re looking for entities that are within your worker instance’s region of interest, search internally on the worker instance instead of using a query

Related pages:

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.

Worker instances can only see the entities they’re interested in. Worker instances can represent these entities locally any way you like.

For example, for worker instances built using Unity, you might want to have a prefab associated with each entity type, and spawn a GameObject for each entity the worker instance has checked out.

You can have other objects that are not entities locally on worker instances - like UI for a player - but no other worker instance will be able to see them, because they’re not part of the SpatialOS world.

Related pages:

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.

Components can contain:

  • properties, which describe persistent values that change over time (for example, Position)
  • events, which are things that can happen to an entity (for example, StartedWalking)
  • commands that another worker instance can call to ask the component to do something, optionally returning a value (for example, Teleport)

An entity can have as many components as you like, but it must have at least Position and EntityAcl. Most entities will have the Persistence and Metadata components.

Components are defined as files in your schema.

Which types of worker can read from or write to which components is governed by access control lists.

Related pages:

Property

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

Property updates can be sent by the worker instance with write access to the component. They’re delivered to other worker instances that are interested in this component of the entity.

For entities they are interested in, worker instances can:

  • Read the current value of a property
  • Watch for changes to the value of a property
  • Send an update to the value of a property (if they have write access)

Related pages:

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

Events let an entity broadcast a transient message about something that has happened to it. In all other respects, events work the same way as updates to persistent properties.

Events can be triggered by the worker instance with write access to the component. They’re delivered to other worker instances that are interested in this component of the entity.

For entities they are interested in, worker instances can:

  • Watch for an event
  • Send an update that triggers an event (if they have write access)

Related pages:

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 to a specific component. The receiving worker instance can take action and should respond to the request.

By default, commands are routed through SpatialOS.

Because which worker instance has write access to a component can change regularly, and commands must be sent to the worker instance with write access, commands can fail if this worker instance changes between the time of sending and the time of receiving.

This means that, for communication within a small area, it’s better to model it using properties or events. Commands are best suited when you don’t know where the target entity is, or know that it’s likely to be far away. You can short-circuit commands that you think will be received by the same worker instance that sent them, but that comes with a lot of caveats.

Worker instances can:

  • Send a command to a component on an entity
  • Respond to a command sent (if they have write access)

Related pages:

Short-circuiting

Commands are routed through SpatialOS by default. You can choose to bypass this and short-circuit commands when the worker instance sending the command has write access to the target component.

This comes with a lot of caveats, because if the worker instance loses write access to the component, the command can fail.

Related pages:

Standard schema library components

Position (required)

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.

This is used by SpatialOS few specific purposes, like load balancing and queries.

Note that there’s no reason that this component must be used to represent entity positions inside, say, worker logic. For example, a 2D simulation could use a custom position component with only two fields, and update improbable.Position at a lower frequency to save bandwidth.

Related pages:

EntityAcl (required)

To read from a component, or make changes to a component, worker instances 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 type of worker can have write access

Related pages:

Persistence (optional)

Persistence is a 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.

If an entity doesn’t have this component, it won’t exist in snapshots. This is fine for transient entities. For example, you probably don’t want the entities associated with players to be saved into a snapshot you take of a deployment, because the players won’t be connected when you restart the deployment.

Related pages:

Metadata (optional)

Metadata is a component in the standard schema library.

It has a single property, entity_type, that’s used to label the entity.

Related pages:

Interest (optional)

Interest is a component in the standard schema library. You use it to specify query-based interest.

Related pages:

EntityId

An EntityId uniquely identifies each entity in the world and in a snapshot.

Entity template

An entity template defines what components an entity has. You use this template when you create an entity.

Creating an entity template varies in different programming languages, but, in general, you create a new Entity object, and then add components to it.

Related pages:

  • Creating and deleting entities in:

Entity database

The entity database is responsible for storing the canonical value of component data for entities, making sure that only worker instances with authority over component data have write access to that data, and informing worker instances of when there are changes to data they have interest in.

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.

Related pages:

Schemalang

Schemalang is SpatialOS’s language for writing a component schemas.

Related pages:

Code generation

Use the command spatial worker codegen to compile generated code from the schema (in C#, C++ and Java).

This code is used by workers to interact with entities: to read from their components, and to make changes to them.

Related pages:

Schema descriptor

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.

Related pages:

Read and write access (“authority”)

Many worker instances can connect to a SpatialOS world. To prevent them from clashing, only one worker instance at a time is allowed to write to each component on each entity: ie, given write access. Write access is sometimes also referred to as authority.

Which types of workers can have write access is governed by each entity’s access control list (ACL).

Which specific worker instance actually has write access is managed by SpatialOS, and can change regularly because of load balancing. However, the list of possible worker instances is constrained by the ACL.

ACLs also control which worker instances can have read access to an entity. Read access is at the entity level: if a worker instance can read from an entity, it is allowed to read from all components on that entity.

Related pages:

Snapshot

A snapshot is a representation of the state of a world at some point in time. It stores each persistent entity and the values of their componentsproperties.

You’ll use a snapshot as the starting point (an initial snapshot) for your world when you deploy, locally or in the cloud.

Related pages:

Initial snapshot

An initial snapshot is a snapshot that you use as the starting point of your world when you deploy, locally or in the cloud.

Related pages:

Taking snapshots

You can take a snapshot from a running cloud deployment, which will capture the current state of all of the persistent entities in the world.

You can take snapshots automatically based on a time interval, or take them manually. You can also use the Platform SDK’s snapshot service to write a script to take snapshots according to your specific use case, and to programmatically download and upload them.

Related pages:

The Runtime

A Runtime instance manages the game world of each deployment.

Worker SDK

Use the Worker SDK to create server-worker types and client-worker types which make your game work as a SpatialOS deployment. You can use these to:

  • extend the functionality of the game development kits for Unity or Unreal.
  • create low-level worker types for game logic that does not require a game engine; these could work without any game engine or with a game engine, complimenting the functionality of worker types in any game engine, including Unity or Unreal.

The Worker SDK is availailable in several programming languages: the C++, C# and Java flavors have a very similar structure; the Worker SDK in C is lower-level and doesn’t include code generation.

Worker SDK in C

The toolkit for developing C# worker types with SpatialOS. This is a fairly low-level set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

Worker SDK in C++

The toolkit for developing C++ worker types with SpatialOS. This is a fairly low-level set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

Worker SDK in Java

The toolkit for developing Java worker types with SpatialOS. This is a fairly low-level set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

C SDK

The lowest level took kit for developing SpatialOS worker types.

Platform SDK

You can use the Platform SDK to build tools, workflows and services that integrate with the SpatialOS platform.

You can use its APIs to integrate SpatialOS into your continuous integration process, create debugging tools as game engine plugins, or build matchmaking and inventory systems that use player identity. You can also manage deployments, snapshots, and other parts of a project locally or in the cloud.

Currently, the Platform SDK is only available in C#.

Related pages:

Related pages:

Unity with SpatialOS

GDK for Unity

A Unity-native experience for developing games with SpatialOS. The GDK for Unity is a toolkit for developing worker types using Unity, built on top of the Worker SDK in C#. It includes APIs for interacting with a SpatialOS world. See the GDK for Unity documentation.

SDK for Unity

Superseded by the GDK for Unity. Until SpatialOS 13.0, SpatialOS included the SDK for Unity. From SpatialOS 13.0 onwards, the SDK for Unity has been released separately.

Unreal with SpatialOS

GDK for Unreal

An Unreal-native experience for developing games with SpatialOS. The GDK for Unreal is a toolkit for developing worker types using Unreal, built on top of the Worker SDK in C++. It includes APIs for interacting with a SpatialOS world. See the GDK for Unreal documentation.

SDK for Unreal

Superseded by the GDK for Unreal. Until SpatialOS 13.0, SpatialOS included the SDK for Unreal. From SpatialOS 13.0 onwards, the SDK for Unreal has been released separately.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums