Steps for integrating a game engine
Since game engines differ greatly, we can’t tell you exactly how to integrate your game engine with SpatialOS.
So this page just goes through the different parts of a game engine integration that are required. You’ll need to work out how best to address each point in your use case.
Before you start: thinking about integrations
Bear in mind that a game engine integration can be as simple or as complex as you want it to be.
The simplest kind of game engine integration isn’t any different to a straightfoward worker built using the C++, C# or Java SDKs. An integration built like that would use the SpatialOS SDKs as they are.
More complex integrations
A more complex game engine integration would be designed to use SpatialOS in a way that feels native to the engine: mapping SpatialOS concepts to engine concepts, and making SpatialOS fit intuitively into the engine’s usual workflows. You need to decide how far down that route you want to go.
You may also want to build layers for ease of use. For example, the schema-generated code for the C# SDK provides
statically-typed handlers for component changes. To register callbacks when the type of component is not known
statically you could use the
Dynamic feature of the SDKs
(example from the C# SDK). You could build
more generic on-component-update functions or even implement a custom
For an example of what a full game engine integration looks like, see the overview of how our Unity integration works.
1. Check requirements
To begin, make sure your game engine is suitable for integration with SpatialOS by checking the Requirements.
2. Set up directory structure
Take a look at the Project directory structure page for an idea of how your directory structure should look. You could start from the blank projects for C# or C++: these are stripped-down SpatialOS repositories.
As per the Configuring a worker page:
- Code for workers goes in directories in the
workers/directory of a project.
- You’re not limited to one worker type per directory: if workers share code or assets, they can go in the same directory.
- Each worker needs a worker configuration file (worker.json).
Following this structure means that SpatialOS knows where your worker source is, and knows how to upload the assembly built from it. Everything else - for example, the structure inside the folder for your worker type - is up to you.
3. Set up the build process
You need to work out how to integrate the SpatialOS libraries into the project build process. They can be built into the project or - if you have access to the game engine’s source code - you could build them into the game engine itself.
This involves telling the build system where to look for the SpatialOS libraries, and schema-generated code. The libraries are downloaded as worker packages.
For C++, take a look at Compiling a C++ worker.
For C#, you might find the Setting up a C# worker page helpful.
For Java, you might find the Setting up a Java worker page helpful.
Build output location
.zip created by your build process must be
built to the directory
Creating build scripts
If you want to use the
spatial worker build command to build your worker, you need to create a
spatial.[worker-type].build.json file. See Build configuration
for information on that type of file.
If you don’t use the
spatial worker build to build your worker, you must make sure you run
spatial worker build build-config
so that your worker configuration file (worker.json) gets built.
This command will put it in the directory
4. Decide on a connection flow
You need to figure out what the flow of connecting the game engine to a running SpatialOS deployment will be.
When designing this, you need to consider that the C API does not offer any guarantees of thread
safety. You can use a single
Connection object from different threads but not from multiple
threads simultaneously, as this may result in undefined behavior.
In general we recommend pinning a given
Connection object to a single thread in as far as your
engine allows. If this isn’t possible, you should protect accesses to the object using a mutex in
order to ensure thread safety. You can safely access different
Connection objects simultaneously
as the objects do not rely on any form of dynamic global state.
5. What to do with schema
SpatialOS only provides serialization/deserialization of the schema information. You may want to write a custom code generator to generate something from schema that fits more natively with the concepts in your game development engine.
Custom code generation is based on an abstract syntax tree generated from schema: see Building a custom code generator for details.
6. Integrating the View and representing entities
You’ll need to work out how to build on top of the View in a way that makes sense for your game engine. For example, you should decide how to represent entities locally in your game engine. It’s important to correctly handle entities coming into and out of your View (as well as actually getting created and deleted). For an example of how you can handle this, see the overview of how our Unity integration works.
You may want to work out how to map the concept of SpatialOS entities to a concept in your game engine, if you can do so in a way that takes advantage of the game engine’s features. An example of this is using GameObjects to represent entities in the GDK for Unity. You could also avoid using the concept of entities, and just interact with the SpatialOS world at the component level: you need to decide what makes most sense in the context of your engine.