SpatialOS for Unreal 2019.1 release


SpatialOS GDK for Unreal header

Our goal with SpatialOS for Unreal is to provide the fastest way to create, launch, and operate an online game with Unreal Engine. We want to help teams focus on gameplay by providing all the building blocks of a modern online game while preserving native Unreal Engine workflows.

Today, we’re delighted to announce 2019.1 - a collection of product releases which provide our biggest step yet towards this goal. This release contains:

Version 0.6.0 of the SpatialOS GDK for Unreal

This is a release of our Unreal Engine plugin, fork and Example Project, containing:

  • Offloading: you can now offload groups of Unreal Actors, such as AI, to an Unreal server-worker separate from your main Unreal gameplay server-worker. This enables you to increase the scale and complexity of the world beyond what a single dedicated Unreal server can achieve. 
  • Stability, performance, and workflow improvements: continued improvements towards supporting Unreal’s features seamlessly in the GDK, and improving the development workflow and performance.
  • Simulated players: scale test early and often by connecting in any number of simulated players, which are fully customisable and exert a similar load on your game instance as real players (but are much easier to corral into a playtest!)

The introduction of Online Services

2019.1 also includes the release of our first Online Services - providing infrastructure around your game's SpatialOS cloud deployment:

  • Matchmaking services: a new set of open-sourced, self-hosted services for authenticating, grouping, and matching players into SpatialOS game instances, and scaling these instances based on player demand. 
  • The Database Sync Worker Example: an example server-worker designed to easily synchronise and persist cross-session game data between SpatialOS and an external database, such as player inventories.

Please read on for more details on these features and don’t hesitate to join us on our forums or on Discord to discuss your impressions!


The GDK now enables you to offload the computation for classes of Actors, such as all AI actors, to an Unreal server-worker separate from your main gameplay server-worker.

In this architecture, SpatialOS runs another Unreal server-worker which has authority only over this specific group of Actors, while your main Unreal server-worker maintains authority over all other Actors.

Since the game state is stored in SpatialOS all server-workers can use state updates. To call RPCs on a different server, they use the GDK’s cross-server RPCs.

offloaded AI architecture

The biggest gains in this architecture occur when you offload computationally expensive but latency-tolerant systems, such as advanced AI or large-scale background physics simulation. This is computation that the Unreal gameplay server-worker won’t have to do, meaning it can run other systems at a larger scale, such as state synchronisation with clients.

To validate this, we created a demo containing simulated players and complex AIs. The AIs are running expensive pathfinding operations using Unreal’s Environment Query System, and seeing other AIs and players using Unreal’s Perception System. They run the EQS query every 0.5s, and map contains 42 moving barriers which go up and down every 30 seconds to change the navmesh.

We ran this demo, on the same hardware, in a native Unreal dedicated server and in a SpatialOS deployment with a main gameplay server and an offloading server authoritative over all the AI. The aim was to understand whether this architecture enables us to exceed native Unreal’s performance.

We fixed the simulated player count at 64 players in each case, but slowly increased the number of AI to see at which point the main gameplay server would no longer cope (that is, where it dropped below 20 FPS).

We observed the following results:

ScenarioSimulated playersMax AI count to maintain Server FPS > 20
Dedicated Unreal server with native Unreal networking64156
SpatialOS deployment with an Unreal server-worker for the main game loop, and AI offloaded to another Unreal server-worker 64393

This is one of many tests we are planning to run and publish in the coming weeks.

To help you get started with offloading, the GDK’s Example Project now includes an AI Offloading Gym. The gym has turret AIs offloaded to one server, humanoid AI offloaded to another, and a main Unreal gameplay server.

This project is fully open-source and available for you to try out and learn from - we’d love to hear your feedback and suggestions.

For more information about how Offloading works and how to use it in your project, check out the reference documentation.

Stability, workflow and performance Improvements

The GDK for Unreal replaces Unreal’s native networking driver with a SpatialOS integration, which will enable us to preserve almost all Unreal’s features, workflows and APIs. In this release, we have added support for:

  • Dynamic Actor Components 
  • The Gameplay Ability System 
  • Ordered RPCs 

This completes our support of Unreal’s Gameplay Framework.

