These are the docs for 12.2, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.1 is the newest →

Unreal SDK documentation

The SpatialOS Unreal integration is currently in beta. We’re very open to feedback - don’t hesitate to get in touch on the forums if you have any thoughts.

Introduction to the Unreal SDK

You can use Unreal Engine 4 as a worker in a SpatialOS project to add physics, game logic and visualization to a SpatialOS game. We provide an Unreal SDK (currently in beta) to make it easier to use Unreal as a worker.

We’re still thinking through how we want to bring SpatialOS concepts to Unreal, and what the workflow will be. There are a few specific issues we’re already aware of; this is just the first step on the way to a native, easy-to-use Unreal integration. Although there are plenty of things missing or in need of improvement, we want to release this to get early feedback from the community.

Known issues

  • Only Windows is supported for development.
  • Not all schema features are supported. Current limitations are:
    • Nested type definitions are not supported.
    • Enums may only assume values within the range 0 - 255.
    • Some schema types are not supported in blueprints due to limitations in the scripting engine: uint32, uint64, int64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, double and improbable.vector3d.
    • Commands with the same name and delegate type (request type + response type) are not supported in schema definition, even if they are defined in different components.
    • Schema types and components with the same name as UnrealEngine UStructs and UClasses will fail to compile. For example type Transform {} conflicts with Unreal’s FTransform.
  • When running a cloud deployment, clients may not be able to connect to your game due to a bug in the Unreal source code. If you encounter this, please patch this pull request into your Unreal Engine source code and rebuild Unreal. Afterwards, you need to build your project using spatial build.

Things we plan to add

  • In-editor support for regenerating code from the schema, packaging workers, etc.
  • Integration with the spatial diagnose command.

Things we plan to improve

  • This is the first time we’re using our C++ APIs with an existing engine, so we’re still working on the best ways to marshal data back and forth, as well as managing and limiting memory allocations to be as efficient as possible.
  • After consulting with Epic, we have decided not to use the built-in networking replication layer, since it’s “close-but-not-quite” in how it operates compared to similar SpatialOS concepts. We do generate code to make using our own data synchronization concepts as easy as possible, both from C++ code and from Blueprints.
  • In order to run in the cloud, we need to cross-compile the engine for the Linux Server target. We’ve leveraged Epic’s work on cross-compilation and will work on making it more seamless.

Thanks for checking out the Unreal integration! We hope you’ll help us shape and improve it by dropping your feedback on the forums.

Getting started

To get started, set up your machine.

Once you’ve done that, see the rest of the documentation to learn how to:

The relationship between SpatialOS and Unreal

When you’re using Unreal on its own, it’s the canonical source of truth about the game world. What’s in Unreal is in the game world.

When you use Unreal as a SpatialOS worker, this isn’t true any more: the canonical source of truth is the world of the SpatialOS simulation, and the entities in that world. Each Unreal worker has a view onto part of that world. It represents the entities from SpatialOS as (entity) blueprints.

An Unreal worker can do whatever it likes to its own representation of the world, run whatever logic it likes, etc etc. But, if the worker doesn’t send these changes to SpatialOS in the form of an update to a SpatialOS entity, those changes will only ever be local: they can’t be seen by any other worker.

Sometimes this is fine. For example, if on a client worker, you are making a purely visual change, no other worker needs to know about it, so it doesn’t need to be represented in SpatialOS.

But for anything else that another worker would need to be aware of, those changes must be made to a SpatialOS entity.

How can Unreal workers change the SpatialOS world?

They can:

  • create entities
  • delete entities
  • set properties of an entity
  • trigger an event on an entity
  • send a command to an entity

For more information, see Creating and deleting entities and Interacting with entity components.

How do Unreal workers get information about the SpatialOS world?

Within the worker’s area of interest, SpatialOS will send the worker updates about changes to components/entities it can read. So a worker can:

  • get the value of a property
  • watch for events being triggered
  • watch for commands being called

Outside its area of interest, a worker can find out about the world by querying for entities.

For more information, see Interacting with entity components and Querying the world.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums