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 clients and managed workers, and the assets your workers 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:

The spatial command-line tool

The spatial command-line tool provides a set of commands that you use to interact with a SpatialOS project. Among other things, you use it to:

Related pages:

Unity SpatialOS window

The Unity SpatialOS window is an extension to the Unity Editor UI. If you’re using the Unity SDK, you can use it to run some of the spatial command-line tool commands from inside the Unity Editor (including building and deploying) to speed up local development.

Related pages:

Building

When you make changes to the code of a worker, you need to build those changes in order to 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, you should only build that worker’s code.

You can build all workers 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 SpatialOS itself. SpatialOS sets up the world based on a snapshot, then starts up the workers needed to run the game world.

Once the deployment is running, you can connect clients to it. You can then use the clients 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:

  • Have a snapshot to be the starting point of your world.
  • Build, if you’ve made any changes to your project/worker code.

You can launch a local deployment using the command spatial local launch, or from the Unity SpatialOS window.

Launching a local deployment runs SpatialOS locally. SpatialOS will start (and stop) the managed workers needed by the game world.

Once the deployment is running, you can connect clients to it in order to play the game (only on your local machine) using:

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 managed workers needed by the game world.

Once the deployment is running, you can connect clients to it, using:

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 spatial command-line tool uses when it launches a deployment. This includes things like how big the world is, which workers to use in the deployment, and what permissions to give them.

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 clients 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 from the assembly you uploaded.

Related pages:

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 (the deployment manager), which shows its status, and gives you access to the Inspector, Logs, and Metrics pages for that deployment.

Related pages:

Worker

SpatialOS manages the world itself: it keeps track of all the entities and their properties. 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.

In order to achieve huge scale, SpatialOS divides up the entities in the world between workers, balancing the work so none of them are overloaded. For each entity in the world, it decides which worker should have write access to each component on the entity. (Only one worker at a time can have write access, to prevent multiple workers clashing.)

As the world changes over time, where entities are and the amount of work associated with them changes. Managed workers report back to SpatialOS how much load they’re under, and SpatialOS adjusts which workers have write access to components on which entities (and starts up new workers when needed). This is called load balancing.

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

If the worker has write access to a component, it can send updates: it can update properties, and trigger events.

Workers can be managed (server-side) or external (eg client workers).

A worker can be written using the Unity SDK or Unreal SDK game engine integrations, or using the C++, C#, Java or JavaScript SDKs.

Related pages:

Managed worker (server-side worker)

A managed worker is any worker that has its lifecycle managed by SpatialOS. That means, in a running deployment SpatialOS is in charge of starting it up and shutting it down, as part of load balancing - unlike an external worker.

Managed workers are often tasked with implementing game logic, physics simulation, etc. They run on the server side, so they’re sometimes called server-side workers.

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

You set whether a worker is managed or external in its worker configuration file.

Related pages:

UnityWorker

Managed workers built using the Unity SDK are usually called UnityWorker.

Related pages:

External worker

