Workers: Workers in the GDK
Before reading this document, make sure you are familiar with the MonoBehaviour and ECS workflow.
What is a SpatialOS worker?
To execute any kind of logic on these entities, we use workers. They perform the computation associated with a world: they can read what’s happening, watch for changes, and make changes of their own.
Find out more about SpatialOS entity, component, and worker concepts, in the SpatialOS concept documentaiton.
Workers and ECS worlds
As described in the MonoBehaviour and ECS workflow document, the GDK uses ECS under the hood, even if you are using the MonoBehaviour workflow. So, in your project, the GDK represents SpatialOS entities as ECS entities.
In the GDK, any server-worker or client-worker essentially consists of its connection to the SpatialOS Runtime and a list of ECS systems - which hold the logic relevant to the game world. When your GDK-created game runs and creates either a client-worker or server-worker, that worker tries to connect to the SpatialOS Runtime.
When it connects, the worker creates an ECS world to keep track of all SpatialOS entities that are in its view and adds all systems that are defined inside it to its ECS world. These systems contain the logic necessary to simulate your game and synchronize changes with the SpatialOS Runtime.
This means that, along with a SpatialOS game world and SpatialOS entities, there is an ECS world with ECS entities. However, while the SpatialOS world is game-wide and represents all SpatialOS entities, the ECS world is much narrower; it’s worker-specific and represents only the ECS entities which are currently in a worker’s view. Of course, this means that you have as many ECS worlds in your game as you have workers.
You add definitions of the systems inside your worker using the worker API
worker.World.GetOrCreateManager<YourSystem>(). (See the worker API documentation for more information.)
To learn about a workers’ connection to the SpatialOS Runtime, see:
To learn more about how to create and use workers in the GDK, please see the following documentation:
- MonoBehaviour workflow - Workers: Creating workers with WorkerConnector
- ECS workflow - worker entity
- API - worker
- API - worker system
In the GDK’s Playground project we provide an example implementation of the connection logic necessary for the workers to connect to the SpatialOS Runtime. These are stored as prefabs, so that you can use them directly in Scenes. We provide three sample Scenes:
SampleScene: This Scenes contains both the
UnityGameLogicprefabs and will start both workers as soon as you load the scene.
ClientScene: This Scene contains only the
UnityClientprefab and can be used to build your client worker for cloud deployments.
GameLogicScene: This Scene contains only the
UnityGameLogicprefab and can be used to build your server worker for cloud deployments.
The position of these prefabs in the Scene define the
Origin of the worker, which is used to translate all entities that have been added to this worker. This ensures that entities checked out by different workers don’t interfere with each other when running multiple workers in the same scene.