The SpatialOS Unity GDK: ECS-powered multiplayer


circuit-desktop blue and purple

The Unity GDK and FPS Starter Project have now launched and can be downloaded today.

You may have seen our recent announcement of our new GDKs, kits that integrate SpatialOS and Unity or Unreal with workflows native to those game engines. In this blog, we are sharing our plans for the new Unity GDK (Game Development Kit) which replaces our existing SDK, and details of how to access its pre-alpha release. The Unity GDK is currently Windows only but is coming to MacOS soon.

For anyone not already part of our community, here’s a quick summary: SpatialOS is a platform for creating and running games that go beyond the limits of a single server. With SpatialOS you can implement new kinds of gameplay, impossible with the traditional client-server approach. It’s a fully managed service so we host and scale your game globally. We also provide tools and services for you to easily deploy your game, iterate on its development, measure its performance and understand what’s happening in your game world. You can sign up here to get updates about our Unity GDK here and our Unreal GDK here.

The Unity GDK

Our Unity GDK focuses on the new Entity Component System (ECS). Using this architecture we are aiming to give you great multiplayer performance and a native-feeling Unity development experience.

The concepts behind the Unity GDK are simple, it provides:

  • A performant, data-driven SpatialOS multiplayer integration that takes full advantage of the new Unity ECS.
  • A library of solutions for hard or common networked game development problems via Feature Modules (there’s more on these below).
  • An example game with shared source code which both tests and demonstrates features, for use as a starting point or resource for game development.

In our work scaling SpatialOS games, we have encountered many technical challenges: this GDK lets us share solutions to some of these problems. This will give you reference solutions and a starting point to build your SpatialOS game.

The pre-alpha starts now

We’re already working with developers who are making SpatialOS games to get feedback on the GDK, including Klang, the creators of the SpatialOS simulation MMO Seed. We want to get as much feedback as possible so even at this early stage we are not developing behind closed doors; we are making the source code for the GDK Core available on GitHub under the Improbable licence.

The GDK is in pre-alpha. This means: APIs will change, it is not optimised and currently we are not supporting game development on it. However, this is a great opportunity to get involved early and help shape the GDK with feedback on the forums and Discord.

The Unity GDK: Core and Feature Modules

At the heart of the Unity Game Development Kit is the Unity GDK Core, the foundation layer that integrates SpatialOS with the Unity engine through its Entity Component System (ECS). The Unity GDK Core provides the APIs and development flows which your game code and GDK Feature Modules both make use of. Feature Modules are packages of gameplay functionality and APIs which you can integrate with your game. To bring all this together and test at scale, we are going to build an example game on top of those Feature Modules.

Unity GDK diagram

The diagram above shows what the structure of the Unity GDK might look like at full release. Right now, we are working on the first iteration of the GDK Core and our first Feature Module, a networked transform library, but there’s plenty more to come.

Included in the pre-alpha release, the GDK Core offers benefits such as faster development iteration and Unity workflow support, and Unity tooling support. Many more features are in the pipeline or experimental development for the GDK core – we detail these below.

Fast iteration

We consider development iteration speed a core value of the Unity GDK: we plan to increase iteration speed, by enabling developers to run both Unity clients and servers in one Unity Editor and by providing an example game.

Less time waiting for builds

In the existing SDK, you can only run one instance of a SpatialOS worker on one instance of Unity. We are experimenting with the ability to run clients and servers in a single instance of Unity: when you are creating your game, you will be able to run both client workers and server workers in the Editor at the same time, greatly reducing how often you need to build during day-to-day development. It also makes testing certain game mechanics far easier as you can see the client and server outcome side by side.

An example game to bootstrap your development

In the pre-alpha version of the GDK, there’s already a simple test scene with moving boxes. Long term, we aim to provide a fully-featured, shared-source example game. This example will demonstrate the GDK Feature Modules and show solutions to common multiplayer and networking problems (such as replicating AI characters and shooting across worker boundaries).

Unity-native workflow and tooling

Only worry about synchronisation when it’s important

With the Unity GDK, updates to component properties are simple. Rather than modifying SpatialOS entity states through methods calls and callbacks as in the SDK, using the GDK you can modify the state by assigning their component properties a value. This is the same workflow as in the native Unity ECS.

You can see this in the code snippet below where we set the health component’s Health property to 10.

for (var i = 0; i < data.Length; ++i)
var healthComponent = data.Health[i];
healthComponent.Health = 10;
data.Health[i] = healthComponent;

The GDK generates code to synchronise these state updates automatically so you don’t normally have to worry about it. However, if you want to customise your game’s synchronisation logic, you can override this behaviour and take full control of the process.

High performance

We plan that the GDK will fully use the performance improvements made possible by the Unity ECS architecture and its integration with the multithreaded Job System.

Get the performance benefits of the ECS architecture

The Unity ECS allows the use of lightweight blittable data structures and native collections: we intend the GDK to take full advantage of these. The Unity ECS framework injects the data structures into Unity ComponentSystems as contiguous blocks of memory which, when iterated over, are efficiently prefetched by the CPU. We plan to use this to make significant performance improvements to key parts of the SpatialOS Unity integration. It’s especially relevant where the GDK has to deal with large numbers of components, such as in synchronisation systems.

Ready for multithreading via jobs

As the GDK makes use of Unity’s ComponentData whenever possible, it’s much easier to use Unity’s Job system to multithread your game code. We hope to take advantage of this to multithread parts of the GDK Core as well.

MonoBehaviour workflows

We know that, while the ECS paradigm provides many benefits, it is not the tool for every task, especially so early in its development. Given that, we are planning to create APIs that will inject data into MonoBehaviours in a way similar to the existing Unity SDK. This also greatly reduces the effort required to port an existing Unity SDK game to the Unity GDK.

Upcoming experiments

We are experimenting with synchronous spawning and schema auto-generation. These tests are very much at the early prototype stage, so we are evaluating their viability. We’ll keep you posted!

Synchronous spawning

In the SDK, spawning is a multistep, asynchronous process, and we see it at the root of many bugs and race conditions. The Unity GDK could provide an API to create entities with their components synchronously, handling the asynchronous spawning process for you behind the scenes. This could make writing code around entity spawning significantly simpler.

Schema auto-generation

Every SpatialOS game uses schema to generate the code required to communicate with SpatialOS. We are experimenting with generating the schema automatically, based upon the structs and classes you define in C#. As well as providing a smoother workflow, this also has the potential to allow a generated component to have a mix of fields; both fields that need to be sent over the network and fields that don’t. This could result in not only fewer components but also components which better encapsulate the data of the feature they are related to. The GDK wouldn’t tie you to this workflow – you can still use this alongside writing schema directly, or include schema from other workers.

Feature Modules

As mentioned earlier, Feature Modules are packages of gameplay functionality and APIs that you can integrate with your game. We are currently working on a Feature Module for transform synchronisation; alongside systems for buffering and interpolating over updates, we plan to add systems for transform extrapolation. In the process, we hope to create systems for synchronising workers and generating timestamps.

If all goes well, we are planning to follow that with modules for concepts such as AI characters, shooting and character controllers, depending on the feedback and demand from our users.

Help shape the GDK

The GDK Core pre-alpha version is available now on GitHub at under the Improbable licence. We are looking forward to hearing what you think about it.

Join our community by signing up for news about the Unity GDK and getting involved in discussions on the Improbable forums and on Discord. And we’d love to meet you – look out for news of our Unity game dev meetups and game jams when we test drive the GDK. We can’t wait to see what you do!

More solutions. More possibilities.

Explore all IMS solutions