We have also improved the day-to-day development workflow with the GDK through:

  • Automated setup: much of the setup of the GDK is now automated and the GDK is now installed as an engine plugin, meaning that it’s faster to create new projects. 
  • Faster local deployment startup: local startup time has had a 4 x speedup down to 5s per launch. 
  • Automatic worker and deployment restarts: when you’re iterating locally, the GDK now automatically reloads your workers when you hit play and restarts your deployment when you regenerate schema. 

Simulated Players

You can now add in Simulated Players - an Unreal client instance controlled by simulated player logic rather than real player input - to any GDK project. This can help you scale test your game, as well as figure out game balance issues when you don’t have your target number of players on hand to join playtests.

Simulated Players are launched in another SpatialOS deployment and connect in to the target deployment that is being scale tested. We’ve introduced a new Deploy button in the GDK’s Unreal toolbar to help you easily launch these deployments.

Just like other SpatialOS deployments, the deployment running Simulated Players has all the usual observability tooling (inspector, logs, metrics) to help diagnose a scale test.

We added simulated players to the Example Project for you to try out - follow the tutorial here.

Matchmaking services

We have released our first services for authenticating, grouping and matching players into SpatialOS game instances. These services provide a framework for developers to write their own completely customizable matchmaking logic. These could also be used to build completely different tools related to getting players into game instances, such as players transferring between worlds or entering dungeons.

In this first iteration, this is a suite of example services that users can download, edit and deploy to a public cloud - the services are not managed by Improbable. This is so we can provide as much flexibility as possible for developers to tailor how the services work.

The matchmaking service consists of:

  • An in-memory database storing the player and party queue;
  • Customisable docker containers providing accessible APIs for the assignment of players and parties in the queue to active matches. 

In addition, we have released a Playfab auth service enabling you to easily authenticate players for your SpatialOS game.

This all runs in the public cloud, using Kubernetes and Redis, scaling the resources it needs appropriately. The system diagram below explains how this works after the system has been deployed to a public cloud:

Matchmaking overview diagram SpatialOS

The Database Sync Worker Example

Another area in which we want to help you to save time and to focus on gameplay is in storing data between player sessions. With our new Database Sync Worker Example, you can easily synchronise game data between SpatialOS and an external database.

A simple example of this might be the players’ permanent data, which could contain persistent character unlocks, stats and customisations. We believe that when this data needs to be read and modified by SpatialOS workers, it should be presented in the same way as all other SpatialOS data: in terms of components, component updates, and commands. This lets you keep your game’s logic using the same data models that are already established.

With the Database Sync Worker Example, we’re demonstrating the ability to easily map a hierarchy of data back and forth between a database and a SpatialOS deployment’s workers and clients without restructuring the data on either side of those interfaces. Our example demonstrates how to add the worker’s schema to your project, configure it, interact with the database, and receive update notifications to re-broadcast notifications from the database to your workers.

Database Sync Worker Diagram

To help you get started with the Database Sync Worker in a GDK project, we’ve released a new tutorial which takes you through synchronising kill/death counts from the Example Project with a Postgres database. All source for this project is available in a branch of the Example Project for reference.

Finally, we are releasing a new C# Worker Template, which was used to create the Database Sync Worker. This template can be used to create workers for functionality that doesn’t require all the power of a game engine, for example, chat systems, high-level AI or game logic, and analytics workers. These standalone workers benefit from C#’s fast build times and ecosystem of tools. This template is based on the .NET Core platform for easy cross-platform development.

Getting started

To summarise: this release introduces offloading to the SpatialOS GDK for Unreal, enabling you to start building richer worlds by offloading computation to separate dedicated workers. For faster iteration through the development of your project, the GDK’s local workflow and support for Unreal features has improved, and you can now easily add Simulated Players to any GDK project for scale testing. Finally, our new matchmaking services and the Database Sync Worker Example provide the basis for building the online services that sit outside of your game deployment.

We hope you’re as excited as we are about this release and would love to hear your feedback. Make sure to register for our upcoming livestream series to help you get started with this release.

SpatialOS Livestreams Get Started

More solutions. More possibilities.

Explore all IMS solutions