An external worker is any worker whose lifecycle isn’t managed by SpatialOS (as opposed to a managed worker. You start them up and shut them down manually.

Player clients are a type of external worker.

You set whether a worker is managed or external in its worker configuration file.

Related pages:

Client worker

A client worker is a worker that is run by a player, on their local machine; they use it to connect to and interact with the SpatialOS world. Having a client worker is a common pattern in SpatialOS games.

Unlike a managed worker, a client worker’s lifecycle is not managed by SpatialOS: they’re external workers. In a running deployment, there will be one client worker per player, and the client worker is started up and shut down by them.

Client workers 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 workers write access to as few components as possible, to make cheating difficult.

UnityClient

Client workers built using the Unity SDK are usually called UnityClient.

Related pages:

Sending an update

If a worker has write access to a component, it can send an update to it. An update is either changing the value of a property, or triggering an event.

Related pages:

Worker configuration

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

Related pages:

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 managed 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 reduces the amount of work each instance is doing to a level it can handle.

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:

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.

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

Component interest

Each worker, in its worker configuration, specifies which components it is interested in. A worker will only get sent updates about components it’s interested in.

This means that, for entities inside a chunk that a worker 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 is interested in. By default, a worker is only interested in the components with checkout_initially explicitly set to true in its worker configuration.

Which components a worker is interested can change at runtime:

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

Related pages:

Checking out

Each individual worker checks out only part of the world. This happens on a chunk-by-chunk basis. A worker “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 will check out all chunks that it is interested in.

Related pages:

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.

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/representation of that world that a worker checks out locally. This is why workers 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.

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 workers can interpret as they choose. For example, Unity workers interpret one world unit as one meter in the Unity coordinate space.

Settings in world units:

Related pages:

Queries

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

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’s region of interest, search internally on the worker 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.

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

For example, for workers built with the Unity SDK, there’s a prefab associated with each entity type. The Unity SDK manages a GameObject for each entity that a worker has checked out.

You can have other objects that are not entities locally on workers - like UI for a player - but no other worker 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 workers.

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 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 workers 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 with write access to the component. They’re delivered to other workers that are interested in this component of the entity.

For entities they are interested in, workers 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. Events let an entity broadcast a message about something that has happened to it.

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

For entities they are interested in, workers 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 to send a request to the worker with write access to a specific component. The receiving worker can take action and should respond to the request.

By default, commands are routed through SpatialOS.

Because which worker has write access to a component can change regularly, and commands must be sent to the worker with write access, commands can fail if this worker 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 that sent them, but that comes with a lot of caveats.

Workers can:

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

Related pages:

Position

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 for a few specific purposes, like load balancing and queries.

Related pages:

Metadata

Metadata is a component in the standard schema library. It’s technically optional, but all entities must have this component if you’re using the Unity SDK.

It has a single property, entity_type, that’s used to specify which prefab should be used to create a GameObject to represent the entity locally.

Related pages:

Persistence

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:

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 can see an entity, and read its components
  • for each component on the entity, which type of worker can write to it

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:

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 workers 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++, Java, and Javascript, as well as for the Unreal and Unity SDKs).

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

Related pages:

Read and write access

Many workers can connect to a SpatialOS world. To prevent them clashing, only one worker instance at a time is allowed to write to each component on each entity: ie, given write access.

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 workers is constrained by the ACL.

ACLs also control which workers can have read access to an entity. 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.

Related pages:

Readers and writers

In the Unity SDK, in order to read from or write to a component, you need to include a component reader or writer - classes created by code generation.

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 snapshots

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:

Live snapshots/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.

Related pages:

Unity SDK

The Unity SDK is a toolkit for developing Unity workers with SpatialOS. The Unity SDK includes APIs for interacting with a SpatialOS world.

It’s built on top of the C# SDK, which means you can use anything in the C# SDK in Unity worker code.

Related pages:

Prefabs

Prefabs are used in the Unity SDK to represent entities locally.

When a Unity worker checks out an entity, the Unity SDK uses the associated prefab (specified using the Metadata standard component) to create a GameObject to represent the entity.

Related pages:

Unreal SDK

The Unreal SDK is a toolkit for developing Unreal workers with SpatialOS. The Unreal SDK includes APIs for interacting with a SpatialOS world.

It’s built on top of the C++ SDK, which means you can use anything in the C++ SDK in Unreal worker code.

Related pages:

C# SDK

The toolkit for developing C# workers with SpatialOS. This is a fairly raw set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

C++ SDK

The toolkit for developing C++ workers with SpatialOS. This is a fairly raw set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

Java SDK

The toolkit for developing Java workers with SpatialOS. This is a fairly raw set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

JavaScript SDK

The toolkit for developing JavaScript workers with SpatialOS. This is a fairly raw set of APIs for interacting with a SpatialOS world, and with snapshots.

Related pages:

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums