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.
- 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:
- 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.
- 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
Things we plan to add
- In-editor support for regenerating code from the schema, packaging workers, etc.
- Integration with the
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.
To get started, set up your machine.
Once you’ve done that, see the rest of the documentation to learn how to:
- Set up a project
- Running your project
- Change the starting state of the world
- Create entity blueprints
- Create and delete entities
- Querying the world
- Make changes to components and call commands
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?
- create entities
- delete entities
- set properties of an entity
- trigger an event on an entity
- send a command to an entity
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.