World, entities, components

GDK for Unreal

If you're using the GDK for Unreal, this page does not apply to you. See the GDK documentation on the world, entities, and components.

If you need further information about terminology used in this concept documentation, take a look at the glossary.

The SpatialOS world

In a game running on SpatialOS, the game world is a core concept. By this we mean the SpatialOS world: the canonical source of truth about things in your game.

Entities and components

All of the data that you want to share between worker instances has to be stored in entities, which are the objects in your game. An entity is made up of components that store data.

For example, in a world with rabbits and lettuces, you'd have Rabbit entities and Lettuce entities, each with components that store data as properties. Both the Rabbit and Lettuce entities have Position components to indicate where they are located. The Rabbit can change position but the Lettuce cannot. The Rabbit also has a Health component and the Lettuce has an Edible component to indicate whether it can be eaten:

As a developer working with SpatialOS, you will:

  • define components, i.e. what data entities can be composed of (write a schema)
  • place entities into your world to form a starting point for your game (create a snapshot)

The components on entities act as the data of the game world. And you’ll write game logic code within workers to make use of that data.

Why is this necessary?

The reason for having this separately-defined world is to store the state of the game world in such a way that many instances of server-workers and client-workers can access and change it, without needing to communicate with each other.

A major reason to use SpatialOS is to exceed those limits: instead of one server looking after the server-side of the game world, SpatialOS coordinates multiple programs (server-workers) to do that.

More information


2019-12-10 Page updated with editorial review: Updated to clarify language and improve diagram

Updated 11 months ago


World, entities, components


Suggested Edits are limited on API Reference Pages

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