Basics 1 - Setup
Welcome to the Basics Tutorial!
In this lesson you’ll:
- set up your machine for development with SpatialOS and Unreal
- get the project code
- run the project locally
- use the Inspector to explore the world
- learn about entities, components and workers - the core concepts of SpatialOS
This first lesson is mostly background work you need to do before you can get going with development. Once your machine is set up and the project is running, we’ll use the project to explain the basic concepts of SpatialOS. So bear with us!
1. Set up your machine
To set up your machine for developing with SpatialOS, follow the setup guide for Windows, including the optional Unreal part. This sets up the
spatial command-line tool, which you use to build, run, and deploy your game. You’ll use it later in the lesson to build the game and run a local deployment.
At the moment, the SpatialOS Unreal SDK only supports development in Windows.
It’s done when: You run
spatial versionin a terminal, and see
'spatial' command-line tool version: <number>(or
'spatial.exe' command-line tool version: <number>) printed in your console output.
2. Set up the project
In this tutorial you’ll develop on a variation of the Unreal Starter Project that we’ve prepared.
This variation contains a pawn for the Player (replacing the cube) and a “bot” pawn.
2.1. Download the source code
Download and unzip the source code.
2.2. Check your setup
Open a terminal and navigate to the directory you just unzipped (the directory that contains
spatial diagnose. This checks that you installed all the software you needed correctly.
If spatial diagnose finds errors with your setup, fix them.
It’s done when: You see
'spatial diagnose' succeeded(or
'spatial.exe diagnose' succeeded) printed in your console output.
2.3. Build the project
In same terminal window, run
spatial worker build --target=local.
This builds the game. It can take a while, so you might want to go and get a cup of tea.
If it doesn’t work first time, you can retry by running
spatial worker clean then
spatial worker build again.
It’s done when: You see
'spatial build' succeeded(or
'spatial.exe build' succeeded) printed in your console output.
2.4. Run the project locally
In the same terminal window as before, run a local deployment of the game by running
spatial local launch. This can take a minute to get up and running.
It’s done when: You see
SpatialOS ready. Access the inspector at http://localhost:21000/inspector printed in your console output. However, the configuration of the project also launches one managed worker and you’ll know it’s ready when you see
The worker UnrealWorker0 registered with SpatialOS successfully.
2.5. Connect a client
Now SpatialOS is running the server-side part of the game. But for you to connect to it and play, you need to run a client.
There are several ways to run a client, but the fastest one for local development is to run one from the Unreal Editor.
Locate the Unreal project file for your project. This can be found in
Right-click on your project’s
.uprojectfile and select Switch Unreal Engine version.
Switch engine versions to the source-built version you built previously.
StarterProject.uprojectto open the project in Unreal. You’ll see a scene containing just a flat surface that is the ground.
Click Play ▶ and when it connects, you’ll see some log messages. You’ll be in control of a pawn that you can move using
WASD, and you’ll see a bot standing in front of you.
3. Open the Inspector
The Inspector is a web-based tool that you use to explore the internal state of a SpatialOS world. You’ll use it right now to find out about the main SpatialOS concepts.
Open the Inspector at
3.1. What you can see in the Inspector window
Entities are the basic building block of a SpatialOS world. Every thing that has some kind of persistence or has data which needs to be replicated in different clients in your game world should be an entity.
Entities are made of components, which describe an entity’s properties (like position, health, or waypoints).
The main area of the Inspector shows you a top-down, real-time view of the entities in your game world. This project contains three entities: your Player that was created when your client connected, a Spawner (you’ll learn about this later, but essentially it’s an entity that can create new entities like your player), and the standing bot.
The bottom-right list initially shows how many entities of each type there are in the current view of the Inspector. We’ll look at this area in more detail shortly.
The top-right list shows the workers connected to SpatialOS.
Essentially, workers are just programs that can read from and modify the entities in the world you see in the Inspector.
In this project, all the workers are instances of Unreal. There are two types:
Unreal running in headless mode. These workers handle the server-side logic. In the list,
UnrealWorker0is of this type.
Unreal running as a client. There’ll be one of these in the list for every player connected. At the moment, there’s just one: yours (
UnrealClientfollowed by a list of random characters).
The number next to each worker represents its load: a measure of how much work it is doing. SpatialOS uses this number to start and stop server-side workers as necessary.
The project is configured to start with one
UnrealWorker; but if you expanded the game world, you’d need more. SpatialOS automatically allocates areas of the world to each
UnrealWorker, and seamlessly stitches the world together between them according to several patterns that you can configure.
As mentioned before, entities are made up of components, and you can view these in the Inspector. To do so, select your player entity by left-clicking on it. Since there are two entities in the same position, you’ll see that you selected both:
This view lists all the entities of each type that you’ve selected. To see the individual ones, expand the list:
You’ll see there’s one player entity (in this case the entity with ID
3). Click the ID number to select the entity.
This view lists all the components of the entity, and which workers have authority over them (you’ll learn about authority in more detail later).
You can select a component to see the information it contains. Do so for the
Position one and you’ll see it has a set of coordinates
coords, which in this case are (0,0,0).
Components are really what define an entity. They can be anything you like, but common examples might be health, or stats. Every entity has a
Position component that defines its location in the SpatialOS world.
3.2. (optional) Stop a worker
To see worker management in action, you can stop the worker running the game logic, and see how SpatialOS starts a new one - without any disruption to players at all. To try this:
Click the name
UnrealWorker0in the list of workers. This shows details about that worker.
Click the red Stop worker button. This shows a confirmation dialog.
Click the Stop worker button.
SpatialOS stops the worker immediately. Just a few seconds later, the load-balancing algorithm kicks in, and it starts a new worker. Note that nothing at all happens in the game window - the client isn’t even disconnected. Load-balancing is completely invisible to players.
4. Stop the game running
In Unreal, click the Stop button to stop your client.
In your terminal, stop the server side of the game by pressing Ctrl + C.
In this lesson you’ve set up the SpatialOS SDK on your machine, and run the project for the first time. You’ve also learned about some fundamental SpatialOS concepts: entities, components and workers.
In the next lesson you’ll add basic movement to the bot as a way to learn how to modify property values of a component.