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.
Simple integrations
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 View.
Integration examples
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.
You also need to know which SDK (C++, C# or Java) you’re going to build on top of. To avoid language interoperability issues, it’s best to choose the language in which your game engine is written.
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 (which how the SDK for Unity and SDK for Unreal do it) 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.
Libraries needed
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
The assembly .zip created by your build process must be
built to the directory build/assembly/worker.
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 build/assembly/<worker type>.
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.
For details on establishing a connection, refer to the C++, C# or Java docs.
When you’re designing this, you need to be aware of that the SpatialOS SDKs do not offer any guarantees of thread safety - so you’ll
need to account for that. This may cause the Connection to block your main thread. If you want multiple threads connecting to SpatialOS,
you’ll need to coordinate it yourself, and take appropriate safety measures. For example, when you process events, you’ll
need to be aware of your threading model, and make sure you’re not calling from the wrong thread.
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 engine.
For example, the SDK for Unity generates “component readers and writers” instead of using the code generated for the C# SDK.
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
At its basic level, an engine integration is just a worker that uses the View - see details about the View in the C++, C# or Java docs.
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 SDK 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.