How to learn SpatialOS
There’s plenty you need to learn in order to build a game on SpatialOS.
This page runs you through a suggested order of things to learn, and tells you about the resources available to you to do that. It concentrates on developing games using the SpatialOS worker SDK, which is available in C++, C#, Java, and as a lower-level C API.
- To use Unity to make SpatialOS games, see the GDK for Unity documentation.
- To use Unreal to make SpatialOS games, see the GDK for Unreal documentation.
Beginner level
This is the stuff you must know in order to do anything with SpatialOS, otherwise it won’t make sense.
1. The fundamentals of the system
Firstly, you need to understand about SpatialOS as a system: how it fundamentally works.
The game world
In a game running on SpatialOS, the world is a core concept. The SpatialOS world is the canonical source of truth about things in your game.
Entities are the things in your game. All of the data needs to be stored in entities, using their components.
Where you can learn about the SpatialOS world
Making the world go
Defining the world separately in this way isn’t how you’d usually do it. The reason for having this separately-defined world is that you’ve got to store this state somewhere, and it’s no longer on a single server.
The whole point of SpatialOS is to exceed those limits: instead of one server/program managing the server-side of the game world, SpatialOS co-ordinates multiple programs to do that.
Each program can only see part of the world.
Any program that connects to the SpatialOS, we call a worker.
Normally, you’ll have two main types of worker:
- Server-workers (also called “Managed workers”) on the server side. These are the ones that SpatialOS co-ordinates and load-balances.
- Client-workers are the programs that players run on their machines to connect to the game.
Where you can learn about workers
Practical stuff: deployments and snapshots
This isn’t conceptually interesting, it’s just stuff you need to do to make things happen.
You’ll need to know how to start (and stop) a deployment - which is really just a running instance of your game - both locally and in the cloud.
The command-line cheat sheet (preview below) might be useful here:
You’ll also need to know how to create and manipulate snapshots. Snapshots are a snapshot of the state of a SpatialOS world. You need one to run a deployment, because we need to know what the state of the world is when the game starts.
Where you can learn about deployments and snapshots
Practical stuff: schema
Your schema is how you define what components entities can have. The reason SpatialOS gets you to define this is to make it easy for different workers to communicate with each other.
You’ll generally only interact with schema when you’re adding new components or changing existing ones.
You need to know roughly what schemalang is, and how you need to use it. You also need to know about generating code from schema: you have to do this every time you change schema.
As part of this, you’ll learn that components can have three constituent parts: properties, events and commands.
Where you can learn about schema
2. Tools you have
So you’ve got a world, and you’re going to write code for your workers that interacts with the world.
The next thing to learn is: What can you actually do to the world from your worker code?
Game development tools
You need to know that there are different SDKs and GDKs for working with SpatialOS, so you know which one you’re going to use.
There is a low-level a worker SDK is available in different programming languages, and high-level Game Development Kits (GDKs) for working with Unity and Unreal.
Worker SDK If you want to use a game engine to work with SpatialOS, you can use the worker SDK to build an integration with your preferred game engine. You can use the worker SDK in different programming languages. These are:
The C++, C# and Java versions of the worker SDK have a very similar structure; the C version is lower-level, and doesn’t include code generation.
You can also make workers using any of those SDKs without integrating a game engine, or you can use the SDKs to make workers that extend or complement the functionality of the SpatialOS development kits for Unity or Unreal (see below).
Where you can learn about GDKs
Unity with SpatialOS There is a higher-level integration you can use with Unity:
- SpatialOS GDK for Unity
A Game Development Kit to use Unity with SpatialOS.
Unreal with SpatialOS There is a higher-level integrations you can use with Unreal:
- SpatialOS GDK for Unreal A new Game Development Kit which provides an Unreal-native experience for developing with SpatialOS.
Components: Properties
You learned about properties as part of schema: they’re an element of a component that stores persistent data about an entity.
You’ll need to know what data you should use properties for, and when a property isn’t appropriate. Some data doesn’t need to be stored at all - for example, if it’s only local to a client.
From workers, you can get the value of properties, set them, or watch for and respond when a property changes.
Where you can learn about properties
Components: Events
You learned about events as part of schema: they’re an element of a component that stores transient data about an entity that happens as a single event.
You’ll need to know what data you should use events for, and when an event isn’t appropriate - for example, when a command might be better.
Where you can learn about events
Components: Commands
You learned about commands as part of schema: they’re an element of a component that lets you send a request, or message, between workers (like an RPC).
You’ll need to learn how to send commands, and how to know which worker will receive a command (it’s to do with authority, which we’ll talk about below). You’ll also need to know about the caveats and limitations of commands
This will help you understand what situations you should use commands in, and when commands aren’t appropriate.
Where you can learn about commands
What can a worker see?
By this point you’ve understood that SpatialOS co-ordinates multiple workers to cover the whole world.
There’s an important consequence to that, which is that workers can’t see the whole world. They only get a view onto part of the world (we say this is the area they have checked out).
You need to understand:
- the idea that each worker has a checkout area
- what “checking out” is
- that the code you write has to take this into account
Where you can learn about worker view
Queries
You learned that workers can’t see the whole world. But sometimes they’ll need to get information about entities outside of their view.
There are two tools you’ll need to know about to do this:
- normal queries, which let a worker search for entities and get information about them at a single point in time
- streaming queries, which let a worker (effectively) check out an entity outside their checkout area
Where you can learn about queries
Adding new entities
You’ve already learned about entities - now you need to know how to create them.
You’ll need to know that an entity is essentially just a group of components (defined in schema, remember?) so when you’re creating an entity you need to specify which components it has.
You also need to specify which workers can read from and write to those components - there’s more about this in Authority below.
Where you can learn about adding entities
Practical stuff: the required components
Alongside components that you define yourself, there are also components from the standard schema library that Improbable provides.
You need to know which components all entities must have, and what they’re for.
Where you can learn about required components
Practical stuff: building
You need to know how to build your worker code into what we call an assembly. (You should have come across this term earlier, as you need an assembly to run a deployment.)
It’s worth knowing what things you need to build when: do you need to re-generate code from schema, compile code for a managed or client worker, or something else? Making sure you only build what’s necessary will speed you up a lot.
Where you can learn about building
3. Authority and checking out
You learned earlier that workers can only see part of the world. Now you need to know why that is, and this should fundamentally shape how you think about developing with SpatialOS.
In order to prevent two workers trying to change the same thing at the same time, for each component on each entity, only one worker can write to that component: we call this write access “authority”.
So if the view of two workers overlaps - for example, if a client and a managed worker can “see” the same part of the world - only one of them will be able to write. The other will only be able to read.
Where you can learn about authority
Practical stuff: Worker attributes, worker requirements
You need to decide which type of worker is allowed write access to each component. The type of worker is called a worker attribute; at the component end, worker requirements specify which worker types are allowed to write to it.
Practically speaking, this is done using a special component called an access control list, or ACL. Each entity needs to have an ACL.
Where you can learn about worker attributes and ACLs
Interest
Earlier we discussed how workers can only see part of the world. Which part of the world they see is determined by their interest.
You need to understand both entity and component interest, and how it affects what your workers can see. In particular, you need to know about the entity interest radius, which affects
Where you can learn about interest
Intermediate level
The topics at this level will help you become a decent SpatialOS developer. You’ll learn how to reason about the system, and build good architecture that makes use of the features without falling into common traps.
4. Thinking spatially (that is, how to use the tools to architect something sensible)
What should happen on each worker
- What should happen locally
- How to use those tools to design a game feature
- Designing authority
Where:
- Plenty of discussion on this in the shooting guide
- Designing workers, in particular Protecting data with authority
Designing components
Examples
5. Starting from scratch, things you have to do when you’re setting up a project
Useful resources:
- C#
- C++
6. Optimisation and load balancing
Chunks and world units
How interest and authority are calculated
- Glossary entry on interest
- Bridge configuration: entity interest
- Bridge configuration: component deliver
- Object interaction design guide
- Understanding read and write access (“authority”)
7. Tools for debugging
- Local deployments
spatial cloud connect external- Running a local deployment across multiple machines
- Metrics
- Cloud logs
8. Interacting with external systems
9. Managing deployments
Advanced level
10. Configuring workers
Build configuration
-
Inside the worker.json. Including using the generated build scripts, and writing custom build scripts.
Bridge configuration
-
Inside the worker.json. Including worker attributes, entity interest, streaming queries, component delivery, and component handover settings.
More about worker attributes
Launch configuration
-
Inside the worker.json. Including launch configuration for managed and for external workers.
Not to be confused with the launch configuration file.
Worker flags
Configuring load balancing
-
Inside the worker.json. Including singleton workers and static and dynamic load-balancing.
Worker permissions
11. Integrating a game engine
12. Running a playtest
No resources yet.