Docs

You are viewing the docs for 10.1, an old version of SpatialOS. 10.3 is the newest →

Unreal integration: Introduction

You can use Unreal Engine 4 as a worker in a SpatialOS project, to add physics, game logic, and visualization to a SpatialOS simulated world. We provide an experimental Unreal SDK, and several starter projects, 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.

On this page:

Known issues

  • Only Windows is supported for development.
  • Only UnrealEngine 4.14.3 is currently supported.
  • The client or editor may occasionally crash when disconnecting.
  • Only two worker types are currently supported (Client and Worker.)
  • (Linux cross-compile) You have to patch out a check for running as root.
  • (Linux cross-compile) You have to patch the Linux toolchain to use libstdc++.
  • (Linux cross-compile) You have to patch the memory management to avoid a static initialization conflict with Protobuf.

Things we plan to add

  • Support for the newly-released 4.15 version of UnrealEngine.
  • In-editor support for regenerating code from the schema, packaging workers, etc.
  • Support for unlimited types of workers.
  • Integration with the spatial diagnose command.

Things we plan to improve

  • The generated blueprints are basic and proof-of-concept.
  • Namespaces, class names, etc. are preliminary and a bit messy. When we have a clearer idea on the direction the APIs should take, we’ll make these more coherent.
  • UnrealBuildTool’s “Unity” builds are not supported.
  • 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 and building the example projects.

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.

A 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.