The SpatialOS Unreal GDK pre-alpha: go beyond Unreal

31 July 2018

Back in June, you may have caught our deeper look into our upcoming Unreal GDK. We showed how the GDK keeps the traditional workflows and networking APIs that Unreal Engine developers are familiar with while introducing new native-feeling idioms that turn Unreal’s single-authority engine into a distributed one. Today, we are releasing a pre-alpha version of the Unreal GDK for you to try out. In this post, we’ll explain why we are releasing at such an early stage, the current set of features and workflow we provide, and our roadmap for the near future.

For those of you who don’t already know what Improbable is doing, here’s a quick summary: SpatialOS is a platform for creating games that go beyond the limits of a single server, enabling you to implement new kinds of gameplay that would be impossible with the traditional client-server approach. It’s a fully managed service, meaning that we do all of the work required to host and scale your game globally while you focus on finding the fun in your game. The Unreal GDK allows you to seamlessly integrate SpatialOS with Unreal Engine 4. It replaces our older SDK, which didn’t integrate as closely with the native workflows of Unreal.

The Unreal GDK

The Unreal GDK integrates core parts of Unreal Engine’s networking APIs as seamlessly as possible with the SpatialOS platform while expanding the toolset to take advantage of a distributed server environment. By integrating into Unreal’s existing paradigm, the GDK retains the functionality of many of the networking features Unreal offers out of the box: transform synchronization, character movement controller, client-side prediction, etc. Our aim is to unlock the potential of game development teams by providing an extended, yet familiar engine and framework with an easy learning curve.

The conversion of Unreal Engine’s networking API to a SpatialOS-based one was built on a few core tenets:

  • Have 1:1 mapping between SpatialOS and native Unreal Engine networking wherever possible. For example:
    • Replicated properties ↔ component updates
    • RPCs ↔ commands/events
  • Where a concept approximates to a SpatialOS feature but doesn’t map exactly, modify the Unreal API and document this appropriately. For example:
    • Actor authority
    • Global Actors
  • Where a concept does not apply to SpatialOS, remove it and provide well-documented alternatives. For example:
    • Network settings such as throttling updates per tick
    • Reliable multicast RPC
  • Where a SpatialOS concept does not apply to Unreal Engine’s model directly, expand the API in a way that’s intuitive to Unreal users. For example:
    • Handover semantics for servers transferring authority between each other
    • Cross-server RPCs
    • Actor proxies

The GDK comes in two parts: the Unreal GDK project, available from the SpatialOS repo, and our fork of the Unreal Engine, which has the changes necessary to enable the GDK. (Please note; you will need to follow these instructions to access the fork.)

To accompany the GDK, we are also releasing two projects which you can use as a reference; a simple Starter Project and a working sample multiplayer game which is a Third Person Shooter. Both projects use Unreal workflows exclusively, with no gameplay-specific SpatialOS code. We’ve also included a network switch so you can easily switch the underlying network driver between SpatialOS and standard Unreal to easily verify functionality and performance. (Note that the Starter Project and Third Person Shooter are also in an early pre-alpha stage, with many improvements on the way.)

Community-Driven Development

We’re releasing the Unreal GDK in a pre-alpha state so you, our community, can drive the direction of the GDK from a very early stage in development; this helps us to make the right decisions. Open development means a much shorter feedback loop, leading to a product that does exactly what you need.

With open development, there is full transparency of our roadmap and direction for the GDK. You’ll be able to plan your projects according to these, aware of when certain features are on the horizon for release.

A Word Of Caution

We are releasing the GDK in pre-alpha so we can react to feedback and iterate on development quickly. To facilitate this, during our pre-alpha stage we will not have a formal deprecation cycle for APIs and workflows. This means that everything and anything can change. In addition, documentation is limited and some aspects of the GDK are not optimized.

Given this, we don’t recommend using the Unreal GDK for games in production just yet but you can start using the GDK if:

  • You don’t mind the rough edges and are interested in contributing to the GDK (see our contributions policy).
  • You want to start evaluating the GDK or prototyping on it for a future project.

This is a great time to get involved and help shape the GDK. With our community steering us, we are committed to improving the GDK very rapidly, aiming for an alpha release in Autumn.

First Steps: Building Upon Single Server Parity

The very first principle of the Unreal GDK is to preserve what works in Unreal Engine. Before we expanded Unreal’s capabilities to work in a distributed environment, we had to make sure the GDK’s networked gameplay worked on a single server.

While the user-facing elements of the Unreal GDK look hardly any different to a standard Unreal Engine, under the hood we rewrote the entire networking logic to allow Unreal to expand to use multiple servers.

You can already use multiple servers to tap into the power of SpatialOS but while multiple-server support is still in its early stages, authoritative interactions between Actors on two sides of server boundaries are not yet functional. This means you can move your character to another server, but you can’t yet shoot a player across server boundaries. We are working on adding these SpatialOS-specific features to the GDK; expect to see these features with our Alpha release in the Autumn.

Parity Features In The Pre-Alpha Release

With this in mind, the Unreal GDK pre-alpha release features:

  • Complete parity with replicated properties and lifetime conditions – all types that you could replicate in native Unreal seamlessly work with the GDK.
  • Parity with most RPCs – your existing RPCs will transition smoothly to a SpatialOS environment.
  • Static component replication – components within Actors are properly replicated.

This means if you are currently working on an Unreal project and port it over to the GDK today, your game would look exactly the same but be running on SpatialOS! You would still be able to explore your core gameplay mechanics and when it comes time to expand your game world beyond a single server, the GDK’s multi-server support is already in place; you will be able to take advantage of its more mature state.


Since many of Unreal’s native networking terms are first-class concepts in the GDK, porting a game from native Unreal networking to SpatialOS, using the GDK, is straightforward. So you can see what your existing Unreal project looks like on the GDK, we’ve provided a guide on how to port your game which you can find in the GDK repo.

Scavengers - A survival shooter co-opetition

Porting is one of our main tools for validating the Unreal GDK. We’ve been working alongside game development studio Midwinter Entertainment, to do just this. Midwinter is using Unreal Engine and SpatialOS to create their debut game, Scavengers. Porting their existing prototype to the GDK has been invaluable for us in validating the GDK’s development and design.

New Concepts

Although this release is focusing on single-server support, we have introduced some new concepts to Unreal that will become crucial in a multi-server environment.

Handover Semantics

When an Actor moves from one server to another, the simulation of that Actor on the new server needs to pick up right where the old server left off. This “handover” of simulation requires the Actor’s state to be exchanged between the two servers. Since this situation only occurs in a multi-server scenario, Unreal doesn’t have support for this concept natively, so we’ve added first-class support for handover semantics into Unreal.

To make an Actor’s property correctly transition its state on authority handover, mark the property with the “Handover” tag, similar to how you would tag a replicated property).

float Health;

For more information regarding handover semantics, check out the Actor handover docs.

Singleton Actors

Traditionally, Unreal has the concept of Actors which hold global state and logic, such as GameMode and GameState. In a distributed environment global concepts, like these actors, become trickier to manage. For the Unreal GDK, we’ve called these kinds of actors “Singleton Actors”. To properly handle Singleton Actors, we have introduced the concept of a “Global Singleton Manager”. Check out our docs for more information.

Next Steps: Multi-Server Paradigm

After this pre-alpha release, our primary focus will be on realising the full multi-server paradigm within Unreal. We have already designed what multi-server communication will look like and are ready to start implementing the required pieces to get it into your hands.

Overlapping Server Boundaries

Overlapping Server Boundaries diagram

In a SpatialOS deployment, individual servers have authority over specific regions of a game world and the entities that are present in the region. A server can express interest in entities which it doesn’t have authority over but which are located close to entities it does have authority over. This entails the server checking out entities it is not authoritative over and receiving component updates for them.

In traditional Unreal, a fundamental assumption is the server always has authority over all Actors. Being able to check out entities which a server isn’t authoritative overthrows this assumption out the window, creating situations where it is possible to have non-authoritative Actors on a server. To fully enable server to server communication, we are modifying how Unreal has traditionally implemented authority.

Cross-Server RPCs

To manipulate Actors that a server does not have authority over, we are introducing a new type of RPC called “cross server” RPCs. These will enable a server without authority over an Actor to communicate with the server which has authority and is able to manipulate the Actor.

For example, here’s what a cross-server RPC would look like:

void TakeDamage(int Damage);

Unlike in native Unreal networking, SpatialOS makes it possible for servers to communicate with Actors that exist on another server entirely – a server that does not have authority over an Actor or does not have an Actor checked out can still communicate with that Actor. This is a necessary feature when dealing with large worlds. To facilitate this in the Unreal GDK, we are introducing the concept of an “Actor Proxy” (or “Proxy”). An Actor Proxy is an empty Actor which allows routing of cross-server RPCs on Actors as if they were checked out. A cross-server RPC is called on an Actor Proxy by providing the “context” of what Actor the Proxy represents. (“Context” in this situation is the SpatialOS entity that approximates to the real Actor.)

Actor Proxies

To get an idea of what Actor Proxies could look like, let’s imagine an Actor with a reference to a teammate (Teammate in the example below):

AMyCharacter* Teammate;

A server checks out the Actor but the teammate object is not known to this server. Teammate will then point to an Actor Proxy, which can call a cross-server RPC if provided with a SpatialOS context for Teammate to the RPC

if (Teammate->Role != ROLE_PROXY) // new net role
 Teammate->Heal(); // Teammate isn't an Actor Proxy, call the RPC directly
 // Teammate is an Actor Proxy
 // explicitly get context of relevant actor
 SpatialOSContext context = GetSpatialOSContext_Teammate();

Note: This design is subject to change. This would reroute the RPC to the server with authority.

On our roadmap

In addition to the upcoming support for multi-server communication, we want to give you insight into some of the other exciting features in our pipeline.

Fully-fledged Subobject Replication

Currently replicated subobject support in the GDK is limited to static components on Actors. We want to expand this to offer the same replication that native Unreal offers, such as dynamic components and custom ReplicateSubobjects functions.

Multi-Server Support For More Unreal Engine Systems

Some of the more complex built-in systems, such as the Ability System, won’t work across server boundaries with the GDK. After we have the basis for multi-server communication completed, we’ll look at fully enabling these systems in a distributed context.

Private Singleton Actor Support

Private Singleton Actors are Singleton Actors which only live on the server, such as GameMode. These Actors need to have first-class support built into the GDK to correctly function in a distributed environment while their state remains hidden from clients.

Runtime Type Bindings

With larger projects, the type binding code we generate can add significant overhead to compilation times. We’re planning to create type bindings which are generic for any Actor, making object-specific type bindings obsolete and reducing build times dramatically.

Be A Part Of The Conversation

The Unreal GDK pre-alpha is available now on Github under the Improbable license. Join our community by signing up for news about the Unreal GDK and getting involved in discussions on the Improbable forums (use the “unreal-gdk” tag) and the Unreal channel on the SpatialOS Discord (we’re very active!). Please do let us know any and all your thoughts regarding the GDK. We are absolutely thrilled to be putting our tech in the hands of enthusiastic creators.